NAME

XmCascadeButton — the CascadeButton widget class.

SYNOPSIS

#include <Xm/CascadeB.h>

DESCRIPTION

CascadeButton links two MenuPanes or a MenuBar to a MenuPane. 

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

It is the only widget that may have a Pulldown MenuPane attached to it as a submenu.  The submenu is displayed when this widget is activated within a MenuBar, a PopupMenu, or a PulldownMenu.  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 a MenuBar. 

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

A CascadeButton’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 CascadeButton within a Pulldown or Popup MenuPane is armed as the result of the user moving the mouse pointer into the widget, 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 widget), or whether the user really wanted the submenu posted.  This time delay is configurable via XmNmappingDelay. 

CascadeButton provides a single mechanism for activating the widget from the keyboard.  This mechanism is referred to as a keyboard mnemonic.  If a mnemonic has been specified for the widget, the user may activate the CascadeButton by simply typing the mnemonic while the CascadeButton is visible.  If the CascadeButton is in a MenuBar, the meta key must be pressed with the mnemonic.  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 XmNcascaadePixmap.  XmNmarginWidth defaults to six if this resource is in a MenuBar; otherwise, it takes Label’s default, which is two. 

Classes

CascadeButton inherits behavior and resources from Core, XmPrimitive, and XmLabel classes. 

The class pointer is xmCascadeButtonWidgetClass. 

The class name is XmCascadeButton. 

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 CascadeButton widget, 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 widget.  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 widget when a CascadeButton is used within a Popup or Pulldown MenuPane and a submenu is attached.  The Label 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 CascadeButton.  The reason sent by the callback is XmCR_CASCADING. 

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

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

Inherited Resources

CascadeButton 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 CascadeButton widget depends on whether the button is part of a PopupMenu system or a PulldownMenu system.  The RowColumn parent determines the mouse button that is used through its XmNrowColumnType and XmNwhichButton resources. 

Default PopupMenu System

Btn3Down<EnterWindow>:
This action arms the CascadeButton 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 CascadeButton. If the mouse pointer has moved into the submenu, then this event is ignored. If not, the CascadeButton is disarmed and its submenu unposted.

<Btn3Up>:
This action posts the submenu attached to the CascadeButton and enables keyboard traversal within the menu. If the CascadeButton does not have a submenu attached, then this event activates the CascadeButton 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 CascadeButton is posted.

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

Default MenuBar

<Btn1Down>:
This event arms both the CascadeButton and the MenuBar and posts the associated submenu. If the menu is already active, this event disables traversal for the menu and returns the user to the mode where the menu is manipulated using the mouse.

Btn1Down<EnterWindow>:
This event unposts any visible MenuPanes if they are associated with a different MenuBar entry, arms the CascadeButton, and posts the associated submenu.

Btn1Down<LeaveWindow>:
This event disarms the CascadeButton if the submenu associated with it is not currently posted or if there is no submenu associated with this CascadeButton. Otherwise, this event is ignored.

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

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

Default PulldownMenu System from a MenuBar

Btn1Down<EnterWindow>:
This event arms the CascadeButton widget, 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 CascadeButton is disarmed and its submenu unposted.

<Btn1Up>:
This event posts the submenu attached to the CascadeButton and enables keyboard traversal within the menu. If the CascadeButton does not have a submenu attached, then this event selects the CascadeButton 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 CascadeButton is posted.

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

Default Translations

The following are default translations for CascadeButton in a MenuBar:

<BtnDown>:MenuBarSelect()
<EnterWindow>: MenuBarEnter()
<LeaveWindow>: MenuBarLeave()
<BtnUp>:DoSelect()
<Key>Return:KeySelect()
<Key>Escape:CleanupMenuBar()
Default translations for CascadeButton in a Popup or Pulldown MenuPane are:
<BtnDown>:StartDrag()
<EnterWindow>: DelayedArm()
<LeaveWindow>: CheckDisarm()
<BtnUp>:DoSelect()
<Key>Return:KeySelect()
<Key>Escape:MenuShellPopdownDone()

Keyboard Traversal

The keyboard traversal translations are listed below:

<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), XmCascadeButtonHighlight(3Xm), XmCreateCascadeButton(3Xm), XmCreateMenuBar(3Xm), XmCreatePulldownMenu(3Xm), XmCreatePopupMenu(3Xm), XmLabel(3Xm), XmPrimitive(3Xm), and XmRowColumn(3Xm). 

7th Edition