PtWidget

Superclass for all widgets

Class hierarchy:

PtWidget

Immediate subclasses:

• PtBasic
• PtTimer

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

PhAB icon:

None — not normally instantiated.

Public header:

<photon/PtWidget.h>

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:

Pt_ARG_ANCHOR_FLAGS

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

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

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

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

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

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

Pt_ARG_CURSOR_TYPE

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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: PtFileSel PtGenList PtGenTree PtList PtRawList PtRawTree PtTree

---

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

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

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

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

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

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

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

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.