XmCascadeButton(Xm) UNIX System V
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 XmMENUBAR,
XmMENUPOPUP or XmMENUPULLDOWN.
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).
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
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 XmCRACTIVATE.
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
XmCRCASCADING.
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(Xm),
XmCreatePulldownMenu(Xm), and XmCreatePopupMenu(Xm) 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.
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
XmNstringDirection XmCStringDirection XmStringDirection XmSTRING_DIRECTION_L_TO_R 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
XmNunitType XmCUnitType unsigned char XmPIXELS 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
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.
<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(Xm), XmCascadeButtonHighlight(Xm),
XmCreateCascadeButton(Xm), XmCreateMenuBar(Xm),
XmCreatePulldownMenu(Xm), XmCreatePopupMenu(Xm),
XmLabel(Xm), XmPrimitive(Xm), and XmRowColumn(Xm).
(printed 2/14/90) XmCascadeButton(Xm)