Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
XmCascadeButtonGadget(3)   Library Functions Manual   XmCascadeButtonGadget(3)

NAME
       XmCascadeButtonGadget --	The CascadeButtonGadget	widget class

SYNOPSIS
       #include	<Xm/CascadeBG.h>

DESCRIPTION
       CascadeButtonGadget  links two menu panes, a MenuBar to a menu pane, or
       an OptionMenu to	a menu pane.

       It is used in menu systems and must have	a RowColumn  parent  with  its
       XmNrowColumnType	resource set to	XmMENU_BAR, XmMENU_POPUP, XmMENU_PULL-
       DOWN, or	XmMENU_OPTION.

       It is the only gadget that can have a Pulldown menu pane	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 menu pane; or it can include only a label or a	pixmap
       when  it	is in an OptionMenu.  The positioning of the PulldownMenu with
       respect to the CascadeButton depends on the XmNlayoutDirection resource
       of the MenuShell.

       The  default  behavior associated with a	CascadeButtonGadget depends on
       the type	of menu	system in which	it resides.  By	default, BSelect  con-
       trols the behavior of the CascadeButtonGadget.  In addition, BMenu con-
       trols the behavior of the CascadeButtonGadget if	it resides in a	Popup-
       Menu system.  The actual	mouse button used is determined	by its RowCol-
       umn parent.  BMenu also performs	the BSelect actions in	all  types  of
       menu systems.

       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	menu  pane  is
       armed  as the result of the user	moving the mouse pointer into the gad-
       get, 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  sub-
       menu posted. This delay is configurable using XmNmappingDelay.

       CascadeButtonGadget provides a single mechanism for activating the gad-
       get from	the keyboard. This mechanism is	referred to as a keyboard mne-
       monic.	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 focus, the	MAlt modifier must be pressed  with  the  mne-
       monic.	Mnemonics are typically	used to	interact with a	menu using the
       keyboard.

       If a CascadeButtonGadget	is in a	Pulldown or Popup menu pane and	 there
       is  a  submenu attached,	the XmNmarginBottom, XmNmarginLeft, XmNmargin-
       Right, and XmNmarginTop resources may enlarge  to  accommodate  XmNcas-
       cadePixmap.   XmNmarginWidth  defaults  to  6  if this resource is in a
       MenuBar;	otherwise, it takes LabelGadget's default, which is 2.

       CascadeButtonGadget uses	the XmQTmenuSystem and	XmQTspecifyRenderTable
       traits.

   Classes
       CascadeButtonGadget  inherits  behavior,	resources, and traits from the
       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  pro-
       grammer	to specify data. The programmer	can also set the resource val-
       ues 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 lowercase or uppercase,
       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		| dynamic | CSG	   |
       +---------------------+-----------------+----------------+---------+--------+
       |XmNcascadingCallback | XmCCallback     | XtCallbackList	| NULL	  | C	   |
       +---------------------+-----------------+----------------+---------+--------+
       |XmNmappingDelay	     | XmCMappingDelay | int		| 180 ms  | CSG	   |
       +---------------------+-----------------+----------------+---------+--------+
       |XmNsubMenuId	     | XmCMenuWidget   | Widget		| NULL	  | 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 when	a mouse	button
		 is  released  or when the mnemonic associated with the	gadget
		 is typed. 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 one end of the gad-
		 get  when  a  CascadeButtonGadget  is	used within a Popup or
		 Pulldown menu pane and	a submenu is attached.	The  LabelGad-
		 get  class  resources	XmNmarginBottom,  XmNmarginLeft,  XmN-
		 marginRight, and XmNmarginTop 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
		 XmUNSPECIFIED_PIXMAP.

		 The  positioning  of the cascade pixmap to either the left of
		 right of the widget, and the direction	of the	arrow,	depend
		 on the	XmNlayoutDirection resource of the MenuShell.

       XmNcascadingCallback
		 Specifies  the	list of	callbacks that is called just prior to
		 the mapping of	the submenu associated with the	CascadeButton-
		 Gadget. 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  sub-
		 menu.	This  delay  is	 used only when	the gadget is within a
		 Popup or Pulldown menu	pane.  The value must not be negative.

       XmNsubMenuId
		 Specifies the widget ID for the Pulldown menu pane to be  as-
		 sociated  with	 this  CascadeButtonGadget. The	specified menu
		 pane 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	XmCre-
		 atePulldownMenu(3), XmCreatePopupMenu(3), and XmCreateOption-
		 Menu(3) for more information on the menu systems.

   Inherited Resources
       CascadeButtonGadget inherits behavior and  resources  from  the	super-
       classes	described in the following tables.  For	a complete description
       of each resource, refer to the reference	page for that superclass.

       +----------------------------------------------------------------------------------------------------------+
       |			  |	       XmLabelGadget Resource Set	  |			 |	  |
       |Name			  | Class		      |	Type		  | Default		 | Access |
       +--------------------------+---------------------------+-------------------+----------------------+--------+
       |XmNaccelerator		  | XmCAccelerator	      |	String		  | NULL		 | N/A	  |
       +--------------------------+---------------------------+-------------------+----------------------+--------+
       |XmNacceleratorText	  | XmCAcceleratorText	      |	XmString	  | NULL		 | N/A	  |
       +--------------------------+---------------------------+-------------------+----------------------+--------+
       |XmNalignment		  | XmCAlignment	      |	unsigned char	  | dynamic		 | CSG	  |
       +--------------------------+---------------------------+-------------------+----------------------+--------+
       |XmNfontList		  | XmCFontList		      |	XmFontList	  | dynamic		 | CSG	  |
       +--------------------------+---------------------------+-------------------+----------------------+--------+
       |XmNlabelInsensitivePixmap | XmCLabelInsensitivePixmap |	Pixmap		  | XmUNSPECIFIED_PIXMAP | CSG	  |
       +--------------------------+---------------------------+-------------------+----------------------+--------+
       |XmNlabelPixmap		  | XmCLabelPixmap	      |	Pixmap		  | XmUNSPECIFIED_PIXMAP | CSG	  |
       +--------------------------+---------------------------+-------------------+----------------------+--------+
       |XmNlabelString		  | XmCXmString		      |	XmString	  | dynamic		 | CSG	  |
       +--------------------------+---------------------------+-------------------+----------------------+--------+
       |XmNlabelType		  | XmCLabelType	      |	unsigned char	  | XmSTRING		 | CSG	  |
       +--------------------------+---------------------------+-------------------+----------------------+--------+
       |XmNmarginBottom		  | XmCMarginBottom	      |	Dimension	  | dynamic		 | CSG	  |
       +--------------------------+---------------------------+-------------------+----------------------+--------+
       |XmNmarginHeight		  | XmCMarginHeight	      |	Dimension	  | 2			 | CSG	  |
       +--------------------------+---------------------------+-------------------+----------------------+--------+
       |XmNmarginLeft		  | XmCMarginLeft	      |	Dimension	  | 0			 | CSG	  |
       +--------------------------+---------------------------+-------------------+----------------------+--------+
       |XmNmarginRight		  | XmCMarginRight	      |	Dimension	  | dynamic		 | CSG	  |
       +--------------------------+---------------------------+-------------------+----------------------+--------+
       |XmNmarginTop		  | XmCMarginTop	      |	Dimension	  | dynamic		 | CSG	  |
       +--------------------------+---------------------------+-------------------+----------------------+--------+
       |XmNmarginWidth		  | XmCMarginWidth	      |	Dimension	  | dynamic		 | CSG	  |
       +--------------------------+---------------------------+-------------------+----------------------+--------+
       |XmNmnemonic		  | XmCMnemonic		      |	KeySym		  | NULL		 | CSG	  |
       +--------------------------+---------------------------+-------------------+----------------------+--------+
       |XmNmnemonicCharSet	  | XmCMnemonicCharSet	      |	String		  | dynamic		 | CSG	  |
       +--------------------------+---------------------------+-------------------+----------------------+--------+
       |XmNrecomputeSize	  | XmCRecomputeSize	      |	Boolean		  | True		 | CSG	  |
       +--------------------------+---------------------------+-------------------+----------------------+--------+
       |XmNrenderTable		  | XmCRenderTable	      |	XmRenderTable	  | dynamic		 | CSG	  |
       +--------------------------+---------------------------+-------------------+----------------------+--------+
       |XmNstringDirection	  | XmCStringDirection	      |	XmStringDirection | dynamic		 | CSG	  |
       +--------------------------+---------------------------+-------------------+----------------------+--------+
       +--------------------------+---------------------------+-------------------+----------------------+--------+
       +-------------------------------------------------------------------------------------------------+
       |		      |		     XmGadget Resource Set	 |			|	 |
       |Name		      |	Class		      |	Type		 | Default		| Access |
       +----------------------+-----------------------+------------------+----------------------+--------+
       |XmNbackground	      |	XmCBackground	      |	Pixel		 | dynamic		| CSG	 |
       +----------------------+-----------------------+------------------+----------------------+--------+
       |XmNbackgroundPixmap   |	XmCPixmap	      |	Pixmap		 | XmUNSPECIFIED_PIXMAP	| CSG	 |
       +----------------------+-----------------------+------------------+----------------------+--------+
       |XmNbottomShadowColor  |	XmCBottomShadowColor  |	Pixel		 | dynamic		| CSG	 |
       +----------------------+-----------------------+------------------+----------------------+--------+
       |XmNbottomShadowPixmap |	XmCBottomShadowPixmap |	Pixmap		 | dynamic		| CSG	 |
       +----------------------+-----------------------+------------------+----------------------+--------+
       |XmNhelpCallback	      |	XmCCallback	      |	XtCallbackList	 | NULL			| C	 |
       +----------------------+-----------------------+------------------+----------------------+--------+
       |XmNforeground	      |	XmCForeground	      |	Pixel		 | dynamic		| CSG	 |
       +----------------------+-----------------------+------------------+----------------------+--------+
       |XmNhighlightColor     |	XmCHighlightColor     |	Pixel		 | dynamic		| CSG	 |
       +----------------------+-----------------------+------------------+----------------------+--------+
       |XmNhighlightOnEnter   |	XmCHighlightOnEnter   |	Boolean		 | False		| CSG	 |
       +----------------------+-----------------------+------------------+----------------------+--------+
       |XmNhighlightPixmap    |	XmCHighlightPixmap    |	Pixmap		 | dynamic		| CSG	 |
       +----------------------+-----------------------+------------------+----------------------+--------+
       |XmNhighlightThickness |	XmCHighlightThickness |	Dimension	 | 0			| CSG	 |
       +----------------------+-----------------------+------------------+----------------------+--------+
       |XmNlayoutDirection    |	XmNCLayoutDirection   |	XmDirection	 | dynamic		| CG	 |
       +----------------------+-----------------------+------------------+----------------------+--------+
       |XmNnavigationType     |	XmCNavigationType     |	XmNavigationType | XmNONE		| CSG	 |
       +----------------------+-----------------------+------------------+----------------------+--------+
       |XmNshadowThickness    |	XmCShadowThickness    |	Dimension	 | 2			| CSG	 |
       +----------------------+-----------------------+------------------+----------------------+--------+
       |XmNtopShadowColor     |	XmCTopShadowColor     |	Pixel		 | dynamic		| CSG	 |
       +----------------------+-----------------------+------------------+----------------------+--------+
       |XmNtopShadowPixmap    |	XmCTopShadowPixmap    |	Pixmap		 | dynamic		| CSG	 |
       +----------------------+-----------------------+------------------+----------------------+--------+
       |XmNtraversalOn	      |	XmCTraversalOn	      |	Boolean		 | True			| CSG	 |
       +----------------------+-----------------------+------------------+----------------------+--------+
       |XmNunitType	      |	XmCUnitType	      |	unsigned char	 | dynamic		| CSG	 |
       +----------------------+-----------------------+------------------+----------------------+--------+
       |XmNuserData	      |	XmCUserData	      |	XtPointer	 | NULL			| CSG	 |
       +----------------------+-----------------------+------------------+----------------------+--------+
       +----------------------+-----------------------+------------------+----------------------+--------+
       +---------------------------------------------------------------------+
       |		     |	RectObj	Resource Set	  |	    |	     |
       |Name		     | Class	      |	Type	  | Default | Access |
       +---------------------+----------------+-----------+---------+--------+
       |XmNancestorSensitive | XmCSensitive   |	Boolean	  | dynamic | G	     |
       +---------------------+----------------+-----------+---------+--------+
       |XmNborderWidth	     | XmCBorderWidth |	Dimension | 0	    | N/A    |
       +---------------------+----------------+-----------+---------+--------+
       |XmNheight	     | XmCHeight      |	Dimension | dynamic | CSG    |
       +---------------------+----------------+-----------+---------+--------+
       |XmNsensitive	     | XmCSensitive   |	Boolean	  | True    | CSG    |
       +---------------------+----------------+-----------+---------+--------+
       |XmNwidth	     | XmCWidth	      |	Dimension | dynamic | 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
       A pointer to the	following structure is passed to 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 by an XEvent

   Behavior
       XmCascadeButtonGadget includes behavior from XmGadget.  XmCascadeButton
       includes	the menu traversal behavior from XmLabel.   Additional	XmCas-
       cadeButtonGadget	 behavior  is  described  in  the following list (in a
       Popup menu system, <Btn3> also performs the <Btn1> actions).

       <Btn1Down>:
		 Unposts any menus posted by the parent	menu.  Arms  the  Cas-
		 cadeButtonGadget, posts the associated	submenu, enables mouse
		 traversal, 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.

       <Btn1Up>: Calls the callbacks in	XmNcascadingCallback, posts  the  sub-
		 menu attached to the CascadeButtonGadget and enables keyboard
		 traversal within the menu.  If	the  CascadeButtonGadget  does
		 not  have a submenu attached, this action calls the callbacks
		 in XmNactivateCallback,  activates  the  CascadeButtonGadget,
		 and unposts all posted	menus in the cascade.

       <Key><osfActivate>:
		 Calls	the  callbacks	in XmNcascadingCallback, and posts the
		 submenu attached to the CascadeButtonGadget if	keyboard  tra-
		 versal	 is  enabled  in the menu.  If the CascadeButtonGadget
		 does not have a submenu attached, this	action calls the call-
		 backs in XmNactivateCallback, activates the CascadeButtonGad-
		 get, and unposts all posted menus in the cascade.   This  ac-
		 tion  applies only to gadgets in MenuBars, PulldownMenus, and
		 PopupMenus. For a CascadeButtonGadget in  an  OptionMenu,  if
		 the  parent is	a manager, this	action passes the event	to the
		 parent.

       <Key><osfSelect>:
		 Calls the callbacks in	XmNcascadingCallback,  and  posts  the
		 submenu  attached to the CascadeButtonGadget if keyboard tra-
		 versal	is enabled in the menu.	  If  the  CascadeButtonGadget
		 does not have a submenu attached, this	action calls the call-
		 backs in XmNactivateCallback, activates the CascadeButtonGad-
		 get, and unposts all posted menus in the cascade.

       <Key><osfHelp>:
		 Unposts all menus in the menu hierarchy and, when the shell's
		 keyboard focus	policy is XmEXPLICIT, restores keyboard	 focus
		 to  the  widget that had the focus before the menu system was
		 entered.  Calls the callbacks for XmNhelpCallback if any  ex-
		 ist.	If  there  are no help callbacks for this widget, this
		 action	calls the help callbacks for the nearest ancestor that
		 has them.

       <Key><osfCancel>:
		 In  a	MenuBar,  disarms the CascadeButtonGadget and the menu
		 and, when the shell's keyboard	focus  policy  is  XmEXPLICIT,
		 restores  keyboard focus to the widget	that had the focus be-
		 fore 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  XmEXPLICIT,  re-
		 stores	keyboard focus to the widget that had the focus	before
		 the MenuBar was entered.  In other  Pulldown  MenuPanes,  un-
		 posts the menu.

		 In  a	Popup MenuPane,	unposts	the menu and restores keyboard
		 focus to the widget from which	the menu was posted.

       <Enter>:	 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	CascadeButton-
		 Gadget	and posts the associated submenu after the delay spec-
		 ified by XmNmappingDelay.

       <Leave>:	 If keyboard traversal is enabled does nothing.	 Otherwise, in
		 a MenuBar, disarms the	CascadeButtonGadget if the submenu as-
		 sociated with the CascadeButtonGadget is not currently	posted
		 or if there is	no submenu associated with the	CascadeButton-
		 Gadget.

		 In  other  menus, if the pointer moves	anywhere except	into a
		 submenu associated with the CascadeButtonGadget, the Cascade-
		 ButtonGadget 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	VirtualBindings(3).

RELATED
       Object(3), RectObj(3), XmCascadeButtonHighlight(3), XmCreateCascadeBut-
       tonGadget(3),   XmCreatePulldownMenu(3),	 XmCreatePopupMenu(3),	XmCre-
       ateOptionMenu(3), XmGadget(3),  XmLabelGadget(3),  XmRowColumn(3),  Xm-
       VaCreateCascadeButtonGadget(3),	and XmVaCreateManagedCascadeButtonGad-
       get(3).

						      XmCascadeButtonGadget(3)

NAME | SYNOPSIS | DESCRIPTION | RELATED

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=XmCascadeButtonGadget&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help