XmPushButton(Xm) UNIX System V
NAME
XmPushButton - 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 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 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 XmCRACTIVATE.
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
XmCRARM.
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.
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 XmCRDISARM.
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
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
XmNstringDirection XmCStringDirection XmStringDirection XmSTRING_DIRECTION_L_TO_R 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
XmNunitType XmCUnitType unsigned char XmPIXELS 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
{
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
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 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()
Keyboard Traversal
For information on keyboard traversal when not in a menu
system, see the man page for XmPrimitive(Xm) 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(Xm), XmCreatePushButton(Xm), XmLabel(Xm),
XmPrimitive(Xm), and XmRowColumn(Xm).
(printed 2/14/90) XmPushButton(Xm)