NAME
Toggle widget − button that maintains a Boolean state.
SYNOPSIS
Public Headers:<X11/StringDefs.h> <X11/Xaw/Toggle.h>
Private Header:<X11/Xaw/ToggleP.h>
Class Name:Toggle
Class Pointer:toggleWidgetClass
Instantiation:widget = XtCreateWidget(name, toggleWidgetClass, ...)
CLASS HIERARCHY
Core → Simple → Label → Command → Toggle
DESCRIPTION
The Toggle widget is an area, often rectangular, containing a text or pixmap label. This widget maintains a Boolean state (e.g., True/False or On/Off) and changes state whenever it is selected. When the pointer is on the button, the button border is highlighted to indicate that the button is ready for selection. When pointer button 1 is pressed and released, the Toggle widget indicates that it has changed state by reversing its foreground and background colors, and its notify action is invoked, calling all functions on its callback list. If the pointer is moved out of the widget before the button is released, the widget reverts to its normal foreground and background colors, and releasing the button has no effect. This behavior allows the user to cancel an action.
Toggle buttons may also be part of a radio group. A radio group is a list of Toggle buttons in which no more than one Toggle may be set at any time. A radio group is identified by the widget ID of any one of its members. The convenience routine XawToggleGetCurrent() returns information about the currently set Toggle button in the radio group.
RESOURCES
When creating a Toggle widget instance, the following resources are retrieved from the argument list or from the resource database:
| Name (XtN...) | Type | Default | Description | |||
| XtNaccelerators | Accelerator- Table |
NULL | List of event-to-action bindings to be executed by this widget, even though the event occurred in another widget. | |||
| XtNancestor− Sensitive |
Boolean | True | (D) Sensitivity state of the ancestors of this widget. A widget is insensitive if either it or any of its ancestors is insensitive. | |||
| XtNbackground | Pixel | XtDefault− Background |
Window background color. | |||
| XtNbackground− Pixmap |
Pixmap | XtUnspecified− Pixmap |
Window background pixmap. | |||
| XtNbitmap | Pixmap | None | Pixmap to display in place of the label. | |||
| XtNborderColor | Pixel | XtDefault− Foreground |
Window border color. | |||
| XtNborderPixmap | Pixmap | XtUnspecified− Pixmap |
Window border pixmap. | |||
| XtNborderWidth | Dimension | 1 | Width of button border. | |||
| XtNcallback | XtCallback- List |
NULL | Callback for button select. | |||
| XtNcolormap | Colormap | Parent’s colormap. | Colormap that this widget will use. | |||
| XtNcornerRound− Percent |
Dimension | 25 | See below. | |||
| XtNcursor | Cursor | None | Pointer cursor. | |||
| XtNdepth | int | Parent’s depth. | (C) Depth of this widget’s window. | |||
| XtNdestroy− Callback |
XtCallbackList | NULL | Callbacks for XtDestroyWidget(). | |||
| XtNencoding | unsigned char | XawTextEncoding- 8bit |
For I18N. | |||
| XtNfont | XFontStruct∗ | XtDefaultFont | Label font. | |||
| XtNforeground | Pixel | XtDefault− Foreground |
Foreground color. | |||
| XtNheight | Dimension | font height + 2 ∗ XtNinternalHeight |
(A) Button height. | |||
| XtNhighlight− Thickness |
Dimension | 2 (0 if shaped) | (A) Width of border to be highlighted. | |||
| XtNinsensitive− Border |
Pixmap | Gray pixmap. | Border when not sensitive. | |||
| XtNinternal− Height |
Dimension | 2 | Internal border height for highlighting. | |||
| XtNinternalWidth | Dimension | 4 | Internal border width for highlighting. | |||
| XtNjustify | XtJustify | XtJustifyCenter | Type of text alignment. | |||
| XtNlabel | String | Name of widget. | Button label. | |||
| (R5) XtNleft- Bitmap |
Bitmap | None | Pixmap before label. | |||
| XtNmappedWhen− Managed |
Boolean | TRUE | Whether XtMapWidget() is automatic. | |||
| XtNradioData | Pointer | Name of widget. | See below. | |||
| XtNradioGroup | Widget | No radio group. | See below. | |||
| XtNresize | Boolean | TRUE | Whether to auto-resize in SetValues. | |||
| XtNscreen | Screen | Parent’s screen. | (R) Screen on which this widget is displayed. | |||
| XtNsensitive | Boolean | TRUE | Whether widget receives input. | |||
| XtNshapeStyle | ShapeStyle | Rectangle | Type of nonrectangular button. | |||
| XtNstate | Boolean | Off | See below. | |||
| XtNtranslations | Translation− Table |
See below. | Event-to-action translations. | |||
| XtNwidth | Dimension | XtNlabelwidth+2∗ XtNinternalWidth |
(A) Button width. | |||
| XtNx | Position | 0 | x-coordinate in pixels. | |||
| XtNy | Position | 0 | y-coordinate in pixels. | |||
Note that:
1.The Toggle widget supports two callback lists: XtNdestroyCallback and
XtNcallback. The notify action executes the callbacks on the XtNcallback list. The call_data argument is unused.
2.When a bitmap of depth greater that 1 is specified, the set, unset, and reset actions have no effect, since no foreground and background colors are used in a multi-plane pixmap.
The new resources (not inherited from superclasses) associated with the Toggle widget are:
XtNradioData
Specifies the data that is returned by XawToggleGetCurrent() when this is the currently set widget in the radio group. This value is also used to identify the Toggle that is set by a call to XawToggleSetCurrent(). XawToggleGetCurrent() returns NULL if no widget in a radio group is currently set. Programmers must not specify NULL (or 0) as XtNradioData.
XtNradioGroup
Specifies another Toggle widget that is in the radio group to which this Toggle widget should be added. A radio group is a group of Toggle widgets, only one of which may be set at a time. If this value is NULL (the default), then the Toggle is not part of any radio group and can change state without affecting any other Toggle widgets. If the widget specified in this resource is not already in a radio group, then a new radio group is created containing these two Toggle widgets. No Toggle widget can be in multiple radio groups. The behavior of a radio group of one toggle is undefined. A converter is registered which will convert widget names to widgets without caching.
XtNstate
Specifies whether the Toggle widget is set (True) or unset (False).
TRANSLATIONS AND ACTIONS
The following default translation bindings are used by the Toggle widget: <EnterWindow>: highlight(Always) <LeaveWindow>: unhighlight() <Btn1Down>,<Btn1Up>: toggle() notify() The Toggle widget supports the following actions:
•Switching the button between the foreground and background colors with set, unset and toggle.
•Processing application callbacks with notify.
•Switching the internal border between highlighted and unhighlighted states with highlight and unhighlight.
The actions supported by Toggle are listed below:
highlight(condition)
Displays the internal highlight border in the color (XtNforeground or XtNbackground) that contrasts with the interior color of the Toggle widget. The conditions WhenUnset and Always are understood by this action procedure. If no argument is passed, WhenUnset is assumed.
unhighlight()
Displays the internal highlight border in the color (XtNforeground or XtNbackground) that matches the interior color of the Toggle widget.
set()
Enters the set state, in which notify is possible, and displays the interior of the button in the foreground color. The label or pixmap is displayed in the background color.
unset()
Cancels the set state and displays the interior of the button, including the highlight border, in the background color. The label or pixmap is displayed in the foreground color.
toggle()
Changes the current state of the Toggle widget, setting the widget if it was previously unset, and unsetting it if it was previously set. If the widget is to be set and is in a radio group, then this action procedure may unset another Toggle widget, causing all routines on its callback list to be invoked. The callback routines for the Toggle to be unset are called before those for the Toggle to be set.
reset()
Cancels any set or highlight action and displays the interior of the button in the background color, with the label displayed in the foreground color.
notify()
When the button is set, this action calls all functions in the callback list named by the XtNcallback resource. The value of the call_data argument in these callback functions is undefined.
RADIO GROUPS
Two types of radio groups are typically desired by applications. In the first type, the default translations for the Toggle widget implement a "zero, or one of many" radio group. This means that no more than one button can be active, but no buttons need to be active.
The other type of radio group is "one of many" and has the more restricted policy that exactly one radio button will always be active. Toggle widgets can be used to provide this interface by modifying the translation table of each Toggle in the group: <EnterWindow>: highlight(Always) <LeaveWindow>: unhighlight() <Btn1Down>,<Btn1Up>: set() notify() This translation table does not allow any Toggle to be unset unless another Toggle has been set. The application programmer must choose an initial state for the radio group by setting the XtNstate resource of one of its member widgets to True.
PUBLIC FUNCTIONS
The following functions allow easy access to the Toggle widget’s radio group functionality.
•To allow an application to either change the Toggle’s radio group, add the Toggle to a radio group, or remove the Toggle from a radio group, use XawToggleChangeRadioGroup(). void XawToggleChangeRadioGroup(w, radio_group)
Widget w, radio_group; where:
wSpecifies the widget ID.
radio_groupSpecifies the widget ID of Toggle in the new radio group. If NULL, then the Toggle is removed from any radio group of which it is a member.
If a Toggle is already set in the new radio group, and if the Toggle to be added is also set, then the previously set Toggle in the radio group is unset and its callback procedures are invoked.
•To find the currently selected Toggle in a radio group of Toggle widgets, use XawToggleGetCurrent(): XtPointer XawToggleGetCurrent(radio_group);
Widget radio_group; where radio_group specifies the widget ID of any Toggle widget in the radio group.
The value returned by this function is the radioData of the Toggle in this radio group that is currently set. The default value for radioData is the name of that Toggle widget. If no Toggle is set in the radio group specified, then NULL is returned.
•To change the Toggle that is currently set in a radio group, use XawToggleSetCurrent(): void XawToggleSetCurrent(radio_group, radio_data);
Widget radio_group;
XtPointer radio_data; where:
radio_groupSpecifies any Toggle widget in the radio group.
radio_dataSpecifies the radioData identifying the Toggle that should be set in the radio group specified by the radio_group argument.
XawToggleSetCurrent() locates the Toggle widget to be set by matching radio_data against the radioData for each Toggle in the radio group. If none match, XawToggleSetCurrent() returns without making any changes. If more than one Toggle matches, XawToggleSetCurrent() arbitrarily chooses a Toggle to set. If this changes the state of any Toggle widgets, all routines in their callback lists will be invoked. The callback routines for a Toggle to be unset are called before those for the Toggle to be set.
•To unset all Toggle widgets in a radio group, use XawToggleUnsetCurrent(): void XawToggleUnsetCurrent(radio_group);
Widget radio_group; where radio_group specifies any Toggle widget in the radio group.
If this changes the state of a Toggle widget, all routines on its callback list will be invoked.
SEE ALSO
Command, Label, MenuButton.