diff options
Diffstat (limited to 'tk8.6/doc/menu.n')
| -rw-r--r-- | tk8.6/doc/menu.n | 837 |
1 files changed, 0 insertions, 837 deletions
diff --git a/tk8.6/doc/menu.n b/tk8.6/doc/menu.n deleted file mode 100644 index 5742e23..0000000 --- a/tk8.6/doc/menu.n +++ /dev/null @@ -1,837 +0,0 @@ -'\" -'\" 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. -'\" -.TH menu n 4.1 Tk "Tk Built-In Commands" -.so man.macros -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -menu, tk_menuSetFocus \- Create and manipulate 'menu' widgets and menubars -.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" -.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 Tk 8.0 on Macintosh -and Windows, all post-commands in a system of menus are executed before any -of those menus are posted. -This is due to the limitations in the individual platforms' menu managers. -.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. -This option is ignored under Aqua/Mac OS X, where menus cannot -be torn off. -.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 value is -.QW "\fBa b\fR" -and menu \fB.x.y\fR is torn off to -create a new menu \fB.x.tearoff1\fR, then the command -.QW "\fBa b .x.y .x.tearoff1\fR" -will be invoked. -This option is ignored under Aqua/Mac OS X, where menus cannot -be torn off. -.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. -.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. -That menu widget can either be used as a pop-up window or applied to a -\fBtoplevel\fR (with its \fB\-menu\fR option) to make it into the menubar for -that toplevel. -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 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. -.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 used in the -application to cause the same result as invoking the menu entry. -This is a display option, it does not actually set the corresponding -binding (which can be achieved using the \fBbind\fR command). -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. -.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. -.SH "TYPES OF ENTRIES" -.SS "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. -.SS "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. -.SS "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. -.SS "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. -.SS "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. -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. -.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. This is not -supported on Windows. -.SS "TEAR-OFF ENTRIES" -.PP -A tear-off entry appears at the top of the menu if enabled with the -\fB\-tearoff\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 "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 across 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. -.SS "SPECIAL MENUS IN MENUBARS" -.PP -Certain menus in a menubar will be treated specially. On the Macintosh, -access to the special Application, Window 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 may be provided if -Motif menu compatibility is enabled. 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, .menubar.window 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 a .menubar.apple menu as the first menu in a menubar on the -Macintosh, that menu's contents make up the first items of the -Application menu whenever the window containing the menubar is in front. -After all of the Tk-defined items, the menu will have a separator, -followed by all standard Application menu items. -Such a .apple menu must be present in a menu when that menu is first -configured as a toplevel's menubar, otherwise a default application menu -(hidden from Tk) will be inserted into the menubar at that time and -subsequent addition of a .apple menu will no longer result in it -becoming the Application menu. -.PP -When Tk sees a .menubar.window menu on the Macintosh, the menu's -contents are inserted into the standard Window menu of the user's -menubar whenever the window's menubar is in front. The first items in -the menu are provided by Mac OS X, and the names of the current -toplevels are automatically appended after all the Tk-defined items and -a separator. -.PP -When Tk sees a .menubar.help menu on the Macintosh, the menu's contents -are appended to the standard Help menu of the user's menubar whenever -the window's menubar is in front. The first items in the menu -are provided by Mac OS X. -.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 is tied to the -application icon 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 sees a Help menu on X Windows and Motif menu compatibility is -enabled the menu is moved to be last in the menubar and is right -justified. Motif menu compatibility is enabled by setting the Tk option -\fB*Menu.useMotifHelp\fR to true or by calling -\fBtk::classic::restore menu\fR. -.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. -.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 -\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 -.QW "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, -.QW \fB@0\fR -indicates the top-most entry in the window. -.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 -\fIpattern\fR -. -If the index does not 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 \fBstring match\fR -are used. -.PP -If the index could match more than one of the above forms, then -the form earlier in the above list takes precedence. -.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 the options listed in the \fBMENU ENTRY OPTIONS\fR -section below. -The \fBadd\fR widget command returns an empty string. -.TP -\fIpathName \fBcget \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 \fBclone \fInewPathname\fR ?\fIcloneType\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 -propagated 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. -.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 \fB\-tearoff\fR option to remove the tear-off entry). -.TP -\fIpathName \fBentrycget \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 names described in the -\fBMENU ENTRY OPTIONS\fR section below. -.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 described in the -\fBMENU ENTRY OPTIONS\fR -section below. 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 type \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 \fB\-postcommand\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 does not correspond to a cascade entry, -or if \fIpathName\fR is not 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 or \fBinsert\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. This subcommand does not work on Windows and the -Macintosh, as those platforms have their own way of unposting menus. -.TP -\fIpathName \fBxposition \fIindex\fR -. -Returns a decimal string giving the x-coordinate within the menu -window of the leftmost pixel in the entry specified by \fIindex\fR. -.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 ENTRY OPTIONS" -The following options are allowed on menu entries. Most options are not -supported by all entry types. -.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 -\fB\-activebackground\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 -\fB\-activeforeground\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 -used to invoke the same function as the menu entry. This is a display -option, it does not actually set the corresponding binding (which can -be achieved using the \fBbind\fR command). 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 -\fB\-background\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 -(as controlled by the \fB\-compound\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\-columnbreak \fIvalue\fR -. -When this option is zero, the entry appears below the previous entry. When -this option is one, the entry appears at the top of a new column in the -menu. -This option is ignored on Aqua/Mac OS X, where menus are always a single -column. -.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\-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. -.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 \fB\-font\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 -\fB\-foreground\fR option for the overall menu is used. -This option is not available for separator or tear-off entries. -.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. -.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 -(as controlled by the \fB\-compound\fR option) -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 \fB\-selectcolor\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 -\fB\-foreground\fR option for the menu and the \fB\-background\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 \fB\-activeforeground\fR -option for the menu along with the \fB\-activebackground\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 -\fB\-disabledforeground\fR option for the menu and the -\fB\-background\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 variable 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. -.RS -.PP -For checkbutton entries, the default value of this option is taken from the -\fB\-label\fR option, and for radiobutton entries a single fixed value is -used. It is recommended that you always set the \fB\-variable\fR option when -creating either a checkbutton or a radiobutton. -.RE -.SH "MENU CONFIGURATIONS" -.PP -The default bindings support four different ways of using menus: -.TP -\fBPulldown Menus in Menubar\fR -. -This is the most common 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. -.TP -\fBPulldown Menus in Menu Buttons\fR -. -This is the compatible 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 -the \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 do not activate and -they ignore mouse button presses and releases. -.PP -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. -.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 is not possible to use the -option database to specify values for the options to individual -entries. -.SH "SEE ALSO" -bind(n), menubutton(n), ttk::menubutton(n), toplevel(n) -.SH KEYWORDS -menu, widget -'\" Local Variables: -'\" mode: nroff -'\" End: |