| 1 | '\" |
| 2 | '\" Copyright (c) 1990-1994 The Regents of the University of California. |
| 3 | '\" Copyright (c) 1994-1997 Sun Microsystems, Inc. |
| 4 | '\" |
| 5 | '\" See the file "license.terms" for information on usage and redistribution |
| 6 | '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. |
| 7 | '\" |
| 8 | '\" RCS: @(#) $Id: menu.n,v 1.8.2.1 2004/10/28 10:19:29 dkf Exp $ |
| 9 | '\" |
| 10 | '\" The definitions below are for supplemental macros used in Tcl/Tk |
| 11 | '\" manual entries. |
| 12 | '\" |
| 13 | '\" .AP type name in/out ?indent? |
| 14 | '\" Start paragraph describing an argument to a library procedure. |
| 15 | '\" type is type of argument (int, etc.), in/out is either "in", "out", |
| 16 | '\" or "in/out" to describe whether procedure reads or modifies arg, |
| 17 | '\" and indent is equivalent to second arg of .IP (shouldn't ever be |
| 18 | '\" needed; use .AS below instead) |
| 19 | '\" |
| 20 | '\" .AS ?type? ?name? |
| 21 | '\" Give maximum sizes of arguments for setting tab stops. Type and |
| 22 | '\" name are examples of largest possible arguments that will be passed |
| 23 | '\" to .AP later. If args are omitted, default tab stops are used. |
| 24 | '\" |
| 25 | '\" .BS |
| 26 | '\" Start box enclosure. From here until next .BE, everything will be |
| 27 | '\" enclosed in one large box. |
| 28 | '\" |
| 29 | '\" .BE |
| 30 | '\" End of box enclosure. |
| 31 | '\" |
| 32 | '\" .CS |
| 33 | '\" Begin code excerpt. |
| 34 | '\" |
| 35 | '\" .CE |
| 36 | '\" End code excerpt. |
| 37 | '\" |
| 38 | '\" .VS ?version? ?br? |
| 39 | '\" Begin vertical sidebar, for use in marking newly-changed parts |
| 40 | '\" of man pages. The first argument is ignored and used for recording |
| 41 | '\" the version when the .VS was added, so that the sidebars can be |
| 42 | '\" found and removed when they reach a certain age. If another argument |
| 43 | '\" is present, then a line break is forced before starting the sidebar. |
| 44 | '\" |
| 45 | '\" .VE |
| 46 | '\" End of vertical sidebar. |
| 47 | '\" |
| 48 | '\" .DS |
| 49 | '\" Begin an indented unfilled display. |
| 50 | '\" |
| 51 | '\" .DE |
| 52 | '\" End of indented unfilled display. |
| 53 | '\" |
| 54 | '\" .SO |
| 55 | '\" Start of list of standard options for a Tk widget. The |
| 56 | '\" options follow on successive lines, in four columns separated |
| 57 | '\" by tabs. |
| 58 | '\" |
| 59 | '\" .SE |
| 60 | '\" End of list of standard options for a Tk widget. |
| 61 | '\" |
| 62 | '\" .OP cmdName dbName dbClass |
| 63 | '\" Start of description of a specific option. cmdName gives the |
| 64 | '\" option's name as specified in the class command, dbName gives |
| 65 | '\" the option's name in the option database, and dbClass gives |
| 66 | '\" the option's class in the option database. |
| 67 | '\" |
| 68 | '\" .UL arg1 arg2 |
| 69 | '\" Print arg1 underlined, then print arg2 normally. |
| 70 | '\" |
| 71 | '\" RCS: @(#) $Id: man.macros,v 1.4 2000/08/25 06:18:32 ericm Exp $ |
| 72 | '\" |
| 73 | '\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. |
| 74 | .if t .wh -1.3i ^B |
| 75 | .nr ^l \n(.l |
| 76 | .ad b |
| 77 | '\" # Start an argument description |
| 78 | .de AP |
| 79 | .ie !"\\$4"" .TP \\$4 |
| 80 | .el \{\ |
| 81 | . ie !"\\$2"" .TP \\n()Cu |
| 82 | . el .TP 15 |
| 83 | .\} |
| 84 | .ta \\n()Au \\n()Bu |
| 85 | .ie !"\\$3"" \{\ |
| 86 | \&\\$1 \\fI\\$2\\fP (\\$3) |
| 87 | .\".b |
| 88 | .\} |
| 89 | .el \{\ |
| 90 | .br |
| 91 | .ie !"\\$2"" \{\ |
| 92 | \&\\$1 \\fI\\$2\\fP |
| 93 | .\} |
| 94 | .el \{\ |
| 95 | \&\\fI\\$1\\fP |
| 96 | .\} |
| 97 | .\} |
| 98 | .. |
| 99 | '\" # define tabbing values for .AP |
| 100 | .de AS |
| 101 | .nr )A 10n |
| 102 | .if !"\\$1"" .nr )A \\w'\\$1'u+3n |
| 103 | .nr )B \\n()Au+15n |
| 104 | .\" |
| 105 | .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n |
| 106 | .nr )C \\n()Bu+\\w'(in/out)'u+2n |
| 107 | .. |
| 108 | .AS Tcl_Interp Tcl_CreateInterp in/out |
| 109 | '\" # BS - start boxed text |
| 110 | '\" # ^y = starting y location |
| 111 | '\" # ^b = 1 |
| 112 | .de BS |
| 113 | .br |
| 114 | .mk ^y |
| 115 | .nr ^b 1u |
| 116 | .if n .nf |
| 117 | .if n .ti 0 |
| 118 | .if n \l'\\n(.lu\(ul' |
| 119 | .if n .fi |
| 120 | .. |
| 121 | '\" # BE - end boxed text (draw box now) |
| 122 | .de BE |
| 123 | .nf |
| 124 | .ti 0 |
| 125 | .mk ^t |
| 126 | .ie n \l'\\n(^lu\(ul' |
| 127 | .el \{\ |
| 128 | .\" Draw four-sided box normally, but don't draw top of |
| 129 | .\" box if the box started on an earlier page. |
| 130 | .ie !\\n(^b-1 \{\ |
| 131 | \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' |
| 132 | .\} |
| 133 | .el \}\ |
| 134 | \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' |
| 135 | .\} |
| 136 | .\} |
| 137 | .fi |
| 138 | .br |
| 139 | .nr ^b 0 |
| 140 | .. |
| 141 | '\" # VS - start vertical sidebar |
| 142 | '\" # ^Y = starting y location |
| 143 | '\" # ^v = 1 (for troff; for nroff this doesn't matter) |
| 144 | .de VS |
| 145 | .if !"\\$2"" .br |
| 146 | .mk ^Y |
| 147 | .ie n 'mc \s12\(br\s0 |
| 148 | .el .nr ^v 1u |
| 149 | .. |
| 150 | '\" # VE - end of vertical sidebar |
| 151 | .de VE |
| 152 | .ie n 'mc |
| 153 | .el \{\ |
| 154 | .ev 2 |
| 155 | .nf |
| 156 | .ti 0 |
| 157 | .mk ^t |
| 158 | \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' |
| 159 | .sp -1 |
| 160 | .fi |
| 161 | .ev |
| 162 | .\} |
| 163 | .nr ^v 0 |
| 164 | .. |
| 165 | '\" # Special macro to handle page bottom: finish off current |
| 166 | '\" # box/sidebar if in box/sidebar mode, then invoked standard |
| 167 | '\" # page bottom macro. |
| 168 | .de ^B |
| 169 | .ev 2 |
| 170 | 'ti 0 |
| 171 | 'nf |
| 172 | .mk ^t |
| 173 | .if \\n(^b \{\ |
| 174 | .\" Draw three-sided box if this is the box's first page, |
| 175 | .\" draw two sides but no top otherwise. |
| 176 | .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c |
| 177 | .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c |
| 178 | .\} |
| 179 | .if \\n(^v \{\ |
| 180 | .nr ^x \\n(^tu+1v-\\n(^Yu |
| 181 | \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c |
| 182 | .\} |
| 183 | .bp |
| 184 | 'fi |
| 185 | .ev |
| 186 | .if \\n(^b \{\ |
| 187 | .mk ^y |
| 188 | .nr ^b 2 |
| 189 | .\} |
| 190 | .if \\n(^v \{\ |
| 191 | .mk ^Y |
| 192 | .\} |
| 193 | .. |
| 194 | '\" # DS - begin display |
| 195 | .de DS |
| 196 | .RS |
| 197 | .nf |
| 198 | .sp |
| 199 | .. |
| 200 | '\" # DE - end display |
| 201 | .de DE |
| 202 | .fi |
| 203 | .RE |
| 204 | .sp |
| 205 | .. |
| 206 | '\" # SO - start of list of standard options |
| 207 | .de SO |
| 208 | .SH "STANDARD OPTIONS" |
| 209 | .LP |
| 210 | .nf |
| 211 | .ta 5.5c 11c |
| 212 | .ft B |
| 213 | .. |
| 214 | '\" # SE - end of list of standard options |
| 215 | .de SE |
| 216 | .fi |
| 217 | .ft R |
| 218 | .LP |
| 219 | See the \\fBoptions\\fR manual entry for details on the standard options. |
| 220 | .. |
| 221 | '\" # OP - start of full description for a single option |
| 222 | .de OP |
| 223 | .LP |
| 224 | .nf |
| 225 | .ta 4c |
| 226 | Command-Line Name: \\fB\\$1\\fR |
| 227 | Database Name: \\fB\\$2\\fR |
| 228 | Database Class: \\fB\\$3\\fR |
| 229 | .fi |
| 230 | .IP |
| 231 | .. |
| 232 | '\" # CS - begin code excerpt |
| 233 | .de CS |
| 234 | .RS |
| 235 | .nf |
| 236 | .ta .25i .5i .75i 1i |
| 237 | .. |
| 238 | '\" # CE - end code excerpt |
| 239 | .de CE |
| 240 | .fi |
| 241 | .RE |
| 242 | .. |
| 243 | .de UL |
| 244 | \\$1\l'|0\(ul'\\$2 |
| 245 | .. |
| 246 | .TH menu n 4.1 Tk "Tk Built-In Commands" |
| 247 | .BS |
| 248 | '\" Note: do not modify the .SH NAME line immediately below! |
| 249 | .SH NAME |
| 250 | menu, tk_menuSetFocus \- Create and manipulate menu widgets |
| 251 | .SH SYNOPSIS |
| 252 | .nf |
| 253 | \fBmenu\fR \fIpathName \fR?\fIoptions\fR? |
| 254 | \fBtk_menuSetFocus\fR \fIpathName\fR |
| 255 | .SO |
| 256 | \-activebackground \-borderwidth \-foreground |
| 257 | \-activeborderwidth \-cursor \-relief |
| 258 | \-activeforeground \-disabledforeground \-takefocus |
| 259 | \-background \-font |
| 260 | |
| 261 | .SE |
| 262 | .SH "WIDGET-SPECIFIC OPTIONS" |
| 263 | .VS |
| 264 | .OP \-postcommand postCommand Command |
| 265 | If this option is specified then it provides a Tcl command to execute |
| 266 | each time the menu is posted. The command is invoked by the \fBpost\fR |
| 267 | widget command before posting the menu. Note that in Tk 8.0 on Macintosh |
| 268 | and Windows, all post-commands in a system of menus are executed before any |
| 269 | of those menus are posted. |
| 270 | This is due to the limitations in the individual platforms' menu managers. |
| 271 | .VE |
| 272 | .OP \-selectcolor selectColor Background |
| 273 | For menu entries that are check buttons or radio buttons, this option |
| 274 | specifies the color to display in the indicator when the check button |
| 275 | or radio button is selected. |
| 276 | .OP \-tearoff tearOff TearOff |
| 277 | This option must have a proper boolean value, which specifies |
| 278 | whether or not the menu should include a tear-off entry at the |
| 279 | top. If so, it will exist as entry 0 of the menu and the other |
| 280 | entries will number starting at 1. The default |
| 281 | menu bindings arrange for the menu to be torn off when the tear-off |
| 282 | entry is invoked. |
| 283 | .OP \-tearoffcommand tearOffCommand TearOffCommand |
| 284 | If this option has a non-empty value, then it specifies a Tcl command |
| 285 | to invoke whenever the menu is torn off. The actual command will |
| 286 | consist of the value of this option, followed by a space, followed |
| 287 | by the name of the menu window, followed by a space, followed by |
| 288 | the name of the name of the torn off menu window. For example, if |
| 289 | the option's is ``\fBa b\fR'' and menu \fB.x.y\fR is torn off to |
| 290 | create a new menu \fB.x.tearoff1\fR, then the command |
| 291 | ``\fBa b .x.y .x.tearoff1\fR'' will be invoked. |
| 292 | .VS |
| 293 | .OP \-title title Title |
| 294 | The string will be used to title the window created when this menu is |
| 295 | torn off. If the title is NULL, then the window will have the title |
| 296 | of the menubutton or the text of the cascade item from which this menu |
| 297 | was invoked. |
| 298 | .OP \-type type Type |
| 299 | This option can be one of \fBmenubar\fR, \fBtearoff\fR, or |
| 300 | \fBnormal\fR, and is set when the menu is created. While the string |
| 301 | returned by the configuration database will change if this option is |
| 302 | changed, this does not affect the menu widget's behavior. This is used |
| 303 | by the cloning mechanism and is not normally set outside of the Tk |
| 304 | library. |
| 305 | .VE |
| 306 | .BE |
| 307 | |
| 308 | .SH INTRODUCTION |
| 309 | .PP |
| 310 | The \fBmenu\fR command creates a new top-level window (given |
| 311 | by the \fIpathName\fR argument) and makes it into a menu widget. |
| 312 | Additional |
| 313 | options, described above, may be specified on the command line |
| 314 | or in the option database |
| 315 | to configure aspects of the menu such as its colors and font. |
| 316 | The \fBmenu\fR command returns its |
| 317 | \fIpathName\fR argument. At the time this command is invoked, |
| 318 | there must not exist a window named \fIpathName\fR, but |
| 319 | \fIpathName\fR's parent must exist. |
| 320 | .PP |
| 321 | .VS |
| 322 | A menu is a widget that displays a collection of one-line entries arranged |
| 323 | in one or more columns. There exist several different types of entries, |
| 324 | each with different properties. Entries of different types may be |
| 325 | combined in a single menu. Menu entries are not the same as |
| 326 | entry widgets. In fact, menu entries are not even distinct widgets; |
| 327 | the entire menu is one widget. |
| 328 | .VE |
| 329 | .PP |
| 330 | Menu entries are displayed with up to three separate fields. |
| 331 | The main field is a label in the form of a text string, |
| 332 | a bitmap, or an image, controlled by the \fB\-label\fR, |
| 333 | \fB\-bitmap\fR, and \fB\-image\fR options for the entry. |
| 334 | If the \fB\-accelerator\fR option is specified for an entry then a second |
| 335 | textual field is displayed to the right of the label. The accelerator |
| 336 | typically describes a keystroke sequence that may be typed in the |
| 337 | application to cause the same result as invoking the menu entry. |
| 338 | The third field is an \fIindicator\fR. The indicator is present only for |
| 339 | checkbutton or radiobutton entries. It indicates whether the entry |
| 340 | is selected or not, and is displayed to the left of the entry's |
| 341 | string. |
| 342 | .PP |
| 343 | In normal use, an entry becomes active (displays itself differently) |
| 344 | whenever the mouse pointer is over the entry. If a mouse |
| 345 | button is released over the entry then the entry is \fIinvoked\fR. |
| 346 | The effect of invocation is different for each type of entry; |
| 347 | these effects are described below in the sections on individual |
| 348 | entries. |
| 349 | .PP |
| 350 | Entries may be \fIdisabled\fR, which causes their labels |
| 351 | and accelerators to be displayed |
| 352 | with dimmer colors. |
| 353 | The default menu bindings will not allow |
| 354 | a disabled entry to be activated or invoked. |
| 355 | Disabled entries may be re-enabled, at which point it becomes |
| 356 | possible to activate and invoke them again. |
| 357 | .VS |
| 358 | .PP |
| 359 | Whenever a menu's active entry is changed, a <<MenuSelect>> virtual |
| 360 | event is send to the menu. The active item can then be queried from |
| 361 | the menu, and an action can be taken, such as setting |
| 362 | context-sensitive help text for the entry. |
| 363 | .VE |
| 364 | |
| 365 | .SH "COMMAND ENTRIES" |
| 366 | .PP |
| 367 | The most common kind of menu entry is a command entry, which |
| 368 | behaves much like a button widget. When a command entry is |
| 369 | invoked, a Tcl command is executed. The Tcl |
| 370 | command is specified with the \fB\-command\fR option. |
| 371 | |
| 372 | .SH "SEPARATOR ENTRIES" |
| 373 | .PP |
| 374 | A separator is an entry that is displayed as a horizontal dividing |
| 375 | line. A separator may not be activated or invoked, and it has |
| 376 | no behavior other than its display appearance. |
| 377 | |
| 378 | .SH "CHECKBUTTON ENTRIES" |
| 379 | .PP |
| 380 | A checkbutton menu entry behaves much like a checkbutton widget. |
| 381 | When it is invoked it toggles back and forth between the selected |
| 382 | and deselected states. When the entry is selected, a particular |
| 383 | value is stored in a particular global variable (as determined by |
| 384 | the \fB\-onvalue\fR and \fB\-variable\fR options for the entry); when |
| 385 | the entry is deselected another value (determined by the |
| 386 | \fB\-offvalue\fR option) is stored in the global variable. |
| 387 | An indicator box is displayed to the left of the label in a checkbutton |
| 388 | entry. If the entry is selected then the indicator's center is displayed |
| 389 | in the color given by the \fB\-selectcolor\fR option for the entry; |
| 390 | otherwise the indicator's center is displayed in the background color for |
| 391 | the menu. If a \fB\-command\fR option is specified for a checkbutton |
| 392 | entry, then its value is evaluated as a Tcl command each time the entry |
| 393 | is invoked; this happens after toggling the entry's |
| 394 | selected state. |
| 395 | |
| 396 | .SH "RADIOBUTTON ENTRIES" |
| 397 | .PP |
| 398 | A radiobutton menu entry behaves much like a radiobutton widget. |
| 399 | Radiobutton entries are organized in groups of which only one |
| 400 | entry may be selected at a time. Whenever a particular entry |
| 401 | becomes selected it stores a particular value into a particular |
| 402 | global variable (as determined by the \fB\-value\fR and |
| 403 | \fB\-variable\fR options for the entry). This action |
| 404 | causes any previously-selected entry in the same group |
| 405 | to deselect itself. |
| 406 | Once an entry has become selected, any change to the entry's |
| 407 | associated variable will cause the entry to deselect itself. |
| 408 | Grouping of radiobutton entries is determined by their |
| 409 | associated variables: if two entries have the same associated |
| 410 | variable then they are in the same group. |
| 411 | An indicator diamond is displayed to the left of the label in each |
| 412 | radiobutton entry. If the entry is selected then the indicator's |
| 413 | center is displayed in the color given by the \fB\-selectcolor\fR option |
| 414 | for the entry; |
| 415 | otherwise the indicator's center is displayed in the background color for |
| 416 | the menu. If a \fB\-command\fR option is specified for a radiobutton |
| 417 | entry, then its value is evaluated as a Tcl command each time the entry |
| 418 | is invoked; this happens after selecting the entry. |
| 419 | |
| 420 | .SH "CASCADE ENTRIES" |
| 421 | .PP |
| 422 | A cascade entry is one with an associated menu (determined |
| 423 | by the \fB\-menu\fR option). Cascade entries allow the construction |
| 424 | of cascading menus. |
| 425 | The \fBpostcascade\fR widget command can be used to post and unpost |
| 426 | the associated menu just next to of the cascade entry. |
| 427 | The associated menu must be a child of the menu containing |
| 428 | the cascade entry (this is needed in order for menu traversal to |
| 429 | work correctly). |
| 430 | .PP |
| 431 | A cascade entry posts its associated menu by invoking a |
| 432 | Tcl command of the form |
| 433 | .CS |
| 434 | \fImenu\fB post \fIx y\fR |
| 435 | .CE |
| 436 | where \fImenu\fR is the path name of the associated menu, and \fIx\fR |
| 437 | and \fIy\fR are the root-window coordinates of the upper-right |
| 438 | corner of the cascade entry. |
| 439 | .VS |
| 440 | On Unix, the lower-level menu is unposted by executing a Tcl command with |
| 441 | the form |
| 442 | .CS |
| 443 | \fImenu\fB unpost\fR |
| 444 | .CE |
| 445 | where \fImenu\fR is the name of the associated menu. |
| 446 | On other platforms, the platform's native code takes care of unposting the |
| 447 | menu. |
| 448 | .VE |
| 449 | .PP |
| 450 | .VS |
| 451 | If a \fB\-command\fR option is specified for a cascade entry then it is |
| 452 | evaluated as a Tcl command whenever the entry is invoked. This is not |
| 453 | supported on Windows. |
| 454 | .VE |
| 455 | |
| 456 | .SH "TEAR-OFF ENTRIES" |
| 457 | .PP |
| 458 | A tear-off entry appears at the top of the menu if enabled with the |
| 459 | \fBtearOff\fR option. It is not like other menu entries in that |
| 460 | it cannot be created with the \fBadd\fR widget command and |
| 461 | cannot be deleted with the \fBdelete\fR widget command. |
| 462 | When a tear-off entry is created it appears as a dashed line at |
| 463 | the top of the menu. Under the default bindings, invoking the |
| 464 | tear-off entry causes a torn-off copy to be made of the menu and |
| 465 | all of its submenus. |
| 466 | |
| 467 | .VS |
| 468 | .SH "MENUBARS" |
| 469 | .PP |
| 470 | Any menu can be set as a menubar for a toplevel window (see |
| 471 | \fBtoplevel\fR command for syntax). On the Macintosh, whenever the |
| 472 | toplevel is in front, this menu's cascade items will appear in the |
| 473 | menubar across the top of the main monitor. On Windows and Unix, this |
| 474 | menu's items will be displayed in a menubar across the top of the |
| 475 | window. These menus will behave according to the interface guidelines |
| 476 | of their platforms. For every menu set as a menubar, a clone menu is |
| 477 | made. See the \fBCLONES\fR section for more information. |
| 478 | .PP |
| 479 | As noted, menubars may behave differently on different platforms. One |
| 480 | example of this concerns the handling of checkbuttons and radiobuttons |
| 481 | within the menu. While it is permitted to put these menu elements on |
| 482 | menubars, they may not be drawn with indicators on some platforms, due |
| 483 | to system restrictions. |
| 484 | .VE |
| 485 | |
| 486 | .VS |
| 487 | .SH "SPECIAL MENUS IN MENUBARS" |
| 488 | .PP |
| 489 | Certain menus in a menubar will be treated specially. On the Macintosh, |
| 490 | access to the special Apple and Help menus is provided. On Windows, |
| 491 | access to the Windows System menu in each window is provided. On X Windows, |
| 492 | a special right-justified help menu is provided. In all cases, these |
| 493 | menus must be created with the command name of the menubar menu concatenated |
| 494 | with the special name. So for a menubar named .menubar, on the Macintosh, |
| 495 | the special menus would be .menubar.apple and .menubar.help; on Windows, |
| 496 | the special menu would be .menubar.system; on X Windows, the help |
| 497 | menu would be .menubar.help. |
| 498 | .PP |
| 499 | When Tk sees an Apple menu on the Macintosh, that menu's contents make |
| 500 | up the first items of the Apple menu on the screen whenever the window |
| 501 | containing the menubar is in front. The menu is the |
| 502 | first one that the user sees and has a title which is an Apple logo. |
| 503 | After all of the Tk-defined items, the menu will have a separator, |
| 504 | followed by all of the items in the user's Apple Menu Items folder. |
| 505 | Since the System uses a different menu definition procedure for |
| 506 | the Apple menu than Tk uses for its menus, and the system APIs do |
| 507 | not fully support everything Tk tries to do, the menu item will only |
| 508 | have its text displayed. No font attributes, images, bitmaps, or colors |
| 509 | will be displayed. In addition, a menu with a tearoff item will have |
| 510 | the tearoff item displayed as "(TearOff)". |
| 511 | .PP |
| 512 | When Tk see a Help menu on the Macintosh, the menu's contents are |
| 513 | appended to the standard help menu on the right of the user's menubar |
| 514 | whenever the user's menubar is in front. The first items in the menu |
| 515 | are provided by Apple. Similar to the Apple Menu, customization in this |
| 516 | menu is limited to what the system provides. |
| 517 | .PP |
| 518 | When Tk sees a System menu on Windows, its items are appended to the |
| 519 | system menu that the menubar is attached to. This menu has an icon |
| 520 | representing a spacebar, and can be invoked with the mouse or by typing |
| 521 | Alt+Spacebar. Due to limitations in the Windows API, any font changes, |
| 522 | colors, images, bitmaps, or tearoff images will not appear in the |
| 523 | system menu. |
| 524 | .PP |
| 525 | When Tk see a Help menu on X Windows, the menu is moved to be last in |
| 526 | the menubar and is right justified. |
| 527 | .VE |
| 528 | |
| 529 | .VS |
| 530 | .SH "CLONES" |
| 531 | .PP |
| 532 | When a menu is set as a menubar for a toplevel window, or when a menu |
| 533 | is torn off, a clone of the menu is made. This clone is a menu widget |
| 534 | in its own right, but it is a child of the original. Changes in the |
| 535 | configuration of the original are reflected in the |
| 536 | clone. Additionally, any cascades that are pointed to are also cloned |
| 537 | so that menu traversal will work right. Clones are destroyed when |
| 538 | either the tearoff or menubar goes away, or when the original menu is |
| 539 | destroyed. |
| 540 | .VE |
| 541 | |
| 542 | .SH "WIDGET COMMAND" |
| 543 | .PP |
| 544 | The \fBmenu\fR command creates a new Tcl command whose |
| 545 | name is \fIpathName\fR. This |
| 546 | command may be used to invoke various |
| 547 | operations on the widget. It has the following general form: |
| 548 | .CS |
| 549 | \fIpathName option \fR?\fIarg arg ...\fR? |
| 550 | .CE |
| 551 | \fIOption\fR and the \fIarg\fRs |
| 552 | determine the exact behavior of the command. |
| 553 | .PP |
| 554 | Many of the widget commands for a menu take as one argument an |
| 555 | indicator of which entry of the menu to operate on. These |
| 556 | indicators are called \fIindex\fRes and may be specified in |
| 557 | any of the following forms: |
| 558 | .TP 12 |
| 559 | \fInumber\fR |
| 560 | Specifies the entry numerically, where 0 corresponds |
| 561 | to the top-most entry of the menu, 1 to the entry below it, and |
| 562 | so on. |
| 563 | .TP 12 |
| 564 | \fBactive\fR |
| 565 | Indicates the entry that is currently active. If no entry is |
| 566 | active then this form is equivalent to \fBnone\fR. This form may |
| 567 | not be abbreviated. |
| 568 | .TP 12 |
| 569 | \fBend\fR |
| 570 | Indicates the bottommost entry in the menu. If there are no |
| 571 | entries in the menu then this form is equivalent to \fBnone\fR. |
| 572 | This form may not be abbreviated. |
| 573 | .TP 12 |
| 574 | \fBlast\fR |
| 575 | Same as \fBend\fR. |
| 576 | .TP 12 |
| 577 | \fBnone\fR |
| 578 | Indicates ``no entry at all''; this is used most commonly with |
| 579 | the \fBactivate\fR option to deactivate all the entries in the |
| 580 | menu. In most cases the specification of \fBnone\fR causes |
| 581 | nothing to happen in the widget command. |
| 582 | This form may not be abbreviated. |
| 583 | .TP 12 |
| 584 | \fB@\fInumber\fR |
| 585 | In this form, \fInumber\fR is treated as a y-coordinate in the |
| 586 | menu's window; the entry closest to that y-coordinate is used. |
| 587 | For example, ``\fB@0\fR'' indicates the top-most entry in the |
| 588 | window. |
| 589 | .TP 12 |
| 590 | \fIpattern\fR |
| 591 | If the index doesn't satisfy one of the above forms then this |
| 592 | form is used. \fIPattern\fR is pattern-matched against the label of |
| 593 | each entry in the menu, in order from the top down, until a |
| 594 | matching entry is found. The rules of \fBTcl_StringMatch\fR |
| 595 | are used. |
| 596 | .PP |
| 597 | The following widget commands are possible for menu widgets: |
| 598 | .TP |
| 599 | \fIpathName \fBactivate \fIindex\fR |
| 600 | Change the state of the entry indicated by \fIindex\fR to \fBactive\fR |
| 601 | and redisplay it using its active colors. |
| 602 | Any previously-active entry is deactivated. If \fIindex\fR |
| 603 | is specified as \fBnone\fR, or if the specified entry is |
| 604 | disabled, then the menu ends up with no active entry. |
| 605 | Returns an empty string. |
| 606 | .TP |
| 607 | \fIpathName \fBadd \fItype \fR?\fIoption value option value ...\fR? |
| 608 | Add a new entry to the bottom of the menu. The new entry's type |
| 609 | is given by \fItype\fR and must be one of \fBcascade\fR, |
| 610 | \fBcheckbutton\fR, \fBcommand\fR, \fBradiobutton\fR, or \fBseparator\fR, |
| 611 | or a unique abbreviation of one of the above. If additional arguments |
| 612 | are present, they specify any of the following options: |
| 613 | .RS |
| 614 | .TP |
| 615 | \fB\-activebackground \fIvalue\fR |
| 616 | Specifies a background color to use for displaying this entry when it |
| 617 | is active. |
| 618 | If this option is specified as an empty string (the default), then the |
| 619 | \fBactiveBackground\fR option for the overall menu is used. |
| 620 | If the \fBtk_strictMotif\fR variable has been set to request strict |
| 621 | Motif compliance, then this option is ignored and the \fB\-background\fR |
| 622 | option is used in its place. |
| 623 | This option is not available for separator or tear-off entries. |
| 624 | .TP |
| 625 | \fB\-activeforeground \fIvalue\fR |
| 626 | Specifies a foreground color to use for displaying this entry when it |
| 627 | is active. |
| 628 | If this option is specified as an empty string (the default), then the |
| 629 | \fBactiveForeground\fR option for the overall menu is used. |
| 630 | This option is not available for separator or tear-off entries. |
| 631 | .TP |
| 632 | \fB\-accelerator \fIvalue\fR |
| 633 | Specifies a string to display at the right side of the menu entry. |
| 634 | Normally describes an accelerator keystroke sequence that may be |
| 635 | typed to invoke the same function as the menu entry. This option |
| 636 | is not available for separator or tear-off entries. |
| 637 | .TP |
| 638 | \fB\-background \fIvalue\fR |
| 639 | Specifies a background color to use for displaying this entry when it |
| 640 | is in the normal state (neither active nor disabled). |
| 641 | If this option is specified as an empty string (the default), then the |
| 642 | \fBbackground\fR option for the overall menu is used. |
| 643 | This option is not available for separator or tear-off entries. |
| 644 | .TP |
| 645 | \fB\-bitmap \fIvalue\fR |
| 646 | Specifies a bitmap to display in the menu instead of a textual |
| 647 | label, in any of the forms accepted by \fBTk_GetBitmap\fR. |
| 648 | This option overrides the \fB\-label\fR option |
| 649 | (as controlled by the \fB\-compound\fR option) |
| 650 | but may be reset |
| 651 | to an empty string to enable a textual label to be displayed. |
| 652 | If a \fB\-image\fR option has been specified, it overrides |
| 653 | \fB\-bitmap\fR. |
| 654 | This option is not available for separator or tear-off entries. |
| 655 | .TP |
| 656 | \fB\-columnbreak \fIvalue\fR |
| 657 | .VS 8.0 |
| 658 | When this option is zero, the entry appears below the previous entry. When |
| 659 | this option is one, the entry appears at the top of a new column in the |
| 660 | menu. |
| 661 | .VE 8.0 |
| 662 | .TP |
| 663 | \fB\-command \fIvalue\fR |
| 664 | Specifies a Tcl command to execute when the menu entry is invoked. |
| 665 | Not available for separator or tear-off entries. |
| 666 | .VS 8.4 |
| 667 | .TP |
| 668 | \fB\-compound \fIvalue\fR |
| 669 | Specifies whether the menu entry should display both an image and text, |
| 670 | and if so, where the image should be placed relative to the text. |
| 671 | Valid values for this option are \fBbottom\fR, \fBcenter\fR, |
| 672 | \fBleft\fR, \fBnone\fR, \fBright\fR and \fBtop\fR. The default value |
| 673 | is \fBnone\fR, meaning that the button will display either an image or |
| 674 | text, depending on the values of the \fB\-image\fR and \fB\-bitmap\fR |
| 675 | options. |
| 676 | .VE |
| 677 | .TP |
| 678 | \fB\-font \fIvalue\fR |
| 679 | Specifies the font to use when drawing the label or accelerator |
| 680 | string in this entry. |
| 681 | If this option is specified as an empty string (the default) then |
| 682 | the \fBfont\fR option for the overall menu is used. |
| 683 | This option is not available for separator or tear-off entries. |
| 684 | .TP |
| 685 | \fB\-foreground \fIvalue\fR |
| 686 | Specifies a foreground color to use for displaying this entry when it |
| 687 | is in the normal state (neither active nor disabled). |
| 688 | If this option is specified as an empty string (the default), then the |
| 689 | \fBforeground\fR option for the overall menu is used. |
| 690 | This option is not available for separator or tear-off entries. |
| 691 | .VS |
| 692 | .TP |
| 693 | \fB\-hidemargin \fIvalue\fR |
| 694 | Specifies whether the standard margins should be drawn for this menu |
| 695 | entry. This is useful when creating palette with images in them, i.e., |
| 696 | color palettes, pattern palettes, etc. 1 indicates that the margin for |
| 697 | the entry is hidden; 0 means that the margin is used. |
| 698 | .VE |
| 699 | .TP |
| 700 | \fB\-image \fIvalue\fR |
| 701 | Specifies an image to display in the menu instead of a text string |
| 702 | or bitmap. |
| 703 | The image must have been created by some previous invocation of |
| 704 | \fBimage create\fR. |
| 705 | This option overrides the \fB\-label\fR and \fB\-bitmap\fR options |
| 706 | (as controlled by the \fB\-compound\fR option) |
| 707 | but may be reset to an empty string to enable a textual or |
| 708 | bitmap label to be displayed. |
| 709 | This option is not available for separator or tear-off entries. |
| 710 | .TP |
| 711 | \fB\-indicatoron \fIvalue\fR |
| 712 | Available only for checkbutton and radiobutton entries. |
| 713 | \fIValue\fR is a boolean that determines whether or not the |
| 714 | indicator should be displayed. |
| 715 | .TP |
| 716 | \fB\-label \fIvalue\fR |
| 717 | Specifies a string to display as an identifying label in the menu |
| 718 | entry. Not available for separator or tear-off entries. |
| 719 | .TP |
| 720 | \fB\-menu \fIvalue\fR |
| 721 | Available only for cascade entries. Specifies the path name of |
| 722 | the submenu associated with this entry. |
| 723 | The submenu must be a child of the menu. |
| 724 | .TP |
| 725 | \fB\-offvalue \fIvalue\fR |
| 726 | Available only for checkbutton entries. Specifies the value to |
| 727 | store in the entry's associated variable when the entry is |
| 728 | deselected. |
| 729 | .TP |
| 730 | \fB\-onvalue \fIvalue\fR |
| 731 | Available only for checkbutton entries. Specifies the value to |
| 732 | store in the entry's associated variable when the entry is selected. |
| 733 | .TP |
| 734 | \fB\-selectcolor \fIvalue\fR |
| 735 | Available only for checkbutton and radiobutton entries. |
| 736 | Specifies the color to display in the indicator when the entry is |
| 737 | selected. |
| 738 | If the value is an empty string (the default) then the \fBselectColor\fR |
| 739 | option for the menu determines the indicator color. |
| 740 | .TP |
| 741 | \fB\-selectimage \fIvalue\fR |
| 742 | Available only for checkbutton and radiobutton entries. |
| 743 | Specifies an image to display in the entry (in place of |
| 744 | the \fB\-image\fR option) when it is selected. |
| 745 | \fIValue\fR is the name of an image, which must have been created |
| 746 | by some previous invocation of \fBimage create\fR. |
| 747 | This option is ignored unless the \fB\-image\fR option has |
| 748 | been specified. |
| 749 | .TP |
| 750 | \fB\-state \fIvalue\fR |
| 751 | Specifies one of three states for the entry: \fBnormal\fR, \fBactive\fR, |
| 752 | or \fBdisabled\fR. In normal state the entry is displayed using the |
| 753 | \fBforeground\fR option for the menu and the \fBbackground\fR |
| 754 | option from the entry or the menu. |
| 755 | The active state is typically used when the pointer is over the entry. |
| 756 | In active state the entry is displayed using the \fBactiveForeground\fR |
| 757 | option for the menu along with the \fBactivebackground\fR option from |
| 758 | the entry. Disabled state means that the entry |
| 759 | should be insensitive: the default bindings will refuse to activate |
| 760 | or invoke the entry. |
| 761 | In this state the entry is displayed according to the |
| 762 | \fBdisabledForeground\fR option for the menu and the |
| 763 | \fBbackground\fR option from the entry. |
| 764 | This option is not available for separator entries. |
| 765 | .TP |
| 766 | \fB\-underline \fIvalue\fR |
| 767 | Specifies the integer index of a character to underline in the entry. |
| 768 | This option is also queried by the default bindings and used to |
| 769 | implement keyboard traversal. |
| 770 | 0 corresponds to the first character of the text displayed in the entry, |
| 771 | 1 to the next character, and so on. |
| 772 | If a bitmap or image is displayed in the entry then this option is ignored. |
| 773 | This option is not available for separator or tear-off entries. |
| 774 | .TP |
| 775 | \fB\-value \fIvalue\fR |
| 776 | Available only for radiobutton entries. Specifies the value to |
| 777 | store in the entry's associated variable when the entry is selected. |
| 778 | If an empty string is specified, then the \fB\-label\fR option |
| 779 | for the entry as the value to store in the variable. |
| 780 | .TP |
| 781 | \fB\-variable \fIvalue\fR |
| 782 | Available only for checkbutton and radiobutton entries. Specifies |
| 783 | the name of a global value to set when the entry is selected. |
| 784 | For checkbutton entries the variable is also set when the entry |
| 785 | is deselected. For radiobutton entries, changing the variable |
| 786 | causes the currently-selected entry to deselect itself. |
| 787 | .LP |
| 788 | The \fBadd\fR widget command returns an empty string. |
| 789 | .RE |
| 790 | .TP |
| 791 | \fIpathName \fBcget\fR \fIoption\fR |
| 792 | Returns the current value of the configuration option given |
| 793 | by \fIoption\fR. |
| 794 | \fIOption\fR may have any of the values accepted by the \fBmenu\fR |
| 795 | command. |
| 796 | .VS |
| 797 | .TP |
| 798 | \fIpathName\fR \fBclone\fR \fInewPathname ?cloneType?\fR |
| 799 | Makes a clone of the current menu named \fInewPathName\fR. This clone |
| 800 | is a menu in its own right, but any changes to the clone are |
| 801 | propogated to the original menu and vice versa. \fIcloneType\fR can be |
| 802 | \fBnormal\fR, \fBmenubar\fR, or \fBtearoff\fR. Should not normally be |
| 803 | called outside of the Tk library. See the \fBCLONES\fR section for |
| 804 | more information. |
| 805 | .VE |
| 806 | .TP |
| 807 | \fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? |
| 808 | Query or modify the configuration options of the widget. |
| 809 | If no \fIoption\fR is specified, returns a list describing all of |
| 810 | the available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for |
| 811 | information on the format of this list). If \fIoption\fR is specified |
| 812 | with no \fIvalue\fR, then the command returns a list describing the |
| 813 | one named option (this list will be identical to the corresponding |
| 814 | sublist of the value returned if no \fIoption\fR is specified). If |
| 815 | one or more \fIoption\-value\fR pairs are specified, then the command |
| 816 | modifies the given widget option(s) to have the given value(s); in |
| 817 | this case the command returns an empty string. |
| 818 | \fIOption\fR may have any of the values accepted by the \fBmenu\fR |
| 819 | command. |
| 820 | .TP |
| 821 | \fIpathName \fBdelete \fIindex1\fR ?\fIindex2\fR? |
| 822 | Delete all of the menu entries between \fIindex1\fR and |
| 823 | \fIindex2\fR inclusive. |
| 824 | If \fIindex2\fR is omitted then it defaults to \fIindex1\fR. |
| 825 | Attempts to delete a tear-off menu entry are ignored (instead, you |
| 826 | should change the \fBtearOff\fR option to remove the tear-off entry). |
| 827 | .TP |
| 828 | \fIpathName \fBentrycget\fR \fIindex option\fR |
| 829 | Returns the current value of a configuration option for |
| 830 | the entry given by \fIindex\fR. |
| 831 | \fIOption\fR may have any of the values accepted by the \fBadd\fR |
| 832 | widget command. |
| 833 | .TP |
| 834 | \fIpathName \fBentryconfigure \fIindex \fR?\fIoptions\fR? |
| 835 | This command is similar to the \fBconfigure\fR command, except that |
| 836 | it applies to the options for an individual entry, whereas \fBconfigure\fR |
| 837 | applies to the options for the menu as a whole. |
| 838 | \fIOptions\fR may have any of the values accepted by the \fBadd\fR |
| 839 | widget command. If \fIoptions\fR are specified, options are modified |
| 840 | as indicated |
| 841 | in the command and the command returns an empty string. |
| 842 | If no \fIoptions\fR are specified, returns a list describing |
| 843 | the current options for entry \fIindex\fR (see \fBTk_ConfigureInfo\fR for |
| 844 | information on the format of this list). |
| 845 | .TP |
| 846 | \fIpathName \fBindex \fIindex\fR |
| 847 | Returns the numerical index corresponding to \fIindex\fR, or |
| 848 | \fBnone\fR if \fIindex\fR was specified as \fBnone\fR. |
| 849 | .TP |
| 850 | \fIpathName \fBinsert \fIindex\fR \fItype \fR?\fIoption value option value ...\fR? |
| 851 | Same as the \fBadd\fR widget command except that it inserts the new |
| 852 | entry just before the entry given by \fIindex\fR, instead of appending |
| 853 | to the end of the menu. The \fItype\fR, \fIoption\fR, and \fIvalue\fR |
| 854 | arguments have the same interpretation as for the \fBadd\fR widget |
| 855 | command. It is not possible to insert new menu entries before the |
| 856 | tear-off entry, if the menu has one. |
| 857 | .TP |
| 858 | \fIpathName \fBinvoke \fIindex\fR |
| 859 | Invoke the action of the menu entry. See the sections on the |
| 860 | individual entries above for details on what happens. If the |
| 861 | menu entry is disabled then nothing happens. If the |
| 862 | entry has a command associated with it then the result of that |
| 863 | command is returned as the result of the \fBinvoke\fR widget |
| 864 | command. Otherwise the result is an empty string. Note: invoking |
| 865 | a menu entry does not automatically unpost the menu; the default |
| 866 | bindings normally take care of this before invoking the \fBinvoke\fR |
| 867 | widget command. |
| 868 | .TP |
| 869 | \fIpathName \fBpost \fIx y\fR |
| 870 | Arrange for the menu to be displayed on the screen at the root-window |
| 871 | coordinates given by \fIx\fR and \fIy\fR. These coordinates are |
| 872 | adjusted if necessary to guarantee that the entire menu is visible on |
| 873 | the screen. This command normally returns an empty string. |
| 874 | If the \fBpostCommand\fR option has been specified, then its value is |
| 875 | executed as a Tcl script before posting the menu and the result of |
| 876 | that script is returned as the result of the \fBpost\fR widget |
| 877 | command. |
| 878 | If an error returns while executing the command, then the error is |
| 879 | returned without posting the menu. |
| 880 | .TP |
| 881 | \fIpathName \fBpostcascade \fIindex\fR |
| 882 | Posts the submenu associated with the cascade entry given by |
| 883 | \fIindex\fR, and unposts any previously posted submenu. |
| 884 | If \fIindex\fR doesn't correspond to a cascade entry, |
| 885 | or if \fIpathName\fR isn't posted, |
| 886 | the command has no effect except to unpost any currently posted |
| 887 | submenu. |
| 888 | .TP |
| 889 | \fIpathName \fBtype \fIindex\fR |
| 890 | Returns the type of the menu entry given by \fIindex\fR. |
| 891 | This is the \fItype\fR argument passed to the \fBadd\fR widget |
| 892 | command when the entry was created, such as \fBcommand\fR |
| 893 | or \fBseparator\fR, or \fBtearoff\fR for a tear-off entry. |
| 894 | .TP |
| 895 | \fIpathName \fBunpost\fR |
| 896 | .VS |
| 897 | Unmap the window so that it is no longer displayed. If a |
| 898 | lower-level cascaded menu is posted, unpost that menu. Returns an |
| 899 | empty string. This subcommand does not work on Windows and the |
| 900 | Macintosh, as those platforms have their own way of unposting menus. |
| 901 | .VE |
| 902 | .TP |
| 903 | \fIpathName \fByposition \fIindex\fR |
| 904 | Returns a decimal string giving the y-coordinate within the menu |
| 905 | window of the topmost pixel in the entry specified by \fIindex\fR. |
| 906 | |
| 907 | .SH "MENU CONFIGURATIONS" |
| 908 | .PP |
| 909 | The default bindings support four different ways of using menus: |
| 910 | .VS |
| 911 | .TP |
| 912 | \fBPulldown Menus in Menubar\fR |
| 913 | This is the most command case. You create a menu widget that will become the |
| 914 | menu bar. You then add cascade entries to this menu, specifying the |
| 915 | pull down menus you wish to use in your menu bar. You then create all |
| 916 | of the pulldowns. Once you have done this, specify the menu using the |
| 917 | \fB\-menu\fR option of the toplevel's widget command. See the |
| 918 | \fBtoplevel\fR manual entry for details. |
| 919 | .VE |
| 920 | .TP |
| 921 | \fBPulldown Menus in Menu Buttons\fR |
| 922 | This is the compatable way to do menu bars. You create one menubutton |
| 923 | widget for each top-level menu, and typically you arrange a series of |
| 924 | menubuttons in a row in a menubar window. You also create the top-level menus |
| 925 | and any cascaded submenus, and tie them together with \fB\-menu\fR |
| 926 | options in menubuttons and cascade menu entries. The top-level menu must |
| 927 | be a child of the menubutton, and each submenu must be a child of the |
| 928 | menu that refers to it. Once you have done this, the default bindings |
| 929 | will allow users to traverse and invoke the tree of menus via its |
| 930 | menubutton; see the \fBmenubutton\fR manual entry for details. |
| 931 | .TP |
| 932 | \fBPopup Menus\fR |
| 933 | Popup menus typically post in response to a mouse button press or |
| 934 | keystroke. You create the popup menus and any cascaded submenus, |
| 935 | then you call the \fBtk_popup\fR procedure at the appropriate time |
| 936 | to post the top-level menu. |
| 937 | .TP |
| 938 | \fBOption Menus\fR |
| 939 | An option menu consists of a menubutton with an associated menu |
| 940 | that allows you to select one of several values. The current value |
| 941 | is displayed in the menubutton and is also stored in a global |
| 942 | variable. Use the \fBtk_optionMenu\fR procedure to create option |
| 943 | menubuttons and their menus. |
| 944 | .TP |
| 945 | \fBTorn-off Menus\fR |
| 946 | You create a torn-off menu by invoking the tear-off entry at |
| 947 | the top of an existing menu. The default bindings will create a new menu |
| 948 | that is a copy of the original menu and leave it permanently |
| 949 | posted as a top-level window. The torn-off menu behaves just |
| 950 | the same as the original menu. |
| 951 | |
| 952 | .SH "DEFAULT BINDINGS" |
| 953 | .PP |
| 954 | Tk automatically creates class bindings for menus that give them |
| 955 | the following default behavior: |
| 956 | .IP [1] |
| 957 | When the mouse enters a menu, the entry underneath the mouse |
| 958 | cursor activates; as the mouse moves around the menu, the active |
| 959 | entry changes to track the mouse. |
| 960 | .IP [2] |
| 961 | When the mouse leaves a menu all of the entries in the menu |
| 962 | deactivate, except in the special case where the mouse moves from |
| 963 | a menu to a cascaded submenu. |
| 964 | .IP [3] |
| 965 | When a button is released over a menu, the active entry (if any) is invoked. |
| 966 | The menu also unposts unless it is a torn-off menu. |
| 967 | .IP [4] |
| 968 | The Space and Return keys invoke the active entry and |
| 969 | unpost the menu. |
| 970 | .IP [5] |
| 971 | If any of the entries in a menu have letters underlined with |
| 972 | the \fB\-underline\fR option, then pressing one of the underlined |
| 973 | letters (or its upper-case or lower-case equivalent) invokes that |
| 974 | entry and unposts the menu. |
| 975 | .IP [6] |
| 976 | The Escape key aborts a menu selection in progress without invoking any |
| 977 | entry. It also unposts the menu unless it is a torn-off menu. |
| 978 | .IP [7] |
| 979 | The Up and Down keys activate the next higher or lower entry |
| 980 | in the menu. When one end of the menu is reached, the active |
| 981 | entry wraps around to the other end. |
| 982 | .IP [8] |
| 983 | The Left key moves to the next menu to the left. |
| 984 | If the current menu is a cascaded submenu, then the submenu is |
| 985 | unposted and the current menu entry becomes the cascade entry |
| 986 | in the parent. |
| 987 | If the current menu is a top-level menu posted from a |
| 988 | menubutton, then the current menubutton is unposted and the |
| 989 | next menubutton to the left is posted. |
| 990 | Otherwise the key has no effect. |
| 991 | The left-right order of menubuttons is determined by their stacking |
| 992 | order: Tk assumes that the lowest menubutton (which by default |
| 993 | is the first one created) is on the left. |
| 994 | .IP [9] |
| 995 | The Right key moves to the next menu to the right. |
| 996 | If the current entry is a cascade entry, then the submenu is |
| 997 | posted and the current menu entry becomes the first entry |
| 998 | in the submenu. |
| 999 | Otherwise, if the current menu was posted from a |
| 1000 | menubutton, then the current menubutton is unposted and the |
| 1001 | next menubutton to the right is posted. |
| 1002 | .PP |
| 1003 | Disabled menu entries are non-responsive: they don't activate and |
| 1004 | they ignore mouse button presses and releases. |
| 1005 | .PP |
| 1006 | .VS 8.4 |
| 1007 | Several of the bindings make use of the command \fBtk_menuSetFocus\fR. |
| 1008 | It saves the current focus and sets the focus to its \fIpathName\fR |
| 1009 | argument, which is a menu widget. |
| 1010 | .VE |
| 1011 | .PP |
| 1012 | The behavior of menus can be changed by defining new bindings for |
| 1013 | individual widgets or by redefining the class bindings. |
| 1014 | |
| 1015 | .SH BUGS |
| 1016 | .PP |
| 1017 | At present it isn't possible to use the |
| 1018 | option database to specify values for the options to individual |
| 1019 | entries. |
| 1020 | |
| 1021 | .SH KEYWORDS |
| 1022 | menu, widget |