XmToggleButtonGadget(3X)XmToggleButtonGadget(3X)NAMEXmToggleButtonGadget - 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 XmN‐
marginLeft may be increased.
Classes
ToggleButtonGadget inherits behavior and resources from Object, Rec‐
tObj, 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 pro‐
grammer to specify data. The programmer can also set the resource val‐
ues 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 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
Class: XmCArmCallback
Default: NULL
Type: XtCallbackList
Access: C
Class: XmCDisarmCallback
Default: NULL
Type: XtCallbackList
Access: C
Class: XmCFillOnSelect
Default: dynamic
Type: Boolean
Access: CSG
Class: XmCIndicatorOn
Default: True
Type: Boolean
Access: CSG
Class: XmCIndicatorSize
Default: dynamic
Type: Dimension
Access: CSG
Class: XmCIndicatorType
Default: dynamic
Type: unsigned char
Access: CSG
Class: XmCSelectColor
Default: dynamic
Type: Pixel
Access: CSG
Class: XmCSelectInsensitivePixmap
Default: XmUNSPECIFIED_PIXMAP
Type: Pixmap
Access: CSG
Class: XmCSelectPixmap
Default: XmUNSPECIFIED_PIXMAP
Type: Pixmap
Access: CSG
Class: XmCSet
Default: False
Type: Boolean
Access: CSG
Class: XmCSpacing
Default: 4
Type: Dimension
Access: CSG
Class: XmCValueChangedCallback
Default: NULL
Type: XtCallbackList
Access: C
Class: XmCVisibleWhenOff
Default: dynamic
Type: Boolean
Access: CSG
Specifies a list of callbacks that is called when the ToggleBut‐
tonGadget 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. 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. For this
callback, the reason is XmCR_DISARM. Fills the indicator with
the color specified in XmNselectColor and switches the top and
bottom shadow colors when set to True. Otherwise, it switches
only the top and bottom shadow colors. The default is set to
the value of XmNindicatorOn. When XmNindicatorOn is False, and
XmNfillOnSelect is set explicitly to True, the background is
filled with the color specified by XmNselectColor. 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. 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. Specifies if the indi‐
cator 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 Toggle‐
ButtonGadget is in a RadioBox, the default is XmONE_OF_MANY;
otherwise, the default is XmN_OF_MANY. 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. To set the background of the button to
XmNselectColor when XmNindicatorOn is False, the value of XmN‐
fillOnSelect must be explicitly set to True. Specifies a pixmap
used as the button face when the ToggleButtonGadget is selected
and the button is insensitive if the LabelGadget resource XmNla‐
belType is XmPIXMAP. If the ToggleButtonGadget is unselected
and the button is insensitive, the pixmap in XmNlabelInsensi‐
tivePixmap is used as the button face. If no value is specified
for XmNlabelInsensitivePixmap, that resource is set to the value
specified for XmNselectInsensitivePixmap. 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 XmNla‐
belPixmap is used. If no value is specified for XmNlabelPixmap,
that resource is set to the value specified for XmNselectPixmap.
Represents the state of the ToggleButton. A value of false
indicates that the ToggleButton is not set. A value of true
indicates that the ToggleButton is set. Setting this resource
sets the state of the ToggleButton. Specifies the amount of
spacing between the toggle indicator and the toggle label (text
or pixmap). Specifies a list of callbacks called when the Tog‐
gleButtonGadget 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. Indicates that the toggle indicator is vis‐
ible 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.
XmLabelGadget Resource Set
Class: XmCAccelerator
Default: NULL
Type: String
Access: CSG
Class: XmCAcceleratorText
Default: NULL
Type: XmString
Access: CSG
Class: XmCAlignment
Default: dynamic
Type: unsigned char
Access: CSG
Class: XmCFontList
Default: dynamic
Type: XmFontList
Access: CSG
Class: XmCLabelInsensitivePixmap
Default: XmUNSPECIFIED_PIXMAP
Type: Pixmap
Access: CSG
Class: XmCLabelPixmap
Default: XmUNSPECIFIED_PIXMAP
Type: Pixmap
Access: CSG
Class: XmCXmString
Default: dynamic
Type: XmString
Access: CSG
Class: XmCLabelType
Default: XmSTRING
Type: unsigned char
Access: CSG
Class: XmCMarginBottom
Default: dynamic
Type: Dimension
Access: CSG
Class: XmCMarginHeight
Default: 2
Type: Dimension
Access: CSG
Class: XmCMarginLeft
Default: dynamic
Type: Dimension
Access: CSG
Class: XmCMarginRight
Default: 0
Type: Dimension
Access: CSG
Class: XmCMarginTop
Default: dynamic
Type: Dimension
Access: CSG
Class: XmCMarginWidth
Default: 2
Type: Dimension
Access: CSG
Class: XmCMnemonic
Default: NULL
Type: KeySym
Access: CSG
Class: XmCMnemonicCharSet
Default: dynamic
Type: String
Access: CSG
Class: XmCRecomputeSize
Default: True
Type: Boolean
Access: CSG
Class: XmCStringDirection
Default: dynamic
Type: XmStringDirection
Access: CSG
XmGadget Resource Set
Class: XmCBottomShadowColor
Default: dynamic
Type: Pixel
Access: G
Class: XmCCallback
Default: NULL
Type: XtCallbackList
Access: C
Class: XmCHighlightColor
Default: dynamic
Type: Pixel
Access: G
Class: XmCHighlightOnEnter
Default: False
Type: Boolean
Access: CSG
Class: XmCHighlightThickness
Default: 2
Type: Dimension
Access: CSG
Class: XmCNavigationType
Default: XmNONE
Type: XmNavigationType
Access: CSG
Class: XmCShadowThickness
Default: dynamic
Type: Dimension
Access: CSG
Class: XmCTopShadowColor
Default: dynamic
Type: Pixel
Access: G
Class: XmCTraversalOn
Default: True
Type: Boolean
Access: CSG
Class: XmCUnitType
Default: dynamic
Type: unsigned char
Access: CSG
Class: XmCUserData
Default: NULL
Type: XtPointer
Access: CSG
RectObj Resource Set
Class: XmCSensitive
Default: dynamic
Type: Boolean
Access: G
Class: XmCBorderWidth
Default: 0
Type: Dimension
Access: CSG
Class: XmCHeight
Default: dynamic
Type: Dimension
Access: CSG
Class: XmCSensitive
Default: True
Type: Boolean
Access: CSG
Class: XmCWidth
Default: dynamic
Type: Dimension
Access: CSG
Class: XmCPosition
Default: 0
Type: Position
Access: CSG
Class: XmCPosition
Default: 0
Type: Position
Access: CSG
Object Resource Set
Class: XmCCallback
Default: NULL
Type: XtCallbackList
Access: C
Callback Information
A pointer to the following structure is passed to each callback: type‐
def struct {
int reason;
XEvent * event;
int set; } XmToggleButtonCallbackStruct;
Indicates why the callback was invoked Points to the XEvent that trig‐
gered the callback Reflects the ToggleButtonGadget's current state when
the callback occurred, either True (selected) or False (unselected)
Behavior
XmToggleButtonGadget includes behavior from XmGadget. XmToggleButton‐
Gadget includes menu traversal behavior from XmLabelGadget. Additional
XmToggleButtonGadget behavior is described below: Drags the contents of
a ToggleButtonGadget label, identified by pressing BDrag. This action
creates a DragContext object whose XmNexportTargets resource is set to
COMPOUND_TEXT for a label type of XmSTRING; otherwise, PIXMAP if the
label type is XmPIXMAP. This action is undefined for ToggleButtonGad‐
gets used in a menu system. In a menu, this action unposts any menus
posted by the ToggleButtonGadget's parent menu, disables keyboard tra‐
versal 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 XmNfil‐
lOnSelect is True, it fills the indicator with the color speci‐
fied 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 XmNlabel‐
Type is XmPIXMAP, the XmNlabelPixmap is used as the button face.
Calls the XmNarmCallback callbacks. 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 previ‐
ously unset, sets it; if the button was previously set, unsets
it. Calls the XmNvalueChangedCallback callbacks.
If the button is outside a menu, calls the XmNdisarmCallback
callbacks. In a Pulldown or Popup MenuPane, unposts all menus
in the menu hierarchy and, when the shell's keyboard focus pol‐
icy is XmEXPLICT, restores keyboard focus to the widget that had
the focus before the menu system was entered. Calls the call‐
backs 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. In a menu, does the
following: unposts all menus in the menu hierarchy; unless the
button is already armed, calls the XmNarmCallback callbacks; and
calls the XmNvalueChangedCallback and XmNdisarmCallback call‐
backs. Outside a menu, if the parent is a manager, passes the
event to the parent. 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 XmN‐
armCallback 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 XmNfil‐
lOnSelect is True, it fills the indicator with the color speci‐
fied 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, XmNdisarm‐
Callback 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 XmNlabel‐
Type is XmPIXMAP, the XmNlabelPixmap is used as the button face.
Calls the XmNarmCallback, XmNvalueChangedCallback, and XmNdis‐
armCallback callbacks. In a toplevel Pulldown MenuPane from a
MenuBar, unposts the menu, disarms the MenuBar CascadeButton and
the MenuBar, and, when the shell's keyboard focus policy is
XmEXPLICT, restores keyboard focus to the widget that had the
focus before the MenuBar was entered. In other Pulldown Menu‐
Panes, unposts the menu. Outside a menu, if the parent is a man‐
ager, this action passes the event to the parent.
In a Popup MenuPane, unposts the menu and restores keyboard
focus to the widget from which the menu was posted. In a menu,
if keyboard traversal is enabled, this action does nothing. Oth‐
erwise, 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. In
a menu, if keyboard traversal is enabled, this action does noth‐
ing. 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).
SEE ALSOObject(3X), RectObj(3X), XmCreateRadioBox(3X), XmCreateToggleButtonGad‐
get(3X), XmGadget(3X), XmLabelGadget(3X), XmRowColumn(3X), XmToggleBut‐
tonGadgetGetState(3X), XmToggleButtonGadgetSetState(3X)XmToggleButtonGadget(3X)
