---

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.

When you:	The widget becomes:	Callback invoked:
Press the left pointer button while pointing at the widget	Armed	Pt_CB_ARM
Release the left pointer button while pointing at an armed widget	Activated	Pt_CB_ACTIVATE
Release the left pointer button when the pointer is outside the widget	Disarmed	Pt_CB_DISARM

---

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:

Resource	C type	Pt type	Default
Pt_ARG_BANDWIDTH_THRESHOLD	unsigned long	Scalar	0
Pt_ARG_BOT_BORDER_COLOR	PgColor_t	Scalar	Pg_DGRAY
Pt_ARG_COLOR	PgColor_t	Scalar	Pg_BLACK
Pt_ARG_FILL_COLOR	PgColor_t	Scalar	Pg_GRAY
Pt_ARG_FILL_PATTERN	PgPattern_t	Struct	Pg_PAT_FULL
Pt_ARG_HIGHLIGHT_ROUNDNESS	unsigned short	Scalar	0
Pt_ARG_MARGIN_HEIGHT	unsigned short	Scalar	0
Pt_ARG_MARGIN_WIDTH	unsigned short	Scalar	0
Pt_ARG_TOP_BORDER_COLOR	PgColor_t	Scalar	Pg_WHITE
Pt_ARG_TRANS_PATTERN	PgPattern_t	Struct	Pg_PAT_NONE
Pt_CB_ACTIVATE	PtCallback_t *	Link	NULL
Pt_CB_ARM	PtCallback_t *	Link	NULL
Pt_CB_DISARM	PtCallback_t *	Link	NULL
Pt_CB_GOT_FOCUS	PtCallback_t *	Link	NULL
Pt_CB_LOST_FOCUS	PtCallback_t *	Link	NULL
Pt_CB_MENU	PtCallback_t *	Link	NULL
Pt_CB_REPEAT	PtCallback_t *	Link	NULL

Pt_ARG_BANDWIDTH_THRESHOLD

C type	Pt type	Default
unsigned long	Scalar	0

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

Pt_ARG_BOT_BORDER_COLOR

C type	Pt type	Default
PgColor_t	Scalar	Pg_DGRAY

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

Pt_ARG_COLOR

C type	Pt type	Default
PgColor_t	Scalar	Pg_BLACK

The widget's foreground or drawing color.

Pt_ARG_FILL_COLOR

C type	Pt type	Default
PgColor_t	Scalar	Pg_GRAY

The widget's background color.

Pt_ARG_FILL_PATTERN

C type	Pt type	Default
PgPattern_t	Struct	Pg_PAT_FULL

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

Pt_ARG_HIGHLIGHT_ROUNDNESS

C type	Pt type	Default
unsigned short	Scalar	0

The roundness of the widget's borders.

Pt_ARG_MARGIN_HEIGHT

C type	Pt type	Default
unsigned short	Scalar	0

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

C type	Pt type	Default
unsigned short	Scalar	0

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

C type	Pt type	Default
PgColor_t	Scalar	Pg_WHITE

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

Pt_ARG_TRANS_PATTERN

C type	Pt type	Default
PgPattern_t	Struct	Pg_PAT_NONE

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

Pt_CB_ACTIVATE

C type	Pt type	Default
PtCallback_t *	Link	NULL

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

C type	Pt type	Default
PtCallback_t *	Link	NULL

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

C type	Pt type	Default
PtCallback_t *	Link	NULL

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

C type	Pt type	Default
PtCallback_t *	Link	NULL

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

C type	Pt type	Default
PtCallback_t *	Link	NULL

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

C type	Pt type	Default
PtCallback_t *	Link	NULL

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

C type	Pt type	Default
PtCallback_t *	Link	NULL

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.

Resource	Inherited from	Default override
Pt_ARG_AREA	PtWidget
Pt_ARG_BITMAP_CURSOR	PtWidget
Pt_ARG_BORDER_WIDTH	PtWidget	0
Pt_ARG_CURSOR_COLOR	PtWidget
Pt_ARG_CURSOR_TYPE	PtWidget
Pt_ARG_DATA	PtWidget
Pt_ARG_DIM	PtWidget
Pt_ARG_EFLAGS	PtWidget
Pt_ARG_FLAGS	PtWidget
Pt_ARG_HELP_TOPIC	PtWidget
Pt_ARG_POS	PtWidget
Pt_ARG_RESIZE_FLAGS	PtWidget	Pt_RESIZE_XY_AS_REQUIRED
Pt_ARG_USER_DATA	PtWidget
Pt_CB_BLOCKED	PtWidget
Pt_CB_DESTROYED	PtWidget
Pt_CB_HOTKEY	PtWidget
Pt_CB_RAW	PtWidget
Pt_CB_REALIZED	PtWidget
Pt_CB_UNREALIZED	PtWidget

---