This version of this document is no longer maintained. For the latest documentation, see http://www.qnx.com/developers/docs.

PtButton

A button for initiating an action

Class hierarchy:

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

Immediate subclasses:

• PtOnOffButton
• PtToggleButton

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

PhAB icon:

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.

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:

Pt_ARG_ARM_COLOR

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

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

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.

---

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.