


XmCascadeButton(3X)					  XmCascadeButton(3X)
OSF/Motif							    OSF/Motif



NAME
  XXmmCCaassccaaddeeBBuuttttoonn - The	CascadeButton widget class

SYNOPSIS


  ##iinncclluuddee <<XXmm//CCaassccaaddeeBB..h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
  XXmmNNrroowwCCoolluummnnTTyyppee resource set	to XXmmMMEENNUU__BBAARR, XXmmMMEENNUU__PPOOPPUUPP or
  XXmmMMEENNUU__PPUULLLLDDOOWWNN.

  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	Menu-
  Pane;	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,	BBSSeelleecctt	controls the behavior
  of the CascadeButton.	 In addition, BBMMeennuu controls the behavior of the Cas-
  cadeButton 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 XXmmNNmmaappppiinnggDDeellaayy.

  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	Cas-
  cadeButton by	simply typing the mnemonic while the CascadeButton is visi-
  ble.	If the CascadeButton is	in a MenuBar and the MenuBar does not have
  the focus, the MMAAlltt 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
  XXmmNNmmaarrggiinnBBoottttoomm, XXmmNNmmaarrggiinnLLeefftt, XXmmNNmmaarrggiinnRRiigghhtt, and XXmmNNmmaarrggiinnTToopp resources
  may enlarge to accommodate XXmmNNccaassccaaddeePPiixxmmaapp.	XXmmNNmmaarrggiinnWWiiddtthh 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 CCoorree, XXmmPPrriimmiittiivvee,	and
  XXmmLLaabbeell classes.

  The class pointer is xxmmCCaassccaaddeeBBuuttttoonnWWiiddggeettCCllaassss.

  The class name is XXmmCCaassccaaddeeBBuuttttoonn.

  New Resources

  The following	table defines a	set of widget resources	used by	the program-
  mer 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	XXmmNN or XXmmCC
  prefix and use the remaining letters.	 To specify one	of the defined values
  for a	resource in a .Xdefaults file, remove the XXmm prefix and	use the
  remaining letters (in	either lowercase or uppercase, but include any under-
  scores between words).  The codes in the access column indicate if the
  given	resource can be	set at creation	time (C), set by using XXttSSeettVVaalluueess
  (S), retrieved by using XXttGGeettVVaalluueess (G), or is not applicable	(N/A).

			 XXmmCCaassccaaddeeBBuuttttoonn RReessoouurrccee SSeett
	    ______________________________________________________
	    NNaammee		    DDeeffaauulltt		    AAcccceessss
		  CCllaassss			  TTyyppee
	    ______________________________________________________
	    ______________________________________________________
	    XmNactivateCallback	    NULL		    C
		  XmCCallback		   XtCallbackList
	    ______________________________________________________
	    XmNcascadePixmap	    dynamic		    CSG
		  XmCPixmap		   Pixmap
	    ______________________________________________________
	    XmNcascadingCallback    NULL		    C
		  XmCCallback		   XtCallbackList
	    ______________________________________________________
	    XmNmappingDelay	    180	ms		    CSG
		  XmCMappingDelay	   int
	    ______________________________________________________
	    XmNsubMenuId	    NULL		    CSG
		  XmCMenuWidget		   Widget
	    ______________________________________________________

  XXmmNNaaccttiivvaatteeCCaallllbbaacckk
	    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	XXmmCCRR__AACCTTIIVVAATTEE.

  XXmmNNccaassccaaddeePPiixxmmaapp
	    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 XXmmNNmmaarrggiinn--
	    BBoottttoomm, XXmmNNmmaarrggiinnLLeefftt, XXmmNNmmaarrggiinnRRiigghhtt, and XXmmNNmmaarrggiinnTToopp 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.

  XXmmNNccaassccaaddiinnggCCaallllbbaacckk
	    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 XXmmCCRR__CCAASSCCAADDIINNGG.

  XXmmNNmmaappppiinnggDDeellaayy
	    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.

  XXmmNNssuubbMMeennuuIIdd
	    Specifies the widget ID for	the Pulldown MenuPane to be associ-
	    ated 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 XXmmCCrreeaatteeMMeennuuBBaarr((33XX)),
	    XXmmCCrreeaatteePPuullllddoowwnnMMeennuu((33XX)), and XXmmCCrreeaatteePPooppuuppMMeennuu((33XX))	for more
	    information	on the menu systems.

  Inherited Resources

  CascadeButton	inherits behavior and resources	from the following superc-
  lasses.  For a complete description of each resource,	refer to the man page
  for that superclass.

			     XXmmLLaabbeell RReessoouurrccee SSeett
      ___________________________________________________________________
      NNaammee				DDeeffaauulltt			   AAcccceessss
	    CCllaassss			      TTyyppee
      ___________________________________________________________________
      ___________________________________________________________________
      XmNaccelerator			NULL			   N/A
	    XmCAccelerator		       String
      ___________________________________________________________________
      XmNacceleratorText		NULL			   N/A
	    XmCAcceleratorText		       XmString
      ___________________________________________________________________
      XmNalignment			dynamic			   CSG
	    XmCAlignment		       unsigned	char
      ___________________________________________________________________
      XmNfontList			dynamic			   CSG
	    XmCFontList			       XmFontList
      ___________________________________________________________________
      XmNlabelInsensitivePixmap		XmUNSPECIFIED_PIXMAP	   CSG
	    XmCLabelInsensitivePixmap	       Pixmap
      ___________________________________________________________________
      XmNlabelPixmap			XmUNSPECIFIED_PIXMAP	   CSG
	    XmCLabelPixmap		       Pixmap
      ___________________________________________________________________
      XmNlabelString			dynamic			   CSG
	    XmCXmString			       XmString
      ___________________________________________________________________
      XmNlabelType			XmSTRING		   CSG
	    XmCLabelType		       unsigned	char
      ___________________________________________________________________
      XmNmarginBottom			dynamic			   CSG
	    XmCMarginBottom		       Dimension
      ___________________________________________________________________
      XmNmarginHeight			2			   CSG
	    XmCMarginHeight		       Dimension
      ___________________________________________________________________
      XmNmarginLeft			0			   CSG
	    XmCMarginLeft		       Dimension
      ___________________________________________________________________
      XmNmarginRight			dynamic			   CSG
	    XmCMarginRight		       Dimension
      ___________________________________________________________________
      XmNmarginTop			dynamic			   CSG
	    XmCMarginTop		       Dimension
      ___________________________________________________________________
      XmNmarginWidth			dynamic			   CSG
	    XmCMarginWidth		       Dimension
      ___________________________________________________________________
      XmNmnemonic			NULL			   CSG
	    XmCMnemonic			       KeySym
      ___________________________________________________________________
      XmNmnemonicCharSet		XmFONTLIST_DEFAULT_TAG	   CSG
	    XmCMnemonicCharSet		       String
      ___________________________________________________________________
      XmNrecomputeSize			True			   CSG
	    XmCRecomputeSize		       Boolean
      ___________________________________________________________________
      XmNstringDirection		dynamic			   CSG
	    XmCStringDirection		       XmStringDirection
      ___________________________________________________________________

			   XXmmPPrriimmiittiivvee RReessoouurrccee	SSeett
	______________________________________________________________
	NNaammee			      DDeeffaauulltt			AAcccceessss
	      CCllaassss			    TTyyppee
	______________________________________________________________
	______________________________________________________________
	XmNbottomShadowColor	      dynamic			CSG
	      XmCBottomShadowColor	     Pixel
	______________________________________________________________
	XmNbottomShadowPixmap	      XmUNSPECIFIED_PIXMAP	CSG
	      XmCBottomShadowPixmap	     Pixmap
	______________________________________________________________
	XmNforeground		      dynamic			CSG
	      XmCForeground		     Pixel
	______________________________________________________________
	XmNhelpCallback		      NULL			C
	      XmCCallback		     XtCallbackList
	______________________________________________________________
	XmNhighlightColor	      dynamic			CSG
	      XmCHighlightColor		     Pixel
	______________________________________________________________
	XmNhighlightOnEnter	      False			CSG
	      XmCHighlightOnEnter	     Boolean
	______________________________________________________________
	XmNhighlightPixmap	      dynamic			CSG
	      XmCHighlightPixmap	     Pixmap
	______________________________________________________________
	XmNhighlightThickness	      0				CSG
	      XmCHighlightThickness	     Dimension
	______________________________________________________________
	XmNnavigationType	      XmNONE			CSG
	      XmCNavigationType		     XmNavigationType
	______________________________________________________________
	XmNshadowThickness	      2				CSG
	      XmCShadowThickness	     Dimension
	______________________________________________________________
	XmNtopShadowColor	      dynamic			CSG
	      XmCTopShadowColor		     Pixel
	______________________________________________________________
	XmNtopShadowPixmap	      dynamic			CSG
	      XmCTopShadowPixmap	     Pixmap
	______________________________________________________________
	XmNtraversalOn		      dynamic			G
	      XmCTraversalOn		     Boolean
	______________________________________________________________
	XmNunitType		      dynamic			CSG
	      XmCUnitType		     unsigned char
	______________________________________________________________
	XmNuserData		      NULL			CSG
	      XmCUserData		     XtPointer
	______________________________________________________________

			      CCoorree RReessoouurrccee SSeett
     ____________________________________________________________________
     NNaammee				   DDeeffaauulltt		   AAcccceessss
	   CCllaassss				 TTyyppee
     ____________________________________________________________________
     ____________________________________________________________________
     XmNaccelerators			   dynamic		   CSG
	   XmCAccelerators			  XtAccelerators
     ____________________________________________________________________
     XmNancestorSensitive		   dynamic		   G
	   XmCSensitive				  Boolean
     ____________________________________________________________________
     XmNbackground			   dynamic		   CSG
	   XmCBackground			  Pixel
     ____________________________________________________________________
     XmNbackgroundPixmap		   XmUNSPECIFIED_PIXMAP	   CSG
	   XmCPixmap				  Pixmap
     ____________________________________________________________________
     XmNborderColor			   XtDefaultForeground	   CSG
	   XmCBorderColor			  Pixel
     ____________________________________________________________________
     XmNborderPixmap			   XmUNSPECIFIED_PIXMAP	   CSG
	   XmCPixmap				  Pixmap
     ____________________________________________________________________
     XmNborderWidth			   0			   CSG
	   XmCBorderWidth			  Dimension
     ____________________________________________________________________
     XmNcolormap			   dynamic		   CG
	   XmCColormap				  Colormap
     ____________________________________________________________________
     XmNdepth				   dynamic		   CG
	   XmCDepth				  int
     ____________________________________________________________________
     XmNdestroyCallback			   NULL			   C
	   XmCCallback				  XtCallbackList
     ____________________________________________________________________
     XmNheight				   dynamic		   CSG
	   XmCHeight				  Dimension
     ____________________________________________________________________
     XmNinitialResourcesPersistent	   True			   C
	   XmCInitialResourcesPersistent	  Boolean
     ____________________________________________________________________
     XmNmappedWhenManaged		   True			   CSG
	   XmCMappedWhenManaged			  Boolean
     ____________________________________________________________________
     XmNscreen				   dynamic		   CG
	   XmCScreen				  Screen *
     ____________________________________________________________________
     XmNsensitive			   True			   CSG
	   XmCSensitive				  Boolean
     ____________________________________________________________________
     XmNtranslations			   dynamic		   CSG
	   XmCTranslations			  XtTranslations
     ____________________________________________________________________
     XmNwidth				   dynamic		   CSG
	   XmCWidth				  Dimension
     ____________________________________________________________________
     XmNx				   0			   CSG
	   XmCPosition				  Position
     ____________________________________________________________________
     XmNy				   0			   CSG
	   XmCPosition				  Position
     ____________________________________________________________________

  Callback Information

  A pointer to the following structure is passed to each callback:


  ttyyppeeddeeff ssttrruucctt
  {{
    iinntt	     _r_e_a_s_o_n;;
    XXEEvveenntt   * _e_v_e_n_t;;
  }} XXmmAAnnyyCCaallllbbaacckkSSttrruucctt;;

  _r_e_a_s_o_n Indicates why the callback was	invoked.

  _e_v_e_n_t	 Points	to the XXEEvveenntt that triggered the callback or is	NULL if	this
	 callback was not triggered due	to an XXEEvveenntt.

  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 ##oovveerrrriiddee or ##aauuggmmeenntt mode	is undefined.

  The translations for a CascadeButton in a MenuBar are	listed below.  These
  translations may not directly	correspond to a	translation table.

       BBSSeelleecctt PPrreessss:: MMeennuuBBaarrSSeelleecctt(())
       BBSSeelleecctt RReelleeaassee::DDooSSeelleecctt(())
       KKAAccttiivvaattee::     KKeeyySSeelleecctt(())
       KKSSeelleecctt::	      KKeeyySSeelleecctt(())
       KKHHeellpp::	      HHeellpp(())
       MMAAnnyy KKCCaanncceell::  CClleeaannuuppMMeennuuBBaarr(())

  The translations for a CascadeButton in a PullDown or	Popup MenuPane are
  listed below.	 In a Popup menu system, BBMMeennuu also performs the BBSSeelleecctt
  actions.  These translations may not directly	correspond to a	translation
  table.

       BBSSeelleecctt PPrreessss:: SSttaarrttDDrraagg(())
       BBSSeelleecctt RReelleeaassee::DDooSSeelleecctt(())
       KKAAccttiivvaattee::     KKeeyySSeelleecctt(())
       KKSSeelleecctt::	      KKeeyySSeelleecctt(())
       KKHHeellpp::	      HHeellpp(())
       MMAAnnyy KKCCaanncceell::  CClleeaannuuppMMeennuuBBaarr(())

  Action Routines

  The XmCascadeButton action routines are described below:

  CClleeaannuuppMMeennuuBBaarr(()):
	    In a MenuBar, disarms the CascadeButton and	the menu and, when
	    the	shell's	keyboard focus policy is XXmmEEXXPPLLIICCTT, restores keyboard
	    focus to the widget	that had the focus before the menu was
	    entered.










	    In a toplevel Pulldown MenuPane from a MenuBar, unposts the	menu,
	    disarms the	MenuBar	CascadeButton and the MenuBar, and, when the
	    shell's keyboard focus policy is XXmmEEXXPPLLIICCTT,	restores keyboard
	    focus to the widget	that had the focus before the MenuBar was
	    entered.  In other Pulldown	MenuPanes, unposts the menu.
	    In a Popup MenuPane, unposts the menu and, when the	shell's
	    keyboard focus policy is XXmmEEXXPPLLIICCTT,	restores keyboard focus	to
	    the	widget from which the menu was posted.

  DDooSSeelleecctt(()):
	    Calls the callbacks	in XXmmNNccaassccaaddiinnggCCaallllbbaacckk, posts the submenu
	    attached to	the CascadeButton and enables keyboard traversal
	    within the menu.  If the CascadeButton does	not have a submenu
	    attached, calls the	callbacks in XXmmNNaaccttiivvaatteeCCaallllbbaacckk, the Cas-
	    cadeButton is activated and	all posted menus in the	cascade	are
	    unposted.

  HHeellpp(()):   Unposts all	menus in the menu hierarchy and, when the shell's
	    keyboard focus policy is XXmmEEXXPPLLIICCTT,	restores keyboard focus	to
	    the	widget that had	the focus before the menu system was entered.
	    Calls the callbacks	for XXmmNNhheellppCCaallllbbaacckk 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.

  KKeeyySSeelleecctt(()):
	    Calls the callbacks	in XXmmNNccaassccaaddiinnggCCaallllbbaacckk, and posts the sub-
	    menu attached to the CascadeButton if keyboard traversal is
	    enabled in the menu.  If the CascadeButton does not	have a sub-
	    menu attached, calls the callbacks in XXmmNNaaccttiivvaatteeCCaallllbbaacckk, the
	    CascadeButton is activated and all posted menus in the cascade
	    are	unposted.

  MMeennuuBBaarrSSeelleecctt(()):
	    Unposts any	menus posted by	the parent menu.  Arms both the	Cas-
	    cadeButton 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.

  SSttaarrttDDrraagg(()):
	    Arms the CascadeButton, posts the associated submenu, and enables
	    mouse traversal.  If the menu is already active, this event	dis-
	    ables keyboard traversal for the menu and returns the menu to
	    mouse traversal mode.

  Additional Behavior

  Posting a submenu calls the XXmmNNccaassccaaddiinnggCCaallllbbaacckk callbacks.  This widget
  has the additional behavior described	below:

  <<EEnntteerrWWiinnddooww>>:
	    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 XXmmNNmmaapp--
	    ppiinnggDDeellaayy.

  <<LLeeaavveeWWiinnddooww>>:
	    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	sub-
	    menu 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 VViirrttuuaallBBiinnddiinnggss((33XX)).

RELATED	INFORMATION
  CCoorree((33XX)), XXmmCCaassccaaddeeBBuuttttoonnHHiigghhlliigghhtt((33XX)),
  XXmmCCrreeaatteeCCaassccaaddeeBBuuttttoonn((33XX)),,XXmmCCrreeaatteeMMeennuuBBaarr((33XX)), XXmmCCrreeaatteePPuullllddoowwnnMMeennuu((33XX)),
  XXmmCCrreeaatteePPooppuuppMMeennuu((33XX)), XXmmLLaabbeell((33XX)), XXmmPPrriimmiittiivvee((33XX)), and XXmmRRoowwCCoolluummnn((33XX)).






























































