XmPushButton(3Xm) XmPushButton(3Xm)
NAME
XmPushButton - the PushButton widget class.
AES SUPPORT LEVEL
full-use
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 PushButton is selected, the shadow
moves to give the appearance that it has been pressed
in. When PushButton is unselected, the shadow moves to
give the appearance that it is out.
The behavior of PushButton differs, depending on the
active mouse button. The active mouse button may be
determined by the parent widget. Normally, mouse button
1 is used to arm and activate the PushButton. However,
if the PushButton resides within a menu, then the mouse
button used is determined by the RowColumn resources
XmNrowColumnType and XmNwhichButton.
Thickness for a second shadow may be specified by using
the XmNshowAsDefault 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.
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 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
- 1 -
XmPushButton(3Xm) XmPushButton(3Xm)
Xm prefix and use the remaining letters (in either
lower case or upper case, 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
Name 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
XmNdisarmCallback XmCCallback XtCallbackList NULL C
XmNfillOnArm XmCFillOnArm Boolean True CSG
XmNshowAsDefault XmCShowAsDefault short 0 CSG
XmNactivateCallback
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.
XmNarmCallback
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.
XmNarmColor
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 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 will appear in
the background color when the button is armed.
XmNarmPixmap
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.
- 2 -
XmPushButton(3Xm) XmPushButton(3Xm)
XmNdisarmCallback
Specifies 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.
XmNfillOnArm
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.
XmNshowAsDefault
Specifies a shadow thickness for a second shadow
to be drawn around the PushButton to visually mark
it as a default button. 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 superclasses. For a complete description of
these resources, refer to the man page for that
superclass.
XmLabel Resource Set
Name Class Type Default Access
_____________________________________________________________________________________________________
XmNaccelerator XmCAccelerator String NULL CSG
XmNacceleratorText XmCAcceleratorText XmString NULL CSG
XmNalignment XmCAlignment unsigned char XmALIGNMENT_CENTER CSG
XmNfontList XmCFontList XmFontList "Fixed" CSG
XmNlabelInsensitivePixmap XmCLabelInsensitivePixmap Pixmap XmUNSPECIFIED_PIXMAP CSG
XmNlabelPixmap XmCPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG
XmNlabelString XmCXmString XmString NULL CSG
XmNlabelType XmCLabelType unsigned char XmSTRING CSG
XmNmarginBottom XmCMarginBottom short dynamic CSG
XmNmarginHeight XmCMarginHeight short 2 CSG
XmNmarginLeft XmCMarginLeft short dynamic CSG
- 3 -
XmPushButton(3Xm) XmPushButton(3Xm)
XmNmarginRight XmCMarginRight short dynamic CSG
XmNmarginTop XmCMarginTop short dynamic CSG
XmNmarginWidth XmCMarginWidth short 2 CSG
XmNmnemonic XmCMnemonic char `\0' CSG
XmNrecomputeSize XmCRecomputeSize Boolean True CSG
XmPrimitive Resource Set
Name Class Type Default Access
______________________________________________________________________________________________
XmNbottomShadowColor XmCForeground Pixel dynamic CSG
XmNbottomShadowPixmap XmCBottomShadowPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG
XmNforeground XmCForeground Pixel dynamic CSG
XmNhelpCallback XmCCallback XtCallbackList NULL C
XmNhighlightColor XmCForeground Pixel Black CSG
XmNhighlightOnEnter XmCHighlightOnEnter Boolean False CSG
XmNhighlightPixmap XmCHighlightPixmap Pixmap dynamic CSG
XmNhighlightThickness XmCHighlightThickness short 0 CSG
XmNshadowThickness XmCShadowThickness short 2 CSG
XmNtopShadowColor XmCBackground Pixel dynamic CSG
XmNtopShadowPixmap XmCTopShadowPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG
XmNtraversalOn XmCTraversalOn Boolean False CSG
XmNuserData XmCUserData caddr_t NULL CSG
Core Resource Set
Name Class Type Default Access
____________________________________________________________________________________________
XmNaccelerators XmCAccelerators XtTranslations NULL CSG
XmNancestorSensitive XmCSensitive Boolean True G
XmNbackground XmCBackground Pixel dynamic CSG
XmNbackgroundPixmap XmCPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG
XmNborderColor XmCBorderColor Pixel Black CSG
XmNborderPixmap XmCPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG
XmNborderWidth XmCBorderWidth Dimension 0 CSG
XmNcolormap XmCColormap Colormap XtCopyFromParent CG
XmNdepth XmCDepth int XtCopyFromParent CG
XmNdestroyCallback XmCCallback XtCallbackList NULL C
XmNheight XmCHeight Dimension 0 CSG
XmNmappedWhenManaged XmCMappedWhenManaged Boolean True CSG
XmNscreen XmCScreen Pointer XtCopyScreen CG
XmNsensitive XmCSensitive Boolean True CSG
XmNtranslations XmCTranslations XtTranslations NULL CSG
XmNwidth XmCWidth Dimension 0 CSG
XmNx XmCPosition Position 0 CSG
XmNy XmCPosition Position 0 CSG
Callback Information
The following structure is returned with each callback:
typedef struct
{
- 4 -
XmPushButton(3Xm) XmPushButton(3Xm)
int reason;
XEvent * event;
} XmAnyCallbackStruct;
reason Indicates why the callback was invoked.
event Points to the XEvent that triggered the
callback. This event will be NULL for the
XmNactivateCallback if the callback was
triggered when Primitive's resource
XmNtraversalOn was True or if the callback was
accessed through the ArmAndActivate action
routine.
Behavior
PushButton is associated with the default behavior
unless it is part of a menu system. In a menu system,
the RowColumn parent determines which mouse button is
used.
Default Behavior
<Btn1Down>:
This action causes the PushButton to be armed.
The shadow is drawn in the armed state, and the
button is filled with the color specified by
XmNarmColor if XmNfillOnArm is set to True. The
callbacks for XmNarmCallback are also called.
<Btn1Up>:
(in button): This action redraws the shadow in
the unarmed state. The background color will
revert to the unarmed color if XmNfillOnArm is set
to True. The callbacks for XmNactivateCallback
are called, followed by callbacks for
XmNdisarmCallback.
(outside of button): This action causes the
callbacks for XmNdisarmCallback to be called.
<Leave Window>:
If the button is pressed and the cursor leaves the
widget's window, the shadow is redrawn in its
unarmed state, and the background color will
revert to the unarmed color if XmNfillOnArm is set
to True.
<Enter Window>:
If the button is pressed and the cursor leaves and
- 5 -
XmPushButton(3Xm) XmPushButton(3Xm)
reenters the widget's window, the shadow is drawn
in the armed state, and the button is filled with
the color specified by XmNarmColor if XmNfillOnArm
is set to True.
Default PopupMenu System
<Btn3Down>:
This action disables keyboard traversal for the
menu and returns the user to drag mode, which is
the mode in which the menu is manipulated by using
the mouse. The shadow is drawn in the armed
state, and the callbacks for XmNarmCallback are
called.
<Btn3Up>:
This action causes the PushButton to be activated
and the menu to be unposted. The callbacks for
XmNactivateCallback are called, followed by
callbacks for XmNdisarmCallback.
<Leave Window>:
If button 3 is pressed and the cursor leaves the
widget's window, the PushButton will be redrawn
with no shadow. The callbacks for
XmNdisarmCallback are called. If keyboard
traversal is enabled in the menu, then this event
is ignored.
<Enter Window>:
If button 3 is pressed and the cursor enters the
widget's window, the shadow will be drawn in the
armed state. The callbacks for XmNarmCallback are
called. If keyboard traversal is enabled in the
menu, then this event is ignored.
<Key>Return:
If keyboard traversal is enabled in the menu, then
this event will cause the PushButton to be
activated and the menu to be unposted. The
callbacks for XmNactivateCallback are called,
followed by callbacks for XmNdisarmCallback.
Default PulldownMenu and OptionMenu System
<Btn1Down>:
This action disables keyboard traversal for the
menu and returns the user to drag mode, which is
the mode in which the menu is manipulated by using
the mouse. The shadow is drawn in the armed
- 6 -
XmPushButton(3Xm) XmPushButton(3Xm)
state, and the callbacks for XmNarmCallback are
called.
<Btn1Up>:
This action causes the PushButton to be activated
and the menu to be unposted. The callbacks for
XmNactivateCallback are called, followed by
callbacks for XmNdisarmCallback.
<Leave Window>:
If mouse button 1 is pressed and the cursor leaves
the widget's window, the PushButton will be
redrawn with no shadow. The callbacks for
XmNdisarmCallback are called. If keyboard
traversal is enabled in the menu, then this event
is ignored.
<Enter Window>:
If mouse button 1 is pressed and the cursor enters
the widget's window, the shadow will be drawn in
the armed state. The callbacks for XmNarmCallback
are called. If keyboard traversal is enabled in
the menu, then this event is ignored.
<Key>Return:
If keyboard traversal is enabled in the menu, then
this event will cause the PushButton to be
activated and the menu to be unposted. The
callbacks for XmNactivateCallback are called,
followed by callbacks for XmNdisarmCallback.
Default Translations
When not in a menu system, the following are PushButton's default translations:
<Btn1Down>: Arm()
<Btn1Up>: Activate()
Disarm()
<Key>Return: ArmAndActivate()
<Key>space: ArmAndActivate()
<EnterWindow>: Enter()
<LeaveWindow>: Leave()
When in a menu system, the following are PushButton's default translations:
<BtnDown>: BtnDown()
<BtnUp>: BtnUp()
<EnterWindow>: Enter()
<LeaveWindow>: Leave()
<Key>Return: KeySelect()
<Key>Escape: MenuShellPopdownDone()
- 7 -
XmPushButton(3Xm) XmPushButton(3Xm)
Keyboard Traversal
For information on keyboard traversal when not in a
menu system, see the man page for XmPrimitive(3X) and
its sections on behavior and default translations.
When in a menu system, the following keyboard traversal
translations are defined:
<Unmap>: Unmap()
<FocusOut>: FocusOut()
<FocusIn>: FocusIn()
<Key>space: Noop()
<Key>Left: MenuTraverseLeft()
<Key>Right: MenuTraverseRight()
<Key>Up: MenuTraverseUp()
<Key>Down: MenuTraverseDown()
<Key>Home: Noop()
RELATED INFORMATION
Core(3X), XmCreatePushButton(3X), XmLabel(3X),
XmPrimitive(3X), and XmRowColumn(3X).
- 8 -