PtBasic

A superclass of basic resources for most widgets

Class hierarchy:

PtWidget → PtBasic

Immediate subclasses:

• PtBarGraph -->
• PtCalendar
• PtClock
• PtContainer
• PtGauge
• PtGraphic
• PtLabel
• PtRaw
• PtSeparator
• PtTrend

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
• bevel colors
• outline and inline colors
• draw color
• fill color
• fill pattern.

Selecting widgets

PtBasic defines some callback resources for actions involving the left pointer button. These callbacks are invoked only if the widget has Pt_SELECTABLE set in its Pt_ARG_FLAGS (see PtWidget).

---

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.

---

If you hold down the left pointer button, the widget's Pt_CB_REPEAT callbacks are invoked.

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. 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.

---

Borders and colors

PtBasic defines resources that give you full control over the widget's colors, shadings, and borders.

A widget's border is made up of various components, all of which are optional; set the bits in Pt_ARG_BASIC_FLAGS to indicate which components to display. These components, going from outside to inside, are:

• A one-pixel etch line
• A one-pixel outline, of the color specified by Pt_ARG_OUTLINE_COLOR
• A shaded bevel, the width of which is set by Pt_ARG_BEVEL_WIDTH (defined by PtWidget)
• A one-pixel inline, of the color specified by Pt_ARG_INLINE_COLOR

A widget displaying all the border components.

The color of the bevel is the same as the widget's fill color unless overridden by Pt_ARG_BEVEL_COLOR. The bevel is shaded according to Pt_ARG_BEVEL_CONTRAST, which is used to calculate the default values of Pt_ARG_DARK_BEVEL_COLOR and Pt_ARG_LIGHT_BEVEL_COLOR. You can override the contrast by setting the light and dark bevel colors explicitly. By default, the upper left corner of the bevel is a gradient that goes from the light bevel color to the light fill color. The lower right bevel goes from the dark fill color to the dark bevel color.

If you set Pt_STATIC_BEVEL_COLORS in Pt_ARG_BASIC_FLAGS, the bevel color doesn't change when you set Pt_ARG_FILL_COLOR.

You can display a full (i.e. half-round) bevel by setting Pt_FULL_BEVELS in Pt_ARG_BASIC_FLAGS:

A widget displaying a half-round bevel.

You can use Pt_ARG_FILL_COLOR to specify the widget's fill color. These bits in Pt_ARG_BASIC_FLAGS affect the fill:

Pt_FLAT_FILL

By default, the widget's fill is a flat color; to use a gradient for the fill, clear this bit.

Pt_REVERSE_GRADIENT

The default gradient goes from the light fill color at the top to the dark fill color at the bottom. To reverse the gradient, set this bit.

Pt_HORIZONTAL_GRADIENT

Make the gradient change color on the horizontal axis instead of the vertical axis.

You can specify the amount of contrast between the light and dark fill colors by setting Pt_ARG_CONTRAST. If this resource doesn't give you the look you want, you can override it by setting Pt_ARG_DARK_FILL_COLOR and Pt_ARG_LIGHT_FILL_COLOR explicitly.

Pt_ARG_COLOR specifies the foreground or drawing color.

---

Setting Pt_ARG_FILL_COLOR overrides any previous setting of Pt_ARG_DARK_FILL_COLOR, and Pt_ARG_LIGHT_FILL_COLOR. If Pt_STATIC_BEVEL_COLORS isn't set in Pt_ARG_BASIC_FLAGS, the new fill color also overrides Pt_ARG_BEVEL_COLOR, Pt_ARG_DARK_BEVEL_COLOR, and Pt_ARG_LIGHT_BEVEL_COLOR.

---

New resources:

Pt_ARG_BANDWIDTH_THRESHOLD

PtBasic defines this resource but ignores any attempts to set it. It is overridden and used by some of PtBasic's descendents. In general, it defines a threshold below which a widget optimizes drawing on a system with a slow connection.

Pt_ARG_BASIC_FLAGS

This flag resource controls which “edge decorations” are rendered for a widget when it's highlighted (see Pt_ARG_FLAGS, defined by PtWidget). It gives you individual control over the rendering of the top, bottom, left, and right edges of a widget. It also gives you control over the fill type (flat or gradient) and several behavior elements with regards to the rendering of a widget's border.

Valid Pt_ARG_BASIC_FLAGS bits (applied only if the widget is also highlighted) control:

• the appearance of the edges
• the fill
• the behavior when the widget's state changes.

Edge-control bits

Pt_TOP_ETCH
Pt_BOTTOM_ETCH
Pt_LEFT_ETCH
Pt_RIGHT_ETCH

Render a single alpha line on an edge of the widget. The top and left lines are dark, and the bottom and right lines are light. This can make a widget look like it's slightly inset.

Pt_BLANK_ETCHES

Don't draw the etched lines.

Pt_OPAQUE_ETCHES

Use a solid line, instead of an alpha line, for the etching. The color is calculated based on the widget's color and widget's parent color.

Pt_TOP_OUTLINE
Pt_BOTTOM_OUTLINE
Pt_LEFT_OUTLINE
Pt_RIGHT_OUTLINE

Render a single-pixel outline on an edge of the widget.

Pt_TOP_BEVEL
Pt_BOTTOM_BEVEL
Pt_LEFT_BEVEL
Pt_RIGHT_BEVEL

Render a bevel Pt_ARG_BEVEL_WIDTH pixels wide on an edge of the widget.

Pt_FULL_BEVELS

Render a full bevel (i.e. half-round) instead of a half bevel (quarter-round).

Pt_TOP_INLINE
Pt_BOTTOM_INLINE
Pt_LEFT_INLINE
Pt_RIGHT_INLINE

Render a single-pixel inline on an edge of the widget.

These convenience manifests make working with these bits easier:

Pt_TOP_LEFT_ETCH
Pt_BOTTOM_RIGHT_ETCH
Pt_ALL_ETCHED
Pt_ALL_ETCHES

Adjust the etching on the top/left, bottom/right, or all edges.

Pt_TOP_LEFT_OUTLINE
Pt_BOTTOM_RIGHT_OUTLINE
Pt_ALL_OUTLINES

Adjust the outline on the top/left, bottom/right, or all edges.

Pt_TOP_LEFT_BEVEL
Pt_BOTTOM_RIGHT_BEVEL
Pt_ALL_BEVELS

Adjust the bevel on the top/left, bottom/right, or all edges.

Pt_TOP_LEFT_INLINE
Pt_BOTTOM_RIGHT_INLINE
Pt_ALL_INLINES

Adjust the inline on the top/left, bottom/right, or all edges.

Pt_ALL_TOP
Pt_ALL_BOTTOM
Pt_ALL_LEFT
Pt_ALL_RIGHT
Pt_ALL

Adjust all edge decorations (etch, outline, bevel, and inline) on the top, left, bottom, right, or all edges.

Fill-control bits

Pt_FLAT_FILL

If set, the widget is filled with a solid color as given by Pt_ARG_FILL_COLOR. If clear, the widget is filled with a gradient.

Pt_HORIZONTAL_GRADIENT

If set, and Pt_FLAT_FILL is clear, the fill gradient changes colors on the horizontal axis. If clear and Pt_FLAT_FILL is clear, the fill gradient changes colors on the vertical axis.

Pt_REVERSE_GRADIENT

If set and Pt_FLAT_FILL is clear, the gradient rendered is reversed (i.e. begin with the dark fill color on the top or left when the widget isn't pressed).

Pt_STATIC_BEVEL_COLORS

If set, the bevel color doesn't change when you set Pt_ARG_FILL_COLOR.

Pt_BASIC_PREVENT_FILL

If set, the widget isn't filled. This is useful when you want to set the base color for borders and etches without actually rendering a fill.

Behavior on state change

These bits affect how the widget behaves when set (depressed) or unset (raised):

Pt_STATIC_GRADIENT

If set, the gradient doesn't reverse when the widget is set or unset.

Pt_STATIC_BEVELS

If set, the rendered bevels don't change when the widget is set or unset.

Pt_ARG_BEVEL_COLOR

The main color of the bevel. See PgColor_t in the Photon Library Reference.

---

This value is automatically generated when you set Pt_ARG_FILL_COLOR. Setting Pt_ARG_FILL_COLOR overrides any values set previously via this resource.

---

Pt_ARG_BEVEL_CONTRAST

This value determines how much the dark and light bevel colors differ from the base bevel color (Pt_ARG_BEVEL_COLOR). The higher the value, the greater the difference:

0

No change.

255

Maximum contrast.

The effect of this resource is visible only if the widget has bevels displayed (see Pt_ARG_BASIC_FLAGS).

Pt_ARG_COLOR

The widget's foreground or drawing color. See PgColor_t in the Photon Library Reference.

Pt_ARG_CONTRAST

This value determines how much the dark and light fill colors differ from the base fill color (Pt_ARG_FILL_COLOR). The higher the value, the greater the difference:

0

No change.

255

Maximum contrast.

---

The effect of this resource is visible only if the widget is filled with a gradient (see Pt_ARG_BASIC_FLAGS).

---

Pt_ARG_DARK_BEVEL_COLOR

This resource, with Pt_ARG_LIGHT_BEVEL_COLOR, specifies the outermost colors used when applying a bevel to a widget. See Pt_ARG_BASIC_FLAGS to find out when gradients and borders are rendered for a given widget.

---

These values are automatically generated when you set Pt_ARG_FILL_COLOR. Setting Pt_ARG_FILL_COLOR overrides any values set previously via these resources.

---

Pt_ARG_DARK_FILL_COLOR

This resource, with Pt_ARG_LIGHT_FILL_COLOR, specifies the colors with which a gradient (if applied) starts and ends. These values are also used as the inner color for the bevels (i.e. the bottom bevel normally goes through a transition from Pt_ARG_DARK_BEVEL_COLOR to Pt_ARG_DARK_FILL_COLOR when a bevel is applied to the widget). See Pt_ARG_BASIC_FLAGS to find out when gradients and bevels are rendered for a given widget.

---

These values are automatically generated when you set Pt_ARG_FILL_COLOR. Setting Pt_ARG_FILL_COLOR overrides any values set previously via these resources.

---

Pt_ARG_FILL_COLOR

The base fill color for the widget. See PgColor_t in the Photon Library Reference.

This color is used as the base color when generating the Pt_ARG_BEVEL_COLOR, Pt_ARG_LIGHT_BEVEL_COLOR, Pt_ARG_DARK_BEVEL_COLOR, Pt_ARG_LIGHT_FILL_COLOR, and Pt_ARG_DARK_FILL_COLOR.

---

Setting this resource effectively overrides all values previously set for the LIGHT and DARK resources. This is like setting the chroma for a widget.

---

If the widget uses a flat fill, that fill is Pt_ARG_FILL_COLOR. If the widget uses a gradient fill, the gradient runs from Pt_ARG_LIGHT_FILL_COLOR to Pt_ARG_DARK_FILL_COLOR. If the widget uses a bevel, it's rendered with color ranges as defined by Pt_ARG_LIGHT_BEVEL_COLOR to Pt_ARG_LIGHT_FILL_COLOR and Pt_ARG_DARK_BEVEL_COLOR to Pt_ARG_DARK_FILL_COLOR.

---

See Pt_ARG_BASIC_FLAGS to find out when gradients and borders are rendered for a given widget.

---

Pt_ARG_FILL_PATTERN

The widget's background pattern. You can't edit this resource in PhAB.

Pt_ARG_HIGHLIGHT_ROUNDNESS

The radius, in pixels, of the widget's borders. The default value of 0 results in square corners. If Pt_ARG_HIGHLIGHT_ROUNDNESS is > 0, gradient fill is bypassed.

---

If you set this resource to a nonzero value, the widget library has to work with a nonrectangular widget. It might take longer to draw the widget, and you might notice some flickering. You can reduce the flickering by placing the widget inside a PtOSContainer.

---

Pt_ARG_INLINE_COLOR

The color of the inline of the border. See PgColor_t in the Photon Library Reference.

The inline is drawn if any of Pt_TOP_INLINE, Pt_BOTTOM_INLINE, Pt_LEFT_INLINE, and Pt_RIGHT_INLINE are set in Pt_ARG_BASIC_FLAGS.

Pt_ARG_LIGHT_BEVEL_COLOR

This resource, with Pt_ARG_DARK_BEVEL_COLOR, specifies the outermost colors used when applying a bevel to a widget. See Pt_ARG_BASIC_FLAGS to find out when gradients and borders are rendered for a given widget.

---

These values are automatically generated when you set Pt_ARG_FILL_COLOR. Setting Pt_ARG_FILL_COLOR overrides any values set previously via these resources.

---

Pt_ARG_LIGHT_FILL_COLOR

This resource, with Pt_ARG_DARK_FILL_COLOR, specifies the colors with which a gradient (if applied) starts and ends. These values are also used as the inner color for the bevels (i.e. the bottom bevel normally goes through a transition from Pt_ARG_DARK_BEVEL_COLOR to Pt_ARG_DARK_FILL_COLOR when a bevel is applied to the widget). See Pt_ARG_BASIC_FLAGS to find out when gradients and borders are rendered for a given widget.

---

These values are automatically generated when you set Pt_ARG_FILL_COLOR. Setting Pt_ARG_FILL_COLOR overrides any values set previously via these resources.

---

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_OUTLINE_COLOR

The color of the outline of the border. See PgColor_t in the Photon Library Reference.

The outline is drawn if any of Pt_TOP_OUTLINE, Pt_BOTTOM_OUTLINE, Pt_LEFT_OUTLINE, and Pt_RIGHT_OUTLINE are set in Pt_ARG_BASIC_FLAGS.

Pt_ARG_STYLE

The style to use for this widget instance. This resource is a complex one, so it requires special handling, as described below.

A style is a collection of override methods that can change how a widget looks and behaves. Styles can also add widget resources. For more information, see “Widget Styles” in the Managing Widgets in Application Code chapter of the Photon Programmer's Guide.

When setting this resource, the value is a character string that's the name of the style. For example:

PtSetResource( widget, Pt_ARG_STYLE, "MyStyle", 0);

Setting this resource has the same effect as calling PtSetWidgetStyle(). For more information, see the Photon Library Reference.

When you get the value of this resource, you get a pointer to a PtWidgetClassStyle_t structure. For example:

PtWidgetClassStyle_t *style = NULL;
…
PtGetResource( widget, Pt_ARG_STYLE, &style, 0);

---

Don't access the members of the PtWidgetClassStyle_t structure directly; call PtGetStyleMember() instead.

---

Pt_ARG_TRANS_PATTERN

The widget's transparency pattern. You'll find this handy for “ghosting” widgets. You can't edit this resource in PhAB.

Pt_CB_ACTIVATE

A list of PtCallback_t structures that define the 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 special versions of Pt_CB_ACTIVATE.

---

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

reason

Pt_CB_ACTIVATE

reason_subtype

Pt_CB_HOTKEY if the callbacks were invoked because a hotkey was pressed; otherwise 0.

event

A pointer to a PhEvent_t structure that describes the event that caused the callback to be invoked, or NULL if there isn't an event.

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 PtCallback_t structures that define the callbacks that the widget calls when it becomes armed. To arm a widget, you typically press the left pointer button while pointing at 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

Pt_CB_ARM

reason_subtype

0 (not used).

event

A pointer to a PhEvent_t structure that describes the event that caused the callback to be invoked, or NULL if there isn't an event.

cbdata

NULL.

These callbacks should return Pt_CONTINUE.

Pt_CB_DISARM

A list of PtCallback_t structures that define the 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

Pt_CB_DISARM

reason_subtype

0 (not used).

event

A pointer to a PhEvent_t structure that describes the event that caused the callback to be invoked, or NULL if there isn't an event.

cbdata

NULL.

These callbacks should return Pt_CONTINUE.

Pt_CB_GOT_FOCUS

A list of PtCallback_t structures that define the callbacks invoked when a widget gets 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). You can call PtIsFocused() 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

Pt_CB_GOT_FOCUS

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, or a pointer to a PtFocusInfo_t. PtFocusInfo_t contains at least:

PtWidget_t *src

A pointer to the widget which is losing focus. This pointer could be NULL.

PtWidget_t *dst

A pointer to the widget which is intended to get the focus. This pointer could be NULL, for example if PtContainerNullFocus() was invoked.

These callbacks should return Pt_CONTINUE.

---

Returning Pt_END doesn't make your widget refuse focus; if the widget doesn't want focus, it has to give focus to another widget by calling one of the focus functions described in the Photon Library Reference.

---

Pt_CB_LOST_FOCUS

A list of PtCallback_t structures that define the callbacks that the widget calls when it loses focus.

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

reason

Pt_CB_LOST_FOCUS

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, or a pointer to a PtFocusInfo_t. PtFocusInfo_t contains at least:

PtWidget_t *src

A pointer to the widget which is losing focus. This pointer could be NULL.

PtWidget_t *dst

A pointer to the widget which is intended to get the focus. This pointer could be NULL, for example if PtContainerNullFocus() was invoked.

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 PtCallback_t structures that define the callbacks that the widget calls when you press the right 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

Pt_CB_MENU

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 Pt_CONTINUE.

Pt_CB_REPEAT

A list of PtCallback_t structures that define the 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

Pt_CB_REPEAT

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 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.