Commit | Line | Data |
---|---|---|
86530b38 AT |
1 | # Copyright (c) 1990-1994 The Regents of the University of California. |
2 | # Copyright (c) 1994-1997 Sun Microsystems, Inc. | |
3 | # See the file "license.terms" for information on usage and redistribution | |
4 | # of this file, and for a DISCLAIMER OF ALL WARRANTIES. | |
5 | # | |
6 | # | |
7 | ||
8 | =head1 NAME | |
9 | ||
10 | Tk::Menu - Create and manipulate Menu widgets | |
11 | ||
12 | =for category Tk Widget Classes | |
13 | ||
14 | =head1 SYNOPSIS | |
15 | ||
16 | S< >I<$menu> = I<$parent>-E<gt>B<Menu>(?I<options>?); | |
17 | ||
18 | =head1 STANDARD OPTIONS | |
19 | ||
20 | B<-activebackground> B<-background> B<-disabledforeground> B<-relief> | |
21 | B<-activeborderwidth> B<-borderwidth> B<-font> B<-takefocus> | |
22 | B<-activeforeground> B<-cursor> B<-foreground> | |
23 | ||
24 | See L<Tk::options> for details of the standard options. | |
25 | ||
26 | =head1 WIDGET-SPECIFIC OPTIONS | |
27 | ||
28 | =over 4 | |
29 | ||
30 | =item Name: B<postCommand> | |
31 | ||
32 | =item Class: B<Command> | |
33 | ||
34 | =item Switch: B<-postcommand> | |
35 | ||
36 | If this option is specified then it provides a L<callback|Tk::callbacks> to execute | |
37 | each time the menu is posted. The callback is invoked by the B<post> | |
38 | method before posting the menu. Note that in 8.0 on Macintosh | |
39 | and Windows, all commands in a menu systems are executed before any | |
40 | are posted. This is due to the limitations in the individual platforms' | |
41 | menu managers. | |
42 | ||
43 | =item Name: B<selectColor> | |
44 | ||
45 | =item Class: B<Background> | |
46 | ||
47 | =item Switch: B<-selectcolor> | |
48 | ||
49 | For menu entries that are check buttons or radio buttons, this option | |
50 | specifies the color to display in the indicator when the check button | |
51 | or radio button is selected. | |
52 | ||
53 | =item Name: B<tearOff> | |
54 | ||
55 | =item Class: B<TearOff> | |
56 | ||
57 | =item Switch: B<-tearoff> | |
58 | ||
59 | This option must have a proper boolean value, which specifies | |
60 | whether or not the menu should include a tear-off entry at the | |
61 | top. If so, it will exist as entry 0 of the menu and the other | |
62 | entries will number starting at 1. The default | |
63 | menu bindings arrange for the menu to be torn off when the tear-off | |
64 | entry is invoked. | |
65 | ||
66 | =item Name: B<tearOffCommand> | |
67 | ||
68 | =item Class: B<TearOffCommand> | |
69 | ||
70 | =item Switch: B<-tearoffcommand> | |
71 | ||
72 | If this option has a non-empty value, then it specifies a L<perl/Tk callback|Tk::callbacks> | |
73 | to invoke whenever the menu is torn off. The actual command will | |
74 | consist of the value of this option, followed by a space, followed | |
75 | by the name of the menu window, followed by a space, followed by | |
76 | the name of the name of the torn off menu window. For example, if | |
77 | the option's is ``B<a b>'' and menu B<.x.y> is torn off to | |
78 | create a new menu B<.x.tearoff1>, then the command | |
79 | ``B<a b .x.y .x.tearoff1>'' will be invoked. | |
80 | ||
81 | =item Name: B<title> | |
82 | ||
83 | =item Class: B<Title> | |
84 | ||
85 | =item Switch: B<-title> | |
86 | ||
87 | The string will be used to title the window created when this menu is | |
88 | torn off. If the title is NULL, then the window will have the title | |
89 | of the menubutton or the text of the cascade item from which this menu | |
90 | was invoked. | |
91 | ||
92 | =item Name: B<type> | |
93 | ||
94 | =item Class: B<Type> | |
95 | ||
96 | =item Switch: B<-type> | |
97 | ||
98 | This option can be one of B<menubar>, B<tearoff>, or | |
99 | B<normal>, and is set when the menu is created. While the string | |
100 | returned by the configuration database will change if this option is | |
101 | changed, this does not affect the menu widget's behavior. This is used | |
102 | by the cloning mechanism and is not normally set outside of the Tk | |
103 | library. | |
104 | ||
105 | =back | |
106 | ||
107 | =head1 DESCRIPTION | |
108 | ||
109 | The B<Menu> method creates a new top-level window (given | |
110 | by the $widget argument) and makes it into a menu widget. | |
111 | Additional | |
112 | options, described above, may be specified on the command line | |
113 | or in the option database | |
114 | to configure aspects of the menu such as its colors and font. | |
115 | The B<menu> command returns its | |
116 | $widget argument. At the time this command is invoked, | |
117 | there must not exist a window named $widget, but | |
118 | $widget's parent must exist. | |
119 | ||
120 | A menu is a widget that displays a collection of one-line entries arranged | |
121 | in one or more columns. There exist several different types of entries, | |
122 | each with different properties. Entries of different types may be | |
123 | combined in a single menu. Menu entries are not the same as | |
124 | entry widgets. In fact, menu entries are not even distinct widgets; | |
125 | the entire menu is one widget. | |
126 | ||
127 | Menu entries are displayed with up to three separate fields. | |
128 | The main field is a label in the form of a text string, | |
129 | a bitmap, or an image, controlled by the B<-label>, | |
130 | B<-bitmap>, and B<-image> options for the entry. | |
131 | If the B<-accelerator> option is specified for an entry then a second | |
132 | textual field is displayed to the right of the label. The accelerator | |
133 | typically describes a keystroke sequence that may be typed in the | |
134 | application to cause the same result as invoking the menu entry. | |
135 | The third field is an I<indicator>. The indicator is present only for | |
136 | checkbutton or radiobutton entries. It indicates whether the entry | |
137 | is selected or not, and is displayed to the left of the entry's | |
138 | string. | |
139 | ||
140 | In normal use, an entry becomes active (displays itself differently) | |
141 | whenever the mouse pointer is over the entry. If a mouse | |
142 | button is released over the entry then the entry is I<invoked>. | |
143 | The effect of invocation is different for each type of entry; | |
144 | these effects are described below in the sections on individual | |
145 | entries. | |
146 | ||
147 | Entries may be I<disabled>, which causes their labels | |
148 | and accelerators to be displayed | |
149 | with dimmer colors. | |
150 | The default menu bindings will not allow | |
151 | a disabled entry to be activated or invoked. | |
152 | Disabled entries may be re-enabled, at which point it becomes | |
153 | possible to activate and invoke them again. | |
154 | ||
155 | Whenever a menu's active entry is changed, a E<lt>E<lt>MenuSelectE<gt>E<gt> virtual | |
156 | event is sent to the menu. The active item can then be queried from | |
157 | the menu, and an action can be taken, such as setting | |
158 | context-sensitive help text for the entry. | |
159 | ||
160 | =head2 COMMAND ENTRIES | |
161 | ||
162 | The most common kind of menu entry is a command entry, which | |
163 | behaves much like a button widget. When a command entry is | |
164 | invoked, a callback is executed. The callback | |
165 | is specified with the B<-command> option. | |
166 | ||
167 | =head2 SEPARATOR ENTRIES | |
168 | ||
169 | A separator is an entry that is displayed as a horizontal dividing | |
170 | line. A separator may not be activated or invoked, and it has | |
171 | no behavior other than its display appearance. | |
172 | ||
173 | =head2 CHECKBUTTON ENTRIES | |
174 | ||
175 | A checkbutton menu entry behaves much like a checkbutton widget. | |
176 | When it is invoked it toggles back and forth between the selected | |
177 | and deselected states. When the entry is selected, a particular | |
178 | value is stored in a particular global variable (as determined by | |
179 | the B<-onvalue> and B<-variable> options for the entry); when | |
180 | the entry is deselected another value (determined by the | |
181 | B<-offvalue> option) is stored in the global variable. | |
182 | An indicator box is displayed to the left of the label in a checkbutton | |
183 | entry. If the entry is selected then the indicator's center is displayed | |
184 | in the color given by the B<-selectcolor> option for the entry; | |
185 | otherwise the indicator's center is displayed in the background color for | |
186 | the menu. If a B<-command> option is specified for a checkbutton | |
187 | entry, then its value is evaluated each time the entry | |
188 | is invoked; this happens after toggling the entry's | |
189 | selected state. | |
190 | ||
191 | =head2 RADIOBUTTON ENTRIES | |
192 | ||
193 | A radiobutton menu entry behaves much like a radiobutton widget. | |
194 | Radiobutton entries are organized in groups of which only one | |
195 | entry may be selected at a time. Whenever a particular entry | |
196 | becomes selected it stores a particular value into a particular | |
197 | global variable (as determined by the B<-value> and | |
198 | B<-variable> options for the entry). This action | |
199 | causes any previously-selected entry in the same group | |
200 | to deselect itself. | |
201 | Once an entry has become selected, any change to the entry's | |
202 | associated variable will cause the entry to deselect itself. | |
203 | Grouping of radiobutton entries is determined by their | |
204 | associated variables: if two entries have the same associated | |
205 | variable then they are in the same group. | |
206 | An indicator diamond is displayed to the left of the label in each | |
207 | radiobutton entry. If the entry is selected then the indicator's | |
208 | center is displayed in the color given by the B<-selectcolor> option | |
209 | for the entry; | |
210 | otherwise the indicator's center is displayed in the background color for | |
211 | the menu. If a B<-command> option is specified for a radiobutton | |
212 | entry, then its value is evaluated each time the entry | |
213 | is invoked; this happens after selecting the entry. | |
214 | ||
215 | =head2 CASCADE ENTRIES | |
216 | ||
217 | A cascade entry is one with an associated menu (determined | |
218 | by the B<-menu> option). Cascade entries allow the construction | |
219 | of cascading menus. | |
220 | The B<postcascade> method can be used to post and unpost | |
221 | the associated menu just next to of the cascade entry. | |
222 | The associated menu must be a child of the menu containing | |
223 | the cascade entry (this is needed in order for menu traversal to | |
224 | work correctly). | |
225 | ||
226 | A cascade entry posts its associated menu by invoking | |
227 | ||
228 | =over 4 | |
229 | ||
230 | I<$menu>-E<gt>B<post>(I<x,y>) | |
231 | ||
232 | =back | |
233 | ||
234 | where I<menu> is the path name of the associated menu, and I<x> | |
235 | and I<y> are the root-window coordinates of the upper-right | |
236 | corner of the cascade entry. | |
237 | On Unix, the lower-level menu is unposted by executing | |
238 | ||
239 | =over 4 | |
240 | ||
241 | I<$menu>-E<gt>B<unpost> | |
242 | ||
243 | =back | |
244 | ||
245 | where I<menu> is the name of the associated menu. | |
246 | On other platforms, the platform's native code takes care of unposting the | |
247 | menu. | |
248 | ||
249 | If a B<-command> option is specified for a cascade entry then it is | |
250 | evaluated whenever the entry is invoked. This is not supported on Windows. | |
251 | ||
252 | =head2 TEAR-OFF ENTRIES | |
253 | ||
254 | A tear-off entry appears at the top of the menu if enabled with the | |
255 | B<tearOff> option. It is not like other menu entries in that | |
256 | it cannot be created with the B<add> method and | |
257 | cannot be deleted with the B<delete> method. | |
258 | When a tear-off entry is created it appears as a dashed line at | |
259 | the top of the menu. Under the default bindings, invoking the | |
260 | tear-off entry causes a torn-off copy to be made of the menu and | |
261 | all of its submenus. | |
262 | ||
263 | =head2 MENUBARS | |
264 | ||
265 | Any menu can be set as a menubar for a toplevel window (see the | |
266 | L<Toplevel|Tk::Toplevel> constructor for syntax). On the Macintosh, whenever the | |
267 | toplevel is in front, this menu's cascade items will appear in the | |
268 | menubar across the top of the main monitor. On Windows and Unix, this | |
269 | menu's items will be displayed in a menubar accross the top of the | |
270 | window. These menus will behave according to the interface guidelines | |
271 | of their platforms. For every menu set as a menubar, a clone menu is | |
272 | made. See L<"CLONES"> for more information. | |
273 | ||
274 | =head2 SPECIAL MENUS IN MENUBARS | |
275 | ||
276 | Certain menus in a menubar will be treated specially. On the Macintosh, | |
277 | access to the special Apple and Help menus is provided. On Windows, | |
278 | access to the Windows System menu in each window is provided. On X Windows, | |
279 | a special right-justified help menu is provided. In all cases, these | |
280 | menus must be created with the command name of the menubar menu concatenated | |
281 | with the special name. So for a menubar named .menubar, on the Macintosh, | |
282 | the special menus would be .menubar.apple and .menubar.help; on Windows, | |
283 | the special menu would be .menubar.system; on X Windows, the help | |
284 | menu would be .menubar.help. | |
285 | ||
286 | When Tk sees an Apple menu on the Macintosh, that menu's contents make | |
287 | up the first items of the Apple menu on the screen whenever the window | |
288 | containing the menubar is in front. The menu is the | |
289 | first one that the user sees and has a title which is an Apple logo. | |
290 | After all of the Tk-defined items, the menu will have a separator, | |
291 | followed by all of the items in the user's Apple Menu Items folder. | |
292 | Since the System uses a different menu definition procedure for | |
293 | the Apple menu than Tk uses for its menus, and the system APIs do | |
294 | not fully support everything Tk tries to do, the menu item will only | |
295 | have its text displayed. No font attributes, images, bitmaps, or colors | |
296 | will be displayed. In addition, a menu with a tearoff item will have | |
297 | the tearoff item displayed as "(TearOff)". | |
298 | ||
299 | When Tk see a Help menu on the Macintosh, the menu's contents are | |
300 | appended to the standard help menu on the right of the user's menubar | |
301 | whenever the user's menubar is in front. The first items in the menu | |
302 | are provided by Apple. Similar to the Apple Menu, cusomization in this | |
303 | menu is limited to what the system provides. | |
304 | ||
305 | When Tk sees a System menu on Windows, its items are appended to the | |
306 | system menu that the menubar is attached to. This menu has an icon | |
307 | representing a spacebar, and can be invoked with the mouse or by typing | |
308 | Alt+Spacebar. Due to limitations in the Windows API, any font changes, | |
309 | colors, images, bitmaps, or tearoff images will not appear in the | |
310 | system menu. | |
311 | ||
312 | When Tk see a Help menu on X Windows, the menu is moved to be last in | |
313 | the menubar and is right justified. | |
314 | ||
315 | =head2 SEPARATORS IN MENUBARS | |
316 | ||
317 | Separator entries are not displayed in menubars. | |
318 | The I<last> separator entry causes remaining entries to be | |
319 | right justified. | |
320 | ||
321 | =head2 CLONES | |
322 | ||
323 | When a menu is set as a menubar for a toplevel window, or when a menu | |
324 | is torn off, a clone of the menu is made. This clone is a menu widget | |
325 | in its own right, but it is a child of the original. Changes in the | |
326 | configuration of the original are reflected in the | |
327 | clone. Additionally, any cascades that are pointed to are also cloned | |
328 | so that menu traversal will work right. Clones are destroyed when | |
329 | either the tearoff or menubar goes away, or when the original menu is | |
330 | destroyed. | |
331 | ||
332 | =head2 WIDGET METHODS | |
333 | ||
334 | The B<Menu> method creates a widget object. | |
335 | This object supports the B<configure> and B<cget> methods | |
336 | described in L<Tk::options> which can be used to enquire and | |
337 | modify the options described above. | |
338 | The widget also inherits all the methods provided by the generic | |
339 | L<Tk::Widget|Tk::Widget> class, and the L<Tk::Wm|Tk::Wm> class. | |
340 | ||
341 | Many of the methods for a menu take as one argument an | |
342 | indicator of which entry of the menu to operate on. These | |
343 | indicators are called I<index>es and may be specified in | |
344 | any of the following forms: | |
345 | ||
346 | =over 4 | |
347 | ||
348 | =item I<number> | |
349 | ||
350 | Specifies the entry numerically, where 0 corresponds | |
351 | to the top-most entry of the menu, 1 to the entry below it, and | |
352 | so on. | |
353 | ||
354 | =item B<active> | |
355 | ||
356 | Indicates the entry that is currently active. If no entry is | |
357 | active then this form is equivalent to B<none>. This form may | |
358 | not be abbreviated. | |
359 | ||
360 | =item B<end> | |
361 | ||
362 | Indicates the bottommost entry in the menu. If there are no | |
363 | entries in the menu then this form is equivalent to B<none>. | |
364 | This form may not be abbreviated. | |
365 | ||
366 | =item B<last> | |
367 | ||
368 | Same as B<end>. | |
369 | ||
370 | =item B<none> | |
371 | ||
372 | Indicates ``no entry at all''; this is used most commonly with | |
373 | the B<activate> option to deactivate all the entries in the | |
374 | menu. In most cases the specification of B<none> causes | |
375 | nothing to happen in the method. | |
376 | This form may not be abbreviated. | |
377 | ||
378 | =item B<@>I<number> | |
379 | ||
380 | In this form, I<number> is treated as a y-coordinate in the | |
381 | menu's window; the entry closest to that y-coordinate is used. | |
382 | For example, ``B<@0>'' indicates the top-most entry in the | |
383 | window. | |
384 | ||
385 | =item I<pattern> | |
386 | ||
387 | If the index doesn't satisfy one of the above forms then this | |
388 | form is used. I<Pattern> is pattern-matched against the label of | |
389 | each entry in the menu, in order from the top down, until a | |
390 | matching entry is found. | |
391 | (In perl/Tk the matching is under review, but exact match | |
392 | should work.) | |
393 | ||
394 | =back | |
395 | ||
396 | The following methods are possible for menu widgets: | |
397 | ||
398 | =over 4 | |
399 | ||
400 | =item I<$menu>-E<gt>B<activate>(I<index>) | |
401 | ||
402 | Change the state of the entry indicated by I<index> to B<active> | |
403 | and redisplay it using its active colors. | |
404 | Any previously-active entry is deactivated. If I<index> | |
405 | is specified as B<none>, or if the specified entry is | |
406 | disabled, then the menu ends up with no active entry. | |
407 | Returns an empty string. | |
408 | ||
409 | =item I<$menu>-E<gt>B<add>(I<type, >?I<option, value, option, value, ...>?) | |
410 | ||
411 | Add a new entry to the bottom of the menu. The new entry's type | |
412 | is given by I<type> and must be one of B<cascade>, | |
413 | B<checkbutton>, B<command>, B<radiobutton>, or B<separator>, | |
414 | or a unique abbreviation of one of the above. If additional arguments | |
415 | are present, they specify any of the following options: | |
416 | ||
417 | =over 8 | |
418 | ||
419 | =item B<-activebackground> =E<gt> I<value> | |
420 | ||
421 | Specifies a background color to use for displaying this entry when it | |
422 | is active. | |
423 | If this option is specified as an empty string (the default), then the | |
424 | B<activeBackground> option for the overall menu is used. | |
425 | If the B<$Tk::strictMotif> variable has been set to request strict | |
426 | Motif compliance, then this option is ignored and the B<-background> | |
427 | option is used in its place. | |
428 | This option is not available for separator or tear-off entries. | |
429 | ||
430 | =item B<-activeforeground> =E<gt> I<value> | |
431 | ||
432 | Specifies a foreground color to use for displaying this entry when it | |
433 | is active. | |
434 | If this option is specified as an empty string (the default), then the | |
435 | B<activeForeground> option for the overall menu is used. | |
436 | This option is not available for separator or tear-off entries. | |
437 | ||
438 | =item B<-accelerator> =E<gt> I<value> | |
439 | ||
440 | Specifies a string to display at the right side of the menu entry. | |
441 | Normally describes an accelerator keystroke sequence that may be | |
442 | typed to invoke the same function as the menu entry. This option | |
443 | is not available for separator or tear-off entries. | |
444 | ||
445 | =item B<-background> =E<gt> I<value> | |
446 | ||
447 | Specifies a background color to use for displaying this entry when it | |
448 | is in the normal state (neither active nor disabled). | |
449 | If this option is specified as an empty string (the default), then the | |
450 | B<background> option for the overall menu is used. | |
451 | This option is not available for separator or tear-off entries. | |
452 | ||
453 | =item B<-bitmap> =E<gt> I<value> | |
454 | ||
455 | Specifies a bitmap to display in the menu instead of a textual | |
456 | label, in any of the forms accepted by B<Tk_GetBitmap>. | |
457 | This option overrides the B<-label> option but may be reset | |
458 | to an empty string to enable a textual label to be displayed. | |
459 | If a B<-image> option has been specified, it overrides | |
460 | B<-bitmap>. | |
461 | This option is not available for separator or tear-off entries. | |
462 | ||
463 | =item B<-columnbreak> =E<gt> I<value> | |
464 | ||
465 | When this option is zero, the appears below the previous entry. When | |
466 | this option is one, the menu appears at the top of a new column in the | |
467 | menu. | |
468 | ||
469 | =item B<-command> =E<gt> I<value> | |
470 | ||
471 | For command, checkbutton, and radiobutton entries, specifies a | |
472 | callback to execute when the menu entry is invoked. | |
473 | For cascade entries, specifies a callback to execute | |
474 | when the entry is activated (i.e. just before its submenu is | |
475 | posted). | |
476 | Not available for separator or tear-off entries. | |
477 | ||
478 | =item B<-font> =E<gt> I<value> | |
479 | ||
480 | Specifies the font to use when drawing the label or accelerator | |
481 | string in this entry. | |
482 | If this option is specified as an empty string (the default) then | |
483 | the B<font> option for the overall menu is used. | |
484 | This option is not available for separator or tear-off entries. | |
485 | ||
486 | =item B<-foreground> =E<gt> I<value> | |
487 | ||
488 | Specifies a foreground color to use for displaying this entry when it | |
489 | is in the normal state (neither active nor disabled). | |
490 | If this option is specified as an empty string (the default), then the | |
491 | B<foreground> option for the overall menu is used. | |
492 | This option is not available for separator or tear-off entries. | |
493 | ||
494 | =item B<-hidemargin> =E<gt> I<value> | |
495 | ||
496 | Specifies whether the standard margins should be drawn for this menu | |
497 | entry. This is useful when creating palette with images in them, i.e., | |
498 | color palettes, pattern palettes, etc. 1 indicates that the margin for | |
499 | the entry is hidden; 0 means that the margin is used. | |
500 | ||
501 | =item B<-image> =E<gt> I<value> | |
502 | ||
503 | Specifies an image to display in the menu instead of a text string | |
504 | or bitmap | |
505 | The image must have been created by some previous invocation of | |
506 | B<image create>. | |
507 | This option overrides the B<-label> and B<-bitmap> options | |
508 | but may be reset to an empty string to enable a textual or | |
509 | bitmap label to be displayed. | |
510 | This option is not available for separator or tear-off entries. | |
511 | ||
512 | =item B<-indicatoron> =E<gt> I<value> | |
513 | ||
514 | Available only for checkbutton and radiobutton entries. | |
515 | I<Value> is a boolean that determines whether or not the | |
516 | indicator should be displayed. | |
517 | ||
518 | =item B<-label> =E<gt> I<value> | |
519 | ||
520 | Specifies a string to display as an identifying label in the menu | |
521 | entry. Not available for separator or tear-off entries. | |
522 | ||
523 | =item B<-menu> =E<gt> I<value> | |
524 | ||
525 | Available only for cascade entries. Specifies the path name of | |
526 | the submenu associated with this entry. | |
527 | The submenu must be a child of the menu. | |
528 | ||
529 | =item B<-offvalue> =E<gt> I<value> | |
530 | ||
531 | Available only for checkbutton entries. Specifies the value to | |
532 | store in the entry's associated variable when the entry is | |
533 | deselected. | |
534 | ||
535 | =item B<-onvalue> =E<gt> I<value> | |
536 | ||
537 | Available only for checkbutton entries. Specifies the value to | |
538 | store in the entry's associated variable when the entry is selected. | |
539 | ||
540 | =item B<-selectcolor> =E<gt> I<value> | |
541 | ||
542 | Available only for checkbutton and radiobutton entries. | |
543 | Specifies the color to display in the indicator when the entry is | |
544 | selected. | |
545 | If the value is an empty string (the default) then the B<selectColor> | |
546 | option for the menu determines the indicator color. | |
547 | ||
548 | =item B<-selectimage> =E<gt> I<value> | |
549 | ||
550 | Available only for checkbutton and radiobutton entries. | |
551 | Specifies an image to display in the entry (in place of | |
552 | the B<-image> option) when it is selected. | |
553 | I<Value> is the name of an image, which must have been created | |
554 | by some previous invocation of B<image create>. | |
555 | This option is ignored unless the B<-image> option has | |
556 | been specified. | |
557 | ||
558 | =item B<-state> =E<gt> I<value> | |
559 | ||
560 | Specifies one of three states for the entry: B<normal>, B<active>, | |
561 | or B<disabled>. In normal state the entry is displayed using the | |
562 | B<foreground> option for the menu and the B<background> | |
563 | option from the entry or the menu. | |
564 | The active state is typically used when the pointer is over the entry. | |
565 | In active state the entry is displayed using the B<activeForeground> | |
566 | option for the menu along with the B<activebackground> option from | |
567 | the entry. Disabled state means that the entry | |
568 | should be insensitive: the default bindings will refuse to activate | |
569 | or invoke the entry. | |
570 | In this state the entry is displayed according to the | |
571 | B<disabledForeground> option for the menu and the | |
572 | B<background> option from the entry. | |
573 | This option is not available for separator entries. | |
574 | ||
575 | =item B<-underline> =E<gt> I<value> | |
576 | ||
577 | Specifies the integer index of a character to underline in the entry. | |
578 | This option is also queried by the default bindings and used to | |
579 | implement keyboard traversal. | |
580 | 0 corresponds to the first character of the text displayed in the entry, | |
581 | 1 to the next character, and so on. | |
582 | If a bitmap or image is displayed in the entry then this option is ignored. | |
583 | This option is not available for separator or tear-off entries. | |
584 | ||
585 | =item B<-value> =E<gt> I<value> | |
586 | ||
587 | Available only for radiobutton entries. Specifies the value to | |
588 | store in the entry's associated variable when the entry is selected. | |
589 | If an empty string is specified, then the B<-label> option | |
590 | for the entry as the value to store in the variable. | |
591 | ||
592 | =item B<-variable> =E<gt> I<value> | |
593 | ||
594 | Available only for checkbutton and radiobutton entries. Specifies | |
595 | the name of a global value to set when the entry is selected. | |
596 | For checkbutton entries the variable is also set when the entry | |
597 | is deselected. For radiobutton entries, changing the variable | |
598 | causes the currently-selected entry to deselect itself. | |
599 | ||
600 | =back | |
601 | ||
602 | The B<add> method returns an empty string. | |
603 | ||
604 | =item I<$menu>-E<gt>B<clone>(I<$parent> ?, I<cloneType?>) | |
605 | ||
606 | Makes a clone of the current menu as a child of I<$parent>. This clone | |
607 | is a menu in its own right, but any changes to the clone are | |
608 | propogated to the original menu and vice versa. I<cloneType> can be | |
609 | B<normal>, B<menubar>, or B<tearoff>. Should not normally be | |
610 | called outside of the Tk library. See L<"CLONES"> for | |
611 | more information. | |
612 | ||
613 | =item I<$menu>-E<gt>B<delete>(I<index1>?, I<index2>?) | |
614 | ||
615 | Delete all of the menu entries between I<index1> and | |
616 | I<index2> inclusive. | |
617 | If I<index2> is omitted then it defaults to I<index1>. | |
618 | Attempts to delete a tear-off menu entry are ignored (instead, you | |
619 | should change the B<tearOff> option to remove the tear-off entry). | |
620 | ||
621 | =item I<$menu>-E<gt>B<entrycget>(I<index, option>) | |
622 | ||
623 | Returns the current value of a configuration option for | |
624 | the entry given by I<index>. | |
625 | I<Option> may have any of the values accepted by the B<add> | |
626 | method. | |
627 | ||
628 | =item I<$menu>-E<gt>B<entryconfigure>(I<index> ?,I<options>?) | |
629 | ||
630 | This method is similar to the B<configure> method, except that | |
631 | it applies to the options for an individual entry, whereas B<configure> | |
632 | applies to the options for the menu as a whole. | |
633 | I<Options> may have any of the values accepted by the B<add> | |
634 | method. If I<options> are specified, options are modified | |
635 | as indicated | |
636 | in the method call and the method returns an empty string. | |
637 | If no I<options> are specified, returns a list describing | |
638 | the current options for entry I<index> (see L<Tk::options> for | |
639 | information on the format of this list). | |
640 | ||
641 | =item I<$menu>-E<gt>B<index>(I<index>) | |
642 | ||
643 | Returns the numerical index corresponding to I<index>, or | |
644 | B<none> if I<index> was specified as B<none>. | |
645 | ||
646 | =item I<$menu>-E<gt>B<insert>(I<index, type>?, I<-option>=E<gt>I<value>, ...?) | |
647 | ||
648 | Same as the B<add> method except that it inserts the new | |
649 | entry just before the entry given by I<index>, instead of appending | |
650 | to the end of the menu. The I<type>, I<-option>, and I<value> | |
651 | arguments have the same interpretation as for the B<add> widget | |
652 | method. It is not possible to insert new menu entries before the | |
653 | tear-off entry, if the menu has one. | |
654 | ||
655 | =item I<$menu>-E<gt>B<invoke>(I<index>) | |
656 | ||
657 | Invoke the action of the menu entry. See the sections on the | |
658 | individual entries above for details on what happens. If the | |
659 | menu entry is disabled then nothing happens. If the | |
660 | entry has a callback associated with it then the result of that | |
661 | callback is returned as the result of the B<invoke> widget | |
662 | method. Otherwise the result is an empty string. Note: invoking | |
663 | a menu entry does not automatically unpost the menu; the default | |
664 | bindings normally take care of this before invoking the B<invoke> | |
665 | method. | |
666 | ||
667 | =item I<$menu>-E<gt>B<post>(I<x, y>) | |
668 | ||
669 | Arrange for the menu to be displayed on the screen at the root-window | |
670 | coordinates given by I<x> and I<y>. These coordinates are | |
671 | adjusted if necessary to guarantee that the entire menu is visible on | |
672 | the screen. This method normally returns an empty string. | |
673 | If the B<postCommand> option has been specified, then its value is | |
674 | executed before posting the menu and the result of | |
675 | that callback is returned as the result of the B<post> widget | |
676 | method. | |
677 | If an error returns while executing the method, then the error is | |
678 | returned without posting the menu. | |
679 | ||
680 | =item I<$menu>-E<gt>B<postcascade>(I<index>) | |
681 | ||
682 | Posts the submenu associated with the cascade entry given by | |
683 | I<index>, and unposts any previously posted submenu. | |
684 | If I<index> doesn't correspond to a cascade entry, | |
685 | or if I<$menu> isn't posted, | |
686 | the method has no effect except to unpost any currently posted | |
687 | submenu. | |
688 | ||
689 | =item I<$menu>-E<gt>B<type>(I<index>) | |
690 | ||
691 | Returns the type of the menu entry given by I<index>. | |
692 | This is the I<type> argument passed to the B<add> widget | |
693 | method when the entry was created, such as B<command> | |
694 | or B<separator>, or B<tearoff> for a tear-off entry. | |
695 | ||
696 | =item I<$menu>-E<gt>B<unpost> | |
697 | ||
698 | Unmap the window so that it is no longer displayed. If a | |
699 | lower-level cascaded menu is posted, unpost that menu. Returns an | |
700 | empty string. This method does not work on Windows and the | |
701 | Macintosh, as those platforms have their own way of unposting menus. | |
702 | ||
703 | =item I<$menu>-E<gt>B<yposition>(I<index>) | |
704 | ||
705 | Returns a decimal string giving the y-coordinate within the menu | |
706 | window of the topmost pixel in the entry specified by I<index>. | |
707 | ||
708 | =back | |
709 | ||
710 | =head1 MENU CONFIGURATIONS | |
711 | ||
712 | The default bindings support four different ways of using menus: | |
713 | ||
714 | =over 4 | |
715 | ||
716 | =item B<Pulldown Menus in Menubar> | |
717 | ||
718 | This is the most command case. You create a menu widget that will become the | |
719 | menu bar. You then add cascade entries to this menu, specifying the | |
720 | pull down menus you wish to use in your menu bar. You then create all | |
721 | of the pulldowns. Once you have done this, specify the menu using the | |
722 | B<-menu> option of the toplevel's method. See the | |
723 | B<toplevel> manual entry for details. | |
724 | ||
725 | =item B<Pulldown Menus in Menu Buttons> | |
726 | ||
727 | This is the compatable way to do menu bars. You create one menubutton | |
728 | widget for each top-level menu, and typically you arrange a series of | |
729 | menubuttons in a row in a menubar window. You also create the top-level menus | |
730 | and any cascaded submenus, and tie them together with B<-menu> | |
731 | options in menubuttons and cascade menu entries. The top-level menu must | |
732 | be a child of the menubutton, and each submenu must be a child of the | |
733 | menu that refers to it. Once you have done this, the default bindings | |
734 | will allow users to traverse and invoke the tree of menus via its | |
735 | menubutton; see the B<menubutton> documentation for details. | |
736 | ||
737 | =item B<Popup Menus> | |
738 | ||
739 | Popup menus typically post in response to a mouse button press or | |
740 | keystroke. You create the popup menus and any cascaded submenus, | |
741 | then you call the B<Post> method at the appropriate time | |
742 | to post the top-level menu. | |
743 | ||
744 | I<$menu>-E<gt>B<Post>(I<$x>,I<$y>?,I<$entry>?) | |
745 | ||
746 | I<$x> and I<$y> are the root window coordinates at which the I<$menu> | |
747 | will be displayed. If I<$entry> is specified then that entry is centred | |
748 | on that point, otherwise the top-left corner of the I<$menu> is placed | |
749 | at that point. | |
750 | ||
751 | B<Menu> also inherits methods from L<Tk::Wm> and so the method | |
752 | B<Popup> can be used to position menu relative to other windows, the | |
753 | mouse cursor or the screen. | |
754 | ||
755 | =item B<Option Menus> | |
756 | ||
757 | An option menu consists of a menubutton with an associated menu | |
758 | that allows you to select one of several values. The current value | |
759 | is displayed in the menubutton and is also stored in a global | |
760 | variable. Use the L<Tk::Optionmenu> class to create option | |
761 | menubuttons and their menus. | |
762 | ||
763 | =item B<Torn-off Menus> | |
764 | ||
765 | You create a torn-off menu by invoking the tear-off entry at | |
766 | the top of an existing menu. The default bindings will create a new menu | |
767 | that is a copy of the original menu and leave it permanently | |
768 | posted as a top-level window. The torn-off menu behaves just | |
769 | the same as the original menu. | |
770 | ||
771 | =back | |
772 | ||
773 | =head1 DEFAULT BINDINGS | |
774 | ||
775 | Tk automatically creates class bindings for menus that give them | |
776 | the following default behavior: | |
777 | ||
778 | =over 4 | |
779 | ||
780 | =item [1] | |
781 | ||
782 | When the mouse enters a menu, the entry underneath the mouse | |
783 | cursor activates; as the mouse moves around the menu, the active | |
784 | entry changes to track the mouse. | |
785 | ||
786 | =item [2] | |
787 | ||
788 | When the mouse leaves a menu all of the entries in the menu | |
789 | deactivate, except in the special case where the mouse moves from | |
790 | a menu to a cascaded submenu. | |
791 | ||
792 | =item [3] | |
793 | ||
794 | When a button is released over a menu, the active entry (if any) is invoked. | |
795 | The menu also unposts unless it is a torn-off menu. | |
796 | ||
797 | =item [4] | |
798 | ||
799 | The Space and Return keys invoke the active entry and | |
800 | unpost the menu. | |
801 | ||
802 | =item [5] | |
803 | ||
804 | If any of the entries in a menu have letters underlined with | |
805 | with B<-underline> option, then pressing one of the underlined | |
806 | letters (or its upper-case or lower-case equivalent) invokes that | |
807 | entry and unposts the menu. | |
808 | ||
809 | =item [6] | |
810 | ||
811 | The Escape key aborts a menu selection in progress without invoking any | |
812 | entry. It also unposts the menu unless it is a torn-off menu. | |
813 | ||
814 | =item [7] | |
815 | ||
816 | The Up and Down keys activate the next higher or lower entry | |
817 | in the menu. When one end of the menu is reached, the active | |
818 | entry wraps around to the other end. | |
819 | ||
820 | =item [8] | |
821 | ||
822 | The Left key moves to the next menu to the left. | |
823 | If the current menu is a cascaded submenu, then the submenu is | |
824 | unposted and the current menu entry becomes the cascade entry | |
825 | in the parent. | |
826 | If the current menu is a top-level menu posted from a | |
827 | menubutton, then the current menubutton is unposted and the | |
828 | next menubutton to the left is posted. | |
829 | Otherwise the key has no effect. | |
830 | The left-right order of menubuttons is determined by their stacking | |
831 | order: Tk assumes that the lowest menubutton (which by default | |
832 | is the first one created) is on the left. | |
833 | ||
834 | =item [9] | |
835 | ||
836 | The Right key moves to the next menu to the right. | |
837 | If the current entry is a cascade entry, then the submenu is | |
838 | posted and the current menu entry becomes the first entry | |
839 | in the submenu. | |
840 | Otherwise, if the current menu was posted from a | |
841 | menubutton, then the current menubutton is unposted and the | |
842 | next menubutton to the right is posted. | |
843 | ||
844 | Disabled menu entries are non-responsive: they don't activate and | |
845 | they ignore mouse button presses and releases. | |
846 | ||
847 | The behavior of menus can be changed by defining new bindings for | |
848 | individual widgets or by redefining the class bindings. | |
849 | ||
850 | =back | |
851 | ||
852 | =head1 BUGS | |
853 | ||
854 | At present it isn't possible to use the | |
855 | option database to specify values for the options to individual | |
856 | entries. | |
857 | ||
858 | =head1 SEE ALSO | |
859 | ||
860 | L<Tk::callbacks|Tk::callbacks> | |
861 | ||
862 | =head1 KEYWORDS | |
863 | ||
864 | menu, widget | |
865 | ||
866 | =cut | |
867 |