menu.n

linux系统下的音频通信

'\"
'\" Copyright (c) 1990-1994 The Regents of the University of California.
'\" Copyright (c) 1994-1997 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.61 97/10/31 12:58:40
'\" 
.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\fR \fIpathName \fR?\fIoptions\fR?
.SO
\-activebackground	\-background	\-disabledforeground	\-relief
\-activeborderwidth	\-borderwidth	\-font	\-takefocus
\-activeforeground	\-cursor	\-foreground
.SE
.SH "WIDGET-SPECIFIC OPTIONS"
.VS
.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. Note that in 8.0 on Macintosh
and Windows, all commands in a menu systems are executed before any
are posted. This is due to the limitations in the individual platforms'
menu managers.
.VE
.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.
.VS
.OP \-title title Title
The string will be used to title the window created when this menu is
torn off. If the title is NULL, then the window will have the title
of the menubutton or the text of the cascade item from which this menu
was invoked.
.OP \-type type Type
This option can be one of \fBmenubar\fR, \fBtearoff\fR, or
\fBnormal\fR, and is set when the menu is created. While the string
returned by the configuration database will change if this option is
changed, this does not affect the menu widget's behavior. This is used
by the cloning mechanism and is not normally set outside of the Tk
library.
.VE
.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
.VS
A menu is a widget that displays a collection of one-line entries arranged
in one or more columns.  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.
.VE
.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.
.VS
.PP
Whenever a menu's active entry is changed, a <<MenuSelect>> virtual
event is send to the menu. The active item can then be queried from
the menu, and an action can be taken, such as setting
context-sensitive help text for the entry.
.VE

.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 next to 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.
.VS
On Unix, 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.
On other platforms, the platform's native code takes care of unposting the
menu.
.VE
.PP
.VS
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. This is not
supported on Windows.
.VE

.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.

.VS
.SH "MENUBARS"
.PP
Any menu can be set as a menubar for a toplevel window (see
\fBtoplevel\fR command for syntax). On the Macintosh, whenever the
toplevel is in front, this menu's cascade items will appear in the
menubar across the top of the main monitor. On Windows and Unix, this
menu's items will be displayed in a menubar accross the top of the
window. These menus will behave according to the interface guidelines
of their platforms. For every menu set as a menubar, a clone menu is
made. See the \fBCLONES\fR section for more information.
.VE

.VS
.SH "SPECIAL MENUS IN MENUBARS"
.PP
Certain menus in a menubar will be treated specially.  On the Macintosh,
access to the special Apple and Help menus is provided. On Windows,
access to the Windows System menu in each window is provided. On X Windows,
a special right-justified help menu is provided. In all cases, these
menus must be created with the command name of the menubar menu concatenated
with the special name. So for a menubar named .menubar, on the Macintosh,
the special menus would be .menubar.apple and .menubar.help; on Windows,
the special menu would be .menubar.system; on X Windows, the help
menu would be .menubar.help.
.PP