PtToggleButton

A toggle switch that's either off or on

Class hierarchy:

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

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

PhAB icon:

Public header:

<photon/PtToggleButton.h>

Description:

A PtToggleButton widget is like a toggle switch, although it behaves like a button. It has on and off states, and pressing the button inverts the current state of the button.

Creating toggle buttons

Toggle buttons inherit resources from PtLabel and PtButton; specify the label for toggle buttons the way you do for these classes.

A toggle button is displayed as a button with a label beside it. The button is either set or unset, and you can control its appearance with the Pt_ARG_INDICATOR_COLOR and Pt_ARG_INDICATOR_TYPE resources. You can set the position of the text relative to the button with the Pt_ARG_BALLOON_POSITION resource.

You can also set Pt_ARG_ARM_COLOR, which specifies the fill color for the button's interior when the button is set. This resource is used only if the value of Pt_ARG_ARM_FILL is Pt_TRUE. These resources are inherited from PtButton.

To determine whether or not the button is set, check the:

• Pt_SET bit in the Pt_ARG_FLAGS resource -- see PtWidget
• Callback data passed to the Pt_CB_ACTIVATE callbacks -- see PtBasic.

Grouping toggle buttons

A group can control how several toggle buttons behave together. If you place the toggle buttons in a group and make them mutually exclusive, they behave like the channel-selector buttons on a car radio: only one of the buttons can be set at any given time, and setting any button automatically unsets the button that's currently set.

To make a group of toggle buttons mutually exclusive, set the Pt_GROUP_EXCLUSIVE bit in the group's Pt_ARG_GROUP_FLAGS resource. For example:

PtSetArg (&argt[n], Pt_ARG_GROUP_FLAGS, Pt_TRUE,
          Pt_GROUP_EXCLUSIVE );
n++;
PtSetArg (&argt[n], Pt_ARG_GROUP_ORIENTATION,
          Pt_GROUP_VERTICAL, 0 ) ;
n++;
group = PtCreateWidget (PtGroup, parent, n, argt );

PtSetArg (&argt[0], Pt_ARG_TEXT_STRING,
          "Button 1", 0 ) ;
button1 = PtCreateWidget (PtToggleButton, group,
                           1, argt ) ;

PtSetArg (&argt[0], Pt_ARG_TEXT_STRING,
          "Button 2", 0 ) ;
button2 = PtCreateWidget (PtToggleButton, group,
                          1, argt ) ;

PtSetArg (&argt[0], Pt_ARG_TEXT_STRING,
          "Button 3", 0 ) ;
button3 = PtCreateWidget (PtToggleButton, group,
                          1, argt ) ;

PtRealizeWidget ( group ) ;

You can use the same callback for all the buttons, but how do you determine which one is selected? There are several ways:

• Specify a Pt_CB_ACTIVATE callback (see PtBasic) for the group. The PtGroup adds its callback to each of its children; when the callback is invoked, the widget argument is a pointer to the selected button, not the group. You can compare the pointer to previously saved pointers to the buttons.

  Or:

• Store a unique value in each button's Pt_ARG_USER_DATA resource (see PtWidget). In the callback, get this resource and use its value to determine which button was pressed.

  Or:

• If you create the buttons in code (instead of in PhAB), you can pass a unique value in the client_data argument to the callback routine.

New resources:

Pt_ARG_INDICATOR_COLOR

The fill color for the toggle button's indicator. See PgColor_t in the Photon Library Reference.

Pt_ARG_INDICATOR_TYPE

Determines how the indicator is drawn. Possible values:

• Pt_TOGGLE_RADIO
• Pt_TOGGLE_CHECK
• Pt_TOGGLE_OUTLINE

Here's how these types look, both set and unset:

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.