|
|
Эта страница руководства для версии 10.9 Mac OS XЕсли Вы выполняете различную версию Mac OS X, просматриваете документацию локально:
Читать страницы руководстваСтраницы руководства предназначаются как справочник для людей, уже понимающих технологию.
|
menubar(n) Create and manipulate menubars menubar(n)
____________________________________________________________________________________________________________
NAME
menubar - Creates an instance of the menubar Class.
SYNOPSIS
package require Tcl 8.6
package require Tk 8.6
package require menubar ?0.5?
menubar new ?options?
mBarInst define body
mBarInst install pathName body
mBarInst menu.configure option tag-settings ?option tag-settings ...?
mBarInst menu.namespace tag namespace
mBarInst menu.hide tag
mBarInst menu.show tag
mBarInst tag.add tag value
mBarInst tag.configure pathName tag ?option value ...option value?
mBarInst tag.cget pathName tag ?option?
mBarInst group.add tag label ?cmd? ?accel? ?sequence? ?state?
mBarInst group.delete tag label
mBarInst group.move direction tag label
mBarInst group.configure tag label ?option value ...option value?
mBarInst group.serialize tag
mBarInst group.deserialize tag stream
mBarInst notebook.addTabStore pathname
mBarInst notebook.deleteTabStore pathname
mBarInst notebook.setTabValue pathname tag
mBarInst notebook.restoreTabValues pathname
____________________________________________________________________________________________________________
DESCRIPTION
menubar new ?options?
Create and return a new instance of the menubar class. The menubar class encapsulates the definition,
installation and dynamic behavior of a menubar. The class doesn't depend on a widget framework and
therefore can be used with or without a framework (e.g. Bwidget, IWidget, Snit, etc.). Unlike other
Tk widget commands, the menubar command doesn't have a pathName argument because menubars are handled
by the window manager (i.e. wm) and not the application.
OPTIONS
The following options can be passed to the menubar new command.
These options are inherited from the Tk menu command, their effect is platform specific.
-activebackground [http://docs.activestate.com/activetcl/8.5/tcl/TkCmd/options.htm#M-activeback-
земля]
-activeborderwidth [http://docs.activestate.com/activetcl/8.5/tcl/TkCmd/options.htm#M-activeborder-
width]
-activeforeground [http://docs.activestate.com/activetcl/8.5/tcl/TkCmd/options.htm#M-activefore-
земля]
-background [http://docs.activestate.com/activetcl/8.5/tcl/TkCmd/options.htm#M-background]
-borderwidth [http://docs.activestate.com/activetcl/8.5/tcl/TkCmd/options.htm#M-borderwidth]
-cursor [http://docs.activestate.com/activetcl/8.5/tcl/TkCmd/options.htm#M-cursor]
-disabledforeground [http://docs.activestate.com/activetcl/8.5/tcl/TkCmd/options.htm#M-disabledfore-
земля]
-font [http://docs.activestate.com/activetcl/8.5/tcl/TkCmd/options.htm#M-font]
-foreground [http://docs.activestate.com/activetcl/8.5/tcl/TkCmd/options.htm#M-foreground]
-relief [http://docs.activestate.com/activetcl/8.5/tcl/TkCmd/options.htm#M-relief]
INTRODUCTION
An instance of the menubar class provides methods for compiling a description of the menubar, config-uring configuring
uring menu items and installing the menubar in toplevel windows.
A menubar can be thought of as a tree of cascading menus. Users define a menubar using a language
that results in a human readable description of a menubar. The description of the menubar is then
compiled by an instance of the menubar class after which it can be installed in one or more toplevel
windows.
The menubar class provides many unique capabilities that are not found in other tcl/tk menubar imple-mentation. implementation.
mentation. Some of these are:
• A tagging system that simplifies access to menu entries in the menu tree.
• Support for user defined tags that depend on the toplevel window context.
• A simplified and uniform interface for all callback commands.
• Namespace support for all callback commands so callback commands can be easily grouped into
namespaces.
• Support for hiding and exposing menus on the menubar.
• A simplified method for creating radiobutton groups.
• Automatic management of state variables for checkbuttons and radiobuttons.
• Scope control for the state variables of checkbuttons and radiobuttons.
• Tear-off menu management that ensures only one tearoff menu is created.
• Support for dynamic menu extension to simplify the creation of recent document menus.
• Support for saving and restoring dynamic menu extensions.
TERMINOLOGY
MENUBAR
The visible rendering of a menubar in a toplevel window is a horizontally group of cascading
Tk menus.
MENU A menu is an ordered list of items that is rendered vertically. Menus are not visible until a
user preforms some action (normally a <ButtonPress-1> event). A menu may contain any number of
child menus that are rendered as cascading menus. Cascading menus are rendered next to the
parent menu when they are activated.
MENU ENTRY
A menu contains an ordered list of items called entries. Menu entries have a type and the
menubar class supports the following 6 entry types: Command, Checkbutton, Radiobutton, Separa-tor, Separator,
tor, Group and Menu.
ENTRY LABEL
Each menu entry has a visible string that is called the entry label.
TAG A tag is name that is normally used to referr to an item in a menu tree. A tag name is an
alphanumeric character string that may include the underscore character. Menu tree tags are
defined for all nodes and leafs in a menu tree. This provides a flat abstraction of the tree
and simplifies item referencing in menubar methods. Without this abstraction it would be nec-essary necessary
essary to reference menu elements using a tree path which could change at run-time. The
menubar class also has a method that can create a user defined tag. User defined tags store
values that change based on the currently active toplevel window. User defined tags can be
used to store widget pathnames use by callback code so that output can be routed to the appro-priate appropriate
priate toplevel window.
METHODS
mBarInst define body
Compiles body into a tree of menu entries which define the visual layout of the menubar. The
body argument describes the layout using the following syntax, where the elements of the syn-tax syntax
tax are described below.
body == definitions
definitions ::= { <ignore> | <definition> | <definition> <definitions> }
ignore ::= { <nl> | <white-space> <nl> | # <comment> <nl> }
definition ::= { <command> | <checkbutton> | <radiobutton> | <separator> | <group> | <menu> }
command ::= <label> C <tag> <nl>
checkbutton ::= <label> X<scope> { <tag> | <tag>+ } <nl>
radiobutton ::= <label> R<scope> { <tag> | <tag>+ } <nl>
separator ::= <stext> S <tag> <nl>
group ::= <dummy> G <tag> <nl>
menu ::= <label> { M:<tag> | M:<tag>+ } <nl> <definitions>
stext ::= '--' | <label>
scope ::= '' | '@' | '='
C - Command
The C type entry is the most common type of entry. This entry executes a command when
it is invoked.
X - Checkbutton
A X type entry behaves much like a Tk checkbutton widget. When it is invoked it toggles
back and forth between a selected and deselected states. The value of a checkbutton is
a boolean (i.e. 1 or 0). By default all checkbuttons are deselected. If you want the
checkbutton to be initially selected then include a trailing plus (+) with the tag
name. See SCOPE CONTROL below for a description of the scope indicator.
R - Radiobutton
A R type menu entry behaves much like a Tk radiobutton widget. Each radiobutton entry
is a member of a radiobutton group that controls the behavior of the radiobuttons in
the group. All radiobuttons in a group are given the same tag name. In the example
below Red, Green and Blue all have the same tag and are therefore all in the same
radiobutton group. A trailing plus (+) on the tag name of a radiobutton entry will
cause the entry to be the initially selected entry. See SCOPE CONTROL below for a
description of the scope indicator.
S - Separator
A S type menu entry is an entry that is displayed either as a horizontal dividing line
or a label. Separators are not active elements of a menu and have no associated behav-ior behavior
ior if they are invoked. If <stext> is two dashes (i.e. '--') then the separator will
be displayed as a horizontal line otherwise <stext> will be displayed as a bold label
surrounded by double dashes (e.g. "-- <stext> --") with a lightgray background.
G - Command Group
The G type menu entry marks a location in the menu tree where entries can be dynami-cally dynamically
cally added and removed. Menu extension can only occur at the end of a menu so G type
entries must be the last item on a menu. A G type entry is rendered as a separator
line. The group.<xxx> sub-commands are used to manipulate command group entries.
M - Menu
An M type entry is used to define both menubar menus and cascading menus. Menu entries
are the most complicated of the 6 menu types. A menu entry is composed of three list
elements. The first element of the list is its label. The second element of the list is
a composite string consisting of a type identifier (M) followed by an optional tag
(beginning with a ':' separator) and finally an optional plus (+) which indicates that
the menu is a tear-off menu. The final element of the list is a LIST VALUE.
mBarInst install pathName body
The install method installs the menubar created with the define method into toplevel window
pathName. The body argument of the command contains a tcl script which is used to initialize
the installed menubar. Normally the tcl script will contain calls to various menubar methods
to perform the initialization. The initialization code is only run once when the menubar is
installed. The namespace in which the install method is executed becomes the default namespace
for callback commands (see menu.namespace below for more details).
METHODS - MENU.XXX
mBarInst menu.configure option tag-settings ?option tag-settings ...?
Configures the tags of a menubar and returns an empty string. This method provides a conve-nient convenient
nient way to configure a larger number of tags without the verbosity of using the tag.config-ure tag.configure
ure method.
option Option may have any of the values accepted by the tag.configure method.
tag-settings
The tag-settings argument is a string that is converted to a list of tag-value pairs
using the following syntax.
Syntax for tag-settings.
tag-settings ::= { <ignore> | <value> | <value> <tag-settings> }
ignore ::= { <nl> | <white-space> <nl> | # <comment> <nl> }
value ::= <tag> <option-value> <nl>
mBarInst menu.namespace tag namespace
Change the namespace for a sub-tree of the menubar starting at entry tag. The new value will
be namespace. Each entry in the menubar tree has an associated namespace which will be used
for its callback procedure. The default namespace is the namespace where the install method
was executed. The namespace method can be used to change the namespace that will be used for
callbacks in a sub-tree of the menubar. This method can only be used in the context of an
install script.
mBarInst menu.hide tag
Remove (hide) a menubar entry. When a menubar tree is defined all entries are visible by
default. This method can be used to hide a menubar entry. The hide methods can be used in
the context of an install script so that a menu will be initially hidden at application start
up. The tag argument is the tag name of the menu to be hidden.
mBarInst menu.show tag
Exposes (shows) a hidden menubar entry. When a menubar tree is defined all entries are visible
by default. If a entry is hidden from the user (using the menu.hide method) then it can be
exposed again using the show method. The tag argument is the tag name of the menu to be shown.
METHODS - TAG.XXX
mBarInst tag.add tag value
Add a user defined tag value. The tag.add method adds a new tag-value pair to the the tags
defined for a menubar. User defined tags are different from the tags created by the define
method. The tag.add method can only be used in an install script and its value is associated
with the toplevel where the menubar is installed. This makes the tag context sensitive so
callback code that queries the tag value will receive a value that is associated with the win-dow window
dow that performed the callback.
mBarInst tag.configure pathName tag ?option value ...option value?
Given the pathName of a toplevel window and a tag this method configures the menu entry asso-ciated associated
ciated with the tag and return an empty string.
Standard Options
These option are the same as those described for menu entries in the Tk menu documenta-tion. documentation.
tion.
-activebackground
-activeforeground
-background
-bitmap
-columnbreak
-compound
-font
-foreground
-hidemargin
-image
-indicatoron
-label
-selectcolor
-selectimage
-state
Class Specific Options
-bind {uline accel sequence}
The value of the -bind option is three element list where the values are as fol-lows. follows.
lows.
uline An integer index of a character to underline in the entry. This value
performs the same function as the Tk menu -underline option. If this
value is an empty string then no underlining is performed.
accel A string to display at the right side of the menu entry. The string nor-mally normally
mally describes an accelerator keystroke sequence that may be typed to
invoke the same function as the menu entry. This value performs the same
function as the Tk menu -accelerator option. If this value is an empty
string then no accelerator is displayed.
sequence
A bind sequence that will cause the entries associated command to fire.
-command cmdprefix
The value of the -command option a command prefix that is evaluated when the
menu entry is invoked. By default the callback is evaluate in the namespace
where the install method was executed. Additional values are appended to the
cmdprefix and are thus passed to the callback command as argument. These addi-tional additional
tional arguments are described in the list below.
command entry
1) The pathname of the toplevel window that invoked the callback.
checkbutton entry
1) The pathname of the toplevel window that invoked the callback.
2) The checkbutton's tag name
3) The new value for the checkbutton
radiobutton entry
1) The pathname of the toplevel window that invoked the callback.
2) The radiobutton's tag name
3) The label of the button that was selected
group entry
1) The pathname of the toplevel window that invoked the callback.
mBarInst tag.cget pathName tag ?option?
Returns the value of the configuration option given by option or the value of a user defined
tag. The option argument may be any of the options accepted by the tag.configure method for
the tag type. User defined tags are queried without an option value.
METHODS - GROUP.XXX
mBarInst group.add tag label ?cmd? ?accel? ?sequence? ?state?
Add a command to the group with tag name tag. This method appends a new command entry to the
end of a command group. The order of the arguments is fixed but arguments to the right can be
ignored. Arguments to this method have the following meaning.
tag (string)
The tag name of the command group.
label (string)
The displayed label for the menu entry.
cmd (string)
A command prefix that will be used for callback command.
accel (string)
An accelerator string that will be displayed next to the entry label.
sequence (string)
A bind sequence that will be bound to the callback command.
state (enum)
Sets the active state of the command. One of: normal, disabled, active
mBarInst group.delete tag label
Delete a command from a group with tag name tag. This method deletes command label from a com-mand command
mand group.
mBarInst group.move direction tag label
Change the position of an entry in a group with tag name tag. The direction argument is the
direction ('up' or 'down') the entry will be moved. The entry that is moved has the name
label.
mBarInst group.configure tag label ?option value ...option value?
Configure the options of an entry in the command group with tag name tag. This method is simi-lar similar
lar to the tag.configure method except that it works on entries in a command group. Set docu-mentation documentation
mentation for the tag.configure method (above) for more details on command entry options.
mBarInst group.serialize tag
Return a string serialization of the entries in a command group. The argument tag is the tag
name for the group that is to be serialized. The resulting serialization is a list containing
three element (1) the tag name of the group (2) a dictionary containing group level options
(3) a list of zero or more similar three element lists that describe the entries in the group.
mBarInst group.deserialize tag stream
Replace the contents of group tag tag with the commands defined in the serialization stream.
The original contents of the group are lost.
METHODS - NOTEBOOK.XXX
mBarInst notebook.addTabStore pathname
This method should be used in code that creates a new notebook tab. Execution of this method
will cause state storage to be allocated for the new notebook tab. The pathname for the note-book notebook
book tab is passed as an argument to the method.
mBarInst notebook.deleteTabStore pathname
This command deallocates the state store for a notebook tab. The pathname for the notebook tab
is passed as an argument to the method.
mBarInst notebook.setTabValue pathname tag
This method should be used in the callback for menubar checkbuttons or radiobuttons that have
notebook tab scope control. When this method is executed it will move the value associated
with tag into the tab store for the tab identified by pathname.
mBarInst notebook.restoreTabValues pathname
This method should be place in a bind script that is triggered by a notebooks <<Notebook-
TabChanged>> event.
SCOPE CONTROL
By default a menubar instance looks the same in all installed toplevel windows. As changes are made
to one instance of a menubar all the other instances are immediately updated. This means the internal
state of all the menu entries for the instances are synchronized. This behavior is called global
scope control of the menubar state.
The menubar class allows finer scope control on check and radio buttons. The scope of these entry
types can be modified by adding a modifier character to their type character. Two modifier characters
are supported as show in the table below.
When the local scope character (@) is added to the definition of a button, the button is given a new
variable for each installed toplevel window. This has the effect of making the button's state local
to the window (i.e. local scope). An example use case for this behavior might be a status bar that
can be toggled on an off by a checkbutton. The developer may want to allow the user to control the
visibility of the status bar on a per window basis. In this case a local modifier would be added to
the status bar selector so the callback code would receive an appropriate value based on the current
toplevel window.
The notebook tab scope character (=) is similar in effect to the local scope character but it allows
a notebook tab selection to also manage the state of of a button. Adding the notebook tab scope modi-fier modifier
fier enables notebook tab scope control but the developer must then make use of the notebook.xxxx
sub-commands to actively manage state values as tabs are added, deleted and selected.
EXAMPLE
package require Tcl
package require Tk
package require menubar
set tout [text .t -width 25 -height 12]
pack ${tout} -expand 1 -fill both
set mbar [menubar new \
-borderwidth 4 \
-relief groove \
-foreground black \
-background tan \
]
${mbar} define {
File M:file {
Exit C exit
}
Edit M:items+ {
# Label Type Tag Name(s)
# ----------------- ---- ---------"Cut" --------"Cut"
"Cut" C cut
"Copy" C copy
"Paste" C paste
-- S s2
"Options" M:opts {
"CheckList" M:chx+ {
Coffee X coffee+
Donut X donut
Eggs X eggs
}
"RadioButtons" M:btn+ {
"Red" R color
"Green" R color+
"Blue" R color
}
}
}
Help M:help {
About C about
}
}
${mbar} install . {
${mbar} tag.add tout ${tout}
${mbar} menu.configure -command {
# file menu
exit {Exit}
# Item menu
cut {CB Edit cut}
copy {CB Edit copy}
paste {CB Edit paste}
# boolean menu
coffee {CB CheckButton}
donut {CB CheckButton}
eggs {CB CheckButton}
# radio menu
color {CB RadioButton}
# Help menu
about {CB About}
} -bind {
exit {1 Cntl+Q Control-Key-q}
cut {2 Cntl+X Control-Key-x}
copy {0 Cntl+C Control-Key-c}
paste {0 Cntl+V Control-Key-v}
coffee {0 Cntl+A Control-Key-a}
donut {0 Cntl+B Control-Key-b}
eggs {0 Cntl+C Control-Key-c}
about 0
} -background {
exit red
} -foreground {
exit white
}
}
proc pout { txt } {
global mbar
set tout [${mbar} tag.cget . tout]
${tout} insert end "${txt}\n"
}
proc Exit { args } {
puts "Goodbye"
exit
}
proc CB { args } {
set alist [lassign ${args} cmd]
pout "${cmd}: [join ${alist} {, }]"
}
wm minsize . 300 300
wm geometry . +4+4
wm protocol . WM_DELETE_WINDOW exit
wm title . "Example"
wm focusmodel . active
pout "Example started ..."
CAVEATS
This implementation uses TclOO so it requires 8.6. The code has been tested on Windows (Vista), Linux
and OSX (10.4).
SEE ALSO
A command that creates menubar objects [http://wiki.tcl.tk/25231], menu
[http://www.tcl.tk/man/tcl8.6/TkCmd/menu.htm]
COPYRIGHT
Copyright (c) 2009 Tom Krehbiel <krehbiel.tom@gmail.com> All rights reserved.
menubar 0.5 menubar(n)
|
Сообщение о проблемах
Способ сообщить о проблеме с этой страницей руководства зависит от типа проблемы:
- Ошибки содержания
- Ошибки отчета в содержании этой документации со ссылками на отзыв ниже.
- Отчеты об ошибках
- Сообщите об ошибках в функциональности описанного инструмента или API через Генератор отчетов Ошибки.
- Форматирование проблем
- Отчет, форматирующий ошибки в интерактивной версии этих страниц со ссылками на отзыв ниже.