| '\" |
| '\" 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. |
| '\" |
| '\" RCS: @(#) $Id: menu.n,v 1.7 2001/11/13 00:00:24 hobbs Exp $ |
| '\" |
| '\" The definitions below are for supplemental macros used in Tcl/Tk |
| '\" manual entries. |
| '\" |
| '\" .AP type name in/out ?indent? |
| '\" Start paragraph describing an argument to a library procedure. |
| '\" type is type of argument (int, etc.), in/out is either "in", "out", |
| '\" or "in/out" to describe whether procedure reads or modifies arg, |
| '\" and indent is equivalent to second arg of .IP (shouldn't ever be |
| '\" needed; use .AS below instead) |
| '\" |
| '\" .AS ?type? ?name? |
| '\" Give maximum sizes of arguments for setting tab stops. Type and |
| '\" name are examples of largest possible arguments that will be passed |
| '\" to .AP later. If args are omitted, default tab stops are used. |
| '\" |
| '\" .BS |
| '\" Start box enclosure. From here until next .BE, everything will be |
| '\" enclosed in one large box. |
| '\" |
| '\" .BE |
| '\" End of box enclosure. |
| '\" |
| '\" .CS |
| '\" Begin code excerpt. |
| '\" |
| '\" .CE |
| '\" End code excerpt. |
| '\" |
| '\" .VS ?version? ?br? |
| '\" Begin vertical sidebar, for use in marking newly-changed parts |
| '\" of man pages. The first argument is ignored and used for recording |
| '\" the version when the .VS was added, so that the sidebars can be |
| '\" found and removed when they reach a certain age. If another argument |
| '\" is present, then a line break is forced before starting the sidebar. |
| '\" |
| '\" .VE |
| '\" End of vertical sidebar. |
| '\" |
| '\" .DS |
| '\" Begin an indented unfilled display. |
| '\" |
| '\" .DE |
| '\" End of indented unfilled display. |
| '\" |
| '\" .SO |
| '\" Start of list of standard options for a Tk widget. The |
| '\" options follow on successive lines, in four columns separated |
| '\" by tabs. |
| '\" |
| '\" .SE |
| '\" End of list of standard options for a Tk widget. |
| '\" |
| '\" .OP cmdName dbName dbClass |
| '\" Start of description of a specific option. cmdName gives the |
| '\" option's name as specified in the class command, dbName gives |
| '\" the option's name in the option database, and dbClass gives |
| '\" the option's class in the option database. |
| '\" |
| '\" .UL arg1 arg2 |
| '\" Print arg1 underlined, then print arg2 normally. |
| '\" |
| '\" RCS: @(#) $Id: man.macros,v 1.4 2000/08/25 06:18:32 ericm Exp $ |
| '\" |
| '\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. |
| .if t .wh -1.3i ^B |
| .nr ^l \n(.l |
| .ad b |
| '\" # Start an argument description |
| .de AP |
| .ie !"\\$4"" .TP \\$4 |
| .el \{\ |
| . ie !"\\$2"" .TP \\n()Cu |
| . el .TP 15 |
| .\} |
| .ta \\n()Au \\n()Bu |
| .ie !"\\$3"" \{\ |
| \&\\$1 \\fI\\$2\\fP (\\$3) |
| .\".b |
| .\} |
| .el \{\ |
| .br |
| .ie !"\\$2"" \{\ |
| \&\\$1 \\fI\\$2\\fP |
| .\} |
| .el \{\ |
| \&\\fI\\$1\\fP |
| .\} |
| .\} |
| .. |
| '\" # define tabbing values for .AP |
| .de AS |
| .nr )A 10n |
| .if !"\\$1"" .nr )A \\w'\\$1'u+3n |
| .nr )B \\n()Au+15n |
| .\" |
| .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n |
| .nr )C \\n()Bu+\\w'(in/out)'u+2n |
| .. |
| .AS Tcl_Interp Tcl_CreateInterp in/out |
| '\" # BS - start boxed text |
| '\" # ^y = starting y location |
| '\" # ^b = 1 |
| .de BS |
| .br |
| .mk ^y |
| .nr ^b 1u |
| .if n .nf |
| .if n .ti 0 |
| .if n \l'\\n(.lu\(ul' |
| .if n .fi |
| .. |
| '\" # BE - end boxed text (draw box now) |
| .de BE |
| .nf |
| .ti 0 |
| .mk ^t |
| .ie n \l'\\n(^lu\(ul' |
| .el \{\ |
| .\" Draw four-sided box normally, but don't draw top of |
| .\" box if the box started on an earlier page. |
| .ie !\\n(^b-1 \{\ |
| \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' |
| .\} |
| .el \}\ |
| \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' |
| .\} |
| .\} |
| .fi |
| .br |
| .nr ^b 0 |
| .. |
| '\" # VS - start vertical sidebar |
| '\" # ^Y = starting y location |
| '\" # ^v = 1 (for troff; for nroff this doesn't matter) |
| .de VS |
| .if !"\\$2"" .br |
| .mk ^Y |
| .ie n 'mc \s12\(br\s0 |
| .el .nr ^v 1u |
| .. |
| '\" # VE - end of vertical sidebar |
| .de VE |
| .ie n 'mc |
| .el \{\ |
| .ev 2 |
| .nf |
| .ti 0 |
| .mk ^t |
| \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' |
| .sp -1 |
| .fi |
| .ev |
| .\} |
| .nr ^v 0 |
| .. |
| '\" # Special macro to handle page bottom: finish off current |
| '\" # box/sidebar if in box/sidebar mode, then invoked standard |
| '\" # page bottom macro. |
| .de ^B |
| .ev 2 |
| 'ti 0 |
| 'nf |
| .mk ^t |
| .if \\n(^b \{\ |
| .\" Draw three-sided box if this is the box's first page, |
| .\" draw two sides but no top otherwise. |
| .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c |
| .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c |
| .\} |
| .if \\n(^v \{\ |
| .nr ^x \\n(^tu+1v-\\n(^Yu |
| \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c |
| .\} |
| .bp |
| 'fi |
| .ev |
| .if \\n(^b \{\ |
| .mk ^y |
| .nr ^b 2 |
| .\} |
| .if \\n(^v \{\ |
| .mk ^Y |
| .\} |
| .. |
| '\" # DS - begin display |
| .de DS |
| .RS |
| .nf |
| .sp |
| .. |
| '\" # DE - end display |
| .de DE |
| .fi |
| .RE |
| .sp |
| .. |
| '\" # SO - start of list of standard options |
| .de SO |
| .SH "STANDARD OPTIONS" |
| .LP |
| .nf |
| .ta 5.5c 11c |
| .ft B |
| .. |
| '\" # SE - end of list of standard options |
| .de SE |
| .fi |
| .ft R |
| .LP |
| See the \\fBoptions\\fR manual entry for details on the standard options. |
| .. |
| '\" # OP - start of full description for a single option |
| .de OP |
| .LP |
| .nf |
| .ta 4c |
| Command-Line Name: \\fB\\$1\\fR |
| Database Name: \\fB\\$2\\fR |
| Database Class: \\fB\\$3\\fR |
| .fi |
| .IP |
| .. |
| '\" # CS - begin code excerpt |
| .de CS |
| .RS |
| .nf |
| .ta .25i .5i .75i 1i |
| .. |
| '\" # CE - end code excerpt |
| .de CE |
| .fi |
| .RE |
| .. |
| .de UL |
| \\$1\l'|0\(ul'\\$2 |
| .. |
| .TH menu n 4.1 Tk "Tk Built-In Commands" |
| .BS |
| '\" Note: do not modify the .SH NAME line immediately below! |
| .SH NAME |
| menu, tk_menuSetFocus \- Create and manipulate menu widgets |
| .SH SYNOPSIS |
| .nf |
| \fBmenu\fR \fIpathName \fR?\fIoptions\fR? |
| \fBtk_menuSetFocus\fR \fIpathName\fR |
| .SO |
| \-activebackground \-borderwidth \-foreground |
| \-activeborderwidth \-cursor \-relief |
| \-activeforeground \-disabledforeground \-takefocus |
| \-background \-font |
| |
| .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. |
| .PP |
| As noted, menubars may behave differently on different platforms. One |
| example of this concerns the handling of checkbuttons and radiobuttons |
| within the menu. While it is permitted to put these menu elements on |
| menubars, they may not be drawn with indicators on some platforms, due |
| to system restrictions. |
| .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 |
| When Tk sees an Apple menu on the Macintosh, that menu's contents make |
| up the first items of the Apple menu on the screen whenever the window |
| containing the menubar is in front. The menu is the |
| first one that the user sees and has a title which is an Apple logo. |
| After all of the Tk-defined items, the menu will have a separator, |
| followed by all of the items in the user's Apple Menu Items folder. |
| Since the System uses a different menu definition procedure for |
| the Apple menu than Tk uses for its menus, and the system APIs do |
| not fully support everything Tk tries to do, the menu item will only |
| have its text displayed. No font attributes, images, bitmaps, or colors |
| will be displayed. In addition, a menu with a tearoff item will have |
| the tearoff item displayed as "(TearOff)". |
| .PP |
| When Tk see a Help menu on the Macintosh, the menu's contents are |
| appended to the standard help menu on the right of the user's menubar |
| whenever the user's menubar is in front. The first items in the menu |
| are provided by Apple. Similar to the Apple Menu, cusomization in this |
| menu is limited to what the system provides. |
| .PP |
| When Tk sees a System menu on Windows, its items are appended to the |
| system menu that the menubar is attached to. This menu has an icon |
| representing a spacebar, and can be invoked with the mouse or by typing |
| Alt+Spacebar. Due to limitations in the Windows API, any font changes, |
| colors, images, bitmaps, or tearoff images will not appear in the |
| system menu. |
| .PP |
| When Tk see a Help menu on X Windows, the menu is moved to be last in |
| the menubar and is right justified. |
| .VE |
| |
| .VS |
| .SH "CLONES" |
| .PP |
| When a menu is set as a menubar for a toplevel window, or when a menu |
| is torn off, a clone of the menu is made. This clone is a menu widget |
| in its own right, but it is a child of the original. Changes in the |
| configuration of the original are reflected in the |
| clone. Additionally, any cascades that are pointed to are also cloned |
| so that menu traversal will work right. Clones are destroyed when |
| either the tearoff or menubar goes away, or when the original menu is |
| destroyed. |
| .VE |
| |
| .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. |
| .VS |
| .TP |
| \fB\-columnbreak \fIvalue\fR |
| When this option is zero, the appears below the previous entry. When |
| this option is one, the menu appears at the top of a new column in the |
| menu. |
| .VE |
| .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 |
| .VS 8.4 |
| \fB\-compound \fIvalue\fR |
| Specifies whether the menu entry should display both an image and text, |
| and if so, where the image should be placed relative to the text. |
| Valid values for this option are \fBbottom\fR, \fBcenter\fR, |
| \fBleft\fR, \fBnone\fR, \fBright\fR and \fBtop\fR. The default value |
| is \fBnone\fR, meaning that the button will display either an image or |
| text, depending on the values of the \fB\-image\fR and \fB\-bitmap\fR |
| options. |
| .VE |
| .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. |
| .VS |
| .TP |
| \fB\-hidemargin \fIvalue\fR |
| Specifies whether the standard margins should be drawn for this menu |
| entry. This is useful when creating palette with images in them, i.e., |
| color palettes, pattern palettes, etc. 1 indicates that the margin for |
| the entry is hidden; 0 means that the margin is used. |
| .VE |
| .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. |
| .VS |
| .TP |
| \fIpathName\fR \fBclone\fR \fInewPathname ?cloneType?\fR |
| Makes a clone of the current menu named \fInewPathName\fR. This clone |
| is a menu in its own right, but any changes to the clone are |
| propogated to the original menu and vice versa. \fIcloneType\fR can be |
| \fBnormal\fR, \fBmenubar\fR, or \fBtearoff\fR. Should not normally be |
| called outside of the Tk library. See the \fBCLONES\fR section for |
| more information. |
| .VE |
| .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 |
| .VS |
| \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. This subcommand does not work on Windows and the |
| Macintosh, as those platforms have their own way of unposting menus. |
| .VE |
| .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: |
| .VS |
| .TP |
| \fBPulldown Menus in Menubar\fR |
| This is the most command case. You create a menu widget that will become the |
| menu bar. You then add cascade entries to this menu, specifying the |
| pull down menus you wish to use in your menu bar. You then create all |
| of the pulldowns. Once you have done this, specify the menu using the |
| \fB-menu\fR option of the toplevel's widget command. See the |
| \fBtoplevel\fR manual entry for details. |
| .VE |
| .TP |
| \fBPulldown Menus in Menu Buttons\fR |
| This is the compatable way to do menu bars. 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 |
| .VS 8.4 |
| Several of the bindings make use of the command \fBtk_menuSetFocus\fR. |
| It saves the current focus and sets the focus to its \fIpathName\fR |
| argument, which is a menu widget. |
| .VE |
| .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 |