XmPushButton(3X)XmPushButton(3X)NAMEXmPushButton - The PushButton widget class
SYNOPSIS
#include <Xm/PushB.h>
DESCRIPTION
PushButton issues commands within an application. It consists of a text
label or pixmap surrounded by a border shadow. When a PushButton is
selected, the shadow changes to give the appearance that it has been
pressed in. When a PushButton is unselected, the shadow changes to
give the appearance that it is out.
The default behavior associated with a PushButton in a menu depends on
the type of menu system in which it resides. By default, BSelect con‐
trols the behavior of the PushButton. In addition, BMenu controls the
behavior of the PushButton if it resides in a PopupMenu system. The
actual mouse button used is determined by its RowColumn parent.
Thickness for a second shadow, used when the PushButton is the default
button, may be specified by using the XmNshowAsDefault resource. If
it has a non-zero value, the Label's resources XmNmarginLeft, XmN‐
marginRight, 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
PushButton inherits behavior and resources from Core, XmPrimitive, and
XmLabel Classes.
The class pointer is xmPushButtonWidgetClass.
The class name is XmPushButton.
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).
XmPushButton Resource Set
Class: XmCCallback
Default: NULL
Type: XtCallbackList
Access: C
Class: XmCCallback
Default: NULL
Type: XtCallbackList
Access: C
Class: XmCArmColor
Default: dynamic
Type: Pixel
Access: CSG
Class: XmCArmPixmap
Default: XmUNSPECIFIED_PIXMAP
Type: Pixmap
Access: CSG
Class: XmCDefaultButtonShadowThickness
Default: dynamic
Type: Dimension
Access: CSG
Class: XmCCallback
Default: NULL
Type: XtCallbackList
Access: C
Class: XmCFillOnArm
Default: True
Type: Boolean
Access: CSG
Class: XmCMultiClick
Default: dynamic
Type: unsigned char
Access: CSG
Class: XmCShowAsDefault
Default: 0
Type: Dimension
Access: CSG
Specifies the list of callbacks that is called when PushButton
is activated. PushButton is activated when the user presses and
releases the active mouse button while the pointer is inside
that widget. Activating the PushButton also disarms it. For
this callback the reason is XmCR_ACTIVATE. Specifies the list
of callbacks that is called when PushButton is armed. PushButton
is armed when the user presses the active mouse button while the
pointer is inside that widget. For this callback the reason is
XmCR_ARM. Specifies the color with which to fill the armed but‐
ton. XmNfillOnArm must be set to True for this resource to have
an effect. The 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, 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 PushButton is armed. This
resource is disabled when the PushButton 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 XmNshowAsDefault. Speci‐
fies the list of callbacks that is called when PushButton is
disarmed. PushButton is disarmed when the user presses and
releases the active mouse button while the pointer is inside
that widget. For this callback, the reason is XmCR_DISARM.
Forces the PushButton 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 PushButton is in a
menu, this resource is ignored and assumed to be False. If a
button click is followed by another button click within the time
span specified by the display's multi-click time, and this
resource is set to XmMULTICLICK_DISCARD, do not process the sec‐
ond 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_DIS‐
CARD; otherwise, for a button not in a menu, XmMULTICLICK_KEEP
is the default value. If XmNdefaultButtonShadowThickness is
greater than zero, a value greater than zero in this resource
specifies to mark this button as the default button. If XmNde‐
faultButtonShadowThickness is zero, a value greater than zero in
this resource specifies to mark this button as the default but‐
ton 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 XmNmarginLeft, 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
PushButton inherits behavior and resources from the following super‐
classes. For a complete description of each resource, refer to the man
page for that superclass.
XmLabel 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: dynamic
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: dynamic
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: XmFONTLIST_DEFAULT_TAG
Type: String
Access: CSG
Class: XmCRecomputeSize
Default: True
Type: Boolean
Access: CSG
Class: XmCStringDirection
Default: dynamic
Type: XmStringDirection
Access: CSG
XmPrimitive Resource Set
Class: XmCBottomShadowColor
Default: dynamic
Type: Pixel
Access: CSG
Class: XmCBottomShadowPixmap
Default: XmUNSPECIFIED_PIXMAP
Type: Pixmap
Access: CSG
Class: XmCForeground
Default: dynamic
Type: Pixel
Access: CSG
Class: XmCCallback
Default: NULL
Type: XtCallbackList
Access: C
Class: XmCHighlightColor
Default: dynamic
Type: Pixel
Access: CSG
Class: XmCHighlightOnEnter
Default: False
Type: Boolean
Access: CSG
Class: XmCHighlightPixmap
Default: dynamic
Type: Pixmap
Access: CSG
Class: XmCHighlightThickness
Default: 2
Type: Dimension
Access: CSG
Class: XmCNavigationType
Default: XmNONE
Type: XmNavigationType
Access: CSG
Class: XmCShadowThickness
Default: 2
Type: Dimension
Access: CSG
Class: XmCTopShadowColor
Default: dynamic
Type: Pixel
Access: CSG
Class: XmCTopShadowPixmap
Default: dynamic
Type: Pixmap
Access: CSG
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
Core Resource Set
Class: XmCAccelerators
Default: dynamic
Type: XtAccelerators
Access: CSG
Class: XmCSensitive
Default: dynamic
Type: Boolean
Access: G
Class: XmCBackground
Default: dynamic
Type: Pixel
Access: CSG
Class: XmCPixmap
Default: XmUNSPECIFIED_PIXMAP
Type: Pixmap
Access: CSG
Class: XmCBorderColor
Default: XtDefaultForeground
Type: Pixel
Access: CSG
Class: XmCPixmap
Default: XmUNSPECIFIED_PIXMAP
Type: Pixmap
Access: CSG
Class: XmCBorderWidth
Default: 0
Type: Dimension
Access: CSG
Class: XmCColormap
Default: dynamic
Type: Colormap
Access: CG
Class: XmCDepth
Default: dynamic
Type: int
Access: CG
Class: XmCCallback
Default: NULL
Type: XtCallbackList
Access: C
Class: XmCHeight
Default: dynamic
Type: Dimension
Access: CSG
Class: XmCInitialResourcesPersistent
Default: True
Type: Boolean
Access: C
Class: XmCMappedWhenManaged
Default: True
Type: Boolean
Access: CSG
Class: XmCScreen
Default: dynamic
Type: Screen *
Access: CG
Class: XmCSensitive
Default: True
Type: Boolean
Access: CSG
Class: XmCTranslations
Default: dynamic
Type: XtTranslations
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
Callback Information
A pointer to the following structure is passed to each callback:
typedef struct {
int reason;
XEvent * event;
int click_count; } XmPushButtonCallbackStruct;
Indicates why the callback was invoked. Points to the XEvent that
triggered the callback. 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 contains 1. The activate callback is invoked for each
click if XmNmultiClick is set to XmMULTICLICK_KEEP.
Translations
XmPushButton includes translations from Primitive.
Note that altering translations in #override or #augment mode is unde‐
fined.
Additional XmPushButton translations for XmPushButtons not in a menu
system are listed below. These translations may not directly correspond
to a translation table.
BDrag Press: ProcessDrag() BSelect Press: Arm() BSelect Click: Acti‐
vate()Disarm() BSelect Release:Activate()Disarm() BSelect Press 2+:MultiArm() BSelect Release
2+:MultiActivate()Disarm() KSelect: ArmAndActivate() KHelp:
Help()XmPushButton inherits menu traversal translations from XmLabel. Addi‐
tional XmPushButton translations for PushButtons in a menu system are
listed below. In a Popup menu system, BMenu also performs the BSelect
actions. These translations may not directly correspond to a transla‐
tion table.
BSelect Press: BtnDown() BSelect Release:BtnUp() KActivate: ArmAn‐
dActivate() KSelect: ArmAndActivate() MAny KCancel:
MenuShellPopdownOne()
Action Routines
The XmPushButton action routines are described below: This action 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 still within the button, this
action calls the callbacks for XmNactivateCallback. This action arms
the PushButton. It draws the shadow in the armed state. If the button
is not in a menu and if XmNfillOnArm is set to True, it fills the but‐
ton with the color specified by XmNarmColor. If XmNlabelType is
XmPIXMAP, the XmNarmPixmap is used for the button face. It calls the
XmNarmCallback callbacks. 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 XmNdis‐
armCallback callbacks.
Outside a menu, does the following: Draws the shadow in the
armed state and, if XmNfillOnArm is set to True, fills the but‐
ton with the color specified by XmNarmColor. If XmNlabelType is
XmPIXMAP, the XmNarmPixmap is used for the button face. Calls
the XmNarmCallback callbacks.
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 XmNlabel‐
Type is XmPIXMAP, the XmNlabelPixmap is used for the button
face. The XmNactivateCallback and XmNdisarmCallback callbacks
are called. This action unposts any menus posted by the Push‐
Button'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. This action unposts all menus in
the menu hierarchy and activates the PushButton. It calls the
XmNactivateCallback callbacks and then the XmNdisarmCallback
callbacks. Calls the callbacks for XmNdisarmCallback. In a
Pulldown or Popup MenuPane, unposts all menus in the menu hier‐
archy and, when the shell's keyboard focus policy is XmEXPLICT,
restores keyboard focus to the widget that had the focus before
the menu system was entered. Calls the callbacks for XmNhelp‐
Callback 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 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.
In a Popup MenuPane, unposts the menu and restores keyboard
focus to the widget from which the menu was posted. If XmNmul‐
tiClick is XmMULTICLICK_DISCARD, this action does nothing.
If XmNmultiClick is XmMULTICLICK_KEEP, this action does the fol‐
lowing: 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 XmNla‐
belPixmap is used for the button face. If the pointer is within
the PushButton, calls the callbacks for XmNactivateCallback.
Calls the callbacks for XmNdisarmCallback. If XmNmultiClick is
XmMULTICLICK_DISCARD, this action does nothing.
If XmNmultiClick is XmMULTICLICK_KEEP, this action does the fol‐
lowing: Draws the shadow in the armed state. If the button is
not in a menu and if XmNfillOnArm is set to True, fills the but‐
ton with the color specified by XmNarmColor. If XmNlabelType is
XmPIXMAP, the XmNarmPixmap is used for the button face. Calls
the XmNarmCallback callbacks. Drags the contents of a PushBut‐
ton 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 Push‐
Buttons used in a menu system.
Additional Behavior
This widget has the additional behavior described below: 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 call‐
backs.
If the PushButton is not in a menu and the cursor leaves and
then reenters the PushButton's window 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 key‐
board traversal is enabled, this action does nothing. Otherwise,
it draws the shadow in the unarmed state and calls the XmNdis‐
armCallback callbacks.
If the PushButton is not in a menu and the cursor leaves the
PushButton's window while the button is pressed, this action
draws the shadow in the unarmed state. If XmNfillOnArm is set to
True, the background color reverts to the unarmed color. If XmN‐
labelType 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).
SEE ALSOCore(3X), XmCreatePushButton(3X), XmLabel(3X), XmPrimitive(3X), XmRow‐
Column(3X)XmPushButton(3X)
