XmCascadeButtonGadget(Xm) UNIX System V
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 XmMENUPOPUP,
XmMENUPULLDOWN, or XmMENUOPTION.
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).
XmCascadeButtonGadget
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
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 XmCRACTIVATE.
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 XmCRCASCADING.
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(Xm), XmCreatePopupMenu(Xm), and
XmCreateOptionMenu(Xm) 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.
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
XmNstringDirection XmCStringDirection XmStringDirection XmSTRING_DIRECTION_L_TO_R 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
XmNunitType XmCUnitType unsigned char XmPIXELS 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:
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.
<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(Xm) and its sections on behavior and default
translations.
RELATED INFORMATION
Object(Xm), RectObj(Xm), XmCascadeButtonHighlight(3),
XmCreateCascadeButtonGadget(Xm), XmCreatePulldownMenu(Xm),
XmCreatePopupMenu(Xm), XmCreateOptionMenu(Xm), XmGadget(Xm),
XmLabelGadget(Xm), and XmRowColumn(Xm).
(printed 2/14/90) XmCascadeButtonGadget(Xm)