624 lines
26 KiB
Plaintext
624 lines
26 KiB
Plaintext
'\"
|
|
'\" Copyright (c) 1990-1994 The Regents of the University of California.
|
|
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
|
|
'\"
|
|
'\" See the file "license.terms" for information on usage and redistribution
|
|
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
|
'\"
|
|
'\" SCCS: @(#) menu.n 1.48 96/08/27 13:21:20
|
|
'\"
|
|
.so man.macros
|
|
.TH menu n 4.1 Tk "Tk Built-In Commands"
|
|
.BS
|
|
'\" Note: do not modify the .SH NAME line immediately below!
|
|
.SH NAME
|
|
menu \- Create and manipulate menu widgets
|
|
.SH SYNOPSIS
|
|
\fBmenu\fI \fIpathName \fR?\fIoptions\fR?
|
|
.SO
|
|
\-activebackground \-background \-disabledforeground \-relief
|
|
\-activeborderwidth \-borderwidth \-font \-takefocus
|
|
\-activeforeground \-cursor \-foreground
|
|
.SE
|
|
.SH "WIDGET-SPECIFIC OPTIONS"
|
|
.OP \-postcommand postCommand Command
|
|
If this option is specified then it provides a Tcl command to execute
|
|
each time the menu is posted. The command is invoked by the \fBpost\fR
|
|
widget command before posting the menu.
|
|
.OP \-selectcolor selectColor Background
|
|
For menu entries that are check buttons or radio buttons, this option
|
|
specifies the color to display in the indicator when the check button
|
|
or radio button is selected.
|
|
.OP \-tearoff tearOff TearOff
|
|
This option must have a proper boolean value, which specifies
|
|
whether or not the menu should include a tear-off entry at the
|
|
top. If so, it will exist as entry 0 of the menu and the other
|
|
entries will number starting at 1. The default
|
|
menu bindings arrange for the menu to be torn off when the tear-off
|
|
entry is invoked.
|
|
.OP \-tearoffcommand tearOffCommand TearOffCommand
|
|
If this option has a non-empty value, then it specifies a Tcl command
|
|
to invoke whenever the menu is torn off. The actual command will
|
|
consist of the value of this option, followed by a space, followed
|
|
by the name of the menu window, followed by a space, followed by
|
|
the name of the name of the torn off menu window. For example, if
|
|
the option's is ``\fBa b\fR'' and menu \fB.x.y\fR is torn off to
|
|
create a new menu \fB.x.tearoff1\fR, then the command
|
|
``\fBa b .x.y .x.tearoff1\fR'' will be invoked.
|
|
.OP \-transient transient Transient
|
|
This option must have a boolean value. True means that the menu
|
|
is used on a transient basis, e.g. as a pop-up, pull-down, or
|
|
cascaded menu. False means that the menu will be displayed
|
|
on the screen continuously, for example as a torn-off menu.
|
|
If the option is true, no window manager border
|
|
will be displayed around the menu and redisplay will be optimized
|
|
using X's ``save under'' facility.
|
|
.BE
|
|
|
|
.SH INTRODUCTION
|
|
.PP
|
|
The \fBmenu\fR command creates a new top-level window (given
|
|
by the \fIpathName\fR argument) and makes it into a menu widget.
|
|
Additional
|
|
options, described above, may be specified on the command line
|
|
or in the option database
|
|
to configure aspects of the menu such as its colors and font.
|
|
The \fBmenu\fR command returns its
|
|
\fIpathName\fR argument. At the time this command is invoked,
|
|
there must not exist a window named \fIpathName\fR, but
|
|
\fIpathName\fR's parent must exist.
|
|
.PP
|
|
A menu is a widget that displays a collection of one-line entries arranged
|
|
in a column. There exist several different types of entries,
|
|
each with different properties. Entries of different types may be
|
|
combined in a single menu. Menu entries are not the same as
|
|
entry widgets. In fact, menu entries are not even distinct widgets;
|
|
the entire menu is one widget.
|
|
.PP
|
|
Menu entries are displayed with up to three separate fields.
|
|
The main field is a label in the form of a text string,
|
|
a bitmap, or an image, controlled by the \fB\-label\fR,
|
|
\fB\-bitmap\fR, and \fB\-image\fR options for the entry.
|
|
If the \fB\-accelerator\fR option is specified for an entry then a second
|
|
textual field is displayed to the right of the label. The accelerator
|
|
typically describes a keystroke sequence that may be typed in the
|
|
application to cause the same result as invoking the menu entry.
|
|
The third field is an \fIindicator\fR. The indicator is present only for
|
|
checkbutton or radiobutton entries. It indicates whether the entry
|
|
is selected or not, and is displayed to the left of the entry's
|
|
string.
|
|
.PP
|
|
In normal use, an entry becomes active (displays itself differently)
|
|
whenever the mouse pointer is over the entry. If a mouse
|
|
button is released over the entry then the entry is \fIinvoked\fR.
|
|
The effect of invocation is different for each type of entry;
|
|
these effects are described below in the sections on individual
|
|
entries.
|
|
.PP
|
|
Entries may be \fIdisabled\fR, which causes their labels
|
|
and accelerators to be displayed
|
|
with dimmer colors.
|
|
The default menu bindings will not allow
|
|
a disabled entry to be activated or invoked.
|
|
Disabled entries may be re-enabled, at which point it becomes
|
|
possible to activate and invoke them again.
|
|
|
|
.SH "COMMAND ENTRIES"
|
|
.PP
|
|
The most common kind of menu entry is a command entry, which
|
|
behaves much like a button widget. When a command entry is
|
|
invoked, a Tcl command is executed. The Tcl
|
|
command is specified with the \fB\-command\fR option.
|
|
|
|
.SH "SEPARATOR ENTRIES"
|
|
.PP
|
|
A separator is an entry that is displayed as a horizontal dividing
|
|
line. A separator may not be activated or invoked, and it has
|
|
no behavior other than its display appearance.
|
|
|
|
.SH "CHECKBUTTON ENTRIES"
|
|
.PP
|
|
A checkbutton menu entry behaves much like a checkbutton widget.
|
|
When it is invoked it toggles back and forth between the selected
|
|
and deselected states. When the entry is selected, a particular
|
|
value is stored in a particular global variable (as determined by
|
|
the \fB\-onvalue\fR and \fB\-variable\fR options for the entry); when
|
|
the entry is deselected another value (determined by the
|
|
\fB\-offvalue\fR option) is stored in the global variable.
|
|
An indicator box is displayed to the left of the label in a checkbutton
|
|
entry. If the entry is selected then the indicator's center is displayed
|
|
in the color given by the \fB-selectcolor\fR option for the entry;
|
|
otherwise the indicator's center is displayed in the background color for
|
|
the menu. If a \fB\-command\fR option is specified for a checkbutton
|
|
entry, then its value is evaluated as a Tcl command each time the entry
|
|
is invoked; this happens after toggling the entry's
|
|
selected state.
|
|
|
|
.SH "RADIOBUTTON ENTRIES"
|
|
.PP
|
|
A radiobutton menu entry behaves much like a radiobutton widget.
|
|
Radiobutton entries are organized in groups of which only one
|
|
entry may be selected at a time. Whenever a particular entry
|
|
becomes selected it stores a particular value into a particular
|
|
global variable (as determined by the \fB\-value\fR and
|
|
\fB\-variable\fR options for the entry). This action
|
|
causes any previously-selected entry in the same group
|
|
to deselect itself.
|
|
Once an entry has become selected, any change to the entry's
|
|
associated variable will cause the entry to deselect itself.
|
|
Grouping of radiobutton entries is determined by their
|
|
associated variables: if two entries have the same associated
|
|
variable then they are in the same group.
|
|
An indicator diamond is displayed to the left of the label in each
|
|
radiobutton entry. If the entry is selected then the indicator's
|
|
center is displayed in the color given by the \fB\-selectcolor\fR option
|
|
for the entry;
|
|
otherwise the indicator's center is displayed in the background color for
|
|
the menu. If a \fB\-command\fR option is specified for a radiobutton
|
|
entry, then its value is evaluated as a Tcl command each time the entry
|
|
is invoked; this happens after selecting the entry.
|
|
|
|
.SH "CASCADE ENTRIES"
|
|
.PP
|
|
A cascade entry is one with an associated menu (determined
|
|
by the \fB\-menu\fR option). Cascade entries allow the construction
|
|
of cascading menus.
|
|
The \fBpostcascade\fR widget command can be used to post and unpost
|
|
the associated menu just to the right of the cascade entry.
|
|
The associated menu must be a child of the menu containing
|
|
the cascade entry (this is needed in order for menu traversal to
|
|
work correctly).
|
|
.PP
|
|
A cascade entry posts its associated menu by invoking a
|
|
Tcl command of the form
|
|
.CS
|
|
\fImenu\fB post \fIx y\fR
|
|
.CE
|
|
where \fImenu\fR is the path name of the associated menu, and \fIx\fR
|
|
and \fIy\fR are the root-window coordinates of the upper-right
|
|
corner of the cascade entry.
|
|
The lower-level menu is unposted by executing a Tcl command with
|
|
the form
|
|
.CS
|
|
\fImenu\fB unpost\fR
|
|
.CE
|
|
where \fImenu\fR is the name of the associated menu.
|
|
.PP
|
|
If a \fB\-command\fR option is specified for a cascade entry then it is
|
|
evaluated as a Tcl command whenever the entry is invoked.
|
|
|
|
.SH "TEAR-OFF ENTRIES"
|
|
.PP
|
|
A tear-off entry appears at the top of the menu if enabled with the
|
|
\fBtearOff\fR option. It is not like other menu entries in that
|
|
it cannot be created with the \fBadd\fR widget command and
|
|
cannot be deleted with the \fBdelete\fR widget command.
|
|
When a tear-off entry is created it appears as a dashed line at
|
|
the top of the menu. Under the default bindings, invoking the
|
|
tear-off entry causes a torn-off copy to be made of the menu and
|
|
all of its submenus.
|
|
|
|
.SH "WIDGET COMMAND"
|
|
.PP
|
|
The \fBmenu\fR command creates a new Tcl command whose
|
|
name is \fIpathName\fR. This
|
|
command may be used to invoke various
|
|
operations on the widget. It has the following general form:
|
|
.CS
|
|
\fIpathName option \fR?\fIarg arg ...\fR?
|
|
.CE
|
|
\fIOption\fR and the \fIarg\fRs
|
|
determine the exact behavior of the command.
|
|
.PP
|
|
Many of the widget commands for a menu take as one argument an
|
|
indicator of which entry of the menu to operate on. These
|
|
indicators are called \fIindex\fRes and may be specified in
|
|
any of the following forms:
|
|
.TP 12
|
|
\fInumber\fR
|
|
Specifies the entry numerically, where 0 corresponds
|
|
to the top-most entry of the menu, 1 to the entry below it, and
|
|
so on.
|
|
.TP 12
|
|
\fBactive\fR
|
|
Indicates the entry that is currently active. If no entry is
|
|
active then this form is equivalent to \fBnone\fR. This form may
|
|
not be abbreviated.
|
|
.TP 12
|
|
\fBend\fR
|
|
Indicates the bottommost entry in the menu. If there are no
|
|
entries in the menu then this form is equivalent to \fBnone\fR.
|
|
This form may not be abbreviated.
|
|
.TP 12
|
|
\fBlast\fR
|
|
Same as \fBend\fR.
|
|
.TP 12
|
|
\fBnone\fR
|
|
Indicates ``no entry at all''; this is used most commonly with
|
|
the \fBactivate\fR option to deactivate all the entries in the
|
|
menu. In most cases the specification of \fBnone\fR causes
|
|
nothing to happen in the widget command.
|
|
This form may not be abbreviated.
|
|
.TP 12
|
|
\fB@\fInumber\fR
|
|
In this form, \fInumber\fR is treated as a y-coordinate in the
|
|
menu's window; the entry closest to that y-coordinate is used.
|
|
For example, ``\fB@0\fR'' indicates the top-most entry in the
|
|
window.
|
|
.TP 12
|
|
\fIpattern\fR
|
|
If the index doesn't satisfy one of the above forms then this
|
|
form is used. \fIPattern\fR is pattern-matched against the label of
|
|
each entry in the menu, in order from the top down, until a
|
|
matching entry is found. The rules of \fBTcl_StringMatch\fR
|
|
are used.
|
|
.PP
|
|
The following widget commands are possible for menu widgets:
|
|
.TP
|
|
\fIpathName \fBactivate \fIindex\fR
|
|
Change the state of the entry indicated by \fIindex\fR to \fBactive\fR
|
|
and redisplay it using its active colors.
|
|
Any previously-active entry is deactivated. If \fIindex\fR
|
|
is specified as \fBnone\fR, or if the specified entry is
|
|
disabled, then the menu ends up with no active entry.
|
|
Returns an empty string.
|
|
.TP
|
|
\fIpathName \fBadd \fItype \fR?\fIoption value option value ...\fR?
|
|
Add a new entry to the bottom of the menu. The new entry's type
|
|
is given by \fItype\fR and must be one of \fBcascade\fR,
|
|
\fBcheckbutton\fR, \fBcommand\fR, \fBradiobutton\fR, or \fBseparator\fR,
|
|
or a unique abbreviation of one of the above. If additional arguments
|
|
are present, they specify any of the following options:
|
|
.RS
|
|
.TP
|
|
\fB\-activebackground \fIvalue\fR
|
|
Specifies a background color to use for displaying this entry when it
|
|
is active.
|
|
If this option is specified as an empty string (the default), then the
|
|
\fBactiveBackground\fR option for the overall menu is used.
|
|
If the \fBtk_strictMotif\fR variable has been set to request strict
|
|
Motif compliance, then this option is ignored and the \fB\-background\fR
|
|
option is used in its place.
|
|
This option is not available for separator or tear-off entries.
|
|
.TP
|
|
\fB\-activeforeground \fIvalue\fR
|
|
Specifies a foreground color to use for displaying this entry when it
|
|
is active.
|
|
If this option is specified as an empty string (the default), then the
|
|
\fBactiveForeground\fR option for the overall menu is used.
|
|
This option is not available for separator or tear-off entries.
|
|
.TP
|
|
\fB\-accelerator \fIvalue\fR
|
|
Specifies a string to display at the right side of the menu entry.
|
|
Normally describes an accelerator keystroke sequence that may be
|
|
typed to invoke the same function as the menu entry. This option
|
|
is not available for separator or tear-off entries.
|
|
.TP
|
|
\fB\-background \fIvalue\fR
|
|
Specifies a background color to use for displaying this entry when it
|
|
is in the normal state (neither active nor disabled).
|
|
If this option is specified as an empty string (the default), then the
|
|
\fBbackground\fR option for the overall menu is used.
|
|
This option is not available for separator or tear-off entries.
|
|
.TP
|
|
\fB\-bitmap \fIvalue\fR
|
|
Specifies a bitmap to display in the menu instead of a textual
|
|
label, in any of the forms accepted by \fBTk_GetBitmap\fR.
|
|
This option overrides the \fB\-label\fR option but may be reset
|
|
to an empty string to enable a textual label to be displayed.
|
|
If a \fB\-image\fR option has been specified, it overrides
|
|
\fB\-bitmap\fR.
|
|
This option is not available for separator or tear-off entries.
|
|
.TP
|
|
\fB\-command \fIvalue\fR
|
|
Specifies a Tcl command to execute when the menu entry is invoked.
|
|
Not available for separator or tear-off entries.
|
|
.TP
|
|
\fB\-font \fIvalue\fR
|
|
Specifies the font to use when drawing the label or accelerator
|
|
string in this entry.
|
|
If this option is specified as an empty string (the default) then
|
|
the \fBfont\fR option for the overall menu is used.
|
|
This option is not available for separator or tear-off entries.
|
|
.TP
|
|
\fB\-foreground \fIvalue\fR
|
|
Specifies a foreground color to use for displaying this entry when it
|
|
is in the normal state (neither active nor disabled).
|
|
If this option is specified as an empty string (the default), then the
|
|
\fBforeground\fR option for the overall menu is used.
|
|
This option is not available for separator or tear-off entries.
|
|
.TP
|
|
\fB\-image \fIvalue\fR
|
|
Specifies an image to display in the menu instead of a text string
|
|
or bitmap
|
|
The image must have been created by some previous invocation of
|
|
\fBimage create\fR.
|
|
This option overrides the \fB\-label\fR and \fB\-bitmap\fR options
|
|
but may be reset to an empty string to enable a textual or
|
|
bitmap label to be displayed.
|
|
This option is not available for separator or tear-off entries.
|
|
.TP
|
|
\fB\-indicatoron \fIvalue\fR
|
|
Available only for checkbutton and radiobutton entries.
|
|
\fIValue\fR is a boolean that determines whether or not the
|
|
indicator should be displayed.
|
|
.TP
|
|
\fB\-label \fIvalue\fR
|
|
Specifies a string to display as an identifying label in the menu
|
|
entry. Not available for separator or tear-off entries.
|
|
.TP
|
|
\fB\-menu \fIvalue\fR
|
|
Available only for cascade entries. Specifies the path name of
|
|
the submenu associated with this entry.
|
|
The submenu must be a child of the menu.
|
|
.TP
|
|
\fB\-offvalue \fIvalue\fR
|
|
Available only for checkbutton entries. Specifies the value to
|
|
store in the entry's associated variable when the entry is
|
|
deselected.
|
|
.TP
|
|
\fB\-onvalue \fIvalue\fR
|
|
Available only for checkbutton entries. Specifies the value to
|
|
store in the entry's associated variable when the entry is selected.
|
|
.TP
|
|
\fB\-selectcolor \fIvalue\fR
|
|
Available only for checkbutton and radiobutton entries.
|
|
Specifies the color to display in the indicator when the entry is
|
|
selected.
|
|
If the value is an empty string (the default) then the \fBselectColor\fR
|
|
option for the menu determines the indicator color.
|
|
.TP
|
|
\fB\-selectimage \fIvalue\fR
|
|
Available only for checkbutton and radiobutton entries.
|
|
Specifies an image to display in the entry (in place of
|
|
the \fB\-image\fR option) when it is selected.
|
|
\fIValue\fR is the name of an image, which must have been created
|
|
by some previous invocation of \fBimage create\fR.
|
|
This option is ignored unless the \fB\-image\fR option has
|
|
been specified.
|
|
.TP
|
|
\fB\-state \fIvalue\fR
|
|
Specifies one of three states for the entry: \fBnormal\fR, \fBactive\fR,
|
|
or \fBdisabled\fR. In normal state the entry is displayed using the
|
|
\fBforeground\fR option for the menu and the \fBbackground\fR
|
|
option from the entry or the menu.
|
|
The active state is typically used when the pointer is over the entry.
|
|
In active state the entry is displayed using the \fBactiveForeground\fR
|
|
option for the menu along with the \fBactivebackground\fR option from
|
|
the entry. Disabled state means that the entry
|
|
should be insensitive: the default bindings will refuse to activate
|
|
or invoke the entry.
|
|
In this state the entry is displayed according to the
|
|
\fBdisabledForeground\fR option for the menu and the
|
|
\fBbackground\fR option from the entry.
|
|
This option is not available for separator entries.
|
|
.TP
|
|
\fB\-underline \fIvalue\fR
|
|
Specifies the integer index of a character to underline in the entry.
|
|
This option is also queried by the default bindings and used to
|
|
implement keyboard traversal.
|
|
0 corresponds to the first character of the text displayed in the entry,
|
|
1 to the next character, and so on.
|
|
If a bitmap or image is displayed in the entry then this option is ignored.
|
|
This option is not available for separator or tear-off entries.
|
|
.TP
|
|
\fB\-value \fIvalue\fR
|
|
Available only for radiobutton entries. Specifies the value to
|
|
store in the entry's associated variable when the entry is selected.
|
|
If an empty string is specified, then the \fB\-label\fR option
|
|
for the entry as the value to store in the variable.
|
|
.TP
|
|
\fB\-variable \fIvalue\fR
|
|
Available only for checkbutton and radiobutton entries. Specifies
|
|
the name of a global value to set when the entry is selected.
|
|
For checkbutton entries the variable is also set when the entry
|
|
is deselected. For radiobutton entries, changing the variable
|
|
causes the currently-selected entry to deselect itself.
|
|
.LP
|
|
The \fBadd\fR widget command returns an empty string.
|
|
.RE
|
|
.TP
|
|
\fIpathName \fBcget\fR \fIoption\fR
|
|
Returns the current value of the configuration option given
|
|
by \fIoption\fR.
|
|
\fIOption\fR may have any of the values accepted by the \fBmenu\fR
|
|
command.
|
|
.TP
|
|
\fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR?
|
|
Query or modify the configuration options of the widget.
|
|
If no \fIoption\fR is specified, returns a list describing all of
|
|
the available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for
|
|
information on the format of this list). If \fIoption\fR is specified
|
|
with no \fIvalue\fR, then the command returns a list describing the
|
|
one named option (this list will be identical to the corresponding
|
|
sublist of the value returned if no \fIoption\fR is specified). If
|
|
one or more \fIoption\-value\fR pairs are specified, then the command
|
|
modifies the given widget option(s) to have the given value(s); in
|
|
this case the command returns an empty string.
|
|
\fIOption\fR may have any of the values accepted by the \fBmenu\fR
|
|
command.
|
|
.TP
|
|
\fIpathName \fBdelete \fIindex1\fR ?\fIindex2\fR?
|
|
Delete all of the menu entries between \fIindex1\fR and
|
|
\fIindex2\fR inclusive.
|
|
If \fIindex2\fR is omitted then it defaults to \fIindex1\fR.
|
|
Attempts to delete a tear-off menu entry are ignored (instead, you
|
|
should change the \fBtearOff\fR option to remove the tear-off entry).
|
|
.TP
|
|
\fIpathName \fBentrycget\fR \fIindex option\fR
|
|
Returns the current value of a configuration option for
|
|
the entry given by \fIindex\fR.
|
|
\fIOption\fR may have any of the values accepted by the \fBadd\fR
|
|
widget command.
|
|
.TP
|
|
\fIpathName \fBentryconfigure \fIindex \fR?\fIoptions\fR?
|
|
This command is similar to the \fBconfigure\fR command, except that
|
|
it applies to the options for an individual entry, whereas \fBconfigure\fR
|
|
applies to the options for the menu as a whole.
|
|
\fIOptions\fR may have any of the values accepted by the \fBadd\fR
|
|
widget command. If \fIoptions\fR are specified, options are modified
|
|
as indicated
|
|
in the command and the command returns an empty string.
|
|
If no \fIoptions\fR are specified, returns a list describing
|
|
the current options for entry \fIindex\fR (see \fBTk_ConfigureInfo\fR for
|
|
information on the format of this list).
|
|
.TP
|
|
\fIpathName \fBindex \fIindex\fR
|
|
Returns the numerical index corresponding to \fIindex\fR, or
|
|
\fBnone\fR if \fIindex\fR was specified as \fBnone\fR.
|
|
.TP
|
|
\fIpathName \fBinsert \fIindex\fR \fItype \fR?\fIoption value option value ...\fR?
|
|
Same as the \fBadd\fR widget command except that it inserts the new
|
|
entry just before the entry given by \fIindex\fR, instead of appending
|
|
to the end of the menu. The \fItype\fR, \fIoption\fR, and \fIvalue\fR
|
|
arguments have the same interpretation as for the \fBadd\fR widget
|
|
command. It is not possible to insert new menu entries before the
|
|
tear-off entry, if the menu has one.
|
|
.TP
|
|
\fIpathName \fBinvoke \fIindex\fR
|
|
Invoke the action of the menu entry. See the sections on the
|
|
individual entries above for details on what happens. If the
|
|
menu entry is disabled then nothing happens. If the
|
|
entry has a command associated with it then the result of that
|
|
command is returned as the result of the \fBinvoke\fR widget
|
|
command. Otherwise the result is an empty string. Note: invoking
|
|
a menu entry does not automatically unpost the menu; the default
|
|
bindings normally take care of this before invoking the \fBinvoke\fR
|
|
widget command.
|
|
.TP
|
|
\fIpathName \fBpost \fIx y\fR
|
|
Arrange for the menu to be displayed on the screen at the root-window
|
|
coordinates given by \fIx\fR and \fIy\fR. These coordinates are
|
|
adjusted if necessary to guarantee that the entire menu is visible on
|
|
the screen. This command normally returns an empty string.
|
|
If the \fBpostCommand\fR option has been specified, then its value is
|
|
executed as a Tcl script before posting the menu and the result of
|
|
that script is returned as the result of the \fBpost\fR widget
|
|
command.
|
|
If an error returns while executing the command, then the error is
|
|
returned without posting the menu.
|
|
.TP
|
|
\fIpathName \fBpostcascade \fIindex\fR
|
|
Posts the submenu associated with the cascade entry given by
|
|
\fIindex\fR, and unposts any previously posted submenu.
|
|
If \fIindex\fR doesn't correspond to a cascade entry,
|
|
or if \fIpathName\fR isn't posted,
|
|
the command has no effect except to unpost any currently posted
|
|
submenu.
|
|
.TP
|
|
\fIpathName \fBtype \fIindex\fR
|
|
Returns the type of the menu entry given by \fIindex\fR.
|
|
This is the \fItype\fR argument passed to the \fBadd\fR widget
|
|
command when the entry was created, such as \fBcommand\fR
|
|
or \fBseparator\fR, or \fBtearoff\fR for a tear-off entry.
|
|
.TP
|
|
\fIpathName \fBunpost\fR
|
|
Unmap the window so that it is no longer displayed. If a
|
|
lower-level cascaded menu is posted, unpost that menu. Returns an
|
|
empty string.
|
|
.TP
|
|
\fIpathName \fByposition \fIindex\fR
|
|
Returns a decimal string giving the y-coordinate within the menu
|
|
window of the topmost pixel in the entry specified by \fIindex\fR.
|
|
|
|
.SH "MENU CONFIGURATIONS"
|
|
.PP
|
|
The default bindings support four different ways of using menus:
|
|
.TP
|
|
\fBPulldown Menus\fR
|
|
This is the most common case. You create one menubutton widget for
|
|
each top-level menu, and typically you arrange a series of menubuttons
|
|
in a row in a menubar window. You also create the top-level menus
|
|
and any cascaded submenus, and tie them together with \fB\-menu\fR
|
|
options in menubuttons and cascade menu entries. The top-level menu must
|
|
be a child of the menubutton, and each submenu must be a child of the
|
|
menu that refers to it. Once you have done this, the default bindings
|
|
will allow users to traverse and invoke the tree of menus via its
|
|
menubutton; see the \fBmenubutton\fR manual entry for details.
|
|
.TP
|
|
\fBPopup Menus\fR
|
|
Popup menus typically post in response to a mouse button press or
|
|
keystroke. You create the popup menus and any cascaded submenus,
|
|
then you call the \fBtk_popup\fR procedure at the appropriate time
|
|
to post the top-level menu.
|
|
.TP
|
|
\fBOption Menus\fR
|
|
An option menu consists of a menubutton with an associated menu
|
|
that allows you to select one of several values. The current value
|
|
is displayed in the menubutton and is also stored in a global
|
|
variable. Use the \fBtk_optionMenu\fR procedure to create option
|
|
menubuttons and their menus.
|
|
.TP
|
|
\fBTorn-off Menus\fR
|
|
You create a torn-off menu by invoking the tear-off entry at
|
|
the top of an existing menu. The default bindings will create a new menu
|
|
that is a copy of the original menu and leave it permanently
|
|
posted as a top-level window. The torn-off menu behaves just
|
|
the same as the original menu.
|
|
|
|
.SH "DEFAULT BINDINGS"
|
|
.PP
|
|
Tk automatically creates class bindings for menus that give them
|
|
the following default behavior:
|
|
.IP [1]
|
|
When the mouse enters a menu, the entry underneath the mouse
|
|
cursor activates; as the mouse moves around the menu, the active
|
|
entry changes to track the mouse.
|
|
.IP [2]
|
|
When the mouse leaves a menu all of the entries in the menu
|
|
deactivate, except in the special case where the mouse moves from
|
|
a menu to a cascaded submenu.
|
|
.IP [3]
|
|
When a button is released over a menu, the active entry (if any) is invoked.
|
|
The menu also unposts unless it is a torn-off menu.
|
|
.IP [4]
|
|
The Space and Return keys invoke the active entry and
|
|
unpost the menu.
|
|
.IP [5]
|
|
If any of the entries in a menu have letters underlined with
|
|
with \fB\-underline\fR option, then pressing one of the underlined
|
|
letters (or its upper-case or lower-case equivalent) invokes that
|
|
entry and unposts the menu.
|
|
.IP [6]
|
|
The Escape key aborts a menu selection in progress without invoking any
|
|
entry. It also unposts the menu unless it is a torn-off menu.
|
|
.IP [7]
|
|
The Up and Down keys activate the next higher or lower entry
|
|
in the menu. When one end of the menu is reached, the active
|
|
entry wraps around to the other end.
|
|
.IP [8]
|
|
The Left key moves to the next menu to the left.
|
|
If the current menu is a cascaded submenu, then the submenu is
|
|
unposted and the current menu entry becomes the cascade entry
|
|
in the parent.
|
|
If the current menu is a top-level menu posted from a
|
|
menubutton, then the current menubutton is unposted and the
|
|
next menubutton to the left is posted.
|
|
Otherwise the key has no effect.
|
|
The left-right order of menubuttons is determined by their stacking
|
|
order: Tk assumes that the lowest menubutton (which by default
|
|
is the first one created) is on the left.
|
|
.IP [9]
|
|
The Right key moves to the next menu to the right.
|
|
If the current entry is a cascade entry, then the submenu is
|
|
posted and the current menu entry becomes the first entry
|
|
in the submenu.
|
|
Otherwise, if the current menu was posted from a
|
|
menubutton, then the current menubutton is unposted and the
|
|
next menubutton to the right is posted.
|
|
.PP
|
|
Disabled menu entries are non-responsive: they don't activate and
|
|
they ignore mouse button presses and releases.
|
|
.PP
|
|
The behavior of menus can be changed by defining new bindings for
|
|
individual widgets or by redefining the class bindings.
|
|
|
|
.SH BUGS
|
|
.PP
|
|
At present it isn't possible to use the
|
|
option database to specify values for the options to individual
|
|
entries.
|
|
|
|
.SH KEYWORDS
|
|
menu, widget
|