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 The Window menu on the Mac also allows toggling the window into a
263 fullscreen state, and managing a tabbed window interface (multiple win‐
264 dows grouped into a single window) if supported by that version of the
265 operating system.
266 When Tk sees a .menubar.help menu on the Macintosh, the menu's contents
268 are appended to the standard Help menu of the user's menubar whenever
269 the window's menubar is in front. The first items in the menu are pro‐
270 vided by Mac OS X.
271 When Tk sees a System menu on Windows, its items are appended to the
273 system menu that the menubar is attached to. This menu is tied to the
274 application icon and can be invoked with the mouse or by typing
275 Alt+Spacebar. Due to limitations in the Windows API, any font changes,
276 colors, images, bitmaps, or tearoff images will not appear in the sys‐
277 tem menu.
278 When Tk sees a Help menu on X Windows and Motif menu compatibility is
280 enabled the menu is moved to be last in the menubar and is right justi‐
281 fied. Motif menu compatibility is enabled by setting the Tk option
282 *Menu.useMotifHelp to true or by calling tk::classic::restore menu.
283
285 When a menu is set as a menubar for a toplevel window, or when a menu
286 is torn off, a clone of the menu is made. This clone is a menu widget
287 in its own right, but it is a child of the original. Changes in the
288 configuration of the original are reflected in the clone. Additionally,
289 any cascades that are pointed to are also cloned so that menu traversal
290 will work right. Clones are destroyed when either the tearoff or
291 menubar goes away, or when the original menu is destroyed.
292
294 The menu command creates a new Tcl command whose name is pathName.
295 This command may be used to invoke various operations on the widget.
296 It has the following general form:
297 pathName option ?arg arg ...?
298 Option and the args determine the exact behavior of the command.
299 Many of the widget commands for a menu take as one argument an indica‐
301 tor of which entry of the menu to operate on. These indicators are
302 called indexes and may be specified in any of the following forms:
303 active Indicates the entry that is currently active. If no entry
305 is active then this form is equivalent to none. This form
306 may not be abbreviated.
307 end Indicates the bottommost entry in the menu. If there are
309 no entries in the menu then this form is equivalent to
310 none. This form may not be abbreviated.
311 last Same as end.
313 none Indicates “no entry at all”; this is used most commonly
315 with the activate option to deactivate all the entries in
316 the menu. In most cases the specification of none causes
317 nothing to happen in the widget command. This form may not
318 be abbreviated.
319 @number In this form, number is treated as a y-coordinate in the
321 menu's window; the entry closest to that y-coordinate is
322 used. For example, “@0” indicates the top-most entry in
323 the window.
324 number Specifies the entry numerically, where 0 corresponds to the
326 top-most entry of the menu, 1 to the entry below it, and so
327 on.
328 pattern If the index does not satisfy one of the above forms then
330 this form is used. Pattern is pattern-matched against the
331 label of each entry in the menu, in order from the top
332 down, until a matching entry is found. The rules of string
333 match are used.
334 If the index could match more than one of the above forms, then the
336 form earlier in the above list takes precedence.
337 The following widget commands are possible for menu widgets:
339 pathName activate index
341 Change the state of the entry indicated by index to active and
342 redisplay it using its active colors. Any previously-active
343 entry is deactivated. If index is specified as none, or if the
344 specified entry is disabled, then the menu ends up with no
345 active entry. Returns an empty string.
346 pathName add type ?option value option value ...?
348 Add a new entry to the bottom of the menu. The new entry's type
349 is given by type and must be one of cascade, checkbutton, com‐
350 mand, radiobutton, or separator, or a unique abbreviation of one
351 of the above. If additional arguments are present, they specify
352 the options listed in the MENU ENTRY OPTIONS section below. The
353 add widget command returns an empty string.
354 pathName cget option
356 Returns the current value of the configuration option given by
357 option. Option may have any of the values accepted by the menu
358 command.
359 pathName clone newPathname ?cloneType?
361 Makes a clone of the current menu named newPathName. This clone
362 is a menu in its own right, but any changes to the clone are
363 propagated to the original menu and vice versa. cloneType can be
364 normal, menubar, or tearoff. Should not normally be called out‐
365 side of the Tk library. See the CLONES section for more informa‐
366 tion.
367 pathName configure ?option? ?value option value ...?
369 Query or modify the configuration options of the widget. If no
370 option is specified, returns a list describing all of the avail‐
371 able options for pathName (see Tk_ConfigureInfo for information
372 on the format of this list). If option is specified with no
373 value, then the command returns a list describing the one named
374 option (this list will be identical to the corresponding sublist
375 of the value returned if no option is specified). If one or
376 more option-value pairs are specified, then the command modifies
377 the given widget option(s) to have the given value(s); in this
378 case the command returns an empty string. Option may have any
379 of the values accepted by the menu command.
380 pathName delete index1 ?index2?
382 Delete all of the menu entries between index1 and index2 inclu‐
383 sive. If index2 is omitted then it defaults to index1.
384 Attempts to delete a tear-off menu entry are ignored (instead,
385 you should change the -tearoff option to remove the tear-off
386 entry).
387 pathName entrycget index option
389 Returns the current value of a configuration option for the
390 entry given by index. Option may have any of the names
391 described in the MENU ENTRY OPTIONS section below.
392 pathName entryconfigure index ?options...?
394 This command is similar to the configure command, except that it
395 applies to the options for an individual entry, whereas config‐
396 ure applies to the options for the menu as a whole. Options may
397 have any of the values described in the MENU ENTRY OPTIONS sec‐
398 tion below. If options are specified, options are modified as
399 indicated in the command and the command returns an empty
400 string. If no options are specified, returns a list describing
401 the current options for entry index (see Tk_ConfigureInfo for
402 information on the format of this list).
403 pathName index index
405 Returns the numerical index corresponding to index, or none if
406 index was specified as none.
407 pathName insert index type ?option value option value ...?
409 Same as the add widget command except that it inserts the new
410 entry just before the entry given by index, instead of appending
411 to the end of the menu. The type, option, and value arguments
412 have the same interpretation as for the add widget command. It
413 is not possible to insert new menu entries before the tear-off
414 entry, if the menu has one.
415 pathName invoke index
417 Invoke the action of the menu entry. See the sections on the
418 individual entries above for details on what happens. If the
419 menu entry is disabled then nothing happens. If the entry has a
420 command associated with it then the result of that command is
421 returned as the result of the invoke widget command. Otherwise
422 the result is an empty string. Note: invoking a menu entry
423 does not automatically unpost the menu; the default bindings
424 normally take care of this before invoking the invoke widget
425 command.
426 pathName post x y ?index?
428 Arrange for the menu to be displayed on the screen at the root-
429 window coordinates given by x and y. If an index is specified
430 the menu will be located so that the entry with that index is
431 displayed at the point. These coordinates are adjusted if nec‐
432 essary to guarantee that the entire menu is visible on the
433 screen. This command normally returns an empty string. If the
434 -postcommand option has been specified, then its value is exe‐
435 cuted as a Tcl script before posting the menu and the result of
436 that script is returned as the result of the post widget com‐
437 mand. If an error returns while executing the command, then the
438 error is returned without posting the menu.
439 pathName postcascade index
441 Posts the submenu associated with the cascade entry given by
442 index, and unposts any previously posted submenu. If index does
443 not correspond to a cascade entry, or if pathName is not posted,
444 the command has no effect except to unpost any currently posted
445 submenu.
446 pathName type index
448 Returns the type of the menu entry given by index. This is the
449 type argument passed to the add or insert widget command when
450 the entry was created, such as command or separator, or tearoff
451 for a tear-off entry.
452 pathName unpost
454 Unmap the window so that it is no longer displayed. If a lower-
455 level cascaded menu is posted, unpost that menu. Returns an
456 empty string. This subcommand does not work on Windows and the
457 Macintosh, as those platforms have their own way of unposting
458 menus.
459 pathName xposition index
461 Returns a decimal string giving the x-coordinate within the menu
462 window of the leftmost pixel in the entry specified by index.
463 pathName yposition index
465 Returns a decimal string giving the y-coordinate within the menu
466 window of the topmost pixel in the entry specified by index.
467
469 The following options are allowed on menu entries. Most options are not
470 supported by all entry types.
471 -activebackground value
473 Specifies a background color to use for displaying this entry
474 when it is active. If this option is specified as an empty
475 string (the default), then the -activebackground option for the
476 overall menu is used. If the tk_strictMotif variable has been
477 set to request strict Motif compliance, then this option is
478 ignored and the -background option is used in its place. This
479 option is not available for separator or tear-off entries.
480 -activeforeground value
482 Specifies a foreground color to use for displaying this entry
483 when it is active. If this option is specified as an empty
484 string (the default), then the -activeforeground option for the
485 overall menu is used. This option is not available for separa‐
486 tor or tear-off entries.
487 -accelerator value
489 Specifies a string to display at the right side of the menu
490 entry. Normally describes an accelerator keystroke sequence
491 that may be used to invoke the same function as the menu entry.
492 This is a display option, it does not actually set the corre‐
493 sponding binding (which can be achieved using the bind command).
494 This option is not available for separator or tear-off entries.
495 -background value
497 Specifies a background color to use for displaying this entry
498 when it is in the normal state (neither active nor disabled).
499 If this option is specified as an empty string (the default),
500 then the -background option for the overall menu is used. This
501 option is not available for separator or tear-off entries.
502 -bitmap value
504 Specifies a bitmap to display in the menu instead of a textual
505 label, in any of the forms accepted by Tk_GetBitmap. This
506 option overrides the -label option (as controlled by the -com‐
507 pound option) but may be reset to an empty string to enable a
508 textual label to be displayed. If a -image option has been
509 specified, it overrides -bitmap. This option is not available
510 for separator or tear-off entries.
511 -columnbreak value
513 When this option is zero, the entry appears below the previous
514 entry. When this option is one, the entry appears at the top of
515 a new column in the menu. This option is ignored on Aqua/Mac OS
516 X, where menus are always a single column.
517 -command value
519 Specifies a Tcl command to execute when the menu entry is
520 invoked. Not available for separator or tear-off entries.
521 -compound value
523 Specifies whether the menu entry should display both an image
524 and text, and if so, where the image should be placed relative
525 to the text. Valid values for this option are bottom, center,
526 left, none, right and top. The default value is none, meaning
527 that the button will display either an image or text, depending
528 on the values of the -image and -bitmap options.
529 -font value
531 Specifies the font to use when drawing the label or accelerator
532 string in this entry. If this option is specified as an empty
533 string (the default) then the -font option for the overall menu
534 is used. This option is not available for separator or tear-off
535 entries.
536 -foreground value
538 Specifies a foreground color to use for displaying this entry
539 when it is in the normal state (neither active nor disabled).
540 If this option is specified as an empty string (the default),
541 then the -foreground option for the overall menu is used. This
542 option is not available for separator or tear-off entries.
543 -hidemargin value
545 Specifies whether the standard margins should be drawn for this
546 menu entry. This is useful when creating palette with images in
547 them, i.e., color palettes, pattern palettes, etc. 1 indicates
548 that the margin for the entry is hidden; 0 means that the margin
549 is used.
550 -image value
552 Specifies an image to display in the menu instead of a text
553 string or bitmap. The image must have been created by some pre‐
554 vious invocation of image create. This option overrides the
555 -label and -bitmap options (as controlled by the -compound
556 option) but may be reset to an empty string to enable a textual
557 or bitmap label to be displayed. This option is not available
558 for separator or tear-off entries.
559 -indicatoron value
561 Available only for checkbutton and radiobutton entries. Value
562 is a boolean that determines whether or not the indicator should
563 be displayed.
564 -label value
566 Specifies a string to display as an identifying label in the
567 menu entry. Not available for separator or tear-off entries.
568 -menu value
570 Available only for cascade entries. Specifies the path name of
571 the submenu associated with this entry. The submenu must be a
572 child of the menu.
573 -offvalue value
575 Available only for checkbutton entries. Specifies the value to
576 store in the entry's associated variable when the entry is dese‐
577 lected.
578 -onvalue value
580 Available only for checkbutton entries. Specifies the value to
581 store in the entry's associated variable when the entry is
582 selected.
583 -selectcolor value
585 Available only for checkbutton and radiobutton entries. Speci‐
586 fies the color to display in the indicator when the entry is
587 selected. If the value is an empty string (the default) then
588 the -selectcolor option for the menu determines the indicator
589 color.
590 -selectimage value
592 Available only for checkbutton and radiobutton entries. Speci‐
593 fies an image to display in the entry (in place of the -image
594 option) when it is selected. Value is the name of an image,
595 which must have been created by some previous invocation of
596 image create. This option is ignored unless the -image option
597 has been specified.
598 -state value
600 Specifies one of three states for the entry: normal, active, or
601 disabled. In normal state the entry is displayed using the
602 -foreground option for the menu and the -background option from
603 the entry or the menu. The active state is typically used when
604 the pointer is over the entry. In active state the entry is
605 displayed using the -activeforeground option for the menu along
606 with the -activebackground option from the entry. Disabled
607 state means that the entry should be insensitive: the default
608 bindings will refuse to activate or invoke the entry. In this
609 state the entry is displayed according to the -disabledfore‐
610 ground option for the menu and the -background option from the
611 entry. This option is not available for separator entries.
612 -underline value
614 Specifies the integer index of a character to underline in the
615 entry. This option is also queried by the default bindings and
616 used to implement keyboard traversal. 0 corresponds to the
617 first character of the text displayed in the entry, 1 to the
618 next character, and so on. If a bitmap or image is displayed in
619 the entry then this option is ignored. This option is not
620 available for separator or tear-off entries.
621 -value value
623 Available only for radiobutton entries. Specifies the value to
624 store in the entry's associated variable when the entry is
625 selected. If an empty string is specified, then the -label
626 option for the entry as the value to store in the variable.
627 -variable value
629 Available only for checkbutton and radiobutton entries. Speci‐
630 fies the name of a global variable to set when the entry is
631 selected. For checkbutton entries the variable is also set when
632 the entry is deselected. For radiobutton entries, changing the
633 variable causes the currently-selected entry to deselect itself.
634 For checkbutton entries, the default value of this option is
636 taken from the -label option, and for radiobutton entries a sin‐
637 gle fixed value is used. It is recommended that you always set
638 the -variable option when creating either a checkbutton or a
639 radiobutton.
640
642 The default bindings support four different ways of using menus:
643 Pulldown Menus in Menubar
645 This is the most common case. You create a menu widget that will
646 become the menu bar. You then add cascade entries to this menu,
647 specifying the pull down menus you wish to use in your menu bar.
648 You then create all of the pulldowns. Once you have done this,
649 specify the menu using the -menu option of the toplevel's widget
650 command. See the toplevel manual entry for details.
651 Pulldown Menus in Menu Buttons
653 This is the compatible way to do menu bars. You create one
654 menubutton widget for each top-level menu, and typically you
655 arrange a series of menubuttons in a row in a menubar window.
656 You also create the top-level menus and any cascaded submenus,
657 and tie them together with -menu options in menubuttons and cas‐
658 cade menu entries. The top-level menu must be a child of the
659 menubutton, and each submenu must be a child of the menu that
660 refers to it. Once you have done this, the default bindings
661 will allow users to traverse and invoke the tree of menus via
662 its menubutton; see the menubutton manual entry for details.
663 Popup Menus
665 Popup menus typically post in response to a mouse button press
666 or keystroke. You create the popup menus and any cascaded sub‐
667 menus, then you call the tk_popup procedure at the appropriate
668 time to post the top-level menu.
669 Option Menus
671 An option menu consists of a menubutton with an associated menu
672 that allows you to select one of several values. The current
673 value is displayed in the menubutton and is also stored in a
674 global variable. Use the tk_optionMenu procedure to create
675 option menubuttons and their menus.
676 Torn-off Menus
678 You create a torn-off menu by invoking the tear-off entry at the
679 top of an existing menu. The default bindings will create a new
680 menu that is a copy of the original menu and leave it perma‐
681 nently posted as a top-level window. The torn-off menu behaves
682 just the same as the original menu.
683
685 Tk automatically creates class bindings for menus that give them the
686 following default behavior:
687 [1] When the mouse enters a menu, the entry underneath the mouse
689 cursor activates; as the mouse moves around the menu, the
690 active entry changes to track the mouse.
691 [2] When the mouse leaves a menu all of the entries in the menu
693 deactivate, except in the special case where the mouse moves
694 from a menu to a cascaded submenu.
695 [3] When a button is released over a menu, the active entry (if any)
697 is invoked. The menu also unposts unless it is a torn-off menu.
698 [4] The Space and Return keys invoke the active entry and unpost the
700 menu.
701 [5] If any of the entries in a menu have letters underlined with the
703 -underline option, then pressing one of the underlined letters
704 (or its upper-case or lower-case equivalent) invokes that entry
705 and unposts the menu.
706 [6] The Escape key aborts a menu selection in progress without
708 invoking any entry. It also unposts the menu unless it is a
709 torn-off menu.
710 [7] The Up and Down keys activate the next higher or lower entry in
712 the menu. When one end of the menu is reached, the active entry
713 wraps around to the other end.
714 [8] The Left key moves to the next menu to the left. If the current
716 menu is a cascaded submenu, then the submenu is unposted and the
717 current menu entry becomes the cascade entry in the parent. If
718 the current menu is a top-level menu posted from a menubutton,
719 then the current menubutton is unposted and the next menubutton
720 to the left is posted. Otherwise the key has no effect. The
721 left-right order of menubuttons is determined by their stacking
722 order: Tk assumes that the lowest menubutton (which by default
723 is the first one created) is on the left.
724 [9] The Right key moves to the next menu to the right. If the cur‐
726 rent entry is a cascade entry, then the submenu is posted and
727 the current menu entry becomes the first entry in the submenu.
728 Otherwise, if the current menu was posted from a menubutton,
729 then the current menubutton is unposted and the next menubutton
730 to the right is posted.
731 Disabled menu entries are non-responsive: they do not activate and
733 they ignore mouse button presses and releases.
734 Several of the bindings make use of the command tk_menuSetFocus. It
736 saves the current focus and sets the focus to its pathName argument,
737 which is a menu widget.
738 The behavior of menus can be changed by defining new bindings for indi‐
740 vidual widgets or by redefining the class bindings.
741
743 At present it is not possible to use the option database to specify
744 values for the options to individual entries.
745
747 bind(n), menubutton(n), ttk::menubutton(n), toplevel(n)
748
750 menu, widget
751Tk 4.1 menu(n)