XmPushButtonGadget(3Xm) XmPushButtonGadget(3Xm)
NAME
XmPushButtonGadget - the PushButtonGadget widget class.
AES SUPPORT LEVEL
full-use
SYNOPSIS
#include <Xm/PushBG.h>
DESCRIPTION
PushButtonGadget issues commands within an application.
It consists of a text label or icon surrounded by a
border shadow. When PushButtonGadget is selected, the
shadow moves to give the appearance that the
PushButtonGadget has been pressed in. When
PushButtonGadget is unselected, the shadow moves to
give the appearance that the PushButtonGadget is out.
The behavior of PushButtonGadget 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
PushButtonGadget. However, if the PushButtonGadget
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
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 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
- 1 -
XmPushButtonGadget(3Xm) XmPushButtonGadget(3Xm)
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).
XmPushButtonGadget
Name Class Type Default Access
_______________________________________________________________________________________
XmNactivateCallback XmCCallback XtCallbackList NULL C
XmNarmCallback XmCCallback caddr_t NULL C
XmNarmColor XmCArmColor Pixel dynamic CSG
XmNarmPixmap XmCArmPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG
XmNdisarmCallback XmCCallback caddr_t NULL C
XmNfillOnArm XmCFillOnArm Boolean True CSG
XmNshowAsDefault XmCShowAsDefault short 0 CSG
XmNactivateCallback
Specifies the list of callbacks that is called
when the PushButtonGadget is activated. It is
activated when the user presses and releases the
active mouse button while the pointer is inside
the PushButtonGadget. Activating PushButtonGadget
also disarms it. For this callback the reason is
XmCR_ACTIVATE.
XmNarmCallback
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 PushButtonGadget. 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 PushButtonGadget
is armed. This resource is disabled when the
PushButtonGadget is in a menu.
- 2 -
XmPushButtonGadget(3Xm) XmPushButtonGadget(3Xm)
XmNdisarmCallback
Specifies the list of callbacks that is called
when the PushButtonGadget 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.
XmNfillOnArm
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.
XmNshowAsDefault
Specifies a shadow thickness for a second shadow
to be drawn around the PushButtonGadget 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 PushButtonGadget is in a
menu.
Inherited Resources
PushButtonGadget inherits behavior and resources from
the following superclasses. For a complete description
of these resources, 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 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 0 CSG
XmNmarginHeight XmCMarginHeight short 2 CSG
- 3 -
XmPushButtonGadget(3Xm) XmPushButtonGadget(3Xm)
XmNmarginLeft XmCMarginLeft short 0 CSG
XmNmarginRight XmCMarginRight short 0 CSG
XmNmarginTop XmCMarginTop short 0 CSG
XmNmarginWidth XmCMarginWidth short 2 CSG
XmNmnemonic XmCMnemonic char `\0' CSG
XmNrecomputeSize XmCRecomputeSize Boolean True CSG
XmGadget Resource Set
Name Class Type Default Access
_________________________________________________________________________________
XmNhelpCallback XmCCallback XtCallbackList NULL C
XmNhighlightOnEnter XmCHighlightOnEnter Boolean False CSG
XmNhighlightThickness XmCHighlightThickness short 0 CSG
XmNshadowThickness XmCShadowThickness short 2 CSG
XmNtraversalOn XmCTraversalOn Boolean False CSG
XmNuserData XmCUserData caddr_t NULL CSG
RectObj Resource Set
Name Class Type Default Access
_____________________________________________________________________________
XmNancestorSensitive XmCSensitive Boolean XtCopyFromParent CSG
XmNborderWidth XmCBorderWidth Dimension 1 CSG
XmNheight XmCHeight Dimension 0 CSG
XmNsensitive XmCSensitive Boolean True CSG
XmNwidth XmCWidth Dimension 0 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
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
- 4 -
XmPushButtonGadget(3Xm) XmPushButtonGadget(3Xm)
accessed through the ArmAndActivate action
routine.
Behavior
PushButtonGadget 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 PushButtonGadget 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
gadget'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 gadget'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
- 5 -
XmPushButtonGadget(3Xm) XmPushButtonGadget(3Xm)
the mouse. The shadow is drawn in the armed
state, and the callbacks for XmNarmCallback are
called.
<Btn3Up>:
This action causes the PushButtonGadget 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 PushButtonGadget 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 PushButtonGadget to be
activated and the menu to be unposted. The
callbacks for XmNactivateCallback are called,
followed by callbacks for XmNdisarmCallback.
Default PulldownMenu System 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 PushButtonGadget 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 PushButtonGadget will be
- 6 -
XmPushButtonGadget(3Xm) XmPushButtonGadget(3Xm)
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 PushButtonGadget to be
activated and the menu to be unposted. The
callbacks for XmNactivateCallback are called,
followed by callbacks for XmNdisarmCallback.
Keyboard Traversal
For information on keyboard traversal outside of menu
systems, see the man page for XmGadget(3X) and its
sections on behavior and default translations. For
information on keyboard traversal inside of menu
systems, see XmRowColumn(3X).
RELATED INFORMATION
Object(3X), RectObj(3X), XmCreatePushButtonGadget(3X),
XmGadget(3X), XmLabelGadget(3X), and XmRowColumn(3X).
- 7 -