PtBasic

A superclass of basic resources for most widgets

Class hierarchy:

PtWidget --> PtBasic

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

PhAB icon:

Public header:

<photon/PtBasic.h>

Description:

The PtBasic superclass provides basic resources for all widgets. It provides the fundamental callbacks for:

• getting/losing focus
• activating
• button press, release, and repeat

Also, PtBasic supports:

• toggle buttons
• autohighlighting

and provides resources for:

• margins
• border colors
• draw color
• fill color
• fill pattern

Some widgets are associated with a command to be performed - when the user clicks on the widget, the command is executed. These widgets have Pt_SELECTABLE set in their Pt_ARG_FLAGS resource.

PtBasic defines several actions involving the left pointer button for its descendants. You can attach callbacks to any of these actions.

Not all widgets change their appearance when armed. The callback information for Pt_CB_ACTIVATE includes the number of clicks. The activate callbacks are invoked once for each click.

PtBasic also defines an action involving the right pointer button: when you press the right pointer button while pointing at a widget, the widget's Pt_CB_MENU callback list is invoked.

In order for this action to occur, the widget must have must have Pt_MENUABLE set and Pt_ALL_BUTTONS cleared in its Pt_ARG_FLAGS resource. The widget doesn't have to have Pt_SELECTABLE set in its Pt_ARG_FLAGS. Pt_CB_MENU is invoked only when the pointer button is pressed, not when the button is released or held down.

If the widget has Pt_ALL_BUTTONS set in its Pt_ARG_FLAGS resource, the actions for all pointer buttons are those for the left button.

New resources:

Pt_ARG_BANDWIDTH_THRESHOLD

Defines the "graphics bandwidth" threshold that defines a slow connection. This resource is used by only a few widgets.

Pt_ARG_BOT_BORDER_COLOR

The color of the bottom and right sides of the border.

Pt_ARG_COLOR

The widget's foreground or drawing color.

Pt_ARG_FILL_COLOR

The widget's background color.

Pt_ARG_FILL_PATTERN

The widget's background pattern. This resource can't be edited in PhAB.

Pt_ARG_HIGHLIGHT_ROUNDNESS

The roundness of the widget's borders.

Pt_ARG_MARGIN_HEIGHT

The amount of vertical space between the widget's canvas and the widget's border. The canvas is the valid drawing area of the widget and is inside all borders and margins.

Pt_ARG_MARGIN_WIDTH

The amount of horizontal space between the widget's canvas and the widget's border. The canvas is the valid drawing area of the widget and is inside all borders and margins.

Pt_ARG_TOP_BORDER_COLOR

The color of the top and left sides of the border.

Pt_ARG_TRANS_PATTERN

The widget's transparency pattern. You'll find this handy for "ghosting" widgets. This resource can't be edited in PhAB.

Pt_CB_ACTIVATE

A list of callbacks that the widget calls when it becomes activated. To activate a widget, you typically release the left pointer button while pointing at an armed widget.

These callbacks are invoked only if the widget has Pt_SELECTABLE set in its Pt_ARG_FLAGS. PtText, PtMultiText, and PtComboBox have a special version of Pt_CB_ACTIVATE. For more information, see the documentation for these widgets.

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

reason

The name of the callback resource (Pt_CB_ACTIVATE) that caused this callback to be invoked.

reason_subtype

0 (not used).

event

A pointer to the event that caused the callback to be invoked.

cbdata

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

• long int value - if the Pt_TOGGLE flag in Pt_ARG_FLAGS is set, value contains either 1 (the widget is pushed in) or 0 (the widget is pushed out). If Pt_TOGGLE isn't set, value contains the click count.

These callbacks should return Pt_CONTINUE.

If you multi-click on a widget, its Pt_CB_ACTIVATE callbacks are invoked once for each click. The callback data includes the click count (1 for the first click, 2 for the second, and so on).

If you want to process only the last of a series of clicks, use a Pt_CB_RAW callback to look for a Ph_EV_BUT_RELEASE event with a subtype of Ph_EV_RELEASE_ENDCLICK. For more information, see PhEvent_t in the Photon Library Reference.

The Ph_EV_BUT_RELEASE event with a subtype of Ph_EV_RELEASE_ENDCLICK occurs approximately half a second after the click, which could be annoying to the user. Most Photon applications don't use multiple clicks because of this.

Pt_CB_ARM

A list of callbacks that the widget calls when it becomes armed. To arm a widget, you typically press a pointer button while the screen pointer is on top of the widget.

These callbacks are invoked only if the widget has Pt_SELECTABLE set in its Pt_ARG_FLAGS.

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

reason

The name of the callback resource (Pt_CB_ARM) that caused this callback to be invoked.

reason_subtype

0 (not used).

event

A pointer to the event that caused the callback to be invoked.

cbdata

NULL.

These callbacks should return Pt_CONTINUE.

Pt_CB_DISARM

A list of callbacks that the widget calls when it becomes disarmed. To disarm a widget, you typically release the left pointer button when not pointing at an armed widget.

These callbacks are invoked only if the widget has Pt_SELECTABLE set in its Pt_ARG_FLAGS.

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

reason

The name of the callback resource (Pt_CB_DISARM) that caused this callback to be invoked.

reason_subtype

0 (not used).

event

A pointer to the event that caused the callback to be invoked.

cbdata

NULL.

These callbacks should return Pt_CONTINUE.

Pt_CB_GOT_FOCUS

A callback list invoked when a widget gets the focus or its focus status changes (e.g. a child widget gets focus from its parent or the focus switches from a child to its parent). The PtIsFocused() function can be used to find the current focus state of any widget.

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

reason

The name of the callback resource (Pt_CB_GOT_FOCUS) that caused this callback to be invoked.

reason_subtype

0 (not used).

event

A pointer to the event that caused the callback to be invoked.

cbdata

NULL.

These callbacks should return Pt_CONTINUE.

Pt_CB_LOST_FOCUS

A list of callbacks that the widget calls when it loses input focus.

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

reason

The name of the callback resource (Pt_CB_LOST_FOCUS) that caused this callback to be invoked.

reason_subtype

0 (not used).

event

A pointer to the event that caused the callback to be invoked.

cbdata

NULL.

These callbacks should return Pt_CONTINUE to relinquish focus, or Pt_END to keep it (for example, if the user has to type something in a text widget).

Pt_CB_MENU

A list of callbacks that the widget calls when the user presses the right mouse button while the pointer is on top of the widget.

The widget must have Pt_MENUABLE set and Pt_ALL_BUTTONS cleared in its Pt_ARG_FLAGS resource. The widget doesn't need to have Pt_SELECTABLE set in its Pt_ARG_FLAGS for these callbacks to be invoked. Pt_CB_MENU is invoked only when the pointer button is pressed, not when the button is released or held down.

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

reason

The name of the callback resource (Pt_CB_MENU) that caused this callback to be invoked.

reason_subtype

0 (not used).

event

A pointer to the event that caused the callback to be invoked.

cbdata

NULL.

These callbacks should return Pt_CONTINUE.

Pt_CB_REPEAT

A list of callbacks that the widget calls when it receives Ph_EV_BUT_REPEAT events. These events occur when you hold down the left pointer button (or the right pointer button if the widget has Pt_ALL_BUTTONS set in its Pt_ARG_FLAGS resource).

These callbacks are invoked only if the widget has Pt_SELECTABLE set in its Pt_ARG_FLAGS.

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

reason

The name of the callback resource (Pt_CB_REPEAT) that caused this callback to be invoked.

reason_subtype

0 (not used).

event

A pointer to the event that caused the callback to be invoked.

cbdata

NULL.

These callbacks should return Pt_CONTINUE.

Inherited resources:

If the widget modifies an inherited resource, the "Default override" column indicates the new value. This modification affects any subclasses of the widget.