XmCascadeButton(3Xm) XmCascadeButton(3Xm)
NAME
XmCascadeButton - the CascadeButton widget class.
AES SUPPORT LEVEL
full-use
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
- 1 -
XmCascadeButton(3Xm) XmCascadeButton(3Xm)
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).
XmCascadeButton Resource Set
Name Class Type Default Access
_________________________________________________________________________________
XmNactivateCallback XmCCallback XtCallbackList NULL C
XmNcascadePixmap XmCPixmap Pixmap "menu-cascade" CSG
XmNcascadingCallback XmCCallback XtCallbackList NULL C
XmNmappingDelay XmCMappingDelay int 100 CSG
- 2 -
XmCascadeButton(3Xm) XmCascadeButton(3Xm)
XmNsubMenuId XmCMenuWidget Widget 0 CSG
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(3X), XmCreatePulldownMenu(3X), and
XmCreatePopupMenu(3X) 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
- 3 -
XmCascadeButton(3Xm) XmCascadeButton(3Xm)
superclass.
XmLabel 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 dynamic CSG
XmNmarginHeight XmCMarginHeight short 2 CSG
XmNmarginLeft XmCMarginLeft short 0 CSG
XmNmarginRight XmCMarginRight short dynamic CSG
XmNmarginTop XmCMarginTop short dynamic CSG
XmNmarginWidth XmCMarginWidth short dynamic CSG
XmNmnemonic XmCMnemonic char `\0' CSG
XmNrecomputeSize XmCRecomputeSize Boolean True CSG
XmPrimitive Resource Set
Name Class Type Default Access
______________________________________________________________________________________________
XmNbottomShadowColor XmCForeground Pixel dynamic CSG
XmNbottomShadowPixmap XmCBottomShadowPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG
XmNforeground XmCForeground Pixel dynamic CSG
XmNhelpCallback XmCCallback XtCallbackList NULL C
XmNhighlightColor XmCForeground Pixel Black CSG
XmNhighlightOnEnter XmCHighlightOnEnter Boolean False CSG
XmNhighlightPixmap XmCHighlightPixmap Pixmap dynamic CSG
XmNhighlightThickness XmCHighlightThickness short 0 CSG
XmNshadowThickness XmCShadowThickness short 2 CSG
XmNtopShadowColor XmCBackground Pixel dynamic CSG
XmNtopShadowPixmap XmCTopShadowPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG
XmNtraversalOn XmCTraversalOn Boolean False CSG
XmNuserData XmCUserData caddr_t NULL CSG
Core Resource Set
Name Class Type Default Access
____________________________________________________________________________________________
XmNaccelerators XmCAccelerators XtTranslations NULL CSG
XmNancestorSensitive XmCSensitive Boolean True G
XmNbackground XmCBackground Pixel dynamic CSG
XmNbackgroundPixmap XmCPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG
XmNborderColor XmCBorderColor Pixel Black CSG
XmNborderPixmap XmCPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG
XmNborderWidth XmCBorderWidth Dimension 0 CSG
- 4 -
XmCascadeButton(3Xm) XmCascadeButton(3Xm)
XmNcolormap XmCColormap Colormap XtCopyFromParent CG
XmNdepth XmCDepth int XtCopyFromParent CG
XmNdestroyCallback XmCCallback XtCallbackList NULL C
XmNheight XmCHeight Dimension 0 CSG
XmNmappedWhenManaged XmCMappedWhenManaged Boolean True CSG
XmNscreen XmCScreen Pointer XtCopyScreen CG
XmNsensitive XmCSensitive Boolean True CSG
XmNtranslations XmCTranslations XtTranslations NULL CSG
XmNwidth XmCWidth Dimension 0 CSG
XmNx XmCPosition Position 0 CSG
XmNy XmCPosition Position 0 CSG
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
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.
- 5 -
XmCascadeButton(3Xm) XmCascadeButton(3Xm)
<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
- 6 -
XmCascadeButton(3Xm) XmCascadeButton(3Xm)
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:
- 7 -
XmCascadeButton(3Xm) XmCascadeButton(3Xm)
<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(3X), XmCascadeButtonHighlight(3X),
XmCreateCascadeButton(3X), XmCreateMenuBar(3X),
XmCreatePulldownMenu(3X), XmCreatePopupMenu(3X),
XmLabel(3X), XmPrimitive(3X), and XmRowColumn(3X).
- 8 -