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

FreeBSD Manual Pages

  
 
  

home | help
iwidgets::menubar(1)		[incr Widgets]		  iwidgets::menubar(1)

______________________________________________________________________________

NAME
       iwidgets::menubar - Create and manipulate menubar menu widgets

SYNOPSIS
       iwidgets::menubar pathName ?options?

INHERITANCE
       itk::Widget <- iwidgets::Menubar

STANDARD OPTIONS
       activeBackground	     activeBorderWidth	   activeForeground
       anchor		     background		   borderWidth
       cursor		     disabledForeground	   font
       foreground	     highlightBackground   hightlightColor
       highligthThickness    justify		   relief
       padX		     padY		   wrapLength

       See the "options" manual	entry for details on the standard options.

WIDGET-SPECIFIC	OPTIONS
       Name:	       helpVariable
       Class:	       HelpVariable
       Command-Line Switch:	      -helpvariable

	      Specifies	the global variable to update whenever the mouse is in
	      motion over a menu entry.	This global variable is	 updated  with
	      the current value	of the active menu entry's helpStr. Other wid-
	      gets can "watch" this variable with the trace command, or	as  is
	      the  case	 with  entry  or  label	 widgets,  they	 can set their
	      textVariable to the same global variable.	This allows for	a sim-
	      ple  implementation  of  a  help	status bar. Whenever the mouse
	      leaves a menu entry, the helpVariable is set to the empty	string
	      {}.  The mainwindow(1) associates	its helpstatus and its menubar
	      in this fashion.

       Name:	       menuButtons
       Class:	       MenuButtons
       Command-Line Switch:	      -menubuttons

	      The menuButton option is a string	which specifies	 the  arrange-
	      ment  of menubuttons on the menubar frame. Each menubutton entry
	      is delimited by the newline character.

	      iwidgets::menubar	.mb -menubuttons {
		      menubutton file -text File
		      menubutton edit -text Edit
		      menubutton options -text Options
	      }

	      specifies	that three menubuttons will be added  to  the  menubar
	      (file, edit, options). Each entry	is translated into an add com-
	      mand call.

	      The menuButtons option can accept	embedded variables,  commands,
	      and  backslash  quoting. Embedded	variables and commands must be
	      enclosed in curly	braces ({}) to ensure proper  parsing  of  the
	      substituted values.
______________________________________________________________________________

DESCRIPTION
       The  iwidgets::menubar command creates a	new window (given by the path-
       Name argument) and makes	it into	a menubar menu widget. Additional  op-
       tions,  described  above	may be specified on the	command	line or	in the
       option database to configure aspects of the menubar such	as its	colors
       and  font. The iwidgets::menubar	command	returns	its pathName argument.
       At the time this	command	is invoked, there  must	 not  exist  a	window
       named pathName, but pathName's parent must exist.

       A menubar is a widget that simplifies the task of creating menu hierar-
       chies. It encapsulates a	frame widget, as well as  menubuttons,	menus,
       and  menu  entries. The menubar allows menus to be specified and	refer-
       enced in	a more consistent manner than using  Tk	 to  build  menus  di-
       rectly.

       Menubar allows a	menu tree to be	expressed in a hierachical "language".
       The menubar accepts a menuButtons option	that allows a list of menubut-
       tons  to	 be  added  to the menubar. In turn, each menubutton accepts a
       menu option that	specifies a list of menu entries to be	added  to  the
       menubutton's  menu.  Cascade  entries  also  accept the menu option for
       specifying a list of menu entries to be added to	the cascade's menu.

       Additionally, the menubar allows	each component of the  menubar	system
       to  be referenced by a simple menuPathName syntax. The menubar also ex-
       tends the set of	options	for menu entries to include a helpStr option.

MENU PATH NAMES
       A menuPathName is a series of component	names  separated  by  the  `.'
       character. Each menubar component can be	referenced via these menuPath-
       Names. menuPathNames are	similar	to widget pathNames in Tk. Some	corre-
       spond  directly	to  a  widget  pathName	 (components  of  type menu or
       menubutton), others correspond to a menu	entry type. Every  widget  and
       entry  in a menubar can be referenced with the menuPathName naming con-
       vention.	A menubar can have four	types of components:

	      frame. A menubar holds exactly one frame which manages  menubut-
	      tons.  The frame is always signified by the `.' character	as the
	      path name.

	      menubutton. A menubutton corresponds directly to a  Tk  menubut-
	      ton. See menubutton(n).

	      menu.  A	menu  is  attached to a	menubutton and corresponds di-
	      rectly to	Tk's menu widget. A menu is always  signified  by  the
	      menuPathName ending with the keyword menu. See menu(n).

	      entry.  An  entry	 corresponds  directly to Tk's menu widget en-
	      tries. Menus consist of a	column of one  line  entries.  Entries
	      may be of	type: command, checkbutton, radiobutton, separator, or
	      cascade. For a complete description of these types see the  dis-
	      cussion on ENTRIES in menu(n).

       The suffix of a menuPathName may	have the form of:

       tkWidgetName  Specifies	the  name  of  the  component, either a	frame,
		     menubutton, menu, or an entry. This is the	normal	naming
		     of	 widgets.  For	example, .file references a menubutton
		     named file.

       The menuPathName	is a series of segment names, each  separated  by  the
       '.' character. Segment names may	be one of the following	forms:

       number	     Specifies	the  index  of the the component. For menubut-
		     tons, 0 corresponds to the	left-most  menubutton  of  the
		     menu bar frame. As	an example, .1 would correspond	to the
		     second menubutton on the menu bar frame.

		     For entries, 0 corresponds	to the top-most	entry  of  the
		     menu.  For	example, .file.0 would correspond to the first
		     entry on the menu attached	to the menubutton named	file.

       end	     Specifes the last component. For menubuttons,  it	speci-
		     fies the right-most entry of the menu bar frame. For menu
		     entries, it specifies the bottom-most entry of the	menu.

       last	     Same as end.

       Finally,	menu components	always end with	the menu keyword. These	compo-
       nents are automatically created via the -menu option on menubuttons and
       cascades	or via the add or insert commands.

       menu	     Specifes the menu pane that is associated with the	 given
		     menubutton	 prefix. For example, .file.menu specifies the
		     menu pane attached	to the .file menubutton.

       For example, the	path .file.new specifies the entry named  new  on  the
       menu  associated	 with the file menubutton located on the menu bar. The
       path .file.menu specifies the menu pane associated with the  menubutton
       .file. The path .last specifies the last	menu on	the menu bar. The path
       .0.last would specify the first menu (file) and the last	entry on  that
       menu (quit), yielding .file.quit.

       As  a  restriction, the last name segment of menuPathName cannot	be one
       of the keywords last, menu, end,	nor may	it be a	numeric	 value	(inte-
       ger).

WIDGET-SPECIFIC	METHODS
       The  iwidgets::menubar  command creates a new Tcl command whose name is
       pathName.  This command may be used to invoke various operations	on the
       widget.	It  has	 the  following	general	form: pathName option ?arg arg
       ...?  option and	the args determine the exact behavior of the command.

       In addition, many of the	widget commands	for menubar take as one	 argu-
       ment a path name	to a menu component. These path	names are called menu-
       PathNames. See the discussion on	MENUBAR	PATH NAMES above.

       The following commands are possible for menubar widgets:

       pathName	add type menuPathName ?option value option value?
	      Adds either a menu to the	menu bar or a menu  entry  to  a  menu
	      pane.

	      If additional arguments are present, they	specify	options	avail-
	      able to component	type entry. See	the man	pages for  menu(1)  in
	      the section on ENTRIES.

	      If type is one of	cascade, checkbutton, command, radiobutton, or
	      separator	it adds	a new entry to the bottom of the menu  denoted
	      by  the  prefix  of  menuPathName.  If  additonal	 arguments are
	      present, they specify options available to menu  entry  widgets.
	      In  addition,  the helpStr option	is added by the	menubar	widget
	      to all components	of type	entry.

	      -helpstr value
		     Specifes the string to associate with the entry. When the
		     mouse  moves  over	the associated entry, the variable de-
		     noted by helpVariable is set. Another widget can bind  to
		     the helpVariable and thus display status help.

	      If  the  type of the component added is menubutton or cascade, a
	      menubutton or cascade is added to	the menubar. If	additional ar-
	      guments  are present, they specify options available to menubut-
	      ton or cascade widgets. In addition, the menu option is added by
	      the menubar widget to all	menubutton and cascade widgets.

	      -menu menuSpec
		     This  is  only valid for menuPathNames of type menubutton
		     or	cascade. Specifes an option set	and/or a  set  of  en-
		     tries  to place on	a menu and associate with the menubut-
		     ton or cascade. The option	keyword	allows the menu	widget
		     to	be configured. Each item in the	menuSpec is treated as
		     add commands (each	with the possibility of	 having	 other
		     -menu  options).  In  this	 way a menu can	be recursively
		     built.

		     The last segment of menuPathName cannot  be  one  of  the
		     keywords  last,  menu, end. Additionally, it may not be a
		     number. However the menuPathName  may  be	referenced  in
		     this manner (see discussion of COMPONENT PATH NAMES).

		     Note  that	 the  same  curly brace	quoting	rules apply to
		     -menu  option  strings  as	 did  to  -menubuttons	option
		     strings.  See  the	 earlier discussion on umenubuttons in
		     the "WIDGET-SPECIFIC OPTIONS" section.

       pathName	cget option
	      Returns the current value	of the configuration option  given  by
	      option.

       pathName	configure ?options value option	value?
	      Query  or	 modify	the configuration options of the widget. If no
	      option is	specified, returns a list describing all of the	avail-
	      able  options for	pathName (see Tk_ConfigureInfo for information
	      on the format of this list). If  option  is  specified  with  no
	      value,  then the command returns a list describing the one named
	      option (this list	will be	identical to the corresponding sublist
	      of the value returned if no option is specified).	If one or more
	      option-value pairs are specified,	then the command modifies  the
	      given  widget option(s) to have the given	value(s); in this case
	      the command returns an empty string.

       pathName	delete menuPathName ?menuPathName2?
	      If menuPathName is of component type Menubutton or Menu,	delete
	      operates	on  menus. If menuPathName is of component type	Entry,
	      delete operates on menu entries.

	      This command deletes all	components  between  menuPathName  and
	      menuPathName2 inclusive. If menuPathName2	is omitted then	it de-
	      faults to	menuPathName. Returns an empty string.

	      If menuPathName is of type menubar, then all menus and the  menu
	      bar  frame  will be destroyed. In	this case menuPathName2	is ig-
	      nored.

       pathName	index menuPathName
	      If menuPathName is of type menubutton or menu,  it  returns  the
	      position of the menu/menubutton on the menubar frame.

	      If  menuPathName	is  of	type  command, separator, radiobutton,
	      checkbutton, or cascade, it returns the menu widget's  numerical
	      index  for  the  entry corresponding to menuPathName. If path is
	      not found	or the path is equal to	".", a	value  of  -1  is  re-
	      turned.

       pathName	insert menuPathName type name ?option value?
	      Insert a new component named name	before the component specified
	      by menuPathName.

	      If menuPathName is of type Menubutton or Menu, the new component
	      inserted	is  of type Menu and given the name name. In this case
	      valid option value pairs are those accepted by menubuttons.

	      If menuPathName is of type Entry,	the new	component inserted  is
	      of  type	entry and given	the name name. In this case, valid op-
	      tion value pairs are those accepted by menu entries.  Name  can-
	      not be one of the	keywords last, menu, end. Additionally,	it may
	      not be a number. However the menuPathName	may be	referenced  in
	      this manner (see discussion of COMPONENT PATH NAMES).

       pathName	invoke menuPathName
	      Invoke the action	of the menu entry denoted by menuPathName. See
	      the sections on the individual entries in	the menu(1) man	pages.
	      If the menu entry	is disabled then nothing happens. If the entry
	      has a command associated with it then the	result of that command
	      is  returned  as the result of the invoke	widget command.	Other-
	      wise the result is an empty string.

	      If menuPathName is not a menu entry, an error is issued.

       pathName	menucget menuPathName option
	      Returns the current value	of the configuration option  given  by
	      option.  The component type of menuPathName determines the valid
	      available	options.

       pathName	menuconfigure menuPathName ?option value?
	      Query or modify the configuration	options	of the componet	of the
	      menubar  specified  by  menuPathName. If no option is specified,
	      returns a	list describing	all of the available options for menu-
	      PathName	(see Tk_ConfigureInfo for information on the format of
	      this list). If option is specified with no value,	then the  com-
	      mand  returns  a list describing the one named option (this list
	      will be identical	to the corresponding sublist of	the value  re-
	      turned  if  no option is specified). If one or more option-value
	      pairs are	specified, then	the command modifies the given	widget
	      option(s)	 to  have the given value(s); in this case the command
	      returns an empty string. The component type of menuPathName  de-
	      termines the valid available options.

       pathName	path ?mode? pattern
	      Returns  a fully formed menuPathName that	matches	pattern. If no
	      match is found it	returns	-1. The	mode  argument	indicates  how
	      the search is to be matched against pattern and it must have one
	      of the following values:

	      -glob  Pattern is	a glob-style pattern which is matched  against
		     each  component  path  using the same rules as the	string
		     match command.

	      -regexp
		     Pattern is	treated	as a regular  expression  and  matched
		     against each component of the menuPathName	using the same
		     rules as the regexp command.  The default mode is -glob.

       pathName	type menuPathName
	      Returns the type of the component	specified by menuPathName. For
	      menu entries, this is the	type argument passed to	the add/insert
	      widget command when the entry was	created, such  as  command  or
	      separator. Othewise it is	either a menubutton or a menu.

       pathName	yposition menuPathName
	      Returns a	decimal	string giving the y-coordinate within the menu
	      window of	the topmost pixel in the entry specified by  menuPath-
	      Name. If the menuPathName	is not an entry, an error is issued.

EXAMPLE	ONE: USING GRAMMAR
       The  following example creates a	menubar	with "File", "Edit", "Options"
       menubuttons. Each of these menubuttons has an associated	menu.  In turn
       the  File  menu	has menu entries, as well as the Edit menu and the Op-
       tions menu. The Options menu is a tearoff menu  with  selectColor  (for
       radiobuttons) set to blue.  In addition,	the Options menu has a cascade
       titled More, with several menu entries attached to it as	well. An entry
       widget  is  provided  to	display	help status.  package require Iwidgets
       4.0 iwidgets::menubar .mb -helpvariable helpVar -menubuttons {
	   menubutton file -text File -menu {
	       options -tearoff	false
	       command new -label New \
		   -helpstr "Open new document"	\
		   -command {puts NEW}
	       command close -label Close \
		   -helpstr "Close current document" \
		   -command {puts CLOSE}
	       separator sep1
	       command exit -label Exit	-command {exit}	\
		   -helpstr "Exit application"
	   }
	   menubutton edit -text Edit -menu {
	       options -tearoff	false
	       command undo -label Undo	-underline 0 \
		   -helpstr "Undo last command"	\
		   -command {puts UNDO}
	       separator sep2
	       command cut -label Cut -underline 1 \
		   -helpstr "Cut selection to clipboard" \
		   -command {puts CUT}
	       command copy -label Copy	-underline 1 \
		   -helpstr "Copy selection to clipboard" \
		   -command {puts COPY}
	       command paste -label Paste -underline 0 \
		   -helpstr "Paste clipboard contents" \
		   -command {puts PASTE}
	   }
	   menubutton options -text Options -menu {
	       options -tearoff	false -selectcolor blue
	       radiobutton byName -variable viewMode \
		   -value NAME -label "by Name"	\
		   -helpstr "View files	by name	order" \
		   -command {puts NAME}
	       radiobutton byDate -variable viewMode \
		   -value DATE -label "by Date"	\
		   -helpstr "View files	by date	order" \
		   -command {puts DATE}
	       cascade prefs -label Preferences	-menu {
		   command colors -label Colors... \
		       -helpstr	"Change	text colors" \
		       -command	{puts COLORS}
		   command fonts -label	Fonts... \
		       -helpstr	"Change	text font" \
		       -command	{puts FONT}
	       }
	   }

       } frame .fr -width 300 -height 300 entry	.ef -textvariable helpVar pack
       .mb -anchor nw -fill x -expand yes pack .fr -fill both -expand yes pack
       .ef -anchor sw -fill x -expand yes

EXAMPLE	TWO: USING METHODS
       Alternatively the same menu could be created by using the add and  con-
       figure methods:

	package	require	Iwidgets 4.0
	iwidgets::menubar .mb
	.mb configure -menubuttons {
	       menubutton file -text File -menu	{
		       command new -label New
		       command close -label Close
		       separator sep1
		       command	      quit -label Quit
	       }
	       menubutton edit -text Edit
	}
	.mb add	command	.edit.undo -label Undo -underline 0
	.mb add	separator .edit.sep2
	.mb add	command	.edit.cut -label Cut -underline	1
	.mb add	command	.edit.copy -label Copy -underline 1
	.mb add	command	.edit.paste -label Paste -underline 0

	.mb add	menubutton .options -text Options -menu	{
	       radiobutton byName -variable viewMode \
			-value NAME -label "by Name"
	       radiobutton byDate -variable viewMode \
			-value DATE -label "by Date"
       }

	.mb add	cascade	.options.prefs -label Preferences -menu	{
		       command colors -label Colors...
		       command fonts -label Fonts...
	}
	pack .mb -side left -anchor nw -fill x -expand yes

CAVEATS
       The  -menubuttons  option  as  well as the -menu	option is evaluated by
       menubar with the	subst command. The positive side of this is  that  the
       option string may contain variables, commands, and/or backslash substi-
       tutions.	However, substitutions might expand into more  than  a	single
       word.  These expansions can be protected	by enclosing candidate substi-
       tutions in curly	braces ({}). This ensures, for example,	a value	for an
       option will still be treated as a single	value and not multiple values.
       The following example illustrates this case:

	      set fileMenuName "File Menu"
	      set var {}
	      iwidgets::menubar	.mb -menubuttons {
		      menubutton file -text {$fileMenuName}
		      menubutton edit -text Edit -menu {
			      checkbutton check	\
				      -label Check \
				      -variable	{[scope	var]} \
				      -onvalue 1 \
				      -offvalue	0
		      }
		      menubutton options -text Options
	      }

	      The variable fileMenuName	will expand to "File  Menu"  when  the
	      subst  command is	used on	the menubutton specification. In addi-
	      tion, the	[scope...] command will	expand to @scope  ::  var.  By
	      enclosing	these inside {}	they stay as a single value. Note that
	      only {} work for this. [list...],	"" etc.	will not protect these
	      from the subst command.

ACKNOWLEDGMENTS
       Bret Schumaker

	      1994 - Early work	on a menubar widget.

       Mark Ulferts, Mark Harrison, John Sigler

	      Invaluable feedback on grammar and usability of the menubar wid-
	      get

AUTHOR
       Bill W. Scott

KEYWORDS
       frame, menu, menubutton,	entries, help

Tk							  iwidgets::menubar(1)

NAME | SYNOPSIS | INHERITANCE | STANDARD OPTIONS | WIDGET-SPECIFIC OPTIONS | DESCRIPTION | MENU PATH NAMES | WIDGET-SPECIFIC METHODS | EXAMPLE ONE: USING GRAMMAR | EXAMPLE TWO: USING METHODS | CAVEATS | ACKNOWLEDGMENTS | AUTHOR | KEYWORDS

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

home | help