OpenCores
URL https://opencores.org/ocsvn/or1k/or1k/trunk

Subversion Repositories or1k

[/] [or1k/] [trunk/] [insight/] [tk/] [doc/] [menu.n] - Blame information for rev 1765

Details | Compare with Previous | View Log

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

powered by: WebSVN 2.1.0

© copyright 1999-2024 OpenCores.org, equivalent to Oliscience, all rights reserved. OpenCores®, registered trademark.