XmCascadeButtonGadget(3Xm) XmCascadeButtonGadget(3Xm)
NAME
XmCascadeButtonGadget - the CascadeButtonGadget widget
class.
AES SUPPORT LEVEL
full-use
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
- 1 -
XmCascadeButtonGadget(3Xm) XmCascadeButtonGadget(3Xm)
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).
XmCascadeButtonGadget
Name Class Type Default Access
_________________________________________________________________________________
XmNactivateCallback XmCCallback XtCallbackList NULL C
XmNcascadePixmap XmCPixmap Pixmap "menu_cascade" CSG
XmNcascadingCallback XmCCallback XtCallbackList NULL C
- 2 -
XmCascadeButtonGadget(3Xm) XmCascadeButtonGadget(3Xm)
XmNmappingDelay XmCMappingDelay int 100 CSG
XmNsubMenuId XmCMenuWidget Widget 0 CSG
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(3X), XmCreatePopupMenu(3X),
and XmCreateOptionMenu(3X) for more information on
the menu systems.
Inherited Resources
CascadeButtonGadget inherits behavior and resources
from the following superclasses. For a complete
- 3 -
XmCascadeButtonGadget(3Xm) XmCascadeButtonGadget(3Xm)
description of these resources, refer to the man page
for that superclass.
XmLabelGadget Resource Set
Name Class Type Default Access
_____________________________________________________________________________________________________
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 2 CSG
XmNmnemonic XmCMnemonic char `\0' CSG
XmNrecomputeSize XmCRecomputeSize Boolean True CSG
XmGadget Resource Set
Name Class Type Default Access
_________________________________________________________________________________
XmNhelpCallback XmCCallback XtCallbackList NULL C
XmNhighlightOnEnter XmCHighlightOnEnter Boolean False CSG
XmNhighlightThickness XmCHighlightThickness short 0 CSG
XmNshadowThickness XmCShadowThickness short 2 CSG
XmNtraversalOn XmCTraversalOn Boolean False CSG
XmNuserData XmCUserData caddr_t NULL CSG
RectObj Resource Set
Name Class Type Default Access
_____________________________________________________________________________
XmNancestorSensitive XmCSensitive Boolean XtCopyFromParent CSG
XmNborderWidth XmCBorderWidth Dimension 1 CSG
XmNheight XmCHeight Dimension 0 CSG
XmNsensitive XmCSensitive Boolean True CSG
XmNwidth XmCWidth Dimension 0 CSG
XmNx XmCPosition Position 0 CSG
XmNy XmCPosition Position 0 CSG
Object Resource Set
Name Class Type Default Access
____________________________________________________________________
XmNdestroyCallback XmCCallback XtCallbackList NULL C
Callback Information
The following structure is returned with each callback:
- 4 -
XmCascadeButtonGadget(3Xm) XmCascadeButtonGadget(3Xm)
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
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.
- 5 -
XmCascadeButtonGadget(3Xm) XmCascadeButtonGadget(3Xm)
<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.
OptionMenu
Default Pulldown MenuPane from a MenuBar or from an
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:
- 6 -
XmCascadeButtonGadget(3Xm) XmCascadeButtonGadget(3Xm)
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(3X) and its sections on behavior and
default translations.
RELATED INFORMATION
Object(3X), RectObj(3X), XmCascadeButtonHighlight(3),
XmCreateCascadeButtonGadget(3X),
XmCreatePulldownMenu(3X), XmCreatePopupMenu(3X),
XmCreateOptionMenu(3X), XmGadget(3X),
XmLabelGadget(3X), and XmRowColumn(3X).
- 7 -