XmToggleButtonGadget(3X)

XmToggleButtonGadget --The ToggleButtonGadget widget class

Showing IRIX 6.5.30 (default release). Unchanged since IRIX 6.5.

NAME
XmToggleButtonGadget --The ToggleButtonGadget widget class

SYNOPSIS
#include <Xm/ToggleBG.h>

VERSION
This page documents version 1.2 of the Motif library.

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 con-
sist 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 se-
lection 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) in-
dicates 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 con-
trols 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 XmNmar-
ginLeft 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 program-
mer 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 and use the re-
maining letters (in either lowercase or uppercase, but include any under-
scores 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 dynamic 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 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.

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. 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 switches only the top and bottom shadow colors.
The default is set to the value of XmNindicatorOn. When XmNindi-
catorOn is False, and XmNfillOnSelect is set explicitly to True,
the background is filled with the color specified by XmNselect-
Color.

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 in-
dicator, the value is XmN_OF_MANY. The N-of-many indicator is
square. The 1-of-many indicator is diamond-shaped. This re-
source specifies only the visuals and does not enforce the behav-
ior. 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 shad-
ows and the fill; otherwise, it is filled completely. This re-
source's default for a color display is a color between the back-
ground and the bottom shadow color. For a monochrome display,
the default is set to the foreground color. To set the back-
ground of the button to XmNselectColor when XmNindicatorOn is
False, the value of XmNfillOnSelect must be explicitly set to
True.

XmNselectInsensitivePixmap
Specifies a pixmap used as the button face when the ToggleButton-
Gadget is selected and the button is insensitive if the LabelGad-
get resource XmNlabelType is XmPIXMAP. If the ToggleButtonGadget
is unselected and the button is insensitive, the pixmap in XmNla-
belInsensitivePixmap is used as the button face. If 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 XmNlabel-
Type is XmPIXMAP and the ToggleButtonGadget is selected. When
the ToggleButtonGadget is unselected, the pixmap specified in La-
belGadget's XmNlabelPixmap is used. If no value is specified for
XmNlabelPixmap, that resource is set to the value specified for
XmNselectPixmap.

XmNset Represents the state of the ToggleButton. A value of false indi-
cates that the ToggleButton is not set. A value of true indi-
cates that the ToggleButton is set. Setting this resource sets
the state of the ToggleButton.

XmNspacingSpecifies 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 ac-
tive mouse button while the pointer is inside the ToggleButton-
Gadget. 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 ToggleButtonGad-
get is in a menu, the default value is False. When the Toggle-
ButtonGadget is in a RadioBox, the default value is True.

Inherited Resources
ToggleButtonGadget inherits behavior and resources from the following su-
perclasses. For a complete description of each resource, refer to the man
page for that superclass.

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

XmGadget Resource Set
Name Class Type Default Access
------------------------------------------------------------------------------------
XmNbottomShadowColor XmCBottomShadowColor Pixel dynamic G
XmNhelpCallback XmCCallback XtCallbackList NULL C
XmNhighlightColor XmCHighlightColor Pixel dynamic G
XmNhighlightOnEnter XmCHighlightOnEnter Boolean False CSG
XmNhighlightThickness XmCHighlightThickness Dimension 2 CSG
XmNnavigationType XmCNavigationType XmNavigationType XmNONE CSG
XmNshadowThickness XmCShadowThickness Dimension dynamic CSG
XmNtopShadowColor XmCTopShadowColor Pixel dynamic G
XmNtraversalOn XmCTraversalOn Boolean True CSG
XmNunitType XmCUnitType unsigned char dynamic CSG
XmNuserData XmCUserData XtPointer 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

Object Resource Set
Name Class Type Default Access
---------------------------------------------------------------------
XmNdestroyCallback XmCCallback XtCallbackList NULL C

Callback Information
A pointer to the following structure is passed to each callback:

typedef struct
{
int reason;
XEvent * event;
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 XmToggle-
ButtonGadget behavior is described below:

BDrag Press:
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 ToggleButtonGadgets used
in a menu system.

BSelect Press:
In a menu, this action unposts any menus posted by the ToggleBut-
tonGadget'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 indi-
cator 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 fol-
lowing: 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 it. Calls the XmNvalueChangedCall-
back 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, when the shell's keyboard focus policy is XmEX-
PLICT, restores keyboard focus to the widget that had the focus
before the menu system was entered. Calls the callbacks for XmN-
helpCallback 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.

Activate: In a menu, does the following: unposts all menus in the menu hi-
erarchy; unless the button is already armed, calls the XmNarm-
Callback callbacks; and calls the XmNvalueChangedCallback and Xm-
NdisarmCallback callbacks. Outside a menu, if the parent is a
manager, passes the event to the parent.

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.

MAny KCancel:
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 fo-
cus to the widget that had the focus before the MenuBar was en-
tered. In other Pulldown MenuPanes, unposts the menu. Outside a
menu, if the parent is a manager, 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.

<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 Tog-
gleButtonGadget while the button is pressed, this action restores the but-
ton'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), XmCreateToggleButtonGad-
get(3X), XmGadget(3X), XmLabelGadget(3X), XmRowColumn(3X), XmToggleButton-
GadgetGetState(3X), and XmToggleButtonGadgetSetState(3X).

XmToggleButtonGadget(3X)