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). 

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. 

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. 

Callback Information

The following structure is returned with each callback:

typedef struct
{
intreason;
XEvent∗ event;
} XmAnyCallbackStruct;

reasonIndicates why the callback was invoked. 

eventPoints 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(3Xm) 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(3Xm), XmCreatePushButton(3Xm), XmLabel(3Xm), XmPrimitive(3Xm), and XmRowColumn(3Xm). 

7th Edition