XmToggleButtonGadget(3X) UNIX System V XmToggleButtonGadget(3X)
NAME
XmToggleButtonGadget - the ToggleButtonGadget widget class.
SYNOPSIS
#include <Xm/ToggleBG.h>
DESCRIPTION
ToggleButtonGadget sets nontransitory state data within an application.
Usually this gadget consists of an indicator (square or diamond-shaped)
with either text or a pixmap on one side of it. However, it can also
consist of just text or a pixmap without the indicator.
The toggle graphics display a 1-of-many or N-of-many selection state.
When a toggle indicator is displayed, a square indicator shows an N-of-
many selection state and a diamond-shaped indicator shows a 1-of-many
selection state.
ToggleButtonGadget implies a selected or unselected state. In the case
of a label and an indicator, an empty indicator (square or diamond-
shaped) indicates that ToggleButtonGadget is unselected, and a filled
indicator shows that it is selected. In the case of a pixmap toggle,
different pixmaps are used to display the selected/unselected states.
The default behavior associated with a ToggleButtonGadget in a menu
depends on the type of menu system in which it resides. By default,
BSelect controls the behavior of the ToggleButtonGadget. In addition,
BMenu controls the behavior of the ToggleButtonGadget if it resides in a
PopupMenu system. The actual mouse button used is determined by its
RowColumn parent.
To accommodate the toggle indicator when created, Label's resource
XmNmarginLeft may be increased.
Classes
ToggleButtonGadget inherits behavior and resources from Object, RectObj,
XmGadget and XmLabelGadget classes.
The class pointer is xmToggleButtonGadgetClass.
The class name is XmToggleButtonGadget.
New Resources
The following table defines a set of widget resources used by the
programmer to specify data. The programmer can also set the resource
values for the inherited classes to set attributes for this widget. To
reference a resource by name or by class in a .Xdefaults file, remove the
XmN or XmC prefix and use the remaining letters. To specify one of the
defined values for a resource in a .Xdefaults file, remove the Xm prefix
10/89 Page 1
XmToggleButtonGadget(3X) UNIX System V XmToggleButtonGadget(3X)
and use the remaining letters (in either lowercase or uppercase, but
include any underscores between words). The codes in the access column
indicate if the given resource can be set at creation time (C), set by
using XtSetValues (S), retrieved by using XtGetValues (G), or is not
applicable (N/A).
__________________________________________________________________________________________________________
| XmToggleButtonGadget Resource Set |
|__________________________|____________________________|________________|______________________|________|
|Name | Class | Type | Default | Access|
|__________________________|____________________________|________________|______________________|________|
|__________________________|____________________________|________________|______________________|________|
|XmNarmCallback | XmCArmCallback | XtCallbackList| NULL | C |
|__________________________|____________________________|________________|______________________|________|
|XmNdisarmCallback | XmCDisarmCallback | XtCallbackList| NULL | C |
|__________________________|____________________________|________________|______________________|________|
|XmNfillOnSelect | XmCFillOnSelect | Boolean | True | CSG |
|__________________________|____________________________|________________|______________________|________|
|XmNindicatorOn | XmCIndicatorOn | Boolean | True | CSG |
|__________________________|____________________________|________________|______________________|________|
|XmNindicatorSize | XmCIndicatorSize | Dimension | dynamic | CSG |
|__________________________|____________________________|________________|______________________|________|
|XmNindicatorType | XmCIndicatorType | unsigned char | dynamic | CSG |
|__________________________|____________________________|________________|______________________|________|
|XmNselectColor | XmCSelectColor | Pixel | dynamic | CSG |
|__________________________|____________________________|________________|______________________|________|
|XmNselectInsensitivePixmap| XmCSelectInsensitivePixmap| Pixmap | XmUNSPECIFIED_PIXMAP| CSG |
|__________________________|____________________________|________________|______________________|________|
|XmNselectPixmap | XmCSelectPixmap | Pixmap | XmUNSPECIFIED_PIXMAP| CSG |
|__________________________|____________________________|________________|______________________|________|
|XmNset | XmCSet | Boolean | False | CSG |
|__________________________|____________________________|________________|______________________|________|
|XmNspacing | XmCSpacing | Dimension | 4 | CSG |
|__________________________|____________________________|________________|______________________|________|
|XmNvalueChangedCallback | XmCValueChangedCallback | XtCallbackList| NULL | C |
|__________________________|____________________________|________________|______________________|________|
|XmNvisibleWhenOff | XmCVisibleWhenOff | Boolean | dynamic | CSG |
|__________________________|____________________________|________________|______________________|________|
XmNarmCallback
Specifies a list of callbacks that is called when the
ToggleButtonGadget is armed. To arm this gadget, press the active
mouse button while the pointer is inside the ToggleButtonGadget.
For this callback, the reason is XmCR_ARM.
XmNdisarmCallback
Specifies a list of callbacks called when ToggleButtonGadget is
disarmed. To disarm this gadget, press and release the active mouse
button while the pointer is inside the ToggleButtonGadget. The
gadget is also disarmed when the user moves out of the gadget and
releases the mouse button when the pointer is outside the gadget.
Page 2 10/89
XmToggleButtonGadget(3X) UNIX System V XmToggleButtonGadget(3X)
For this callback, the reason is XmCR_DISARM.
XmNfillOnSelect
Fills the indicator with the color specified in XmNselectColor and
switches the top and bottom shadow colors when set to True.
Otherwise, it only switches the top and bottom shadow colors.
XmNindicatorOn
Specifies that a toggle indicator is drawn to one side of the
toggle text or pixmap when set to True. When set to False, no
space is allocated for the indicator, and it is not displayed. If
XmNindicatorOn is True, the indicator shadows are switched when the
button is selected or unselected, but any shadows around the entire
gadget are not switched. However, if XmNindicatorOn is False, any
shadows around the entire gadget are switched when the toggle is
selected or unselected.
XmNindicatorSize
Sets the size of the indicator. If no value is specified, the size
of the indicator is based on the size of the label string or
pixmap. If the label string or pixmap changes, the size of the
indicator is recomputed based on the size of the label string or
pixmap. Once a value has been specified for XmNindicatorSize, the
indicator has that size, regardless of the size of the label string
or pixmap, until a new value is specified.
XmNindicatorType
Specifies if the indicator is a 1-of or an N-of indicator. For the
1-of indicator, the value is XmONE_OF_MANY. For the N-of
indicator, the value is XmN_OF_MANY. The N-of-many indicator is
square. The 1-of-many indicator is diamond-shaped. This resource
specifies only the visuals and does not enforce the behavior. When
the ToggleButtonGadget is in a RadioBox, the default is
XmONE_OF_MANY; otherwise, the default is XmN_OF_MANY.
XmNselectColor
Allows the application to specify what color fills the center of
the square or diamond-shaped indicator when it is set. If this
color is the same as either the top or the bottom shadow color of
the indicator, a one-pixel-wide margin is left between the shadows
and the fill; otherwise, it is filled completely. This resource's
default for a color display is a color between the background and
the bottom shadow color. For a monochrome display, the default is
set to the foreground color. The meaning of this resource is
undefined when XmNindicatorOn is False.
XmNselectInsensitivePixmap
Specifies a pixmap used as the button face when the
ToggleButtonGadget is selected and the button is insensitive if the
LabelGadget resource XmNlabelType is XmPIXMAP. If the
ToggleButtonGadget is unselected and the button is insensitive, the
pixmap in XmNlabelInsensitivePixmap is used as the button face. If
10/89 Page 3
XmToggleButtonGadget(3X) UNIX System V XmToggleButtonGadget(3X)
no value is specified for XmNlabelInsensitivePixmap, that resource
is set to the value specified for XmNselectInsensitivePixmap.
XmNselectPixmap
Specifies the pixmap to be used as the button face if XmNlabelType
is XmPIXMAP and the ToggleButtonGadget is selected. When the
ToggleButtonGadget is unselected, the pixmap specified in
LabelGadget's XmNlabelPixmap is used. If no value is specified for
XmNlabelPixmap, that resource is set to the value specified for
XmNselectPixmap.
XmNset
Displays the button in its selected state if set to True. This
shows some conditions as active when a set of buttons first
appears.
XmNspacing
Specifies the amount of spacing between the toggle indicator and
the toggle label (text or pixmap).
XmNvalueChangedCallback
Specifies a list of callbacks called when the ToggleButtonGadget
value is changed. To change the value, press and release the
active mouse button while the pointer is inside the
ToggleButtonGadget. This action also causes the gadget to be
disarmed. For this callback, the reason is XmCR_VALUE_CHANGED.
XmNvisibleWhenOff
Indicates that the toggle indicator is visible in the unselected
state when the Boolean value is True. When the ToggleButtonGadget
is in a menu, the default value is False. When the
ToggleButtonGadget is in a RadioBox, the default value is True.
Inherited Resources
ToggleButtonGadget inherits behavior and resources from the following
superclasses. For a complete description of each resource, refer to the
man page for that superclass.
Page 4 10/89
XmToggleButtonGadget(3X) UNIX System V XmToggleButtonGadget(3X)
___________________________________________________________________________________________________________
| XmLabelGadget Resource Set |
|_________________________|___________________________|___________________|______________________|________|
|Name | Class | Type | Default | Access|
|_________________________|___________________________|___________________|______________________|________|
|_________________________|___________________________|___________________|______________________|________|
|XmNaccelerator | XmCAccelerator | String | NULL | CSG |
|_________________________|___________________________|___________________|______________________|________|
|XmNacceleratorText | XmCAcceleratorText | XmString | NULL | CSG |
|_________________________|___________________________|___________________|______________________|________|
|XmNalignment | XmCAlignment | unsigned char | dynamic | CSG |
|_________________________|___________________________|___________________|______________________|________|
|XmNfontList | XmCFontList | XmFontList | dynamic | CSG |
|_________________________|___________________________|___________________|______________________|________|
|XmNlabelInsensitivePixmap| XmCLabelInsensitivePixmap| Pixmap | XmUNSPECIFIED_PIXMAP| CSG |
|_________________________|___________________________|___________________|______________________|________|
|XmNlabelPixmap | XmCLabelPixmap | Pixmap | XmUNSPECIFIED_PIXMAP| CSG |
|_________________________|___________________________|___________________|______________________|________|
|XmNlabelString | XmCXmString | XmString | dynamic | CSG |
|_________________________|___________________________|___________________|______________________|________|
|XmNlabelType | XmCLabelType | unsigned char | XmSTRING | CSG |
|_________________________|___________________________|___________________|______________________|________|
|XmNmarginBottom | XmCMarginBottom | Dimension | dynamic | CSG |
|_________________________|___________________________|___________________|______________________|________|
|XmNmarginHeight | XmCMarginHeight | Dimension | 2 | CSG |
|_________________________|___________________________|___________________|______________________|________|
|XmNmarginLeft | XmCMarginLeft | Dimension | dynamic | CSG |
|_________________________|___________________________|___________________|______________________|________|
|XmNmarginRight | XmCMarginRight | Dimension | 0 | CSG |
|_________________________|___________________________|___________________|______________________|________|
|XmNmarginTop | XmCMarginTop | Dimension | dynamic | CSG |
|_________________________|___________________________|___________________|______________________|________|
|XmNmarginWidth | XmCMarginWidth | Dimension | 2 | CSG |
|_________________________|___________________________|___________________|______________________|________|
|XmNmnemonic | XmCMnemonic | KeySym | NULL | CSG |
|_________________________|___________________________|___________________|______________________|________|
|XmNmnemonicCharSet | XmCMnemonicCharSet | String | dynamic | CSG |
|_________________________|___________________________|___________________|______________________|________|
|XmNrecomputeSize | XmCRecomputeSize | Boolean | True | CSG |
|_________________________|___________________________|___________________|______________________|________|
|XmNstringDirection | XmCStringDirection | XmStringDirection| dynamic | CSG |
|_________________________|___________________________|___________________|______________________|________|
10/89 Page 5
XmToggleButtonGadget(3X) UNIX System V XmToggleButtonGadget(3X)
_____________________________________________________________________________________
| XmGadget Resource Set |
|_____________________|_______________________|__________________|_________|________|
|Name | Class | Type | Default| Access|
|_____________________|_______________________|__________________|_________|________|
|_____________________|_______________________|__________________|_________|________|
|XmNhelpCallback | XmCCallback | XtCallbackList | NULL | C |
|_____________________|_______________________|__________________|_________|________|
|XmNhighlightOnEnter | XmCHighlightOnEnter | Boolean | False | CSG |
|_____________________|_______________________|__________________|_________|________|
|XmNhighlightThickness| XmCHighlightThickness| Dimension | 2 | CSG |
|_____________________|_______________________|__________________|_________|________|
|XmNnavigationType | XmCNavigationType | XmNavigationType| XmNONE | G |
|_____________________|_______________________|__________________|_________|________|
|XmNshadowThickness | XmCShadowThickness | Dimension | dynamic| CSG |
|_____________________|_______________________|__________________|_________|________|
|XmNtraversalOn | XmCTraversalOn | Boolean | True | CSG |
|_____________________|_______________________|__________________|_________|________|
|XmNunitType | XmCUnitType | unsigned char | dynamic| CSG |
|_____________________|_______________________|__________________|_________|________|
|XmNuserData | XmCUserData | Pointer | NULL | CSG |
|_____________________|_______________________|__________________|_________|________|
______________________________________________________________________
| RectObj Resource Set |
|_____________________|________________|___________|_________|________|
| Name | Class | Type | Default| Access|
|_____________________|________________|___________|_________|________|
|_____________________|________________|___________|_________|________|
| XmNancestorSensitive| XmCSensitive | Boolean | dynamic| G |
|_____________________|________________|___________|_________|________|
| XmNborderWidth | XmCBorderWidth| Dimension| 0 | CSG |
|_____________________|________________|___________|_________|________|
| XmNheight | XmCHeight | Dimension| dynamic| CSG |
|_____________________|________________|___________|_________|________|
| XmNsensitive | XmCSensitive | Boolean | True | CSG |
|_____________________|________________|___________|_________|________|
| XmNwidth | XmCWidth | Dimension| dynamic| CSG |
|_____________________|________________|___________|_________|________|
| XmNx | XmCPosition | Position | 0 | CSG |
|_____________________|________________|___________|_________|________|
| XmNy | XmCPosition | Position | 0 | CSG |
|_____________________|________________|___________|_________|________|
Callback Information
A pointer to the following structure is passed to each callback:
typedef struct
{
int reason;
XEvent * event;
Page 6 10/89
XmToggleButtonGadget(3X) UNIX System V XmToggleButtonGadget(3X)
int set;
} XmToggleButtonCallbackStruct;
reason Indicates why the callback was invoked
event Points to the XEvent that triggered the callback
set Reflects the ToggleButtonGadget's current state when the callback
occurred, either True (selected) or False (unselected)
Behavior
XmToggleButtonGadget includes behavior from XmGadget.
XmToggleButtonGadget includes menu traversal behavior from XmLabelGadget.
Additional XmToggleButtonGadget behavior is described below:
BSelect Press:
In a menu, this action unposts any menus posted by the
ToggleButtonGadget's parent menu, disables keyboard traversal for
the menu, and enables mouse traversal for the menu. It draws the
shadow in the armed state and, unless the button is already armed,
calls the XmNarmCallback callbacks.
Outside a menu, if the button was previously unset, this action
does the following: If XmNindicatorOn is True, it draws the
indicator shadow so that the indicator looks pressed; if
XmNfillOnSelect is True, it fills the indicator with the color
specified by XmNselectColor. If XmNindicatorOn is False, it draws
the button shadow so that the button looks pressed. If
XmNlabelType is XmPIXMAP, the XmNselectPixmap is used as the button
face. Calls the XmNarmCallback callbacks.
Outside a menu, if the button was previously set, this action does
the following: If both XmNindicatorOn and XmNvisibleWhenOff are
True, it draws the indicator shadow so that the indicator looks
raised; if XmNfillOnSelect is True, it fills the indicator with the
background color. If XmNindicatorOn is False, it draws the button
shadow so that the button looks raised. If XmNlabelType is
XmPIXMAP, the XmNlabelPixmap is used as the button face. Calls the
XmNarmCallback callbacks.
BSelect Release:
In a menu, this action does the following: It unposts all menus in
the menu hierarchy. If the ToggleButtonGadget was previously set,
unsets it; if the ToggleButtonGadget was previously unset, sets it.
It calls the XmNvalueChangedCallback callbacks and then the
XmNdisarmCallback callbacks.
If the button is outside a menu and the pointer is within the
button, this action does the following: If the button was
previously unset, sets it; if the button was previously set, unsets
10/89 Page 7
XmToggleButtonGadget(3X) UNIX System V XmToggleButtonGadget(3X)
it. Calls the XmNvalueChangedCallback callbacks.
If the button is outside a menu, calls the XmNdisarmCallback
callbacks.
KHelp:
In a Pulldown or Popup MenuPane, unposts all menus in the menu
hierarchy and restores keyboard focus to the tab group that had the
focus before the menu system was entered. Calls the callbacks for
XmNhelpCallback if any exist. If there are no help callbacks for
this widget, this action calls the help callbacks for the nearest
ancestor that has them.
KActivate or KSelect:
If the ToggleButtonGadget was previously set, unsets it; if the
ToggleButtonGadget was previously unset, sets it.
In a menu, does the following: Unposts all menus in the menu
hierarchy. Unless the button is already armed, calls the
XmNarmCallback callbacks. Calls the XmNvalueChangedCallback and
XmNdisarmCallback callbacks.
Outside a menu, if the button was previously unset, this action
does the following: If XmNindicatorOn is True, it draws the
indicator shadow so that the indicator looks pressed; if
XmNfillOnSelect is True, it fills the indicator with the color
specified by XmNselectColor. If XmNindicatorOn is False, it draws
the button shadow so that the button looks pressed. If
XmNlabelType is XmPIXMAP, the XmNselectPixmap is used as the button
face. Calls the XmNarmCallback, XmNvalueChangedCallback,
XmNdisarmCallback callbacks.
Outside a menu, if the button was previously set, this action does
the following: If both XmNindicatorOn and XmNvisibleWhenOff are
True, it draws the indicator shadow so that the indicator looks
raised; if XmNfillOnSelect is True, it fills the indicator with the
background color. If XmNindicatorOn is False, it draws the button
shadow so that the button looks raised. If XmNlabelType is
XmPIXMAP, the XmNlabelPixmap is used as the button face. Calls the
XmNarmCallback, XmNvalueChangedCallback, and XmNdisarmCallback
callbacks.
MAny KCancel:
In a toplevel Pulldown MenuPane from a MenuBar, unposts the menu,
disarms the MenuBar CascadeButton and the MenuBar, and restores
keyboard focus to the tab group that had the focus before the
MenuBar was entered. In other Pulldown MenuPanes, unposts the
menu.
In a Popup MenuPane, unposts the menu and restores keyboard focus
to the widget from which the menu was posted.
Page 8 10/89
XmToggleButtonGadget(3X) UNIX System V XmToggleButtonGadget(3X)
<Enter>:
In a menu, if keyboard traversal is enabled, this action does
nothing. Otherwise, it draws the shadow in the armed state and
calls the XmNarmCallback callbacks.
If the ToggleButtonGadget is not in a menu and the cursor leaves
and then reenters the ToggleButtonGadget while the button is
pressed, this action restores the button's armed appearance.
<Leave>:
In a menu, if keyboard traversal is enabled, this action does
nothing. Otherwise, it draws the shadow in the unarmed state and
calls the XmNdisarmCallback callbacks.
If the ToggleButtonGadget is not in a menu and the cursor leaves
the ToggleButtonGadget while the button is pressed, this action
restores the button's unarmed appearance.
Virtual Bindings
The bindings for virtual keys are vendor specific. For information about
bindings for virtual buttons and keys, see VirtualBindings(3X).
RELATED INFORMATION
Object(3X), RectObj(3X), XmCreateRadioBox(3X),
XmCreateToggleButtonGadget(3X), XmGadget(3X), XmLabelGadget(3X),
XmRowColumn(3X), XmToggleButtonGadgetGetState(3X), and
XmToggleButtonGadgetSetState(3X).
10/89 Page 9