1menu(n) Tk Built-In Commands menu(n)
2______________________________________________________________________________
6
8 menu, tk_menuSetFocus - Create and manipulate 'menu' widgets and
9 menubars
10
12 menu pathName ?options?
13 tk_menuSetFocus pathName
14
16 -activebackground -borderwidth -foreground
17 -activeborderwidth -cursor -relief
18 -activeforeground -disabledforeground -takefocus
19 -background -font
20 See the options manual entry for details on the standard options.
22
24 Command-Line Name:-postcommand
25 Database Name: postCommand
26 Database Class: Command
27 If this option is specified then it provides a Tcl command to
29 execute each time the menu is posted. The command is invoked by
30 the post widget command before posting the menu. Note that in Tk
31 8.0 on Macintosh and Windows, all post-commands in a system of
32 menus are executed before any of those menus are posted. This
33 is due to the limitations in the individual platforms' menu man‐
34 agers.
35 Command-Line Name:-selectcolor
37 Database Name: selectColor
38 Database Class: Background
39 For menu entries that are check buttons or radio buttons, this
41 option specifies the color to display in the indicator when the
42 check button or radio button is selected.
43 Command-Line Name:-tearoff
45 Database Name: tearOff
46 Database Class: TearOff
47 This option must have a proper boolean value, which specifies
49 whether or not the menu should include a tear-off entry at the
50 top. If so, it will exist as entry 0 of the menu and the other
51 entries will number starting at 1. The default menu bindings
52 arrange for the menu to be torn off when the tear-off entry is
53 invoked. This option is ignored under Aqua/Mac OS X, where
54 menus cannot be torn off.
55 Command-Line Name:-tearoffcommand
57 Database Name: tearOffCommand
58 Database Class: TearOffCommand
59 If this option has a non-empty value, then it specifies a Tcl
61 command to invoke whenever the menu is torn off. The actual
62 command will consist of the value of this option, followed by a
63 space, followed by the name of the menu window, followed by a
64 space, followed by the name of the name of the torn off menu
65 window. For example, if the option's value is “a b” and menu
66 .x.y is torn off to create a new menu .x.tearoff1, then the com‐
67 mand “a b .x.y .x.tearoff1” will be invoked. This option is
68 ignored under Aqua/Mac OS X, where menus cannot be torn off.
69 Command-Line Name:-title
71 Database Name: title
72 Database Class: Title
73 The string will be used to title the window created when this
75 menu is torn off. If the title is NULL, then the window will
76 have the title of the menubutton or the text of the cascade item
77 from which this menu was invoked.
78 Command-Line Name:-type
80 Database Name: type
81 Database Class: Type
82 This option can be one of menubar, tearoff, or normal, and is
84 set when the menu is created. While the string returned by the
85 configuration database will change if this option is changed,
86 this does not affect the menu widget's behavior. This is used by
87 the cloning mechanism and is not normally set outside of the Tk
88 library.
89______________________________________________________________________________
90
92 The menu command creates a new top-level window (given by the pathName
93 argument) and makes it into a menu widget. That menu widget can either
94 be used as a pop-up window or applied to a toplevel (with its -menu
95 option) to make it into the menubar for that toplevel. Additional
96 options, described above, may be specified on the command line or in
97 the option database to configure aspects of the menu such as its colors
98 and font. The menu command returns its pathName argument. At the time
99 this command is invoked, there must not exist a window named pathName,
100 but pathName's parent must exist.
101 A menu is a widget that displays a collection of one-line entries
103 arranged in one or more columns. There exist several different types
104 of entries, each with different properties. Entries of different types
105 may be combined in a single menu. Menu entries are not the same as
106 entry widgets. In fact, menu entries are not even distinct widgets;
107 the entire menu is one widget.
108 Menu entries are displayed with up to three separate fields. The main
110 field is a label in the form of a text string, a bitmap, or an image,
111 controlled by the -label, -bitmap, and -image options for the entry.
112 If the -accelerator option is specified for an entry then a second
113 textual field is displayed to the right of the label. The accelerator
114 typically describes a keystroke sequence that may be used in the appli‐
115 cation to cause the same result as invoking the menu entry. This is a
116 display option, it does not actually set the corresponding binding
117 (which can be achieved using the bind command). The third field is an
118 indicator. The indicator is present only for checkbutton or radiobut‐
119 ton entries. It indicates whether the entry is selected or not, and is
120 displayed to the left of the entry's string.
121 In normal use, an entry becomes active (displays itself differently)
123 whenever the mouse pointer is over the entry. If a mouse button is
124 released over the entry then the entry is invoked. The effect of invo‐
125 cation is different for each type of entry; these effects are described
126 below in the sections on individual entries.
127 Entries may be disabled, which causes their labels and accelerators to
129 be displayed with dimmer colors. The default menu bindings will not
130 allow a disabled entry to be activated or invoked. Disabled entries
131 may be re-enabled, at which point it becomes possible to activate and
132 invoke them again.
133 Whenever a menu's active entry is changed, a <<MenuSelect>> virtual
135 event is send to the menu. The active item can then be queried from the
136 menu, and an action can be taken, such as setting context-sensitive
137 help text for the entry.
138
140 COMMAND ENTRIES
141 The most common kind of menu entry is a command entry, which behaves
142 much like a button widget. When a command entry is invoked, a Tcl com‐
143 mand is executed. The Tcl command is specified with the -command
144 option.
145 SEPARATOR ENTRIES
147 A separator is an entry that is displayed as a horizontal dividing
148 line. A separator may not be activated or invoked, and it has no
149 behavior other than its display appearance.
150 CHECKBUTTON ENTRIES
152 A checkbutton menu entry behaves much like a checkbutton widget. When
153 it is invoked it toggles back and forth between the selected and dese‐
154 lected states. When the entry is selected, a particular value is
155 stored in a particular global variable (as determined by the -onvalue
156 and -variable options for the entry); when the entry is deselected
157 another value (determined by the -offvalue option) is stored in the
158 global variable. An indicator box is displayed to the left of the
159 label in a checkbutton entry. If the entry is selected then the indi‐
160 cator's center is displayed in the color given by the -selectcolor
161 option for the entry; otherwise the indicator's center is displayed in
162 the background color for the menu. If a -command option is specified
163 for a checkbutton entry, then its value is evaluated as a Tcl command
164 each time the entry is invoked; this happens after toggling the
165 entry's selected state.
166 RADIOBUTTON ENTRIES
168 A radiobutton menu entry behaves much like a radiobutton widget.
169 Radiobutton entries are organized in groups of which only one entry may
170 be selected at a time. Whenever a particular entry becomes selected it
171 stores a particular value into a particular global variable (as deter‐
172 mined by the -value and -variable options for the entry). This action
173 causes any previously-selected entry in the same group to deselect
174 itself. Once an entry has become selected, any change to the entry's
175 associated variable will cause the entry to deselect itself. Grouping
176 of radiobutton entries is determined by their associated variables: if
177 two entries have the same associated variable then they are in the same
178 group. An indicator diamond is displayed to the left of the label in
179 each radiobutton entry. If the entry is selected then the indicator's
180 center is displayed in the color given by the -selectcolor option for
181 the entry; otherwise the indicator's center is displayed in the back‐
182 ground color for the menu. If a -command option is specified for a
183 radiobutton entry, then its value is evaluated as a Tcl command each
184 time the entry is invoked; this happens after selecting the entry.
185 CASCADE ENTRIES
187 A cascade entry is one with an associated menu (determined by the -menu
188 option). Cascade entries allow the construction of cascading menus.
189 The postcascade widget command can be used to post and unpost the asso‐
190 ciated menu just next to of the cascade entry. The associated menu
191 must be a child of the menu containing the cascade entry (this is
192 needed in order for menu traversal to work correctly).
193 A cascade entry posts its associated menu by invoking a Tcl command of
195 the form
196 menu post x y
197 where menu is the path name of the associated menu, and x and y are the
198 root-window coordinates of the upper-right corner of the cascade entry.
199 On Unix, the lower-level menu is unposted by executing a Tcl command
200 with the form
201 menu unpost
202 where menu is the name of the associated menu. On other platforms, the
203 platform's native code takes care of unposting the menu.
204 If a -command option is specified for a cascade entry then it is evalu‐
206 ated as a Tcl command whenever the entry is invoked. This is not sup‐
207 ported on Windows.
208 TEAR-OFF ENTRIES
210 A tear-off entry appears at the top of the menu if enabled with the
211 -tearoff option. It is not like other menu entries in that it cannot
212 be created with the add widget command and cannot be deleted with the
213 delete widget command. When a tear-off entry is created it appears as
214 a dashed line at the top of the menu. Under the default bindings,
215 invoking the tear-off entry causes a torn-off copy to be made of the
216 menu and all of its submenus.
217
219 Any menu can be set as a menubar for a toplevel window (see toplevel
220 command for syntax). On the Macintosh, whenever the toplevel is in
221 front, this menu's cascade items will appear in the menubar across the
222 top of the main monitor. On Windows and Unix, this menu's items will be
223 displayed in a menubar across the top of the window. These menus will
224 behave according to the interface guidelines of their platforms. For
225 every menu set as a menubar, a clone menu is made. See the CLONES sec‐
226 tion for more information.
227 As noted, menubars may behave differently on different platforms. One
229 example of this concerns the handling of checkbuttons and radiobuttons
230 within the menu. While it is permitted to put these menu elements on
231 menubars, they may not be drawn with indicators on some platforms, due
232 to system restrictions.
233 SPECIAL MENUS IN MENUBARS
235 Certain menus in a menubar will be treated specially. On the Macin‐
236 tosh, access to the special Application, Window and Help menus is pro‐
237 vided. On Windows, access to the Windows System menu in each window is
238 provided. On X Windows, a special right-justified help menu may be
239 provided if Motif menu compatibility is enabled. In all cases, these
240 menus must be created with the command name of the menubar menu con‐
241 catenated with the special name. So for a menubar named .menubar, on
242 the Macintosh, the special menus would be .menubar.apple, .menubar.win‐
243 dow and .menubar.help; on Windows, the special menu would be
244 .menubar.system; on X Windows, the help menu would be .menubar.help.
245 When Tk sees a .menubar.apple menu as the first menu in a menubar on
247 the Macintosh, that menu's contents make up the first items of the
248 Application menu whenever the window containing the menubar is in
249 front. After all of the Tk-defined items, the menu will have a separa‐
250 tor, followed by all standard Application menu items. Such a .apple
251 menu must be present in a menu when that menu is first configured as a
252 toplevel's menubar, otherwise a default application menu (hidden from
253 Tk) will be inserted into the menubar at that time and subsequent addi‐
254 tion of a .apple menu will no longer result in it becoming the Applica‐
255 tion menu.
256 When Tk sees a .menubar.window menu on the Macintosh, the menu's con‐
258 tents are inserted into the standard Window menu of the user's menubar
259 whenever the window's menubar is in front. The first items in the menu
260 are provided by Mac OS X, and the names of the current toplevels are
261 automatically appended after all the Tk-defined items and a separator.
262 When Tk sees a .menubar.help menu on the Macintosh, the menu's contents
264 are appended to the standard Help menu of the user's menubar whenever
265 the window's menubar is in front. The first items in the menu are pro‐
266 vided by Mac OS X.
267 When Tk sees a System menu on Windows, its items are appended to the
269 system menu that the menubar is attached to. This menu is tied to the
270 application icon and can be invoked with the mouse or by typing
271 Alt+Spacebar. Due to limitations in the Windows API, any font changes,
272 colors, images, bitmaps, or tearoff images will not appear in the sys‐
273 tem menu.
274 When Tk sees a Help menu on X Windows and Motif menu compatibility is
276 enabled the menu is moved to be last in the menubar and is right justi‐
277 fied. Motif menu compatibility is enabled by setting the Tk option
278 *Menu.useMotifHelp to true or by calling tk::classic::restore menu.
279
281 When a menu is set as a menubar for a toplevel window, or when a menu
282 is torn off, a clone of the menu is made. This clone is a menu widget
283 in its own right, but it is a child of the original. Changes in the
284 configuration of the original are reflected in the clone. Additionally,
285 any cascades that are pointed to are also cloned so that menu traversal
286 will work right. Clones are destroyed when either the tearoff or
287 menubar goes away, or when the original menu is destroyed.
288
290 The menu command creates a new Tcl command whose name is pathName.
291 This command may be used to invoke various operations on the widget.
292 It has the following general form:
293 pathName option ?arg arg ...?
294 Option and the args determine the exact behavior of the command.
295 Many of the widget commands for a menu take as one argument an indica‐
297 tor of which entry of the menu to operate on. These indicators are
298 called indexes and may be specified in any of the following forms:
299 active Indicates the entry that is currently active. If no entry
301 is active then this form is equivalent to none. This form
302 may not be abbreviated.
303 end Indicates the bottommost entry in the menu. If there are
305 no entries in the menu then this form is equivalent to
306 none. This form may not be abbreviated.
307 last Same as end.
309 none Indicates “no entry at all”; this is used most commonly
311 with the activate option to deactivate all the entries in
312 the menu. In most cases the specification of none causes
313 nothing to happen in the widget command. This form may not
314 be abbreviated.
315 @number In this form, number is treated as a y-coordinate in the
317 menu's window; the entry closest to that y-coordinate is
318 used. For example, “@0” indicates the top-most entry in
319 the window.
320 number Specifies the entry numerically, where 0 corresponds to the
322 top-most entry of the menu, 1 to the entry below it, and so
323 on.
324 pattern If the index does not satisfy one of the above forms then
326 this form is used. Pattern is pattern-matched against the
327 label of each entry in the menu, in order from the top
328 down, until a matching entry is found. The rules of string
329 match are used.
330 If the index could match more than one of the above forms, then the
332 form earlier in the above list takes precedence.
333 The following widget commands are possible for menu widgets:
335 pathName activate index
337 Change the state of the entry indicated by index to active and
338 redisplay it using its active colors. Any previously-active
339 entry is deactivated. If index is specified as none, or if the
340 specified entry is disabled, then the menu ends up with no
341 active entry. Returns an empty string.
342 pathName add type ?option value option value ...?
344 Add a new entry to the bottom of the menu. The new entry's type
345 is given by type and must be one of cascade, checkbutton, com‐
346 mand, radiobutton, or separator, or a unique abbreviation of one
347 of the above. If additional arguments are present, they specify
348 the options listed in the MENU ENTRY OPTIONS section below. The
349 add widget command returns an empty string.
350 pathName cget option
352 Returns the current value of the configuration option given by
353 option. Option may have any of the values accepted by the menu
354 command.
355 pathName clone newPathname ?cloneType?
357 Makes a clone of the current menu named newPathName. This clone
358 is a menu in its own right, but any changes to the clone are
359 propagated to the original menu and vice versa. cloneType can be
360 normal, menubar, or tearoff. Should not normally be called out‐
361 side of the Tk library. See the CLONES section for more informa‐
362 tion.
363 pathName configure ?option? ?value option value ...?
365 Query or modify the configuration options of the widget. If no
366 option is specified, returns a list describing all of the avail‐
367 able options for pathName (see Tk_ConfigureInfo for information
368 on the format of this list). If option is specified with no
369 value, then the command returns a list describing the one named
370 option (this list will be identical to the corresponding sublist
371 of the value returned if no option is specified). If one or
372 more option-value pairs are specified, then the command modifies
373 the given widget option(s) to have the given value(s); in this
374 case the command returns an empty string. Option may have any
375 of the values accepted by the menu command.
376 pathName delete index1 ?index2?
378 Delete all of the menu entries between index1 and index2 inclu‐
379 sive. If index2 is omitted then it defaults to index1.
380 Attempts to delete a tear-off menu entry are ignored (instead,
381 you should change the -tearoff option to remove the tear-off
382 entry).
383 pathName entrycget index option
385 Returns the current value of a configuration option for the
386 entry given by index. Option may have any of the names
387 described in the MENU ENTRY OPTIONS section below.
388 pathName entryconfigure index ?options...?
390 This command is similar to the configure command, except that it
391 applies to the options for an individual entry, whereas config‐
392 ure applies to the options for the menu as a whole. Options may
393 have any of the values described in the MENU ENTRY OPTIONS sec‐
394 tion below. If options are specified, options are modified as
395 indicated in the command and the command returns an empty
396 string. If no options are specified, returns a list describing
397 the current options for entry index (see Tk_ConfigureInfo for
398 information on the format of this list).
399 pathName index index
401 Returns the numerical index corresponding to index, or none if
402 index was specified as none.
403 pathName insert index type ?option value option value ...?
405 Same as the add widget command except that it inserts the new
406 entry just before the entry given by index, instead of appending
407 to the end of the menu. The type, option, and value arguments
408 have the same interpretation as for the add widget command. It
409 is not possible to insert new menu entries before the tear-off
410 entry, if the menu has one.
411 pathName invoke index
413 Invoke the action of the menu entry. See the sections on the
414 individual entries above for details on what happens. If the
415 menu entry is disabled then nothing happens. If the entry has a
416 command associated with it then the result of that command is
417 returned as the result of the invoke widget command. Otherwise
418 the result is an empty string. Note: invoking a menu entry
419 does not automatically unpost the menu; the default bindings
420 normally take care of this before invoking the invoke widget
421 command.
422 pathName post x y
424 Arrange for the menu to be displayed on the screen at the root-
425 window coordinates given by x and y. These coordinates are
426 adjusted if necessary to guarantee that the entire menu is visi‐
427 ble on the screen. This command normally returns an empty
428 string. If the -postcommand option has been specified, then its
429 value is executed as a Tcl script before posting the menu and
430 the result of that script is returned as the result of the post
431 widget command. If an error returns while executing the com‐
432 mand, then the error is returned without posting the menu.
433 pathName postcascade index
435 Posts the submenu associated with the cascade entry given by
436 index, and unposts any previously posted submenu. If index does
437 not correspond to a cascade entry, or if pathName is not posted,
438 the command has no effect except to unpost any currently posted
439 submenu.
440 pathName type index
442 Returns the type of the menu entry given by index. This is the
443 type argument passed to the add or insert widget command when
444 the entry was created, such as command or separator, or tearoff
445 for a tear-off entry.
446 pathName unpost
448 Unmap the window so that it is no longer displayed. If a lower-
449 level cascaded menu is posted, unpost that menu. Returns an
450 empty string. This subcommand does not work on Windows and the
451 Macintosh, as those platforms have their own way of unposting
452 menus.
453 pathName xposition index
455 Returns a decimal string giving the x-coordinate within the menu
456 window of the leftmost pixel in the entry specified by index.
457 pathName yposition index
459 Returns a decimal string giving the y-coordinate within the menu
460 window of the topmost pixel in the entry specified by index.
461
463 The following options are allowed on menu entries. Most options are not
464 supported by all entry types.
465 -activebackground value
467 Specifies a background color to use for displaying this entry
468 when it is active. If this option is specified as an empty
469 string (the default), then the -activebackground option for the
470 overall menu is used. If the tk_strictMotif variable has been
471 set to request strict Motif compliance, then this option is
472 ignored and the -background option is used in its place. This
473 option is not available for separator or tear-off entries.
474 -activeforeground value
476 Specifies a foreground color to use for displaying this entry
477 when it is active. If this option is specified as an empty
478 string (the default), then the -activeforeground option for the
479 overall menu is used. This option is not available for separa‐
480 tor or tear-off entries.
481 -accelerator value
483 Specifies a string to display at the right side of the menu
484 entry. Normally describes an accelerator keystroke sequence
485 that may be used to invoke the same function as the menu entry.
486 This is a display option, it does not actually set the corre‐
487 sponding binding (which can be achieved using the bind command).
488 This option is not available for separator or tear-off entries.
489 -background value
491 Specifies a background color to use for displaying this entry
492 when it is in the normal state (neither active nor disabled).
493 If this option is specified as an empty string (the default),
494 then the -background option for the overall menu is used. This
495 option is not available for separator or tear-off entries.
496 -bitmap value
498 Specifies a bitmap to display in the menu instead of a textual
499 label, in any of the forms accepted by Tk_GetBitmap. This
500 option overrides the -label option (as controlled by the -com‐
501 pound option) but may be reset to an empty string to enable a
502 textual label to be displayed. If a -image option has been
503 specified, it overrides -bitmap. This option is not available
504 for separator or tear-off entries.
505 -columnbreak value
507 When this option is zero, the entry appears below the previous
508 entry. When this option is one, the entry appears at the top of
509 a new column in the menu. This option is ignored on Aqua/Mac OS
510 X, where menus are always a single column.
511 -command value
513 Specifies a Tcl command to execute when the menu entry is
514 invoked. Not available for separator or tear-off entries.
515 -compound value
517 Specifies whether the menu entry should display both an image
518 and text, and if so, where the image should be placed relative
519 to the text. Valid values for this option are bottom, center,
520 left, none, right and top. The default value is none, meaning
521 that the button will display either an image or text, depending
522 on the values of the -image and -bitmap options.
523 -font value
525 Specifies the font to use when drawing the label or accelerator
526 string in this entry. If this option is specified as an empty
527 string (the default) then the -font option for the overall menu
528 is used. This option is not available for separator or tear-off
529 entries.
530 -foreground value
532 Specifies a foreground color to use for displaying this entry
533 when it is in the normal state (neither active nor disabled).
534 If this option is specified as an empty string (the default),
535 then the -foreground option for the overall menu is used. This
536 option is not available for separator or tear-off entries.
537 -hidemargin value
539 Specifies whether the standard margins should be drawn for this
540 menu entry. This is useful when creating palette with images in
541 them, i.e., color palettes, pattern palettes, etc. 1 indicates
542 that the margin for the entry is hidden; 0 means that the margin
543 is used.
544 -image value
546 Specifies an image to display in the menu instead of a text
547 string or bitmap. The image must have been created by some pre‐
548 vious invocation of image create. This option overrides the
549 -label and -bitmap options (as controlled by the -compound
550 option) but may be reset to an empty string to enable a textual
551 or bitmap label to be displayed. This option is not available
552 for separator or tear-off entries.
553 -indicatoron value
555 Available only for checkbutton and radiobutton entries. Value
556 is a boolean that determines whether or not the indicator should
557 be displayed.
558 -label value
560 Specifies a string to display as an identifying label in the
561 menu entry. Not available for separator or tear-off entries.
562 -menu value
564 Available only for cascade entries. Specifies the path name of
565 the submenu associated with this entry. The submenu must be a
566 child of the menu.
567 -offvalue value
569 Available only for checkbutton entries. Specifies the value to
570 store in the entry's associated variable when the entry is dese‐
571 lected.
572 -onvalue value
574 Available only for checkbutton entries. Specifies the value to
575 store in the entry's associated variable when the entry is
576 selected.
577 -selectcolor value
579 Available only for checkbutton and radiobutton entries. Speci‐
580 fies the color to display in the indicator when the entry is
581 selected. If the value is an empty string (the default) then
582 the -selectcolor option for the menu determines the indicator
583 color.
584 -selectimage value
586 Available only for checkbutton and radiobutton entries. Speci‐
587 fies an image to display in the entry (in place of the -image
588 option) when it is selected. Value is the name of an image,
589 which must have been created by some previous invocation of
590 image create. This option is ignored unless the -image option
591 has been specified.
592 -state value
594 Specifies one of three states for the entry: normal, active, or
595 disabled. In normal state the entry is displayed using the
596 -foreground option for the menu and the -background option from
597 the entry or the menu. The active state is typically used when
598 the pointer is over the entry. In active state the entry is
599 displayed using the -activeforeground option for the menu along
600 with the -activebackground option from the entry. Disabled
601 state means that the entry should be insensitive: the default
602 bindings will refuse to activate or invoke the entry. In this
603 state the entry is displayed according to the -disabledfore‐
604 ground option for the menu and the -background option from the
605 entry. This option is not available for separator entries.
606 -underline value
608 Specifies the integer index of a character to underline in the
609 entry. This option is also queried by the default bindings and
610 used to implement keyboard traversal. 0 corresponds to the
611 first character of the text displayed in the entry, 1 to the
612 next character, and so on. If a bitmap or image is displayed in
613 the entry then this option is ignored. This option is not
614 available for separator or tear-off entries.
615 -value value
617 Available only for radiobutton entries. Specifies the value to
618 store in the entry's associated variable when the entry is
619 selected. If an empty string is specified, then the -label
620 option for the entry as the value to store in the variable.
621 -variable value
623 Available only for checkbutton and radiobutton entries. Speci‐
624 fies the name of a global variable to set when the entry is
625 selected. For checkbutton entries the variable is also set when
626 the entry is deselected. For radiobutton entries, changing the
627 variable causes the currently-selected entry to deselect itself.
628 For checkbutton entries, the default value of this option is
630 taken from the -label option, and for radiobutton entries a sin‐
631 gle fixed value is used. It is recommended that you always set
632 the -variable option when creating either a checkbutton or a
633 radiobutton.
634
636 The default bindings support four different ways of using menus:
637 Pulldown Menus in Menubar
639 This is the most common case. You create a menu widget that will
640 become the menu bar. You then add cascade entries to this menu,
641 specifying the pull down menus you wish to use in your menu bar.
642 You then create all of the pulldowns. Once you have done this,
643 specify the menu using the -menu option of the toplevel's widget
644 command. See the toplevel manual entry for details.
645 Pulldown Menus in Menu Buttons
647 This is the compatible way to do menu bars. You create one
648 menubutton widget for each top-level menu, and typically you
649 arrange a series of menubuttons in a row in a menubar window.
650 You also create the top-level menus and any cascaded submenus,
651 and tie them together with -menu options in menubuttons and cas‐
652 cade menu entries. The top-level menu must be a child of the
653 menubutton, and each submenu must be a child of the menu that
654 refers to it. Once you have done this, the default bindings
655 will allow users to traverse and invoke the tree of menus via
656 its menubutton; see the menubutton manual entry for details.
657 Popup Menus
659 Popup menus typically post in response to a mouse button press
660 or keystroke. You create the popup menus and any cascaded sub‐
661 menus, then you call the tk_popup procedure at the appropriate
662 time to post the top-level menu.
663 Option Menus
665 An option menu consists of a menubutton with an associated menu
666 that allows you to select one of several values. The current
667 value is displayed in the menubutton and is also stored in a
668 global variable. Use the tk_optionMenu procedure to create
669 option menubuttons and their menus.
670 Torn-off Menus
672 You create a torn-off menu by invoking the tear-off entry at the
673 top of an existing menu. The default bindings will create a new
674 menu that is a copy of the original menu and leave it perma‐
675 nently posted as a top-level window. The torn-off menu behaves
676 just the same as the original menu.
677
679 Tk automatically creates class bindings for menus that give them the
680 following default behavior:
681 [1] When the mouse enters a menu, the entry underneath the mouse
683 cursor activates; as the mouse moves around the menu, the
684 active entry changes to track the mouse.
685 [2] When the mouse leaves a menu all of the entries in the menu
687 deactivate, except in the special case where the mouse moves
688 from a menu to a cascaded submenu.
689 [3] When a button is released over a menu, the active entry (if any)
691 is invoked. The menu also unposts unless it is a torn-off menu.
692 [4] The Space and Return keys invoke the active entry and unpost the
694 menu.
695 [5] If any of the entries in a menu have letters underlined with the
697 -underline option, then pressing one of the underlined letters
698 (or its upper-case or lower-case equivalent) invokes that entry
699 and unposts the menu.
700 [6] The Escape key aborts a menu selection in progress without
702 invoking any entry. It also unposts the menu unless it is a
703 torn-off menu.
704 [7] The Up and Down keys activate the next higher or lower entry in
706 the menu. When one end of the menu is reached, the active entry
707 wraps around to the other end.
708 [8] The Left key moves to the next menu to the left. If the current
710 menu is a cascaded submenu, then the submenu is unposted and the
711 current menu entry becomes the cascade entry in the parent. If
712 the current menu is a top-level menu posted from a menubutton,
713 then the current menubutton is unposted and the next menubutton
714 to the left is posted. Otherwise the key has no effect. The
715 left-right order of menubuttons is determined by their stacking
716 order: Tk assumes that the lowest menubutton (which by default
717 is the first one created) is on the left.
718 [9] The Right key moves to the next menu to the right. If the cur‐
720 rent entry is a cascade entry, then the submenu is posted and
721 the current menu entry becomes the first entry in the submenu.
722 Otherwise, if the current menu was posted from a menubutton,
723 then the current menubutton is unposted and the next menubutton
724 to the right is posted.
725 Disabled menu entries are non-responsive: they do not activate and
727 they ignore mouse button presses and releases.
728 Several of the bindings make use of the command tk_menuSetFocus. It
730 saves the current focus and sets the focus to its pathName argument,
731 which is a menu widget.
732 The behavior of menus can be changed by defining new bindings for indi‐
734 vidual widgets or by redefining the class bindings.
735
737 At present it is not possible to use the option database to specify
738 values for the options to individual entries.
739
741 bind(n), menubutton(n), ttk::menubutton(n), toplevel(n)
742
744 menu, widget
745Tk 4.1 menu(n)