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

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. 

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. 

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

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(3Xm) and its sections on behavior and default translations.  For information on keyboard traversal inside of menu systems, see XmRowColumn(3Xm). 

RELATED INFORMATION

Object(3Xm), RectObj(3Xm), XmCreatePushButtonGadget(3Xm), XmGadget(3Xm), XmLabelGadget(3Xm), and XmRowColumn(3Xm). 

7th Edition