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/MacOS, where menus
54 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 ig‐
68 nored under Aqua/MacOS, 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 op‐
95 tion) to make it into the menubar for that toplevel. Additional op‐
96 tions, described above, may be specified on the command line or in the
97 option database to configure aspects of the menu such as its colors and
98 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 ar‐
103 ranged in one or more columns. There exist several different types of
104 entries, each with different properties. Entries of different types
105 may be combined in a single menu. Menu entries are not the same as en‐
106 try widgets. In fact, menu entries are not even distinct widgets; the
107 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 re‐
124 leased over the entry then the entry is invoked. The effect of invoca‐
125 tion 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 op‐
144 tion.
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 be‐
149 havior 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 an‐
157 other value (determined by the -offvalue option) is stored in the
158 global variable. An indicator box is displayed to the left of the la‐
159 bel in a checkbutton entry. If the entry is selected then the indica‐
160 tor's center is displayed in the color given by the -selectcolor option
161 for the entry; otherwise the indicator's center is displayed in the
162 background color for the menu. If a -command option is specified for a
163 checkbutton entry, then its value is evaluated as a Tcl command each
164 time the entry is invoked; this happens after toggling the entry's se‐
165 lected state.
166 RADIOBUTTON ENTRIES
168 A radiobutton menu entry behaves much like a radiobutton widget. Ra‐
169 diobutton 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 it‐
174 self. Once an entry has become selected, any change to the entry's as‐
175 sociated variable will cause the entry to deselect itself. Grouping of
176 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 ra‐
183 diobutton entry, then its value is evaluated as a Tcl command each time
184 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, in‐
215 voking the tear-off entry causes a torn-off copy to be made of the menu
216 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 Ap‐
248 plication menu whenever the window containing the menubar is in front.
249 After all of the Tk-defined items, the menu will have a separator, fol‐
250 lowed by all standard Application menu items. Such a .apple menu must
251 be present in a menu when that menu is first configured as a toplevel's
252 menubar, otherwise a default application menu (hidden from Tk) will be
253 inserted into the menubar at that time and subsequent addition of a
254 .apple menu will no longer result in it becoming the Application menu.
255 When Tk sees a .menubar.window menu on the Macintosh, the menu's con‐
257 tents are inserted into the standard Window menu of the user's menubar
258 whenever the window's menubar is in front. The first items in the menu
259 are provided by Mac OS X, and the names of the current toplevels are
260 automatically appended after all the Tk-defined items and a separator.
261 The Window menu on the Mac also allows toggling the window into a
262 fullscreen state, and managing a tabbed window interface (multiple win‐
263 dows grouped into a single window) if supported by that version of the
264 operating system.
265 When Tk sees a .menubar.help menu on the Macintosh, the menu's contents
267 are appended to the standard Help menu of the user's menubar whenever
268 the window's menubar is in front. The first items in the menu are pro‐
269 vided by Mac OS X.
270 When Tk sees a System menu on Windows, its items are appended to the
272 system menu that the menubar is attached to. This menu is tied to the
273 application icon and can be invoked with the mouse or by typing
274 Alt+Spacebar. Due to limitations in the Windows API, any font changes,
275 colors, images, bitmaps, or tearoff images will not appear in the sys‐
276 tem menu.
277 When Tk sees a Help menu on X Windows and Motif menu compatibility is
279 enabled the menu is moved to be last in the menubar and is right justi‐
280 fied. Motif menu compatibility is enabled by setting the Tk option
281 *Menu.useMotifHelp to true or by calling tk::classic::restore menu.
282
284 When a menu is set as a menubar for a toplevel window, or when a menu
285 is torn off, a clone of the menu is made. This clone is a menu widget
286 in its own right, but it is a child of the original. Changes in the
287 configuration of the original are reflected in the clone. Additionally,
288 any cascades that are pointed to are also cloned so that menu traversal
289 will work right. Clones are destroyed when either the tearoff or
290 menubar goes away, or when the original menu is destroyed.
291
293 The menu command creates a new Tcl command whose name is pathName.
294 This command may be used to invoke various operations on the widget.
295 It has the following general form:
296 pathName option ?arg arg ...?
297 Option and the args determine the exact behavior of the command.
298 Many of the widget commands for a menu take as one argument an indica‐
300 tor of which entry of the menu to operate on. These indicators are
301 called indexes and may be specified in any of the following forms:
302 active Indicates the entry that is currently active. If no entry
304 is active then this form is equivalent to none. This form
305 may not be abbreviated.
306 end Indicates the bottommost entry in the menu. If there are
308 no entries in the menu then this form is equivalent to
309 none. This form may not be abbreviated.
310 last Same as end.
312 none Indicates “no entry at all”; this is used most commonly
314 with the activate option to deactivate all the entries in
315 the menu. In most cases the specification of none causes
316 nothing to happen in the widget command. This form may not
317 be abbreviated.
318 @number In this form, number is treated as a y-coordinate in the
320 menu's window; the entry closest to that y-coordinate is
321 used. For example, “@0” indicates the top-most entry in
322 the window.
323 number Specifies the entry numerically, where 0 corresponds to the
325 top-most entry of the menu, 1 to the entry below it, and so
326 on.
327 pattern If the index does not satisfy one of the above forms then
329 this form is used. Pattern is pattern-matched against the
330 label of each entry in the menu, in order from the top
331 down, until a matching entry is found. The rules of string
332 match are used.
333 If the index could match more than one of the above forms, then the
335 form earlier in the above list takes precedence.
336 The following widget commands are possible for menu widgets:
338 pathName activate index
340 Change the state of the entry indicated by index to active and
341 redisplay it using its active colors. Any previously-active en‐
342 try is deactivated. If index is specified as none, or if the
343 specified entry is disabled, then the menu ends up with no ac‐
344 tive entry. Returns an empty string.
345 pathName add type ?option value option value ...?
347 Add a new entry to the bottom of the menu. The new entry's type
348 is given by type and must be one of cascade, checkbutton, com‐
349 mand, radiobutton, or separator, or a unique abbreviation of one
350 of the above. If additional arguments are present, they specify
351 the options listed in the MENU ENTRY OPTIONS section below. The
352 add widget command returns an empty string.
353 pathName cget option
355 Returns the current value of the configuration option given by
356 option. Option may have any of the values accepted by the menu
357 command.
358 pathName clone newPathname ?cloneType?
360 Makes a clone of the current menu named newPathName. This clone
361 is a menu in its own right, but any changes to the clone are
362 propagated to the original menu and vice versa. cloneType can be
363 normal, menubar, or tearoff. Should not normally be called out‐
364 side of the Tk library. See the CLONES section for more informa‐
365 tion.
366 pathName configure ?option? ?value option value ...?
368 Query or modify the configuration options of the widget. If no
369 option is specified, returns a list describing all of the avail‐
370 able options for pathName (see Tk_ConfigureInfo for information
371 on the format of this list). If option is specified with no
372 value, then the command returns a list describing the one named
373 option (this list will be identical to the corresponding sublist
374 of the value returned if no option is specified). If one or
375 more option-value pairs are specified, then the command modifies
376 the given widget option(s) to have the given value(s); in this
377 case the command returns an empty string. Option may have any
378 of the values accepted by the menu command.
379 pathName delete index1 ?index2?
381 Delete all of the menu entries between index1 and index2 inclu‐
382 sive. If index2 is omitted then it defaults to index1. At‐
383 tempts to delete a tear-off menu entry are ignored (instead, you
384 should change the -tearoff option to remove the tear-off entry).
385 pathName entrycget index option
387 Returns the current value of a configuration option for the en‐
388 try given by index. Option may have any of the names described
389 in the MENU ENTRY OPTIONS section below.
390 pathName entryconfigure index ?options...?
392 This command is similar to the configure command, except that it
393 applies to the options for an individual entry, whereas config‐
394 ure applies to the options for the menu as a whole. Options may
395 have any of the values described in the MENU ENTRY OPTIONS sec‐
396 tion below. If options are specified, options are modified as
397 indicated in the command and the command returns an empty
398 string. If no options are specified, returns a list describing
399 the current options for entry index (see Tk_ConfigureInfo for
400 information on the format of this list).
401 pathName index index
403 Returns the numerical index corresponding to index, or none if
404 index was specified as none.
405 pathName insert index type ?option value option value ...?
407 Same as the add widget command except that it inserts the new
408 entry just before the entry given by index, instead of appending
409 to the end of the menu. The type, option, and value arguments
410 have the same interpretation as for the add widget command. It
411 is not possible to insert new menu entries before the tear-off
412 entry, if the menu has one.
413 pathName invoke index
415 Invoke the action of the menu entry. See the sections on the
416 individual entries above for details on what happens. If the
417 menu entry is disabled then nothing happens. If the entry has a
418 command associated with it then the result of that command is
419 returned as the result of the invoke widget command. Otherwise
420 the result is an empty string. Note: invoking a menu entry
421 does not automatically unpost the menu; the default bindings
422 normally take care of this before invoking the invoke widget
423 command.
424 pathName post x y ?index?
426 Arrange for the menu to be displayed on the screen at the root-
427 window coordinates given by x and y. If an index is specified
428 the menu will be located so that the entry with that index is
429 displayed at the point. These coordinates are adjusted if nec‐
430 essary to guarantee that the entire menu is visible on the
431 screen. This command normally returns an empty string. If the
432 -postcommand option has been specified, then its value is exe‐
433 cuted as a Tcl script before posting the menu and the result of
434 that script is returned as the result of the post widget com‐
435 mand. If an error returns while executing the command, then the
436 error is returned without posting the menu.
437 pathName postcascade index
439 Posts the submenu associated with the cascade entry given by in‐
440 dex, and unposts any previously posted submenu. If index does
441 not correspond to a cascade entry, or if pathName is not posted,
442 the command has no effect except to unpost any currently posted
443 submenu.
444 pathName type index
446 Returns the type of the menu entry given by index. This is the
447 type argument passed to the add or insert widget command when
448 the entry was created, such as command or separator, or tearoff
449 for a tear-off entry.
450 pathName unpost
452 Unmap the window so that it is no longer displayed. If a lower-
453 level cascaded menu is posted, unpost that menu. Returns an
454 empty string. This subcommand does not work on Windows and the
455 Macintosh, as those platforms have their own way of unposting
456 menus.
457 pathName xposition index
459 Returns a decimal string giving the x-coordinate within the menu
460 window of the leftmost pixel in the entry specified by index.
461 pathName yposition index
463 Returns a decimal string giving the y-coordinate within the menu
464 window of the topmost pixel in the entry specified by index.
465
467 The following options are allowed on menu entries. Most options are not
468 supported by all entry types.
469 -activebackground value
471 Specifies a background color to use for displaying this entry
472 when it is active. This option is ignored on Aqua/MacOS. If it
473 is specified as an empty string (the default), then the -active‐
474 background option for the overall menu is used. If the
475 tk_strictMotif variable has been set to request strict Motif
476 compliance, then this option is ignored and the -background op‐
477 tion is used in its place. This option is not available for
478 separator or tear-off entries.
479 -activeforeground value
481 Specifies a foreground color to use for displaying this entry
482 when it is active. This option is ignored on Aqua/macOS. If
483 this option is specified as an empty string (the default), then
484 the -activeforeground option for the overall menu is used. This
485 option is not available for separator or tear-off entries.
486 -accelerator value
488 Specifies a string to display at the right side of the menu en‐
489 try. Normally describes an accelerator keystroke sequence that
490 may be used to invoke the same function as the menu entry. This
491 is a display option, it does not actually set the corresponding
492 binding (which can be achieved using the bind command). This op‐
493 tion is not available for separator or tear-off entries.
494 -background value
496 Specifies a background color to use for displaying this entry
497 when it is in the normal state (neither active nor disabled).
498 This option is ignored on Aqua/macOS. If it is specified as an
499 empty string (the default), then the -background option for the
500 overall menu is used. This option is not available for separa‐
501 tor 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 op‐
506 tion overrides the -label option (as controlled by the -compound
507 option) but may be reset to an empty string to enable a textual
508 label to be displayed. If a -image option has been specified,
509 it overrides -bitmap. This option is not available for separa‐
510 tor 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/macOS,
516 where menus are always a single column.
517 -command value
519 Specifies a Tcl command to execute when the menu entry is in‐
520 voked. 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 This option is ignored on Aqua/macOS. If it is specified as an
541 empty string (the default), then the -foreground option for the
542 overall menu is used. This option is not available for separa‐
543 tor or tear-off entries.
544 -hidemargin value
546 Specifies whether the standard margins should be drawn for this
547 menu entry. This is useful when creating palette with images in
548 them, i.e., color palettes, pattern palettes, etc. 1 indicates
549 that the margin for the entry is hidden; 0 means that the margin
550 is used.
551 -image value
553 Specifies an image to display in the menu instead of a text
554 string or bitmap. The image must have been created by some pre‐
555 vious invocation of image create. This option overrides the
556 -label and -bitmap options (as controlled by the -compound op‐
557 tion) but may be reset to an empty string to enable a textual or
558 bitmap label to be displayed. This option is not available for
559 separator or tear-off entries.
560 -indicatoron value
562 Available only for checkbutton and radiobutton entries. Value
563 is a boolean that determines whether or not the indicator should
564 be displayed.
565 -label value
567 Specifies a string to display as an identifying label in the
568 menu entry. Not available for separator or tear-off entries.
569 -menu value
571 Available only for cascade entries. Specifies the path name of
572 the submenu associated with this entry. The submenu must be a
573 child of the menu.
574 -offvalue value
576 Available only for checkbutton entries. Specifies the value to
577 store in the entry's associated variable when the entry is dese‐
578 lected.
579 -onvalue value
581 Available only for checkbutton entries. Specifies the value to
582 store in the entry's associated variable when the entry is se‐
583 lected.
584 -selectcolor value
586 Available only for checkbutton and radiobutton entries. Speci‐
587 fies the color to display in the indicator when the entry is se‐
588 lected. If the value is an empty string (the default) then the
589 -selectcolor option for the menu determines the indicator 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 im‐
596 age create. This option is ignored unless the -image option has
597 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 se‐
625 lected. If an empty string is specified, then the -label option
626 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 se‐
631 lected. 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 ra‐
639 diobutton.
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 ar‐
655 range a series of menubuttons in a row in a menubar window. You
656 also create the top-level menus and any cascaded submenus, and
657 tie them together with -menu options in menubuttons and cascade
658 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 op‐
675 tion 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 ac‐
690 tive entry changes to track the mouse.
691 [2] When the mouse leaves a menu all of the entries in the menu de‐
693 activate, except in the special case where the mouse moves from
694 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 in‐
708 voking any entry. It also unposts the menu unless it is a torn-
709 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)