XmCascadeButton(3X) UNIX System V XmCascadeButton(3X)
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 can 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 Popup 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, BSelect controls the
behavior of the CascadeButton. In addition, BMenu controls the behavior
of the CascadeButton if it resides in a PopupMenu system. 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, 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 (that is, 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 and the MenuBar does not
have the focus, the MAlt modifier 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, XmNmarginLeft, XmNmarginRight, and XmNmarginTop
resources may enlarge to accommodate XmNcascadePixmap. XmNmarginWidth
10/89 Page 1
XmCascadeButton(3X) UNIX System V XmCascadeButton(3X)
defaults to 6 if this resource is in a MenuBar; otherwise, it takes
Label's default, which is 2.
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 lowercase or uppercase, 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 | dynamic| CSG |
|_____________________|_________________|________________|_________|________|
| XmNcascadingCallback| XmCCallback | XtCallbackList| NULL | C |
|_____________________|_________________|________________|_________|________|
| XmNmappingDelay | XmCMappingDelay| int | 180 ms | CSG |
|_____________________|_________________|________________|_________|________|
| XmNsubMenuId | XmCMenuWidget | Widget | NULL | 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.
Page 2 10/89
XmCascadeButton(3X) UNIX System V XmCascadeButton(3X)
XmNcascadePixmap
Specifies the cascade pixmap displayed on one end of the widget
when a CascadeButton is used within a Popup or Pulldown MenuPane
and a submenu is attached. The Label class resources
XmNmarginBottom, XmNmarginLeft, XmNmarginRight, and XmNmarginTop
may be modified to ensure that room is left for the cascade pixmap.
The default cascade pixmap is an arrow pointing to the side of the
menu where the submenu will appear.
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 used only when the widget is within a Popup or Pulldown
MenuPane. The value must not be negative.
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 each resource, refer to the
man page for that superclass.
10/89 Page 3
XmCascadeButton(3X) UNIX System V XmCascadeButton(3X)
___________________________________________________________________________________________________________
| XmLabel Resource Set |
|_________________________|___________________________|___________________|______________________|________|
|Name | Class | Type | Default | Access|
|_________________________|___________________________|___________________|______________________|________|
|_________________________|___________________________|___________________|______________________|________|
|XmNaccelerator | XmCAccelerator | String | NULL | N/A |
|_________________________|___________________________|___________________|______________________|________|
|XmNacceleratorText | XmCAcceleratorText | XmString | NULL | N/A |
|_________________________|___________________________|___________________|______________________|________|
|XmNalignment | XmCAlignment | unsigned char | dynamic | CSG |
|_________________________|___________________________|___________________|______________________|________|
|XmNfontList | XmCFontList | XmFontList | dynamic | CSG |
|_________________________|___________________________|___________________|______________________|________|
|XmNlabelInsensitivePixmap| XmCLabelInsensitivePixmap| Pixmap | XmUNSPECIFIED_PIXMAP| CSG |
|_________________________|___________________________|___________________|______________________|________|
|XmNlabelPixmap | XmCLabelPixmap | Pixmap | XmUNSPECIFIED_PIXMAP| CSG |
|_________________________|___________________________|___________________|______________________|________|
|XmNlabelString | XmCXmString | XmString | dynamic | CSG |
|_________________________|___________________________|___________________|______________________|________|
|XmNlabelType | XmCLabelType | unsigned char | XmSTRING | CSG |
|_________________________|___________________________|___________________|______________________|________|
|XmNmarginBottom | XmCMarginBottom | Dimension | dynamic | CSG |
|_________________________|___________________________|___________________|______________________|________|
|XmNmarginHeight | XmCMarginHeight | Dimension | 2 | CSG |
|_________________________|___________________________|___________________|______________________|________|
|XmNmarginLeft | XmCMarginLeft | Dimension | 0 | CSG |
|_________________________|___________________________|___________________|______________________|________|
|XmNmarginRight | XmCMarginRight | Dimension | dynamic | CSG |
|_________________________|___________________________|___________________|______________________|________|
|XmNmarginTop | XmCMarginTop | Dimension | dynamic | CSG |
|_________________________|___________________________|___________________|______________________|________|
|XmNmarginWidth | XmCMarginWidth | Dimension | 2 | CSG |
|_________________________|___________________________|___________________|______________________|________|
|XmNmnemonic | XmCMnemonic | KeySym | NULL | CSG |
|_________________________|___________________________|___________________|______________________|________|
|XmNmnemonicCharSet | XmCMnemonicCharSet | String | dynamic | CSG |
|_________________________|___________________________|___________________|______________________|________|
|XmNrecomputeSize | XmCRecomputeSize | Boolean | True | CSG |
|_________________________|___________________________|___________________|______________________|________|
|XmNstringDirection | XmCStringDirection | XmStringDirection| dynamic | CSG |
|_________________________|___________________________|___________________|______________________|________|
Page 4 10/89
XmCascadeButton(3X) UNIX System V XmCascadeButton(3X)
__________________________________________________________________________________________________
| XmPrimitive Resource Set |
|_____________________|_______________________|__________________|______________________|________|
|Name | Class | Type | Default | Access|
|_____________________|_______________________|__________________|______________________|________|
|_____________________|_______________________|__________________|______________________|________|
|XmNbottomShadowColor | XmCBottomShadowColor | Pixel | dynamic | CSG |
|_____________________|_______________________|__________________|______________________|________|
|XmNbottomShadowPixmap| XmCBottomShadowPixmap| Pixmap | XmUNSPECIFIED_PIXMAP| CSG |
|_____________________|_______________________|__________________|______________________|________|
|XmNforeground | XmCForeground | Pixel | dynamic | CSG |
|_____________________|_______________________|__________________|______________________|________|
|XmNhelpCallback | XmCCallback | XtCallbackList | NULL | C |
|_____________________|_______________________|__________________|______________________|________|
|XmNhighlightColor | XmCHighlightColor | Pixel | dynamic | CSG |
|_____________________|_______________________|__________________|______________________|________|
|XmNhighlightOnEnter | XmCHighlightOnEnter | Boolean | False | CSG |
|_____________________|_______________________|__________________|______________________|________|
|XmNhighlightPixmap | XmCHighlightPixmap | Pixmap | dynamic | CSG |
|_____________________|_______________________|__________________|______________________|________|
|XmNhighlightThickness| XmCHighlightThickness| Dimension | 2 | CSG |
|_____________________|_______________________|__________________|______________________|________|
|XmNnavigationType | XmCNavigationType | XmNavigationType| XmNONE | G |
|_____________________|_______________________|__________________|______________________|________|
|XmNshadowThickness | XmCShadowThickness | Dimension | 2 | CSG |
|_____________________|_______________________|__________________|______________________|________|
|XmNtopShadowColor | XmCTopShadowColor | Pixel | dynamic | CSG |
|_____________________|_______________________|__________________|______________________|________|
|XmNtopShadowPixmap | XmCTopShadowPixmap | Pixmap | dynamic | CSG |
|_____________________|_______________________|__________________|______________________|________|
|XmNtraversalOn | XmCTraversalOn | Boolean | True | CSG |
|_____________________|_______________________|__________________|______________________|________|
|XmNunitType | XmCUnitType | unsigned char | dynamic | CSG |
|_____________________|_______________________|__________________|______________________|________|
|XmNuserData | XmCUserData | Pointer | NULL | CSG |
|_____________________|_______________________|__________________|______________________|________|
10/89 Page 5
XmCascadeButton(3X) UNIX System V XmCascadeButton(3X)
________________________________________________________________________________________________________________
| Core Resource Set |
|_____________________________|_______________________________|________________|______________________|________|
|Name | Class | Type | Default | Access|
|_____________________________|_______________________________|________________|______________________|________|
|_____________________________|_______________________________|________________|______________________|________|
|XmNaccelerators | XmCAccelerators | XtAccelerators| dynamic | CSG |
|_____________________________|_______________________________|________________|______________________|________|
|XmNancestorSensitive | XmCSensitive | Boolean | dynamic | G |
|_____________________________|_______________________________|________________|______________________|________|
|XmNbackground | XmCBackground | Pixel | dynamic | CSG |
|_____________________________|_______________________________|________________|______________________|________|
|XmNbackgroundPixmap | XmCPixmap | Pixmap | XmUNSPECIFIED_PIXMAP| CSG |
|_____________________________|_______________________________|________________|______________________|________|
|XmNborderColor | XmCBorderColor | Pixel | XtDefaultForeground | CSG |
|_____________________________|_______________________________|________________|______________________|________|
|XmNborderPixmap | XmCPixmap | Pixmap | XmUNSPECIFIED_PIXMAP| CSG |
|_____________________________|_______________________________|________________|______________________|________|
|XmNborderWidth | XmCBorderWidth | Dimension | 0 | CSG |
|_____________________________|_______________________________|________________|______________________|________|
|XmNcolormap | XmCColormap | Colormap | dynamic | CG |
|_____________________________|_______________________________|________________|______________________|________|
|XmNdepth | XmCDepth | int | dynamic | CG |
|_____________________________|_______________________________|________________|______________________|________|
|XmNdestroyCallback | XmCCallback | XtCallbackList| NULL | C |
|_____________________________|_______________________________|________________|______________________|________|
|XmNheight | XmCHeight | Dimension | dynamic | CSG |
|_____________________________|_______________________________|________________|______________________|________|
|XmNinitialResourcesPersistent| XmCInitialResourcesPersistent| Boolean | True | C |
|_____________________________|_______________________________|________________|______________________|________|
|XmNmappedWhenManaged | XmCMappedWhenManaged | Boolean | True | CSG |
|_____________________________|_______________________________|________________|______________________|________|
|XmNscreen | XmCScreen | Screen * | dynamic | CG |
|_____________________________|_______________________________|________________|______________________|________|
|XmNsensitive | XmCSensitive | Boolean | True | CSG |
|_____________________________|_______________________________|________________|______________________|________|
|XmNtranslations | XmCTranslations | XtTranslations| dynamic | CSG |
|_____________________________|_______________________________|________________|______________________|________|
|XmNwidth | XmCWidth | Dimension | dynamic | CSG |
|_____________________________|_______________________________|________________|______________________|________|
|XmNx | XmCPosition | Position | 0 | CSG |
|_____________________________|_______________________________|________________|______________________|________|
|XmNy | XmCPosition | Position | 0 | CSG |
|_____________________________|_______________________________|________________|______________________|________|
Callback Information
A pointer to the following structure is passed to each callback:
typedef struct
{
int reason;
Page 6 10/89
XmCascadeButton(3X) UNIX System V XmCascadeButton(3X)
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.
Translations
XmCascadeButton includes translations from Primitive. XmCascadeButton
includes the menu traversal translations from XmLabel. These
translations may not directly correspond to a translation table.
Note that altering translations in #override or #augment mode is
undefined.
The translations for a CascadeButton in a MenuBar are listed below.
These translations may not directly correspond to a translation table.
BSelect Press: MenuBarSelect()
BSelect Release:DoSelect()
KActivate: KeySelect()
KSelect: KeySelect()
KHelp: Help()
MAny KCancel: CleanupMenuBar()
The translations for a CascadeButton in a PullDown or Popup MenuPane are
listed below. In a Popup menu system, BMenu also performs the BSelect
actions. These translations may not directly correspond to a translation
table.
BSelect Press: StartDrag()
BSelect Release:DoSelect()
KActivate: KeySelect()
KSelect: KeySelect()
KHelp: Help()
MAny KCancel: CleanupMenuBar()
Action Routines
The XmCascadeButton action routines are described below:
CleanupMenuBar():
In a MenuBar, disarms the CascadeButton and the menu and restores
keyboard focus to the tab group that had the focus before the menu
was entered.
10/89 Page 7
XmCascadeButton(3X) UNIX System V XmCascadeButton(3X)
In a toplevel Pulldown MenuPane from a MenuBar, unposts the menu,
disarms the MenuBar CascadeButton and the MenuBar, and restores
keyboard focus to the tab group that had the focus before the
MenuBar was entered. In other Pulldown MenuPanes, unposts the
menu.
In a Popup MenuPane, unposts the menu and restores keyboard focus
to the widget from which the menu was posted.
DoSelect():
Posts the submenu attached to the CascadeButton and enables
keyboard traversal within the menu. If the CascadeButton does not
have a submenu attached, the CascadeButton is activated and all
posted menus in the cascade are unposted.
Help():
Unposts all menus in the menu hierarchy and restores keyboard focus
to the tab group that had the focus before the menu system was
entered. Calls the callbacks for XmNhelpCallback if any exist. If
there are no help callbacks for this widget, this action calls the
help callbacks for the nearest ancestor that has them.
KeySelect():
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 all
posted menus in the cascade are unposted.
MenuBarSelect():
Unposts any menus posted by the parent menu. Arms both the
CascadeButton and the MenuBar, posts the associated submenu, and
enables mouse traversal. If the menu is already active, this event
disables keyboard traversal for the menu and returns the menu to
mouse traversal mode.
StartDrag():
Arms the CascadeButton, posts the associated submenu, and enables
mouse traversal. If the menu is already active, this event
disables keyboard traversal for the menu and returns the menu to
mouse traversal mode.
Additional Behavior
Posting a submenu calls the XmNcascadingCallback callbacks. This widget
has the additional behavior described below:
<EnterWindow>:
If keyboard traversal is enabled does nothing. Otherwise, in a
MenuBar that is armed, unposts any MenuPanes associated with
another MenuBar entry, arms the CascadeButton, and posts the
associated submenu. In other menus, arms the CascadeButton and
posts the associated submenu after the delay specified by
Page 8 10/89
XmCascadeButton(3X) UNIX System V XmCascadeButton(3X)
XmNmappingDelay.
<LeaveWindow>:
If keyboard traversal is enabled does nothing. Otherwise, in a
MenuBar that is armed, disarms the CascadeButton if the submenu
associated with the CascadeButton is not currently posted or if
there is no submenu associated with the CascadeButton.
In other menus, if the pointer moves anywhere except into a submenu
associated with the CascadeButton, the CascadeButton is disarmed
and its submenu is unposted.
Virtual Bindings
The bindings for virtual keys are vendor specific. For information about
bindings for virtual buttons and keys, see VirtualBindings(3X).
RELATED INFORMATION
Core(3X), XmCascadeButtonHighlight(3X), XmCreateCascadeButton(3X),
XmCreateMenuBar(3X), XmCreatePulldownMenu(3X), XmCreatePopupMenu(3X),
XmLabel(3X), XmPrimitive(3X), and XmRowColumn(3X).
10/89 Page 9