NAME

XmCascadeButtonGadget — the CascadeButtonGadget widget class.

SYNOPSIS

#include <Xm/CascadeBG.h>

DESCRIPTION

CascadeButtonGadget links two MenuPanes or an OptionMenu to a MenuPane. 

It is used in menu systems and must have a RowColumn parent with its XmNrowColumnType resource set to XmMENU_POPUP, XmMENU_PULLDOWN, or XmMENU_OPTION. 

It is the only gadget that may have a Pulldown MenuPane attached to is as a submenu.  The submenu is displayed when this gadget is activated within a PopupMenu, a PulldownMenu, or an OptionMenu.  Its visuals can include a label or pixmap and a cascading indicator when it is in a Popop or Pulldown MenuPane; or, it can include only a label or a pixmap when it is in an OptionMenu. 

The default behavior associated with a CascadeButtonGadget depends on the type of menu system in which it resides.  By default, mouse button 1 controls the behavior of the CascadeButtonGadget if it resides in a PulldownMenu or an OptionMenu; and, mouse button 3 controls the behavior of the CascadeButtonGadget if it resides in a PopupMenu.  The actual mouse button used is determined by its RowColumn parent. 

A CascadeButtonGadget’s visuals differ from most other button gadgets.  When the button becomes armed, its visuals change from a 2-D to a 3-D look, and it displays the submenu that has been attached to it.  If no submenu is attached, then it simply changes its visuals. 

When a CascadeButtonGadget within a Pulldown or Popup MenuPane is armed as the result of the user moving the mouse pointer into the gadget, it does not immediately display its submenu.  Instead, it waits a short amount of time to see if the arming was temporary (i.e., the user was simply passing through the gadget), or whether the user really wanted the submenu posted.  This time delay is configurable via XmNmappingDelay. 

CascadeButtonGadget provides a single mechanism for activating the gadget from the keyboard.  This mechanism is referred to as a keyboard mnemonic.  If a mnemonic has been specified for the gadget, the user may activate it by simply typing the mnemonic while the CascadeButtonGadget is visible.  Mnemonics are typically used to interact with a menu via the keyboard interface. 

If in a Pulldown or Popup MenuPane and there is a submenu attached, the XmNmarginBottom, XmNmarginRight, and XmNmarginTop resources enlarge to accommodate XmNcascadePixmap. 

Classes

CascadeButtonGadget inherits behavior and resources from Object, RectObj, XmGadget, and XmLabelGadget classes. 

The class pointer is xmCascadeButtonGadgetClass. 

The class name is XmCascadeButtonGadget. 

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 user activates the CascadeButtonGadget, and there is no submenu attached to pop up.  The activation occurs by releasing a mouse button or by typing the mnemonic associated with the gadget.  The specific mouse button depends on information in the RowColumn parent.  The reason sent by the callback is XmCR_ACTIVATE. 

XmNcascadePixmap
Specifies the cascade pixmap displayed on the right end of the gadget when a CascadeButtonGadget is used within a Popup or Pulldown MenuPane and a submenu is attached. The LabelGadget class resources XmNmarginRight, XmNmarginTop, and XmNmarginBottom may be modified to ensure room is left for the cascade pixmap.  The default cascade pixmap is an arrow pointing to the right. 

XmNcascadingCallback
Specifies the list of callbacks that is called just prior to the mapping of the submenu associated with the CascadeButtonGadget.  The reason sent by the callback is XmCR_CASCADING. 

XmNmappingDelay
Specifies the amount of time, in milliseconds, between when a CascadeButtonGadget becomes armed and when it maps its submenu.  This delay is only used when the gadget is within a Popup or Pulldown MenuPane.

XmNsubMenuId
Specifies the widget ID for the Pulldown MenuPane to be associated with this CascadeButtonGadget.  The specified MenuPane is displayed when the CascadeButtonGadget becomes armed.  The MenuPane must have been created with the appropriate parentage depending on the type of menu used.  See XmCreatePulldownMenu(3Xm), XmCreatePopupMenu(3Xm), and XmCreateOptionMenu(3Xm) for more information on the menu systems. 

Inherited Resources

CascadeButtonGadget 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 or is NULL if this callback was not triggered due to an XEvent. 

Behavior

The default behavior associated with a CascadeButtonGadget depends on whether the button is part of a PopupMenu system, a Pulldown MenuPane in a MenuBar, or an OptionMenu system.  The RowColumn parent determines the mouse button which is used through its XmNrowColumnType and XmNwhichButton resources. 

Default PopupMenu System

Btn3Down<EnterWindow>:
This action arms the CascadeButtonGadget and posts the associated submenu after a short delay.

Btn3Down<LeaveWindow>:
The action that takes place depends on whether the mouse pointer has moved into the submenu associated with this CascadeButtonGadget. If the mouse pointer has moved into the submenu, then this event is ignored. If not, the CascadeButtonGadget is disarmed and its submenu unposted.

<Btn3Up>:
This action posts the submenu attached to the CascadeButtonGadget and enables keyboard traversal within the menu. If the CascadeButtonGadget does not have a submenu attached, then this event activates the CascadeButtonGadget and unposts the menu.

<Btn3Down>:
This action disables traversal for the menu and returns the user to drag mode in which the menu is manipulated using the mouse. The submenu associated with this CascadeButtonGadget is posted.

<Key>Return:
This event posts the submenu attached to the CascadeButtonGadget if keyboard traversal is enabled in the menu. If the CascadeButtonGadget does not have a submenu attached, then this event activates the CascadeButtonGadget and unposts the menu.

Default Pulldown MenuPane from a MenuBar or from an OptionMenu

Btn1Down<EnterWindow>:
This event arms the CascadeButtonGadget, and after a short delay, posts the associated submenu.

Btn1Down<LeaveWindow>:
The event is ignored if the mouse pointer has moved into the submenu. In all other cases, the CascadeButtonGadget is disarmed and its submenu unposted.

<Btn1Up>:
This event posts the submenu attached to the CascadeButtonGadget and enables keyboard traversal within the menu. If the CascadeButtonGadget does not have a submenu attached, then this event activates the CascadeButtonGadget and unposts the menu.

<Btn1Down>:
This event disables traversal for the menu and returns the user to the drag mode. The submenu associated with this CascadeButtonGadget is posted.

<Key>Return:
This event posts the submenu attached to the CascadeButtonGadget if keyboard traversal is enabled in the menu. If the CascadeButtonGadget does not have a submenu attached, then this event activates the CascadeButtonGadget and unposts the menu.

Default OptionMenu

<Btn1Down>:
This event arms the CascadeButtonGadget and posts the associated submenu.

<Key>Return:
This event posts the associated submenu and enables traversal within the menu.

Keyboard Traversal

For information on keyboard traversal, see the man page for XmRowColumn(3Xm) and its sections on behavior and default translations. 

RELATED INFORMATION

Object(3Xm), RectObj(3Xm), XmCascadeButtonHighlight(3), XmCreateCascadeButtonGadget(3Xm), XmCreatePulldownMenu(3Xm), XmCreatePopupMenu(3Xm), XmCreateOptionMenu(3Xm), XmGadget(3Xm), XmLabelGadget(3Xm), and XmRowColumn(3Xm). 

7th Edition