


XmCascadeButtonGadget(3X)			    XmCascadeButtonGadget(3X)
OSF/Motif							    OSF/Motif



NAME
  XXmmCCaassccaaddeeBBuuttttoonnGGaaddggeett	- The CascadeButtonGadget widget class

SYNOPSIS


  ##iinncclluuddee <<XXmm//CCaassccaaddeeBBGG..hh>>

DESCRIPTION
  CascadeButtonGadget links two	MenuPanes, a MenuBar to	a MenuPane, or an
  OptionMenu 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, XXmmMMEENNUU__PPUULLLLDDOOWWNN,
  or XXmmMMEENNUU__OOPPTTIIOONN.

  It is	the only gadget	that can have a	Pulldown MenuPane attached to it 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 Popup 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,	BBSSeelleecctt	controls the
  behavior of the CascadeButtonGadget.	In addition, BBMMeennuu controls the
  behavior of the CascadeButtonGadget if it resides in a PopupMenu system.
  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, 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 time to see
  if the arming	was temporary (that is,	the user was simply passing through
  the gadget), or the user really wanted the submenu posted.  This delay is
  configurable via XXmmNNmmaappppiinnggDDeellaayy.

  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.  If
  the CascadeButtonGadget 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.

  If a CascadeButtonGadget is 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 LabelGadget's default, which	is 2.




  Classes

  CascadeButtonGadget inherits behavior	and resources from OObbjjeecctt, RReeccttOObbjj,
  XXmmGGaaddggeett, and	XXmmLLaabbeellGGaaddggeett classes.

  The class pointer is xxmmCCaassccaaddeeBBuuttttoonnGGaad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nGGaaddggeett.

  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nGGaaddgge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 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	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 gadget
	    when a CascadeButtonGadget is used within a	Popup or Pulldown
	    MenuPane and a submenu is attached.	 The LabelGadget class
	    resources 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 may be	modified to ensure that	room is	left for the
	    cascade pixmap.  The default cascade pixmap	in menus other than
	    option menus is an arrow pointing to the side of the menu where
	    the	submenu	will appear.  The default for the CascadeButtonGadget
	    in an option menu is XXmmUUNNSSPPEECCIIFFIIEEDD__PPIIXXMMAAPP.

  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 the CascadeButtonGadget.
	    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
	    CascadeButtonGadget	becomes	armed and when it maps its submenu.
	    This delay is used only when the gadget 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 CascadeButtonGadget.	 The specified MenuPane	is
	    displayed when the CascadeButtonGadget becomes armed.  The Menu-
	    Pane must have been	created	with the appropriate parentage
	    depending on the type of menu used.	 See
	    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)), and
	    XXmmCCrreeaatteeOOppttiioonnMMeennuu((33XX)) for more information	on the menu systems.

  Inherited Resources

  CascadeButtonGadget inherits behavior	and resources from the following
  superclasses.	 For a complete	description of each resource, refer to the
  man page for that superclass.

			  XXmmLLaabbeellGGaaddggeett	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		dynamic			   CSG
	    XmCMnemonicCharSet		       String
      ___________________________________________________________________
      XmNrecomputeSize			True			   CSG
	    XmCRecomputeSize		       Boolean
      ___________________________________________________________________
      XmNstringDirection		dynamic			   CSG
	    XmCStringDirection		       XmStringDirection
      ___________________________________________________________________

			    XXmmGGaaddggeett 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			G
	      XmCBottomShadowColor	     Pixel
	______________________________________________________________
	XmNhelpCallback		      NULL			C
	      XmCCallback		     XtCallbackList
	______________________________________________________________
	XmNhighlightColor	      dynamic			G
	      XmCHighlightColor		     Pixel
	______________________________________________________________
	XmNhighlightOnEnter	      False			CSG
	      XmCHighlightOnEnter	     Boolean
	______________________________________________________________
	XmNhighlightThickness	      0				CSG
	      XmCHighlightThickness	     Dimension
	______________________________________________________________
	XmNnavigationType	      XmNONE			CSG
	      XmCNavigationType		     XmNavigationType
	______________________________________________________________
	XmNshadowThickness	      2				CSG
	      XmCShadowThickness	     Dimension
	______________________________________________________________
	XmNtopShadowColor	      dynamic			G
	      XmCTopShadowColor		     Pixel
	______________________________________________________________
	XmNtraversalOn		      True			CSG
	      XmCTraversalOn		     Boolean
	______________________________________________________________
	XmNunitType		      dynamic			CSG
	      XmCUnitType		     unsigned char
	______________________________________________________________
	XmNuserData		      NULL			CSG
	      XmCUserData		     XtPointer
	______________________________________________________________

			     RReeccttOObbjj 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
	       ________________________________________________
	       ________________________________________________
	       XmNancestorSensitive   dynamic		 G
		     XmCSensitive	     Boolean
	       ________________________________________________
	       XmNborderWidth	      0			 CSG
		     XmCBorderWidth	     Dimension
	       ________________________________________________
	       XmNheight	      dynamic		 CSG
		     XmCHeight		     Dimension
	       ________________________________________________
	       XmNsensitive	      True		 CSG
		     XmCSensitive	     Boolean
	       ________________________________________________
	       XmNwidth		      dynamic		 CSG
		     XmCWidth		     Dimension
	       ________________________________________________
	       XmNx		      0			 CSG
		     XmCPosition	     Position
	       ________________________________________________
	       XmNy		      0			 CSG
		     XmCPosition	     Position
	       ________________________________________________

			      OObbjjeecctt 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
	      ___________________________________________________
	      ___________________________________________________
	      XmNdestroyCallback   NULL			   C
		    XmCCallback		  XtCallbackList
	      ___________________________________________________

  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 by an XXEEvveenntt.

  Behavior

  XmCascadeButtonGadget	includes behavior from XmGadget.  XmCascadeButton
  includes the menu traversal behavior from XmLabel.  Additional XmCascade-
  ButtonGadget behavior	is described below (in a Popup menu system, BBMMeennuu
  also performs	the BBSSeelleecctt actions):

  BBSSeelleecctt PPrreessss:
	    Unposts any	menus posted by	the parent menu.  Arms the Cascade-
	    ButtonGadget, posts	the associated submenu,	enables	mouse traver-
	    sal, and, in a MenuBar, arms the MenuBar.  If the menu is already
	    active, this event disables	keyboard traversal for the menu	and
	    returns the	menu to	mouse traversal	mode.

  BBSSeelleecctt RReelleeaassee:
	    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 CascadeButtonGadget	and enables keyboard traver-
	    sal	within the menu.  If the CascadeButtonGadget 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
	    CascadeButtonGadget	is activated and all posted menus in the
	    cascade are	unposted.

  KKAAccttiivvaattee:
	    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 CascadeButtonGadget if	keyboard traversal is
	    enabled in the menu.  If the CascadeButtonGadget 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
	    CascadeButtonGadget	is activated and all posted menus in the cas-
	    cade are unposted.	This action applies only to gadgets in Menu-
	    Bars, PulldownMenus, and PopupMenus.  For a	CascadeButtonGadget
	    in an OptionMenu, if the parent is a manager, this action passes
	    the	event to the parent.

  KKS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 CascadeButtonGadget if	keyboard traversal is
	    enabled in the menu.  If the CascadeButtonGadget 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
	    CascadeButtonGadget	is activated and all posted menus in the cas-
	    cade are unposted.

  KKH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.

  MMAAnnyy KKCCaanncceell:
	    In a MenuBar, disarms the CascadeButtonGadget 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.  For a	CascadeButtonGadget in an OptionMenu, if the
	    parent is a	manager, this action passes the	event to the parent.
	    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 restores keyboard	focus
	    to the widget from which the menu was posted.

  <<EEnntteerr>>:  If keyboard	traversal is enabled does nothing.  Otherwise, in a
	    MenuBar, unposts any MenuPanes associated with another MenuBar
	    entry, arms	the CascadeButtonGadget, and posts the associated
	    submenu.  In other menus, arms the CascadeButtonGadget and posts
	    the	associated submenu after the delay specified by	XXmmNNmmaappppiinnggDDee--
	    llaayy.

  <<LLeeaavvee>>:  If keyboard	traversal is enabled does nothing.  Otherwise, in a
	    MenuBar, disarms the CascadeButtonGadget if	the submenu associ-
	    ated with the CascadeButtonGadget is not currently posted or if
	    there is no	submenu	associated with	the CascadeButtonGadget.
	    In other menus, if the pointer moves anywhere except into a	sub-
	    menu associated with the CascadeButtonGadget, the CascadeBut-
	    tonGadget 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
  OObbjjeecctt((33XX)), RReeccttOObbjj((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nGGaaddggeett((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mCCrreeaatteeOOppttiioonnMMeennuu((33XX)),,XXmmGGaaddggeett((33XX)),
  XXmmLLaabbeellGGaaddggeett((33XX)), XXmmRRoowwCCoolluummnn((33XX))




























































