[Previous] [Contents] [Index] [Next]

PtButton

A button for initiating an action

Class hierarchy:

PtWidget --> PtBasic --> PtLabel --> PtButton

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 the application. Clicking the 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, the shading is reversed to make it appear as though the button is recessed. 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 use the PtButton widget class to create pushbutton widgets. You specify a label for the pushbutton 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 is shaded so that the button appears recessed. 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. It you wish to change only the color, the Pt_ARG_ARM_COLOR can be set when the image is a bitmap with backfill turned on. The arm color will be 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_DATA 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 gets armed.

New resources:

Resource C type Pt type Default
Pt_ARG_ARM_COLOR PgColor_t Scalar PgGray(170)
Pt_ARG_ARM_DATA void * Alloc NULL
Pt_ARG_ARM_FILL unsigned char Scalar Pt_TRUE

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

Pt_ARG_ARM_DATA

C type Pt type Default
void * Alloc NULL

Contains a pointer. If the label type (Pt_ARG_LABEL_TYPE - see PtLabel) is Pt_Z_STRING, this resource points to a text string. If the label type is Pt_IMAGE, this resource points to a PhImage_t structure. For more information, see PtLabel.

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: Remember that this is an Alloc resource. 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.

Pt_ARG_ARM_FILL

C type Pt type Default
unsigned char Scalar Pt_TRUE

Determines whether or not Pt_ARG_ARM_COLOR will be used. Possible values:

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

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_AREA PtWidget
Pt_ARG_BALLOON_COLOR PtLabel
Pt_ARG_BALLOON_FILL_COLOR PtLabel
Pt_ARG_BALLOON_POSITION PtLabel
Pt_ARG_BANDWIDTH_THRESHOLD PtBasic Not used by this class.
Pt_ARG_BITMAP_CURSOR PtWidget
Pt_ARG_BORDER_WIDTH PtWidget 0
Pt_ARG_BOT_BORDER_COLOR PtBasic
Pt_ARG_COLOR PtBasic
Pt_ARG_CURSOR_COLOR PtWidget
Pt_ARG_CURSOR_TYPE PtWidget
Pt_ARG_DATA PtWidget
Pt_ARG_DIM PtWidget
Pt_ARG_EFLAGS PtWidget
Pt_ARG_FILL_COLOR PtBasic Pg_GRAY
Pt_ARG_FILL_PATTERN PtBasic
Pt_ARG_FLAGS PtWidget |=Pt_SELECTABLE|
Pt_HIGHLIGHTED
Pt_ARG_HELP_TOPIC PtWidget
Pt_ARG_HIGHLIGHT_ROUNDNESS PtBasic
Pt_ARG_HORIZONTAL_ALIGNMENT PtLabel Pt_CENTER
Pt_ARG_LABEL_BALLOON PtLabel
Pt_ARG_LABEL_DATA PtLabel
Pt_ARG_LABEL_FLAGS PtLabel
Pt_ARG_LABEL_TYPE PtLabel
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_POS PtWidget
Pt_ARG_RESIZE_FLAGS PtWidget Pt_RESIZE_XY_AS_REQUIRED
Pt_ARG_TEXT_FONT PtLabel
Pt_ARG_TEXT_STRING PtLabel
Pt_ARG_TOP_BORDER_COLOR PtBasic
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_CB_ACTIVATE PtBasic
Pt_CB_ARM PtBasic
Pt_CB_BLOCKED PtWidget
Pt_CB_DESTROYED PtWidget
Pt_CB_DISARM PtBasic
Pt_CB_GOT_FOCUS PtBasic
Pt_CB_HOTKEY PtWidget
Pt_CB_LOST_FOCUS PtBasic
Pt_CB_MENU PtBasic
Pt_CB_RAW PtWidget
Pt_CB_REALIZED PtWidget
Pt_CB_REPEAT PtBasic
Pt_CB_UNREALIZED PtWidget

[Previous] [Contents] [Index] [Next]