XmPushButtonGadget(3X)XmPushButtonGadget(3X)NAMEXmPushButtonGadget — The PushButtonGadget widget class
SYNOPSIS
#include <Xm/PushBG.h>
VERSION
This page documents version 1.2 of the Motif library.
DESCRIPTION
PushButtonGadget issues commands within an application. It consists of
a text label or pixmap surrounded by a border shadow. When PushButton‐
Gadget is selected, the shadow changes to give the appearance that the
PushButtonGadget has been pressed in. When PushButtonGadget is unse‐
lected, the shadow changes to give the appearance that the PushButton‐
Gadget is out.
The default behavior associated with a PushButtonGadget in a menu
depends on the type of menu system in which it resides. By default,
BSelect controls the behavior of the PushButtonGadget. In addition,
BMenu controls the behavior of the PushButtonGadget if it resides in a
PopupMenu system. The actual mouse button used is determined by its
RowColumn parent.
Thickness for a second shadow may be specified by using the XmNshowAs‐
Default resource. If it has a non-zero value, the Label's resources
XmNmarginLeft, XmNmarginRight, XmNmarginTop, and XmNmarginBottom may be
modified to accommodate the second shadow.
If an initial value is specified for XmNarmPixmap but not for XmNla‐
belPixmap, the XmNarmPixmap value is used for XmNlabelPixmap.
Classes
PushButtonGadget inherits behavior and resources from Object, RectObj,
XmGadget and XmLabelGadget classes.
The class pointer is xmPushButtonGadgetClass.
The class name is XmPushButtonGadget.
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).
XmPushButtonGadgetName Class Type Default Access
───────────────────────────────────────────────────────────────────────────────────────────────────────────────────
XmNactivateCallback XmCCallback XtCallbackList NULL C
XmNarmCallback XmCCallback XtCallbackList NULL C
XmNarmColor XmCArmColor Pixel dynamic CSG
XmNarmPixmap XmCArmPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG
XmNdefaultButtonShadowThickness XmCdefaultButtonShadowThickness Dimension dynamic CSG
XmNdisarmCallback XmCCallback XtCallbackList NULL C
XmNfillOnArm XmCFillOnArm Boolean True CSG
XmNmultiClick XmCMultiClick unsigned char dynamic CSG
XmNshowAsDefault XmCShowAsDefault Dimension 0 CSG
Specifies the list of callbacks that is called when the PushButtonGad‐
get is activated. It is activated when the user presses and releases
the active mouse button while the pointer is inside the PushButtonGad‐
get. Activating PushButtonGadget also disarms it. For this callback
the reason is XmCR_ACTIVATE. Specifies the list of callbacks that is
called when PushButtonGadget is armed. It is armed when the user
presses the active mouse button while the pointer is inside the Push‐
ButtonGadget. For this callback the reason is XmCR_ARM. Specifies the
color with which to fill the armed button. XmNfillOnArm must be set to
True for this resource to have an effect. The default for a color dis‐
play is a color between the background and the bottom shadow color.
For a monochrome display, the default is set to the foreground color,
and any text in the label appears in the background color when the but‐
ton is armed. Specifies the pixmap to be used as the button face if
XmNlabeltype is XmPIXMAP and PushButtonGadget is armed. This resource
is disabled when the PushButtonGadget is in a menu. This resource
specifies the width of the default button indicator shadow. If this
resource is zero, the width of the shadow comes from the value of the
XmNshowAsDefault resource. If this resource is greater than zero, the
XmNshowAsDefault resource is only used to specify whether this button
is the default. The default value is the initial value of XmNshowAsDe‐
fault. Specifies the list of callbacks that is called when the Push‐
ButtonGadget is disarmed. PushButtonGadget is disarmed when the user
presses and releases the active mouse button while the pointer is
inside that gadget. For this callback, the reason is XmCR_DISARM.
Forces the PushButtonGadget to fill the background of the button with
the color specified by XmNarmColor when the button is armed and when
this resource is set to True. If False, only the top and bottom shadow
colors are switched. When the PushButtonGadget is in a menu, this
resource is ignored and assumed to be False. If a button click is fol‐
lowed by another button click within the time span specified by the
display's multi-click time, and this resource is set to XmMUL‐
TICLICK_DISCARD, do not process the second click. If this resource is
set to XmMULTICLICK_KEEP, process the event and increment click_count
in the callback structure. When the button is in a menu, the default
is XmMULTICLICK_DISCARD; otherwise, for a button not in a menu XmMUL‐
TICLICK_KEEP is the default value. If XmNdefaultButtonShadowThickness
is greater than zero, a value greater than zero in this resource speci‐
fies to mark this button as the default button. If XmNdefaultButton‐
ShadowThickness is zero, a value greater than zero in this resource
specifies to mark this button as the default button with the shadow
thickness specified by this resource. The space between the shadow and
the default shadow is equal to the sum of both shadows. The default
value is zero. When this value is not zero, the Label resources XmN‐
marginLeft, XmNmarginRight, XmNmarginTop, and XmNmarginBottom may be
modified to accommodate the second shadow. This resource is disabled
when the PushButton is in a menu.
Inherited Resources
PushButtonGadget 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
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 dynamic 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 dynamic 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 2 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: type‐
def struct { int reason; XEvent * event;
int click_count; } XmPushButtonCallbackStruct; Indicates why the
callback was invoked. Points to the XEvent that triggered the call‐
back. This value is valid only when the reason is XmCR_ACTIVATE. It
contains the number of clicks in the last multiclick sequence if the
XmNmultiClick resource is set to XmMULTICLICK_KEEP, otherwise it con‐
tains 1. The activate callback is invoked for each click if XmNmul‐
tiClick is set to XmMULTICLICK_KEEP.
Behavior
XmPushButtonGadget includes behavior from XmGadget. XmPushButtonGadget
includes menu traversal behavior from XmLabelGadget. Additional behav‐
ior for XmPushButtonGadget is described below: Drags the contents of a
PushButtonGadget label, identified by pressing BDrag. This action cre‐
ates 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 PushButton‐
Gadgets used in a menu system. This action arms the PushButtonGadget.
In a menu, this action unposts any menus posted by the PushButtonGad‐
get's parent menu, disables keyboard traversal for the menu, and
enables mouse traversal for the menu. It draws the shadow in the armed
state. Unless the button is already armed, it calls the XmNarmCallback
callbacks.
If the button is not in a menu, this action draws the shadow in the
armed state. If XmNfillOnArm is set to True, it fills the button with
the color specified by XmNarmColor. If XmNlabelType is XmPIXMAP, the
XmNarmPixmap is used for the button face. It calls the XmNarmCallback
callbacks. If XmNmultiClick is XmMULTICLICK_DISCARD, this action does
nothing.
If XmNmultiClick is XmMULTICLICK_KEEP, this action does the following:
Draws the shadow in the armed state. If the button is not in a menu
and if XmNfillOnArm is set to True, fills the button with the color
specified by XmNarmColor. If XmNlabelType is XmPIXMAP, the XmN‐
armPixmap is used for the button face. Calls the XmNarmCallback call‐
backs. In a menu, this action unposts all menus in the menu hierarchy
and activates the PushButtonGadget. It calls the XmNactivateCallback
callbacks and then the XmNdisarmCallback callbacks.
If the PushButtonGadget is not in a menu, this action draws the shadow
in the unarmed state. If XmNfillOnArm is set to True, the background
color reverts to the unarmed color. If XmNlabelType is XmPIXMAP, the
XmNlabelPixmap is used for the button face. If the pointer is still
within the button, this action calls the callbacks for XmNactivateCall‐
back. Calls the callbacks for XmNdisarmCallback. If XmNmultiClick is
XmMULTICLICK_DISCARD, this action does nothing.
If XmNmultiClick is XmMULTICLICK_KEEP, this action does the following:
Increments click_count in the callback structure. Draws the shadow in
the unarmed state. If the button is not in a menu and if XmNfillOnArm
is set to True, the background color reverts to the unarmed color. If
XmNlabelType is XmPIXMAP, the XmNlabelPixmap is used for the button
face. If the pointer is within the PushButtonGadget, calls the call‐
backs for XmNactivateCallback. Calls the callbacks for XmNdisarmCall‐
back. 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 XmNactivateCallback and XmNdisarmCallback
callbacks. Outside a menu, KActivate has no effect. For PushButton‐
Gadgets outside of a menu, if the parent is a manager, this action
passes the event to the parent. 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 XmNactivateCallback and
XmNdisarmCallback callbacks.
Outside a menu, does the following: Draws the shadow in the armed state
and, if XmNfillOnArm is set to True, fills the button with the color
specified by XmNarmColor. If XmNlabelType is XmPIXMAP, the XmN‐
armPixmap is used for the button face. Calls the XmNarmCallback call‐
backs.
Outside a menu, this action also arranges for the following to happen,
either immediately or at a later time: The shadow is drawn in the
unarmed state and, if XmNfillOnArm is set to True, the background color
reverts to the unarmed color. If XmNlabelType is XmPIXMAP, the XmNla‐
belPixmap is used for the button face. The XmNactivateCallback and
XmNdisarmCallback callbacks are called. In a Pulldown or Popup Menu‐
Pane, unposts all menus in the menu hierarchy and restores keyboard
focus to the widget 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. In a toplevel Pull‐
down MenuPane from a MenuBar, unposts the menu, disarms the MenuBar
CascadeButton and the MenuBar, and restores keyboard focus to the wid‐
get that had the focus before the MenuBar was entered. In other Pull‐
down MenuPanes, unposts the menu.
In a Popup MenuPane, unposts the menu and restores keyboard focus to
the widget from which the menu was posted. For a PushButtonGadget out‐
side of a menu, if the parent is a manger, this action passes the event
to the parent. 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 PushButtonGadget is not in a menu and the cursor leaves and then
reenters the PushButtonGadget while the button is pressed, this action
draws the shadow in the armed state. If XmNfillOnArm is set to True,
it also fills the button with the color specified by XmNarmColor. If
XmNlabelType is XmPIXMAP, the XmNarmPixmap is used for the button face.
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 PushButtonGadget is not in a menu and the cursor leaves the
PushButtonGadget while the button is pressed, this action draws the
shadow in the unarmed state. If XmNfillOnArm is set to True, the back‐
ground color reverts to the unarmed color. If XmNlabelType is
XmPIXMAP, the XmNlabelPixmap is used for the button face.
Virtual Bindings
The bindings for virtual keys are vendor specific. For information
about bindings for virtual buttons and keys, see VirtualBindings(3X).
RELATED INFORMATIONObject(3X), RectObj(3X), XmCreatePushButtonGadget(3X), XmGadget(3X),
XmLabelGadget(3X), and XmRowColumn(3X).
XmPushButtonGadget(3X)
