PtButton

A button for initiating an action

Class hierarchy:

PtWidgetPtBasicPtLabelPtButton

Immediate subclasses:

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

PhAB icon:

PtButton button in PhAB

Public header:

<photon/PtButton.h>

Description:

The PtButton class draws a button. Buttons let you initiate an action within your application; clicking a button invokes an application callback.


PtButton


A PtButton widget.

Creating pushbuttons

A pushbutton is like a button you might find on a calculator or a control panel. The label is displayed within the button. The widget itself is shaded to appear like a raised button. When you click on the button, it becomes “pressed in.”

The label inside the button is usually a text string and/or icon representing the action that's performed when the button is pressed. You specify a label for the button in the same way as for PtLabel widgets.

Pushbutton behavior

A pushbutton is usually associated with a command to be performed — when you click on the pushbutton, the command is executed. For more information, see PtBasic.

Visual feedback

A visual cue is displayed when a pushbutton is armed. Usually the pushbutton appears to be pressed in. The original appearance is restored once the pushbutton has been disarmed or activated.

You can also configure a pushbutton so that the background of the widget is filled with a different color to provide more noticeable feedback when the button is armed. Use the Pt_ARG_ARM_COLOR resource to set the fill color for armed pushbuttons. This resource is ignored if the Pt_ARG_ARM_FILL resource hasn't been set to Pt_TRUE.

When the pushbutton is displaying an image, you may want the image to change when the pushbutton is armed. This is useful if you want to change the color of the icon displayed or change the actual image, such as changing a mail box icon from one with the flag up to one with the flag down. If you wish to change only the color, you can use Pt_ARG_ARM_COLOR if the image is a bitmap with backfill turned on. The arm color is used in place of the widget's fill color.

To display a different image entirely when the button is armed, use the Pt_ARG_ARM_IMAGE resource. When the Pt_ARG_LABEL_TYPE resource (see PtLabel) is set to an image type, this resource is consulted to see if an alternate image is available for displaying when the pushbutton is armed. If the data points to an image, that image is displayed when the button is armed.

New resources:

Resource C type Pt type Default
Pt_ARG_ARM_COLOR PgColor_t Scalar PgGray(170)
Pt_ARG_ARM_FILL unsigned char Scalar Pt_FALSE
Pt_ARG_ARM_IMAGE PhImage_t * Image NULL

Pt_ARG_ARM_COLOR

C type Pt type Default
PgColor_t Scalar PgGray(170)

The background color used when the button is armed (pressed in). See PgColor_t in the Photon Library Reference.

This resource is used only if Pt_ARG_ARM_FILL is set to Pt_TRUE.

Pt_ARG_ARM_FILL

C type Pt type Default
unsigned char Scalar Pt_FALSE

Determines whether or not to use Pt_ARG_ARM_COLOR as the background color used when the button is armed (pressed in). Possible values:

Pt_TRUE
Use the value of Pt_ARG_ARM_COLOR.
Pt_FALSE
Ignore the value of Pt_ARG_ARM_COLOR.

Pt_ARG_ARM_IMAGE

C type Pt type Default
PhImage_t * Image NULL

A pointer to a PhImage_t structure (see the Photon Library Reference) that defines the image to use when the button is armed. It's used only if the label type (Pt_ARG_LABEL_TYPE — see PtLabel) is Pt_IMAGE or Pt_TEXT_IMAGE.

Set the flags member of the PhImage_t structure to:

Ph_RELEASE_IMAGE | Ph_RELEASE_PALETTE |
Ph_RELEASE_TRANSPARENCY_MASK | Ph_RELEASE_GHOST_BITMAP
      

before providing the image to the widget. If you do this, the memory used for the image is released when the widget is unrealized or destroyed.


Note: When you set this resource, the widget copies the PhImage_t structure but not the data pointed to by the members of the structure. After setting this resource, you can free() the PhImage_t if you don't need it, but don't free() the members of it.

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_ACCEL_KEY PtLabel
Pt_ARG_ANCHOR_FLAGS PtWidget
Pt_ARG_ANCHOR_OFFSETS PtWidget
Pt_ARG_AREA PtWidget
Pt_ARG_BALLOON_COLOR PtLabel
Pt_ARG_BALLOON_FILL_COLOR PtLabel
Pt_ARG_BALLOON_POSITION PtLabel
Pt_ARG_BALLOON_TEXT PtLabel
Pt_ARG_BANDWIDTH_THRESHOLD PtBasic Not used by this class.
Pt_ARG_BASIC_FLAGS PtBasic Pt_ALL_ETCHES | Pt_ALL_BEVELS | Pt_ALL_OUTLINES | Pt_STATIC_GRADIENT
Pt_ARG_BEVEL_WIDTH PtWidget 1
Pt_ARG_BITMAP_CURSOR PtWidget
Pt_ARG_BEVEL_COLOR PtBasic
Pt_ARG_BEVEL_CONTRAST PtBasic
Pt_ARG_COLOR PtBasic
Pt_ARG_CONTRAST PtBasic
Pt_ARG_CURSOR_COLOR PtWidget
Pt_ARG_CURSOR_TYPE PtWidget
Pt_ARG_DARK_BEVEL_COLOR PtBasic
Pt_ARG_DARK_FILL_COLOR PtBasic
Pt_ARG_DATA PtWidget
Pt_ARG_DIM PtWidget
Pt_ARG_EFLAGS PtWidget
Pt_ARG_EXTENT PtWidget
Pt_ARG_FILL_COLOR PtBasic Pg_LGREY
Pt_ARG_FILL_PATTERN PtBasic
Pt_ARG_FLAGS PtWidget |=Pt_SELECTABLE|
Pt_HIGHLIGHTED
Pt_ARG_GRID_LAYOUT_DATA PtWidget
Pt_ARG_HEIGHT PtWidget
Pt_ARG_HELP_TOPIC PtWidget
Pt_ARG_HIGHLIGHT_ROUNDNESS PtBasic
Pt_ARG_HORIZONTAL_ALIGNMENT PtLabel Pt_CENTER
Pt_ARG_INLINE_COLOR PtBasic
Pt_ARG_LABEL_BALLOON PtLabel
Pt_ARG_LABEL_FLAGS PtLabel
Pt_ARG_LABEL_IMAGE PtLabel
Pt_ARG_LABEL_TYPE PtLabel
Pt_ARG_LAYOUT_DATA PtWidget
Pt_ARG_LIGHT_BEVEL_COLOR PtBasic
Pt_ARG_LIGHT_FILL_COLOR PtBasic
Pt_ARG_LINE_SPACING PtLabel
Pt_ARG_MARGIN_BOTTOM PtLabel
Pt_ARG_MARGIN_HEIGHT PtBasic
Pt_ARG_MARGIN_LEFT PtLabel
Pt_ARG_MARGIN_RIGHT PtLabel
Pt_ARG_MARGIN_TOP PtLabel
Pt_ARG_MARGIN_WIDTH PtBasic
Pt_ARG_MAXIMUM_DIM PtWidget
Pt_ARG_MINIMUM_DIM PtWidget
Pt_ARG_OUTLINE_COLOR PtBasic
Pt_ARG_POINTER PtWidget
Pt_ARG_POS PtWidget
Pt_ARG_RESIZE_FLAGS PtWidget Pt_RESIZE_XY_AS_REQUIRED
Pt_ARG_ROW_LAYOUT_DATA PtWidget
Pt_ARG_SECONDARY_H_ALIGN PtLabel
Pt_ARG_SECONDARY_V_ALIGN PtLabel
Pt_ARG_STYLE PtBasic
Pt_ARG_TEXT_FONT PtLabel
Pt_ARG_TEXT_IMAGE_SPACING PtLabel
Pt_ARG_TEXT_STRING PtLabel
Pt_ARG_TRANS_PATTERN PtBasic
Pt_ARG_UNDERLINE_TYPE PtLabel
Pt_ARG_UNDERLINE1 PtLabel
Pt_ARG_UNDERLINE2 PtLabel
Pt_ARG_USER_DATA PtWidget
Pt_ARG_VERTICAL_ALIGNMENT PtLabel Pt_CENTER
Pt_ARG_WIDTH PtWidget
Pt_CB_ACTIVATE PtBasic
Pt_CB_ARM PtBasic
Pt_CB_BLOCKED PtWidget
Pt_CB_DESTROYED PtWidget
Pt_CB_DISARM PtBasic
Pt_CB_DND PtWidget
Pt_CB_FILTER PtWidget
Pt_CB_GOT_FOCUS PtBasic
Pt_CB_HOTKEY PtWidget
Pt_CB_IS_DESTROYED PtWidget
Pt_CB_LOST_FOCUS PtBasic
Pt_CB_MENU PtBasic
Pt_CB_OUTBOUND PtWidget
Pt_CB_RAW PtWidget
Pt_CB_REALIZED PtWidget
Pt_CB_REPEAT PtBasic
Pt_CB_UNREALIZED PtWidget