`PtWidget`

Superclass for all widgets

Class hierarchy:

PtWidget

Immediate subclasses:

For more information, see the diagram of the widget hierarchy.

Description:

PtWidget is the fundamental superclass. All widgets belong to a subclass of PtWidget.

Geometry

Geometry refers to the size and location of the widget. The following resources let you set and get the widget's geometry in various ways:

Pt_ARG_AREA: The (x, y) coordinates of the widget's upper left corner, and the widget's height and width.
Pt_ARG_DIM: The widget's width and height.
Pt_ARG_EXTENT: A rectangle giving the coordinates of the upper-left and lower-right corners of the widget.
Pt_ARG_GRID_LAYOUT_DATA: The grid layout data structure, which contains layout hints and settings for the widget when its container has a layout type of PtGridLayout.
Pt_ARG_HEIGHT: The overall height.
Pt_ARG_LAYOUT_DATA: A generic resource to set the layout data structure, which contains layout hints and settings for the widget.
Pt_ARG_MAXIMUM_DIM: The maximum size of the widget.
Pt_ARG_MINIMUM_DIM: The minimum size of the widget.
Pt_ARG_POS: The coordinates of the upper left corner of the widget.
Pt_ARG_ROW_LAYOUT_DATA: The row layout data structure, which contains layout hints and settings for the widget when its container has a layout type of PtRowLayout.
Pt_ARG_WIDTH: The overall width of the widget.

These resources aren't displayed in PhAB's control panel; you can use the pointer to change a widget's size and location, or you can edit the values in PhAB's toolbar. Setting one of these resources causes the others to be updated automatically.

Storing arbitrary user data

You can store arbitrary data in a widget by using these resources:

Pt_ARG_POINTER: When you set this resource, the widget copies the value of the pointer into its internal memory.
If you use Pt_ARG_POINTER, you can have several widgets pointing at the same data. If you free the data, you'll need to make sure that no widgets still refer to it.
Pt_ARG_USER_DATA: When you set this resource, the widget copies a block of data of a given size into its internal memory.

There's another resource, Pt_ARG_DATA, that sounds like it can be used for storing user data, but it can't. It's used internally by PhAB applications and compound widgets.

New resources:

Resource	C type	Pt type	Default
Pt_ARG_ANCHOR_FLAGS	`unsigned`	Flag	0
Pt_ARG_ANCHOR_OFFSETS	`PhRect_t`	Struct	0, 0, 0, 0
Pt_ARG_AREA	`PhArea_t`	Struct	0,0,0,0
Pt_ARG_BEVEL_WIDTH	`unsigned short`	Scalar	2
Pt_ARG_BITMAP_CURSOR	`PhCursorDef_t *`	Alloc	NULL
Pt_ARG_CURSOR_COLOR	`PgColor_t`	Scalar	Ph_CURSOR_DEFAULT_COLOR
Pt_ARG_CURSOR_TYPE	`unsigned short`	Scalar	Ph_CURSOR_INHERIT
Pt_ARG_DATA	`void *`	Alloc	NULL
Pt_ARG_DIM	`PhDim_t`	Struct	0,0
Pt_ARG_EFLAGS	`unsigned long`	Flag	0
Pt_ARG_EXTENT	`PhRect_t`	Struct	0,0,0,0
Pt_ARG_FLAGS	`long`	Flag	0
Pt_ARG_GRID_LAYOUT_DATA	`PtGridLayoutData_t *`	Struct	NULL
Pt_ARG_HEIGHT	`unsigned short`	Scalar	0
Pt_ARG_HELP_TOPIC	`char *`	String	NULL
Pt_ARG_LAYOUT_DATA	`void *`	Struct	NULL
Pt_ARG_MAXIMUM_DIM	`PhDim_t`	Struct	0,0
Pt_ARG_MINIMUM_DIM	`PhDim_t`	Struct	0,0
Pt_ARG_POINTER	`void *`	Pointer	NULL
Pt_ARG_POS	`PhPoint_t`	Struct	0,0
Pt_ARG_RESIZE_FLAGS	`long`	Flag	0
Pt_ARG_ROW_LAYOUT_DATA	`PtRowLayoutData_t *`	Struct	NULL
Pt_ARG_USER_DATA	`void *`	Alloc	NULL
Pt_ARG_WIDTH	`unsigned short`	Scalar	0
Pt_CB_BLOCKED	`PtCallback_t *`	Link	NULL
Pt_CB_DESTROYED	`PtCallback_t *`	Link	NULL
Pt_CB_DND	`PtCallback_t *`	Link	NULL
Pt_CB_FILTER	`PtRawCallback_t *`	Link	NULL
Pt_CB_HOTKEY	`PtHotkeyCallback_t *`	Link	NULL
Pt_CB_IS_DESTROYED	`PtCallback_t *`	Link	NULL
Pt_CB_OUTBOUND	`PtCallback_t *`	Link	NULL
Pt_CB_RAW	`PtRawCallback_t *`	Link	NULL
Pt_CB_REALIZED	`PtCallback_t` *	Link	NULL
Pt_CB_UNREALIZED	`PtCallback_t` *	Link	NULL

Pt_ARG_ANCHOR_FLAGS

C type	Pt type	Default
`unsigned`	Flag	0

This resource specifies how the widget is anchored to its parent. The possible values are:

Pt_LEFT_ANCHORED_RIGHT: Anchor the widget's left extent to the right edge of its parent's canvas.
Pt_RIGHT_ANCHORED_RIGHT: Anchor the widget's right extent to the right edge of its parent's canvas.
Pt_TOP_ANCHORED_BOTTOM: Anchor the widget's top extent to the bottom edge of its parent's canvas.
Pt_BOTTOM_ANCHORED_BOTTOM: Anchor the widget's bottom extent to the bottom edge of its parent's canvas.
Pt_LEFT_ANCHORED_LEFT: Anchor the widget's left extent to the left edge of its parent's canvas.
Pt_RIGHT_ANCHORED_LEFT: Anchor the widget's right extent to the left edge of its parent's canvas.
Pt_TOP_ANCHORED_TOP: Anchor the widget's top extent to the top edge of its parent's canvas.
Pt_BOTTOM_ANCHORED_TOP: Anchor the widget's bottom extent to the top edge of its parent's canvas.
Pt_BALLOONS_ON: If a child widget has been assigned a balloon, pop up the balloon as soon as the pointer passes over the child widget; otherwise delay the pop up for 1.25 seconds.

If the resize policy conflicts with the anchors, the Pt_ARG_RESIZE_FLAGS override Pt_ARG_ANCHOR_OFFSETS and Pt_ARG_ANCHOR_FLAGS.

For more information about anchors, see the Geometry Management chapter of the Photon Programmer's Guide.

Pt_ARG_ANCHOR_OFFSETS

C type	Pt type	Default
`PhRect_t`	Struct	0, 0, 0, 0

The four values in this PhRect_t structure (see the Photon Library Reference) determine the anchor offsets of each of the widget's sides. (An anchor offset is the distance between the anchoring side of the parent and corresponding side of the child.)

The Pt_ARG_ANCHOR_OFFSETS resource isn't displayed in PhAB because PhAB sets it automatically.

If a side is anchored, its anchor offsets, if explicitly specified, override Pt_ARG_AREA and Pt_ARG_DIM.

Only offsets that have a corresponding bit set in the Pt_ARG_ANCHOR_FLAGS resource are applied. For example, let's say you have a Pt_ARG_ANCHOR_OFFSETS resource of (5,10,20,25) with absolute anchoring and a Pt_ARG_ANCHOR_FLAGS resource of Pt_LEFT_ANCHORED_LEFT | Pt_RIGHT_ANCHORED_RIGHT | Pt_TOP_ANCHORED_TOP | Pt_BOTTOM_ANCHORED_BOTTOM. In that case, the pane's extent will be:

5 pixels from its parent's left canvas edge
10 pixels from its parent's top canvas edge
20 pixels from its parent's right canvas edge
and 25 pixels from its parent's bottom canvas edge

This remains true even as the parent is resized.

If the resize policy conflicts with the anchors, the Pt_ARG_RESIZE_FLAGS override Pt_ARG_ANCHOR_OFFSETS and Pt_ARG_ANCHOR_FLAGS.

Pt_ARG_AREA

C type	Pt type	Default
`PhArea_t`	Struct	0,0,0,0

A PhArea_t structure (see the Photon Library Reference) that contains the x, y, height, and width values for the widget. For related resources, see the “Geometry” section, above.

You can edit this resource in PhAB's toolbar, not the control panel; PhAB also sets it automatically when you move or size the widget.

Pt_ARG_BEVEL_WIDTH

C type	Pt type	Default
`unsigned short`	Scalar	2

The width of the widget's bevel if the widget is highlighted and is to draw a bevel (see Pt_ARG_FLAGS, below, and the Pt_ARG_BASIC_FLAGS resource defined for PtBasic).

Pt_ARG_BITMAP_CURSOR

C type	Pt type	Default
`PhCursorDef_t *`	Alloc	NULL

Defines bitmaps for the cursor when the cursor type (Pt_ARG_CURSOR_TYPE) is set to Ph_CURSOR_BITMAP. You can't edit this resource in PhAB.

The widget automatically sets the hdr member of the PhCursorDef_t structure. For information, see the Photon Library Reference.

Pt_ARG_CURSOR_COLOR

C type	Pt type	Default
`PgColor_t`	Scalar	Ph_CURSOR_DEFAULT_COLOR

The color of the pointer when it's inside the widget. See PgColor_t in the Photon Library Reference.

Pt_ARG_CURSOR_TYPE

C type	Pt type	Default
`unsigned short`	Scalar	Ph_CURSOR_INHERIT

The type of cursor:

Ph_CURSOR_INHERIT: Inherit the cursor, not from the class hierarchy, but from the family hierarchy; that is, from the way your application nests the widgets. The cursor might even be inherited from the Photon server itself.
Ph_CURSOR_BITMAP: Use the bitmap stored in Pt_ARG_BITMAP_CURSOR for the cursor.

By default, bitmap cursors aren't inherited by a widget's child regions. To change this, set Pt_ARG_CURSOR_TYPE to:

Ph_CURSOR_BITMAP & ~Ph_CURSOR_NO_INHERIT

For other cursor definitions, see the cursor type table in PhCharacterCursorDescription_t.

Pt_ARG_DATA

C type	Pt type	Default
`void *`	Alloc	NULL

This resource is used internally by PhAB applications as well as by compound widgets. It isn't displayed in PhAB. For more information, see Building Custom Widgets.

If you want to store arbitrary data in a widget, use its Pt_ARG_POINTER or Pt_ARG_USER_DATA resource. See “Storing arbitrary user data,” above.

Pt_ARG_DIM

C type	Pt type	Default
`PhDim_t`	Struct	0,0

A PhDim_t structure (see the Photon Library Reference) that defines the height and width values for the widget. For related resources, see the “Geometry” section, above.

You can edit this resource in PhAB's toolbar, not the control panel; PhAB also sets it automatically when you size the widget.

Pt_ARG_EFLAGS

C type	Pt type	Default
`unsigned long`	Flag	0

Extended flags inherited by all widgets:

Pt_CONSUME_EVENTS: Consume any event encountered, whether or not an action was performed as a result of that event. (When a widget has processed an event and prevents another widget from interacting with the event, the first widget is said to have consumed the event.)
Pt_INTERNAL_HELP: Display help information for the widget in a balloon, not in the Helpviewer. See the chapter on Context-Sensitive Help in the Photon Programmer's Guide.
Pt_DAMAGE_PARENT (read-only): If the widget is damaged for any reason, damage its parent instead (internal use only).
Pt_SKIP_LAYOUT: Skip this widget when performing a layout. See Using layouts in the Geometry Management chapter of the Photon Programmer's Guide.

Pt_ARG_EXTENT

C type	Pt type	Default
`PhRect_t`	Struct	0,0,0,0

A PhRect_t structure (see the Photon Library Reference) that contains the extent of the widget, a rectangle that specifies the upper-left and lower-right corners of the widget. For related resources, see the “Geometry” section, above.

A widget's extent isn't normally calculated until the widget is realized. You can force a widget to calculate its extent by calling PtExtentWidget() — see the Photon Library Reference.

Pt_ARG_FLAGS

C type	Pt type	Default
`long`	Flag	0

Common flags used by all widgets. Except for those indicated as read-only, these flags are all read/write.

PtWidgetFlags() is a convenience function that retrieves the value of this resource.

The flags include:

Pt_ALL_BUTTONS: Any pointer button can activate the widget. Default is the left button only.
Pt_AUTOHIGHLIGHT: Highlight and give focus to the widget when the cursor enters its extent, and unhighlight and remove focus when the cursor leaves.
Pt_BLOCKED: Prevent the widget and all its non-window-class children from interacting with Photon events.
Pt_CALLBACKS_ACTIVE: If certain widgets have this bit set, and your application sets their resources, the relevant callbacks are invoked. Otherwise callbacks aren't invoked when your application sets resources. If a callback refers to this flag, its description says so explicitly.
For example, if this bit is set for a PtDivider and you use PtSetResources() to change the size of one of its children, the Pt_CB_DIVIDER_DRAG callback is invoked.
Pt_CLEAR (read-only): The widget's brothers-in-front don't intersect with its extent.
Pt_CLIP_HIGHLIGHT: Clip the corners of the highlighting rectangle.
Pt_DAMAGED (read-only): The widget requires repair.
Pt_DAMAGE_FAMILY (read-only): The widget and all its children need to be repaired.
Pt_DELAY_REALIZE: Prevent the widget from becoming realized unless it's explicitly realized with PtRealizeWidget().
Pt_DESTROYED (read-only): The widget has been marked for destruction.
Pt_FOCUS_RENDER: Render a focus indicator when the widget when it gets focus.
Pt_GETS_FOCUS: Allow the widget to be granted focus. The widget needs to have this bit set if it's to receive key events.
Pt_GHOST: Dim the widget. Setting this flag doesn't affect the widget's behavior, just its appearance. The simplest way to disable the widget is to set the Pt_BLOCKED flag in this resource.
Pt_HIGHLIGHTED: Allow the widget to be highlighted as defined by the Pt_ARG_BEVEL_WIDTH, and the Pt_ARG_BASIC_FLAGS resource defined by PtBasic.
Pt_IN_FLUX (read-only): A call to PtContainerHold() has been made on the widget.
Pt_MENUABLE: Respond to clicks on the pointer's right button (i.e. enable the Pt_CB_MENU callback defined by PtBasic).
Pt_MENU_BUTTON: The widget is a menu item.
Pt_OBSCURED (read-only): The widget is completely covered by one other widget, or it's completely outside its parent container's canvas.
Pt_OPAQUE (read-only): This widget obscures everything directly behind it (i.e. it isn't transparent).
Pt_PROCREATED (read-only): The widget was created by another widget (as opposed to an application), such as the PtList and PtText created by a PtComboBox.
Pt_REALIZED (read-only): The widget is realized.
Pt_REALIZING (read-only): The widget is in the process of being realized.
Pt_REGION: Force the widget to have a region.
Pt_SELECTABLE: You can select (repeat, arm, disarm, and activate) the widget. Widgets usually provide visual feedback when selected.
Pt_SELECT_NOREDRAW: The widget doesn't change its appearance when set or unset. This is meaningful only when the widget is selectable.
Pt_SET: The widget is in a “set” state. Generally, this indicates that the widget has been selected.
Pt_TOGGLE: Pressing the pointer button on this widget causes it to toggle between being set and unset. Normally, selectable widgets act as push buttons — they become set when you press the pointer button, and unset when you release the button.
Pt_WIDGET_REBUILD (read-only): The widget will be rebuilt (rerealized) when the widget engine is finished applying resource changes.
Pt_WIDGET_RESIZE (read-only): The widget will be resized when the widget engine is finished applying resource changes.

The default setting of this resource is 0; that is, no flags have been set.

Pt_ARG_GRID_LAYOUT_DATA

C type	Pt type	Default
`PtGridLayoutData_t *`	Struct	NULL

A PtGridLayoutData_t structure that defines additional layout data for the widget when its container widget uses a PtGridLayout type layout.

PtGridLayoutData_t has at least these members:

short flags

Combination of the following flags:

Pt_H_GRAB — If the parent grows horizontally, this child's cell gets some or all of the extra space, depending on the setting of the h_weight member, and whether or not other cells are also grabbing extra space.
Pt_V_GRAB — If the parent grows vertically, this child's cell gets some or all of the extra space, depending on the setting of the v_weight member, and whether or not other cells are also grabbing extra space .
Pt_GRAB_BOTH — Pt_V_GRAB | Pt_V_GRAB
Pt_H_ALIGN_BEGINNING — Left align the widget in its cell
Pt_H_ALIGN_CENTER — Center the widget horizontally in its cell
Pt_H_ALIGN_END — Right align the widget in its cell
Pt_H_ALIGN_FILL — Horizontally stretch (or “fill”) the widget in its cell
Pt_V_ALIGN_BEGINNING — Top align the widget in its cell
Pt_V_ALIGN_CENTER — Center the widget vertically in its cell
Pt_V_ALIGN_END — Bottom align the widget in its cell
Pt_V_ALIGN_FILL — Vertically stretch (or “fill”) the widget in its cell
Pt_ALIGN_BEGINNING_BOTH — Pt_H_ALIGN_BEGINNING | Pt_V_ALIGN_BEGINNING
Pt_ALIGN_CENTER_BOTH — Pt_H_ALIGN_CENTER | Pt_V_ALIGN_CENTER
Pt_ALIGN_END_BOTH — Pt_H_ALIGN_END | Pt_V_ALIGN_END
Pt_ALIGN_FILL_BOTH — Pt_H_ALIGN_FILL | Pt_V_ALIGN_FILL

short h_span

Horizontal span of this child in a number of columns.

short v_span

Vertical span of this child in a number of rows.

PhDim_t hint

The w (width) and h (height) hints for this child widget. Think of these hints as a user defined minimum size, even if the widget could be smaller. Set w and h to 0 if you just want to apply flags to this child.

short h_weight

The portion of the extra space the widget's cell gets if its parent grows, and the widget has the Pt_H_GRAB flag set.

short v_weight

The portion of the extra space the widget's cell gets if its parent grows, and the widget has the Pt_V_GRAB flag set.

PhRect_t margin

cell margins in pixels, where:

ul.x is the left
ul.y is the top
lr.x is the right
lr.y is the bottom

You can use PtGridLayoutDataDflts to initialize your copy of PtGridLayoutData_t. It has the following values:

flags = Pt_H_ALIGN_BEGINNING | Pt_V_ALIGN_BEGINNING
h_span = v_span = 1
hint.w = hint.h = 0
h_weigth = v_weight = 0
margin.ul.x = margin.ul.y = margin.lr.x = margin.lr.y = 0

For more information about using layouts and layout resources, see Using Layouts in Geometry Management in the Photon Programmer's Guide.

Pt_ARG_HEIGHT

C type	Pt type	Default
`unsigned short`	Scalar	0

The height of the widget. For related resources, see the “Geometry” section, above.

You can edit this resource in PhAB's toolbar, not the control panel; PhAB also sets it automatically when you size the widget.

Pt_ARG_HELP_TOPIC

C type	Pt type	Default
`char *`	String	NULL

The meaning of this resource depends on the bits set in Pt_ARG_EFLAGS:

If Pt_INTERNAL_HELP isn't set, Pt_ARG_HELP_TOPIC is used to set the topic position within the HTML help file.
If Pt_INTERNAL_HELP is set, Pt_ARG_HELP_TOPIC is the help information to be displayed.

For more information, see the PtHelp*() functions and the chapter on Context-Sensitive Help in the Photon Programmer's Guide.

Pt_ARG_LAYOUT_DATA

C type	Pt type	Default
`void *`	Struct	NULL

This resource provides a convenient method to get or set either of the Pt_ARG_*_LAYOUT_DATA resources.

When you set this resource using PtSetResource() or PtSetArg(), set the value argument to a pointer to the layout data structure you want to use. This can be one of:

PtRowLayoutData_t
PtGridLayoutData_t

You can optionally set the len argument to a pointer to the layout type that corresponds to the data structure (that is, PtRowLayout or PtGridLayout). If you set len to NULL, the layout data structure for the current layout is set. In this case, make sure that the data structure corresponds to the correct layout type, or your application might crash.

For more information about using layouts and layout resources, see Using Layouts in Geometry Management in the Photon Programmer's Guide.

Pt_ARG_MAXIMUM_DIM

C type	Pt type	Default
`PhDim_t`	Struct	0,0

A PhDim_t structure (see the Photon Library Reference) that defines the maximum size that a widget can be. For related resources, see the “Geometry” section, above.

Pt_ARG_MINIMUM_DIM

C type	Pt type	Default
`PhDim_t`	Struct	0,0

A PhDim_t structure (see the Photon Library Reference) that defines the minimum size that a widget can be. For related resources, see the “Geometry” section, above.

Pt_ARG_POINTER

C type	Pt type	Default
`void *`	Pointer	NULL

A pointer to any data that you want to associate with the widget.

For a comparison between this resource and Pt_ARG_USER_DATA, see “Storing arbitrary user data,” above.

Pt_ARG_POS

C type	Pt type	Default
`PhPoint_t`	Struct	0,0

A PhPoint_t structure that stores the x and y coordinates for the widget. For related resources, see the “Geometry” section, above.

You can edit this resource in PhAB's toolbar, not the control panel; PhAB also sets it automatically when you move the widget.

Pt_ARG_RESIZE_FLAGS

C type	Pt type	Default
`long`	Flag	0

Controls a widget's resize policy in both the x and y directions. Possible values:

Pt_RESIZE_X_AS_REQUIRED
Pt_RESIZE_X_ALWAYS
Pt_RESIZE_X_INITIAL
Pt_RESIZE_X_BITS
Pt_RESIZE_Y_AS_REQUIRED
Pt_RESIZE_Y_ALWAYS
Pt_RESIZE_Y_INITIAL
Pt_RESIZE_Y_BITS
Pt_RESIZE_XY_ALWAYS
Pt_RESIZE_XY_AS_REQUIRED
Pt_RESIZE_XY_INITIAL
Pt_RESIZE_XY_BITS

Note that each ...BITS flag is a mask that represents all the bits of that type.

The default setting of this resource is 0; that is, no resize policy is in effect.

A widget's resize policy deals solely with the widget's renderable data. For a button, the data is its text; for a container, the data is its children. Any rendered data that doesn't fit within the widget's canvas is clipped.

If no resize policy is in effect, the widget's size is unbounded; it may be made as large or small as specified via Pt_ARG_DIM or Pt_ARG_AREA.

If a resize policy is in effect, the widget grows or shrinks to honor that policy. If the policy is ...ALWAYS, the widget resizes itself to fit its data—the dimensions specified via Pt_ARG_DIM or Pt_ARG_AREA don't apply. If the policy is ...AS_REQUIRED, the widget resizes itself to fit its data only if its current canvas size is inadequate to contain that data. In other words, it grows, but doesn't shrink, to fit its data.

If the widget has the ...INITIAL bit set, the resize policy is applied only once each time the widget is realized. This bit is meaningful only in concert with ...ALWAYS or ...AS_REQUIRED.

If the resize policy conflicts with the anchors, the Pt_ARG_RESIZE_FLAGS override Pt_ARG_ANCHOR_OFFSETS and Pt_ARG_ANCHOR_FLAGS.

For more information about resize policies, see the Geometry Management chapter of the Photon Programmer's Guide.

Pt_ARG_ROW_LAYOUT_DATA

C type	Pt type	Default
`PtRowLayoutData_t *`	Struct	NULL

A PtRowLayoutData_t structure that defines additional layout data for the widget when its container widget uses a PtRowLayout type layout.

PtRowLayoutData_t has at least these members:

PhDim_t hint

Contains w (width) and h (height) hints for this child widget. Think of these hints as a user defined minimum size, even if the widget could be smaller. Set w and h to 0 if you just want to apply flags to this child.

short flags

Combination of the following flags:

Pt_ROW_WRAP_AFTER — Unconditionally wrap after this child. Pt_ROW_WRAP should be set in the flags member of the PtRowLayoutInfo_t of the parent.
Pt_ROW_WRAP_BEFORE — Unconditionally wrap this child. Pt_ROW_WRAP should be set in the flags member of the PtRowLayoutInfo_t of the parent.
Pt_ROW_FILL — If this child is the last one in its row or column, stretch or shrink it to occupy all the available space.

You can use PtRowLayoutDataDflts to initialize your copy of PtRowLayoutData_t. It has the following values:

flags = NULL
hint.w = hint.h = 0

For more information about using layouts and layout resources, see Using Layouts in Geometry Management in the Photon Programmer's Guide.

Pt_ARG_USER_DATA

C type	Pt type	Default
`void *`	Alloc	NULL

Data that you want to store in the widget's internal memory.

For a comparison between this resource and Pt_ARG_POINTER, see “Storing arbitrary user data,” above.

Pt_ARG_WIDTH

C type	Pt type	Default
`unsigned short`	Scalar	0

The width of the widget. For related resources, see the “Geometry” section, above.

You can edit this resource in PhAB's toolbar, not the control panel; PhAB also sets it automatically when you size the widget.

Pt_CB_BLOCKED

C type	Pt type	Default
`PtCallback_t *`	Link	NULL

A list of PtCallback_t structures that define the callbacks that the widget invokes whenever it must ignore an event due to being blocked.

Each callback is passed a PtCallbackInfo_t structure that contains at least the following members:

reason: Pt_CB_BLOCKED
event: A pointer to a PhEvent_t structure that describes the event that was blocked for this widget.
cbdata: NULL

These callbacks should return Pt_CONTINUE.

Pt_CB_DESTROYED

C type	Pt type	Default
`PtCallback_t *`	Link	NULL

A list of PtCallback_t structures that define the callbacks invoked when the widget is marked for destruction and is no longer visible. You can use these callbacks, for example, to adjust the appearance of the widgets around the one being destroyed.

In contrast, the Pt_CB_IS_DESTROYED callbacks are invoked when the widget's resources are actually being released.

Each callback is passed a PtCallbackInfo_t structure that contains at least the following members:

reason: Pt_CB_DESTROYED
event: A pointer to a PhEvent_t structure filled with NULLs.
cbdata: NULL

These callbacks should return Pt_CONTINUE.

Pt_CB_DND

C type	Pt type	Default
`PtCallback_t *`	Link	NULL

A list of PtCallback_t structures that define the callbacks called when a drag-and-drop (Ph_EV_DNDROP) event is received. For more information, see the Drag and Drop chapter of the Photon Programmer's Guide.

A widget doesn't have to have Pt_SELECTABLE set in its Pt_ARG_FLAGS for its Pt_CB_DND callbacks to be invoked.

Each callback is passed a PtCallbackInfo_t structure that contains at least the following members:

reason

Pt_CB_DND

reason_subtype

One of:

Ph_EV_DND_ENTER — the pointer has moved into the widget during a drag-and-drop operation.
Ph_EV_DND_LEAVE — the pointer has left the widget.
Ph_EV_DND_CANCEL — the drag-and-drop operation has been canceled.
Ph_EV_DND_COMPLETE — the drag-and-drop operation has been completed.
Ph_EV_DND_MOTION — the pointer is moving.
Ph_EV_DND_DROP — the user is dropping the dragged item on this widget.

event

A pointer to a PhEvent_t structure that describes the event that caused the callback to be invoked.

cbdata

A pointer to a PtDndCallbackInfo_t structure that contains at least the following members:

PtTransportCtrl_t *trans_ctrl — a pointer to the PtTransportCtrl_t structure (see the Photon Library Reference) controlling the drag-and-drop operation if this application is the originator of it. NULL otherwise.
The following members are valid only when the reason_subtype is Ph_EV_DND_DROP:

int unsigned fetch_index

This contains the index of the element defined in the “fetch array” that describes the data contained in the data member of this structure.

PhTransportHdr_t *trans_hdr

A pointer to the transport header for the unpacked data. See <PhTransport.h>.

void *data

A pointer to the data extracted from the drag-and-drop event. The type of data is given by examining the fetch_index member.

The following member is meaningful only when the reason_subtype is Ph_EV_DND_ENTER:

int unsigned flags

If set to Ph_DND_DELAY_ACK in the callback, the library doesn't automatically acknowledge the ENTER event. This results in a clock cursor over this drop zone until the drag-and-drop operation is canceled.
Otherwise the library automatically acknowledges the ENTER event based on the number of data items selected from the drag-and-drop event via PtDndSelect().

The PtTransportCtrl_t structure also includes:

int unsigned handle

A variable for the your convenience. The value placed here will be found in handle in subsequent callbacks related to the ENTER event where the handle was set.

Additional data is passed to Pt_CB_DND callbacks for these widget classes:

A drag-and-drop recipient typically calls PtDndSelect() when the reason_subtype is Ph_EV_DND_ENTER, and handles the data when the reason_subtype is Ph_EV_DND_DROP. The other subtypes can be generally ignored.

For more information, see the Drag and Drop chapter of the Photon Programmer's Guide.

Pt_CB_FILTER

C type	Pt type	Default
`PtRawCallback_t *`	Link	NULL

A list of raw callbacks invoked when an event that matches the provided event mask is to be passed to the widget.

These callbacks are invoked before the event is processed by the widget. Contrast this resource with Pt_CB_RAW.

Because the Pt_CB_FILTER callback is called before the widget processes the event, it gives you the opportunity to decide if the event should be ignored, discarded, or processed by the widget. The return code from the callback indicates what is to happen to the event.

You can add a Pt_CB_FILTER callback to a widget in your application's code by calling PtAddFilterCallback() or PtAddFilterCallbacks(). For more information about this callback, see “Event handlers” in the Events chapter of the Photon Programmer's Guide.

Each callback is passed a PtCallbackInfo_t structure that contains at least the following members:

reason: Pt_CB_FILTER
reason_subtype: 0 (not used).
event: A pointer to a PhEvent_t structure that describes the event that caused the callback to be invoked.
cbdata: NULL

These callbacks should return one of:

Pt_CONSUME: Consume the event and prevent further propagation of it.
Pt_IGNORE: Ignore the event. The event is still consumed if the widget has Pt_CONSUME_EVENTS set in its Pt_ARG_EFLAGS. If Pt_CONSUME_EVENTS isn't set, the event continues through the widget hierarchy as if the current widget didn't exist.
Pt_PROCESS: Allow the event to be processed by the widget as usual.

Pt_CB_HOTKEY

C type	Pt type	Default
`PtHotkeyCallback_t *`	Link	NULL

A list of PtHotkeyCallback_t structures. If the widget receives a key event that matches a structure's key cap and key modifiers, the widget calls the function specified in that structure. If a function isn't specified, the widget invokes its Pt_CB_ACTIVATE callback list with a reason_subtype of Pt_CB_HOTKEY.

A hotkey isn't invoked if any ancestor of the widget that owns it is blocked.

You can add a Pt_CB_HOTKEY callback to a widget in your application's code by calling PtAddHotkeyHandler(). For more information about this callback, see “Hotkey callbacks” in the Editing Resources and Callbacks in PhAB chapter of the Photon Programmer's Guide.

Each callback is passed a PtCallbackInfo_t structure that contains at least the following members:

reason: Pt_CB_HOTKEY
event: A pointer to a PhEvent_t structure that describes the event that caused the callback to be invoked.
cbdata: A pointer to a PtHotkeyCallback_t structure.

These callbacks should return Pt_CONTINUE.

Pt_CB_IS_DESTROYED

C type	Pt type	Default
`PtCallback_t *`	Link	NULL

A list of PtCallback_t structures that define the callbacks invoked when the widget's resources are being released. You'll find this resource useful for cleaning up variables or memory associated with the widget.

In contrast, the Pt_CB_DESTROYED callbacks are invoked when the widget is marked for destruction and is no longer visible.

Each callback is passed a PtCallbackInfo_t structure that contains at least the following members:

reason: Pt_CB_IS_DESTROYED
event: A pointer to a PhEvent_t structure filled with NULLs.
cbdata: NULL

These callbacks should return Pt_CONTINUE.

Pt_CB_OUTBOUND

C type	Pt type	Default
`PtCallback_t *`	Link	NULL

A list of PtCallback_t structures that define the callbacks invoked when you press the pointer button on the widget and then move out of the “hot spot” with the button still depressed.

This callback is particularly useful for initiating drag or drag-and-drop operations. For more information, see the Drag and Drop chapter of the Photon Programmer's Guide.

Each callback is passed a PtCallbackInfo_t structure that contains at least the following members:

reason

Pt_CB_OUTBOUND

reason_subtype

The button state (the same as ptr->button_state if the code given below is included in your callback).

event

A pointer to a PhEvent_t structure that describes the event that caused the callback to be invoked. The event data is a PhPointerEvent_t structure (see the Photon Library Reference) that can be fetched in the following manner:

PhPointerEvent_t *ptr =
   (PhPointerEvent_t *)PhGetData( cbinfo->event );

cbdata

NULL

These callbacks should return Pt_CONTINUE.

Pt_CB_RAW

C type	Pt type	Default
`PtRawCallback_t *`	Link	NULL

A list of PtRawCallback_t structures that defines the raw callbacks that the widget invokes if the event it receives matches the event mask provided in the PtRawCallback_t structure.

These callbacks are invoked after the widget has processed the event, even if the widget's class methods consume it. Contrast this with the Pt_CB_FILTER resource, which is invoked before the widget processes the event.

You can add a Pt_CB_RAW callback to a widget in your application's code by calling PtAddEventHandler() or PtAddEventHandlers(). For more information about this callback, see “Event handlers” in the Events chapter of the Photon Programmer's Guide.

Each callback is passed a PtCallbackInfo_t structure that contains at least the following members:

reason: Pt_CB_RAW
event: A pointer to a PhEvent_t structure that describes the event that caused the callback to be invoked. If the widget's class methods consumed the event, Ph_CONSUMED is set in the event's processing_flags member.
cbdata: NULL

These callbacks should return one of:

Pt_CONSUME: Consume the event and prevent further propagation of it.
Pt_CONTINUE: Allow the event to be passed up to the widget's parent.

Pt_CB_REALIZED

C type	Pt type	Default
`PtCallback_t` *	Link	NULL

A list of PtCallback_t structures that define the callbacks that the widget invokes whenever it is realized.

Each callback is passed a PtCallbackInfo_t structure that contains at least the following members:

reason: Pt_CB_REALIZED
event: A pointer to a PhEvent_t structure filled with NULLs.
cbdata: NULL

These callbacks should return Pt_CONTINUE.

Pt_CB_UNREALIZED

C type	Pt type	Default
`PtCallback_t` *	Link	NULL

A list of PtCallback_t structures that define the callbacks that the widget invokes whenever it's unrealized.

Each callback is passed a PtCallbackInfo_t structure that contains at least the following members:

reason: Pt_CB_UNREALIZED
event: A pointer to a PhEvent_t structure filled with NULLs.
cbdata: NULL

These callbacks should return Pt_CONTINUE.