XmPushButtonGadget(Xm) UNIX System V
NAME
XmPushButtonGadget - the PushButtonGadget widget class.
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 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 XmCRACTIVATE.
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 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 PushButtonGadget is armed.
This resource is disabled when the PushButtonGadget is
in a menu.
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 XmCRDISARM.
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
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
XmNstringDirection XmCStringDirection XmStringDirection XmSTRING_DIRECTION_L_TO_R 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
XmNunitType XmCUnitType unsigned char XmPIXELS 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 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 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 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(Xm) and its sections
on behavior and default translations. For information on
keyboard traversal inside of menu systems, see
XmRowColumn(Xm).
RELATED INFORMATION
Object(Xm), RectObj(Xm), XmCreatePushButtonGadget(Xm),
XmGadget(Xm), XmLabelGadget(Xm), and XmRowColumn(Xm).
(printed 2/14/90) XmPushButtonGadget(Xm)