1iwidgets::menubar  −  Create  and manipulate menubar menu widgets

iwidgets::menubar pathName ?options? itk::Widget <‐ iwid‐

3gets::Menubar

activeBackground activeBorderWidth activeForeground

anchor background borderWidth

cursor disabledForeground font

foreground highlightBackground hightlightColor

highligthThickness justify relief

padX padY wrapLength

10See  the  "options"  manual entry for details on the standard op‐
11tions.
12Name:           helpVariable
13Class:          HelpVariable
14Command‐Line Switch:           ‐helpvariable
15Specifies the global variable to update whenever the mouse is  in
16motion  over  a  menu entry. This global variable is updated with
17the current value of the active menu entry’s helpStr. Other  wid‐
18gets  can  "watch" this variable with the trace command, or as is
19the case  with  entry  or  label  widgets,  they  can  set  their

textVariable to the same global variable. This allows for a sim‐

21ple implementation of a  help  status  bar.  Whenever  the  mouse
22leaves  a menu entry, the helpVariable is set to the empty string
23{}. The mainwindow(1) associates its helpstatus and  its  menubar
24in this fashion.
25Name:           menuButtons
26Class:          MenuButtons
27Command‐Line Switch:           ‐menubuttons
28The menuButton option is a string which specifies the arrangement
29of menubuttons on the menubar frame. Each menubutton entry is de‐
30limited by the newline character.
31iwidgets::menubar .mb ‐menubuttons {
32        menubutton file ‐text File
33        menubutton edit ‐text Edit
34        menubutton options ‐text Options
35}
36specifies  that  three  menubuttons  will be added to the menubar
37(file, edit, options). Each entry is translated into an add  com‐
38mand call.  The menuButtons option can accept embedded variables,
39commands, and backslash quoting. Embedded variables and  commands
40must be enclosed in curly braces ({}) to ensure proper parsing of
41the substituted values.  The iwidgets::menubar command creates  a
42new  window  (given by the pathName argument) and makes it into a
44specified  on  the command line or in the option database to con‐
45figure aspects of the menubar such as its colors  and  font.  The

iwidgets::menubar command returns its pathName argument. At the

47time this command is invoked, there must not exist a window named
48pathName,  but pathName’s parent must exist.  A menubar is a wid‐
49get that simplifies the task of creating menu hierarchies. It en‐
50capsulates  a  frame  widget,  as well as menubuttons, menus, and
51menu entries. The menubar allows menus to be specified and refer‐
52enced  in  a  more consistent manner than using Tk to build menus
53directly.
54
56guage".  The  menubar  accepts a menuButtons option that allows a
57list of menubuttons to be added to the  menubar.  In  turn,  each
58menubutton  accepts  a  menu option that specifies a list of menu
59entries to be added to the menubutton’s menu. Cascade entries al‐
60so  accept  the menu option for specifying a list of menu entries
61to be added to the cascade’s menu.
62
63Additionally, the menubar allows each component  of  the  menubar
64system  to  be  referenced  by  a simple menuPathName syntax. The
65menubar also extends the set of options for menu entries  to  in‐
66clude  a helpStr option.  A menuPathName is a series of component
67names separated by the ‘.’ character. Each menubar component  can
68be  referenced via these menuPathNames. menuPathNames are similar
69to widget pathNames in Tk. Some correspond directly to  a  widget
70pathName  (components  of type menu or menubutton), others corre‐
71spond to a menu entry type. Every widget and entry in  a  menubar
72can  be  referenced  with  the  menuPathName naming convention. A
73menubar can have four types of components: frame. A menubar holds
74exactly  one frame which manages menubuttons. The frame is always
75signified by the ‘.’ character as the path name.   menubutton.  A
76menubutton  corresponds directly to a Tk menubutton. See menubut‐
77ton(n).  menu. A menu is attached to a menubutton and corresponds
78directly  to  Tk’s menu widget. A menu is always signified by the
80An  entry corresponds directly to Tk’s menu widget entries. Menus
81consist of a column of one line entries. Entries may be of  type:

command, checkbutton, radiobutton, separator, or cascade. For a

83complete description of these types see the discussion on ENTRIES
84in  menu(n).   The suffix of a menuPathName may have the form of:

tkWidgetName Specifies the name of the component, either a frame,

87gets. For example, .file references a menubutton named file.  The
89’.’ character. Segment names may be one of the  following  forms:

number Specifies the index of the the component. For menubuttons,

910 corresponds to the left‐most menubutton of the menu bar  frame.
92As  an  example,  .1 would correspond to the second menubutton on
93the menu bar frame.  For entries, 0 corresponds to  the  top‐most
94entry  of  the menu. For example, .file.0 would correspond to the
95first entry on the menu attached to the  menubutton  named  file.

end Specifes the last component. For menubuttons, it specifies

97the right‐most entry of the menu bar frame. For menu entries,  it
98specifies  the  bottom‐most entry of the menu.  last Same as end.
99Finally, menu components always end with the menu keyword.  These
100components  are  automatically  created  via  the ‐menu option on
101menubuttons and cascades or via the add or insert commands.  menu
102Specifes the menu pane that is associated with the given menubut‐
103ton prefix. For example, .file.menu specifies the menu  pane  at‐
104tached  to the .file menubutton.  For example, the path .file.new
105specifies the entry named new on the  menu  associated  with  the
106file  menubutton  located  on  the  menu bar. The path .file.menu
107specifies the menu pane associated with the menubutton .file. The
108path  .last  specifies  the  last  menu on the menu bar. The path

.0.last would specify the first menu (file) and the last entry on

110that menu (quit), yielding .file.quit.
111
112As a restriction, the last name segment of menuPathName cannot be
113one of the keywords last, menu, end, nor may it be a numeric val‐
114ue  (integer).   The  iwidgets::menubar command creates a new Tcl
115command whose name is pathName.  This command may be used to  in‐
116voke  various operations on the widget. It has the following gen‐
117eral form: pathName option ?arg arg ...?  option and the args de‐
118termine  the exact behavior of the command.  In addition, many of
119the widget commands for menubar take as one argument a path  name
120to  a  menu component. These path names are called menuPathNames.
121See the discussion on MENUBAR PATH NAMES  above.   The  following
122commands  are  possible  for  menubar  widgets: pathName add type
124the menu bar or a menu entry to a menu pane.  If additional argu‐
125ments are present, they specify options  available  to  component
126type  entry.  See the man pages for menu(1) in the section on EN‐

TRIES.

128
129If type is one of cascade, checkbutton, command, radiobutton,  or

separator it adds a new entry to the bottom of the menu denoted

131by  the  prefix  of  menuPathName.  If  additonal  arguments  are
132present, they specify options available to menu entry widgets. In
133addition, the helpStr option is added by the  menubar  widget  to
134all components of type entry.  ‐helpstr value Specifes the string
135to associate with the entry. When the mouse moves over the  asso‐
136ciated entry, the variable denoted by helpVariable is set. Anoth‐
137er widget can bind to the helpVariable and  thus  display  status
138help.   If  the type of the component added is menubutton or cas‐

cade, a menubutton or cascade is added to the menubar. If addi‐

140tional  arguments  are present, they specify options available to
141menubutton or cascade widgets. In addition, the  menu  option  is
142added  by  the  menubar widget to all menubutton and cascade wid‐
143gets.  ‐menu menuSpec This is only  valid  for  menuPathNames  of
144type  menubutton  or cascade. Specifes an option set and/or a set
145of entries to place on a menu and associate with  the  menubutton
146or  cascade. The option keyword allows the menu widget to be con‐
147figured. Each item in the menuSpec is  treated  as  add  commands
148(each  with  the  possibility  of having other ‐menu options). In
149this way a menu can be recursively built.  The  last  segment  of
151tionally, it may not be a number. However the menuPathName may be
152referenced  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

155the earlier discussion on umenubuttons  in  the  "WIDGET‐SPECIFIC

OPTIONS" section. pathName cget option Returns the current value

157of the configuration option given by option.  pathName  configure
158?options  value  option value?  Query or modify the configuration
159options of the widget. If no option is specified, returns a  list
160describing all of the available options for pathName (see Tk_Con‐

figureInfo for information on the format of this list). If option

162is  specified  with no value, then the command returns a list de‐
163scribing the one named option (this list will be identical to the
164corresponding sublist of the value returned if no option is spec‐
165ified). If one or more option‐value pairs are specified, then the
166command  modifies  the  given  widget option(s) to have the given
167value(s); in this case  the  command  returns  an  empty  string.

pathName delete menuPathName ?menuPathName2? If menuPathName is

169of component type Menubutton or Menu, delete operates  on  menus.
170If  menuPathName  is  of component type Entry, delete operates on
171menu entries.
172
173This command deletes  all  components  between  menuPathName  and
175faults to menuPathName. Returns an empty string.
176
177If menuPathName is of type menubar, then all menus and  the  menu
178bar  frame  will  be destroyed. In this case menuPathName2 is ig‐
179nored.  pathName index menuPathName If menuPathName  is  of  type
180menubutton  or menu, it returns the position of the menu/menubut‐
181ton on the menubar frame.
182
183If menuPathName  is  of  type  command,  separator,  radiobutton,

checkbutton, or cascade, it returns the menu widget’s numerical

185index for the entry corresponding to menuPathName. If path is not
186found  or  the  path  is equal to ".", a value of ‐1 is returned.

pathName insert menuPathName type name ?option value? Insert a

188new  component named name before the component specified by menu‐

PathName. If menuPathName is of type Menubutton or Menu, the new

190component  inserted  is  of type Menu and given the name name. In
191this case valid option value pairs are those accepted by menubut‐
192tons.   If  menuPathName  is of type Entry, the new component in‐
193serted is of type entry and given the name name.  In  this  case,
194valid  option  value  pairs  are  those accepted by menu entries.

Name cannot be one of the keywords last, menu, end. Additionally,

196it  may  not  be a number. However the menuPathName may be refer‐
197enced in this manner (see discussion of  COMPONENT  PATH  NAMES).

pathName invoke menuPathName Invoke the action of the menu entry

199denoted by menuPathName. See the sections on the  individual  en‐
200tries  in  the  menu(1)  man pages. If the menu entry is disabled
201then nothing happens. If the entry has a command associated  with
202it  then  the result of that command is returned as the result of
203the invoke widget command.  Otherwise  the  result  is  an  empty
204string.
205
206If  menuPathName  is not a menu entry, an error is issued.  path‐

Name menucget menuPathName option Returns the current value of

208the  configuration  option given by option. The component type of
211configuration options of the componet of the menubar specified by
213ing all of the available options for menuPathName (see Tk_Config‐

ureInfo for information on the format of this list). If option is

215specified with no value, then the command returns a list describ‐
216ing the one named option (this list will be identical to the cor‐
217responding sublist of the value returned if no option  is  speci‐
218fied).  If one or more option‐value pairs are specified, then the
219command modifies the given widget option(s)  to  have  the  given
220value(s);  in  this case the command returns an empty string. The
221component type of menuPathName determines the valid available op‐
222tions.  pathName path ?mode? pattern Returns a fully formed menu‐

PathName that matches pattern. If no match is found it returns

224‐1.  The  mode argument indicates how the search is to be matched
225against pattern and it must have one  of  the  following  values:

‐glob Pattern is a glob‐style pattern which is matched against

227each component path using the same rules as the string match com‐
228mand.   ‐regexp  Pattern  is  treated as a regular expression and
229matched against each component of the menuPathName using the same
230rules  as  the regexp command.  The default mode is ‐glob.  path‐

Name type menuPathName Returns the type of the component speci‐

232fied by menuPathName. For menu entries, this is the type argument
233passed to the add/insert widget command when the entry was creat‐
234ed,  such  as  command  or  separator.  Othewise  it  is either a
236decimal  string giving the y‐coordinate within the menu window of
237the topmost pixel in the entry specified by menuPathName. If  the
239example creates a menubar with "File", "Edit", "Options" menubut‐
240tons.  Each of these menubuttons has an associated menu.  In turn
241the File menu has menu entries, as well as the Edit menu and  the
242Options menu. The Options menu is a tearoff menu with selectColor
243(for radiobuttons) set to blue.  In addition,  the  Options  menu
244has  a cascade titled More, with several menu entries attached to
245it as well. An entry widget is provided to display  help  status.
246package  require Iwidgets 4.0 iwidgets::menubar .mb ‐helpvariable
247helpVar ‐menubuttons {
248    menubutton file ‐text File ‐menu {
249        options ‐tearoff false
250        command new ‐label New \
251            ‐helpstr "Open new document" \
252            ‐command {puts NEW}
253        command close ‐label Close \
254            ‐helpstr "Close current document" \
255            ‐command {puts CLOSE}
256        separator sep1
257        command exit ‐label Exit ‐command {exit} \
258            ‐helpstr "Exit application"
259    }
260    menubutton edit ‐text Edit ‐menu {
261        options ‐tearoff false
262        command undo ‐label Undo ‐underline 0 \
263            ‐helpstr "Undo last command" \
264            ‐command {puts UNDO}
265        separator sep2
266        command cut ‐label Cut ‐underline 1 \
267            ‐helpstr "Cut selection to clipboard" \
268            ‐command {puts CUT}
269        command copy ‐label Copy ‐underline 1 \
270            ‐helpstr "Copy selection to clipboard" \
271            ‐command {puts COPY}
272        command paste ‐label Paste ‐underline 0 \
273            ‐helpstr "Paste clipboard contents" \
274            ‐command {puts PASTE}
275    }
276    menubutton options ‐text Options ‐menu {
277        options ‐tearoff false ‐selectcolor blue
278        radiobutton byName ‐variable viewMode \
279            ‐value NAME ‐label "by Name" \
280            ‐helpstr "View files by name order" \
281            ‐command {puts NAME}
282        radiobutton byDate ‐variable viewMode \
283            ‐value DATE ‐label "by Date" \
284            ‐helpstr "View files by date order" \
285            ‐command {puts DATE}
286        cascade prefs ‐label Preferences ‐menu {
287            command colors ‐label Colors... \
288                ‐helpstr "Change text colors" \
289                ‐command {puts COLORS}
290            command fonts ‐label Fonts... \
291                ‐helpstr "Change text font" \
292                ‐command {puts FONT}
293        }
294    }
295
296} frame .fr ‐width 300 ‐height 300 entry .ef ‐textvariable  help‐
297Var  pack  .mb ‐anchor nw ‐fill x ‐expand yes pack .fr ‐fill both
298‐expand yes pack .ef ‐anchor sw ‐fill x ‐expand yes Alternatively
299the  same  menu  could  be created by using the add and configure
300methods:
301 package require Iwidgets 4.0
302 iwidgets::menubar .mb
303 .mb configure ‐menubuttons {
304        menubutton file ‐text File ‐menu {
305                command new ‐label New
306                command close ‐label Close
307                separator sep1
308                command        quit ‐label Quit
309        }
310        menubutton edit ‐text Edit
311 }
312 .mb add command .edit.undo ‐label Undo ‐underline 0
313 .mb add separator .edit.sep2
314 .mb add command .edit.cut ‐label Cut ‐underline 1
315 .mb add command .edit.copy ‐label Copy ‐underline 1
316 .mb add command .edit.paste ‐label Paste ‐underline 0
317
318 .mb add menubutton .options ‐text Options ‐menu {
319        radiobutton byName ‐variable viewMode \
320                 ‐value NAME ‐label "by Name"
321        radiobutton byDate ‐variable viewMode \
322                 ‐value DATE ‐label "by Date"
323}
324
325 .mb add cascade .options.prefs ‐label Preferences ‐menu {
326                command colors ‐label Colors...
327                command fonts ‐label Fonts...
328 }
329 pack .mb ‐side left ‐anchor nw ‐fill x ‐expand yes
330The ‐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 substitutions. However, substitutions might expand into more than a single word. These expansions can be protected by enclosing candidate substitutions 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:
331set fileMenuName "File Menu"
332set var {}
333iwidgets::menubar .mb ‐menubuttons {
334        menubutton file ‐text {$fileMenuName}
335        menubutton edit ‐text Edit ‐menu {
336                checkbutton check \
337                        ‐label Check \
338                        ‐variable {[scope var]} \
339                        ‐onvalue 1 \
340                        ‐offvalue 0
341        }
342        menubutton options ‐text Options
343}
344The variable fileMenuName will expand to  "File  Menu"  when  the

subst command is used on the menubutton specification. In addi‐

346tion, the [scope...] command will expand to @scope :: var. By en‐
347closing  these  inside  {} they stay as a single value. Note that
348only {} work for this. [list...], "" etc. will not protect  these
349from  the  subst  command.  Bret Schumaker 1994 ‐ Early work on a
350menubar widget.  Mark Ulferts, Mark Harrison, John Sigler Invalu‐
351able feedback on grammar and usability of the menubar widget Bill
352W. Scott frame, menu, menubutton, entries, help
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
Impressum