diff options
Diffstat (limited to 'Master/tlpkg/tlperl/lib/Tk/Menu.pod')
-rw-r--r-- | Master/tlpkg/tlperl/lib/Tk/Menu.pod | 876 |
1 files changed, 0 insertions, 876 deletions
diff --git a/Master/tlpkg/tlperl/lib/Tk/Menu.pod b/Master/tlpkg/tlperl/lib/Tk/Menu.pod deleted file mode 100644 index b7414e57510..00000000000 --- a/Master/tlpkg/tlperl/lib/Tk/Menu.pod +++ /dev/null @@ -1,876 +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. -# -# - -=head1 NAME - -Tk::Menu - Create and manipulate Menu widgets - -=for category Tk Widget Classes - -=head1 SYNOPSIS - -S< >I<$menu> = I<$parent>-E<gt>B<Menu>(?I<options>?); - -=head1 STANDARD OPTIONS - -B<-activebackground> B<-background> B<-disabledforeground> B<-relief> -B<-activeborderwidth> B<-borderwidth> B<-font> B<-takefocus> -B<-activeforeground> B<-cursor> B<-foreground> - -See L<Tk::options> for details of the standard options. - -=head1 WIDGET-SPECIFIC OPTIONS - -=over 4 - -=item Name: B<postCommand> - -=item Class: B<Command> - -=item Switch: B<-postcommand> - -If this option is specified then it provides a L<callback|Tk::callbacks> to execute -each time the menu is posted. The callback is invoked by the B<post> -method 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. - -=item Name: B<selectColor> - -=item Class: B<Background> - -=item Switch: B<-selectcolor> - -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. - -=item Name: B<tearOff> - -=item Class: B<TearOff> - -=item Switch: B<-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. - -=item Name: B<tearOffCommand> - -=item Class: B<TearOffCommand> - -=item Switch: B<-tearoffcommand> - -If this option has a non-empty value, then it specifies a L<perl/Tk callback|Tk::callbacks> -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 ``B<a b>'' and menu B<.x.y> is torn off to -create a new menu B<.x.tearoff1>, then the command -``B<a b .x.y .x.tearoff1>'' will be invoked. - -=item Name: B<title> - -=item Class: B<Title> - -=item Switch: B<-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. - -=item Name: B<type> - -=item Class: B<Type> - -=item Switch: B<-type> - -This option can be one of B<menubar>, B<tearoff>, or -B<normal>, 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. - -=back - -=head1 DESCRIPTION - -The B<Menu> method creates a new top-level window (given -by the $widget 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 B<menu> command returns its -$widget argument. At the time this command is invoked, -there must not exist a window named $widget, but -$widget's parent must exist. - -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. - -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 B<-label>, -B<-bitmap>, and B<-image> options for the entry. -If the B<-accelerator> 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 I<indicator>. 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. - -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 I<invoked>. -The effect of invocation is different for each type of entry; -these effects are described below in the sections on individual -entries. - -Entries may be I<disabled>, 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. - -Whenever a menu's active entry is changed, a E<lt>E<lt>MenuSelectE<gt>E<gt> virtual -event is sent 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. - -=head2 COMMAND ENTRIES - -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 callback is executed. The callback -is specified with the B<-command> option. - -=head2 SEPARATOR ENTRIES - -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. - -=head2 CHECKBUTTON ENTRIES - -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 B<-onvalue> and B<-variable> options for the entry); when -the entry is deselected another value (determined by the -B<-offvalue> 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 B<-selectcolor> option for the entry; -otherwise the indicator's center is displayed in the background color for -the menu. If a B<-command> option is specified for a checkbutton -entry, then its value is evaluated each time the entry -is invoked; this happens after toggling the entry's -selected state. - -=head2 RADIOBUTTON ENTRIES - -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 B<-value> and -B<-variable> 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 B<-selectcolor> option -for the entry; -otherwise the indicator's center is displayed in the background color for -the menu. If a B<-command> option is specified for a radiobutton -entry, then its value is evaluated each time the entry -is invoked; this happens after selecting the entry. - -=head2 CASCADE ENTRIES - -A cascade entry is one with an associated menu (determined -by the B<-menu> option). Cascade entries allow the construction -of cascading menus. -The B<postcascade> method 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). - -A cascade entry posts its associated menu by invoking - -=over 4 - -I<$menu>-E<gt>B<post>(I<x,y>) - -=back - -where I<menu> is the path name of the associated menu, and I<x> -and I<y> are the root-window coordinates of the upper-right -corner of the cascade entry. -On Unix, the lower-level menu is unposted by executing - -=over 4 - -I<$menu>-E<gt>B<unpost> - -=back - -where I<menu> is the name of the associated menu. -On other platforms, the platform's native code takes care of unposting the -menu. - -If a B<-command> option is specified for a cascade entry then it is -evaluated whenever the entry is invoked. This is not supported on Windows. - -=head2 TEAR-OFF ENTRIES - -A tear-off entry appears at the top of the menu if enabled with the -B<tearOff> option. It is not like other menu entries in that -it cannot be created with the B<add> method and -cannot be deleted with the B<delete> method. -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. - -=head2 MENUBARS - -Any menu can be set as a menubar for a toplevel window (see the -L<Toplevel|Tk::Toplevel> constructor 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 L<"CLONES"> for more information. - -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. - -=head2 SPECIAL MENUS IN MENUBARS - -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. - -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)". - -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. - -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. - -When Tk see a Help menu on X Windows, the menu is moved to be last in -the menubar and is right justified. - -=head2 CLONES - -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. - -=head2 WIDGET METHODS - -The B<Menu> method creates a widget object. -This object supports the B<configure> and B<cget> methods -described in L<Tk::options> which can be used to enquire and -modify the options described above. -The widget also inherits all the methods provided by the generic -L<Tk::Widget|Tk::Widget> class, and the L<Tk::Wm|Tk::Wm> class. - -Many of the methods for a menu take as one argument an -indicator of which entry of the menu to operate on. These -indicators are called I<index>es and may be specified in -any of the following forms: - -=over 4 - -=item I<number> - -Specifies the entry numerically, where 0 corresponds -to the top-most entry of the menu, 1 to the entry below it, and -so on. - -=item B<active> - -Indicates the entry that is currently active. If no entry is -active then this form is equivalent to B<none>. This form may -not be abbreviated. - -=item B<end> - -Indicates the bottommost entry in the menu. If there are no -entries in the menu then this form is equivalent to B<none>. -This form may not be abbreviated. - -=item B<last> - -Same as B<end>. - -=item B<none> - -Indicates ``no entry at all''; this is used most commonly with -the B<activate> option to deactivate all the entries in the -menu. In most cases the specification of B<none> causes -nothing to happen in the method. -This form may not be abbreviated. - -=item B<@>I<number> - -In this form, I<number> is treated as a y-coordinate in the -menu's window; the entry closest to that y-coordinate is used. -For example, ``B<@0>'' indicates the top-most entry in the -window. - -=item I<pattern> - -If the index doesn't satisfy one of the above forms then this -form is used. I<Pattern> is pattern-matched against the label of -each entry in the menu, in order from the top down, until a -matching entry is found. -(In perl/Tk the matching is under review, but exact match -should work.) - -=back - -The following methods are possible for menu widgets: - -=over 4 - -=item I<$menu>-E<gt>B<activate>(I<index>) - -Change the state of the entry indicated by I<index> to B<active> -and redisplay it using its active colors. -Any previously-active entry is deactivated. If I<index> -is specified as B<none>, or if the specified entry is -disabled, then the menu ends up with no active entry. -Returns an empty string. - -=item I<$menu>-E<gt>B<add>(I<type, >?I<option, value, option, value, ...>?) - -Add a new entry to the bottom of the menu. The new entry's type -is given by I<type> and must be one of B<cascade>, -B<checkbutton>, B<command>, B<radiobutton>, or B<separator>, -or a unique abbreviation of one of the above. If additional arguments -are present, they specify any of the following options: - -=over 8 - -=item B<-activebackground> =E<gt> I<value> - -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 -B<activeBackground> option for the overall menu is used. -If the B<$Tk::strictMotif> variable has been set to request strict -Motif compliance, then this option is ignored and the B<-background> -option is used in its place. -This option is not available for separator or tear-off entries. - -=item B<-activeforeground> =E<gt> I<value> - -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 -B<activeForeground> option for the overall menu is used. -This option is not available for separator or tear-off entries. - -=item B<-accelerator> =E<gt> I<value> - -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. - -=item B<-background> =E<gt> I<value> - -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 -B<background> option for the overall menu is used. -This option is not available for separator or tear-off entries. - -=item B<-bitmap> =E<gt> I<value> - -Specifies a bitmap to display in the menu instead of a textual -label, in any of the forms accepted by B<Tk_GetBitmap>. -This option overrides the B<-label> option but may be reset -to an empty string to enable a textual label to be displayed. -If a B<-image> option has been specified, it overrides -B<-bitmap>. -This option is not available for separator or tear-off entries. - -=item B<-columnbreak> =E<gt> I<value> - -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. - -=item B<-compound> =E<gt> I<value> - -Specifies whether the button 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 B<bottom>, B<center>, B<left>, -B<none>, B<right> and B<top>. The default value is B<none>, meaning -that the button will display either an image or text, depending on the -values of the -image and -bitmap options. - -=item B<-command> =E<gt> I<value> - -For command, checkbutton, and radiobutton entries, specifies a -callback to execute when the menu entry is invoked. -For cascade entries, specifies a callback to execute -when the entry is activated (i.e. just before its submenu is -posted). -Not available for separator or tear-off entries. - -=item B<-font> =E<gt> I<value> - -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 B<font> option for the overall menu is used. -This option is not available for separator or tear-off entries. - -=item B<-foreground> =E<gt> I<value> - -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 -B<foreground> option for the overall menu is used. -This option is not available for separator or tear-off entries. - -=item B<-hidemargin> =E<gt> I<value> - -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. - -=item B<-image> =E<gt> I<value> - -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 -B<image create>. -This option overrides the B<-label> and B<-bitmap> 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. - -=item B<-indicatoron> =E<gt> I<value> - -Available only for checkbutton and radiobutton entries. -I<Value> is a boolean that determines whether or not the -indicator should be displayed. - -=item B<-label> =E<gt> I<value> - -Specifies a string to display as an identifying label in the menu -entry. Not available for separator or tear-off entries. - -=item B<-menu> =E<gt> I<value> - -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. - -=item B<-offvalue> =E<gt> I<value> - -Available only for checkbutton entries. Specifies the value to -store in the entry's associated variable when the entry is -deselected. - -=item B<-onvalue> =E<gt> I<value> - -Available only for checkbutton entries. Specifies the value to -store in the entry's associated variable when the entry is selected. - -=item B<-selectcolor> =E<gt> I<value> - -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 B<selectColor> -option for the menu determines the indicator color. - -=item B<-selectimage> =E<gt> I<value> - -Available only for checkbutton and radiobutton entries. -Specifies an image to display in the entry (in place of -the B<-image> option) when it is selected. -I<Value> is the name of an image, which must have been created -by some previous invocation of B<image create>. -This option is ignored unless the B<-image> option has -been specified. - -=item B<-state> =E<gt> I<value> - -Specifies one of three states for the entry: B<normal>, B<active>, -or B<disabled>. In normal state the entry is displayed using the -B<foreground> option for the menu and the B<background> -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 B<activeForeground> -option for the menu along with the B<activebackground> 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 -B<disabledForeground> option for the menu and the -B<background> option from the entry. -This option is not available for separator entries. - -=item B<-underline> =E<gt> I<value> - -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. - -=item B<-value> =E<gt> I<value> - -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 B<-label> option -for the entry as the value to store in the variable. - -=item B<-variable> =E<gt> I<value> - -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. - -=back - -The B<add> method returns an empty string. - -=item I<$menu>-E<gt>B<clone>(I<$parent> ?, I<cloneType?>) - -Makes a clone of the current menu as a child of I<$parent>. This clone -is a menu in its own right, but any changes to the clone are -propogated to the original menu and vice versa. I<cloneType> can be -B<normal>, B<menubar>, or B<tearoff>. Should not normally be -called outside of the Tk library. See L<"CLONES"> for -more information. - -=item I<$menu>-E<gt>B<delete>(I<index1>?, I<index2>?) - -Delete all of the menu entries between I<index1> and -I<index2> inclusive. -If I<index2> is omitted then it defaults to I<index1>. -Attempts to delete a tear-off menu entry are ignored (instead, you -should change the B<tearOff> option to remove the tear-off entry). - -=item I<$menu>-E<gt>B<entrycget>(I<index, option>) - -Returns the current value of a configuration option for -the entry given by I<index>. -I<Option> may have any of the values accepted by the B<add> -method. - -=item I<$menu>-E<gt>B<entryconfigure>(I<index> ?,I<options>?) - -This method is similar to the B<configure> method, except that -it applies to the options for an individual entry, whereas B<configure> -applies to the options for the menu as a whole. -I<Options> may have any of the values accepted by the B<add> -method. If I<options> are specified, options are modified -as indicated -in the method call and the method returns an empty string. -If no I<options> are specified, returns a list describing -the current options for entry I<index> (see L<Tk::options> for -information on the format of this list). - -=item I<$menu>-E<gt>B<index>(I<index>) - -Returns the numerical index corresponding to I<index>, or -B<none> if I<index> was specified as B<none>. - -=item I<$menu>-E<gt>B<insert>(I<index, type>?, I<-option>=E<gt>I<value>, ...?) - -Same as the B<add> method except that it inserts the new -entry just before the entry given by I<index>, instead of appending -to the end of the menu. The I<type>, I<-option>, and I<value> -arguments have the same interpretation as for the B<add> widget -method. It is not possible to insert new menu entries before the -tear-off entry, if the menu has one. - -=item I<$menu>-E<gt>B<invoke>(I<index>) - -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 callback associated with it then the result of that -callback is returned as the result of the B<invoke> widget -method. 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 B<invoke> -method. - -=item I<$menu>-E<gt>B<post>(I<x, y>) - -Arrange for the menu to be displayed on the screen at the root-window -coordinates given by I<x> and I<y>. These coordinates are -adjusted if necessary to guarantee that the entire menu is visible on -the screen. This method normally returns an empty string. -If the B<postCommand> option has been specified, then its value is -executed before posting the menu and the result of -that callback is returned as the result of the B<post> widget -method. -If an error returns while executing the method, then the error is -returned without posting the menu. - -=item I<$menu>-E<gt>B<postcascade>(I<index>) - -Posts the submenu associated with the cascade entry given by -I<index>, and unposts any previously posted submenu. -If I<index> doesn't correspond to a cascade entry, -or if I<$menu> isn't posted, -the method has no effect except to unpost any currently posted -submenu. - -=item I<$menu>-E<gt>B<type>(I<index>) - -Returns the type of the menu entry given by I<index>. -This is the I<type> argument passed to the B<add> widget -method when the entry was created, such as B<command> -or B<separator>, or B<tearoff> for a tear-off entry. - -=item I<$menu>-E<gt>B<unpost> - -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 method does not work on Windows and the -Macintosh, as those platforms have their own way of unposting menus. - -=item I<$menu>-E<gt>B<yposition>(I<index>) - -Returns a decimal string giving the y-coordinate within the menu -window of the topmost pixel in the entry specified by I<index>. - -=back - -=head1 MENU CONFIGURATIONS - -The default bindings support four different ways of using menus: - -=over 4 - -=item B<Pulldown Menus in Menubar> - -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 -B<-menu> option of the toplevel's method. See the -B<toplevel> manual entry for details. - -=item B<Pulldown Menus in Menu Buttons> - -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 B<-menu> -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 B<menubutton> documentation for details. - -=item B<Popup Menus> - -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 B<Post> method at the appropriate time -to post the top-level menu. - -I<$menu>-E<gt>B<Post>(I<$x>,I<$y>?,I<$entry>?) - -I<$x> and I<$y> are the root window coordinates at which the I<$menu> -will be displayed. If I<$entry> is specified then that entry is centred -on that point, otherwise the top-left corner of the I<$menu> is placed -at that point. - -B<Menu> also inherits methods from L<Tk::Wm> and so the method -B<Popup> can be used to position menu relative to other windows, the -mouse cursor or the screen. - -=item B<Option Menus> - -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 L<Tk::Optionmenu> class to create option -menubuttons and their menus. - -=item B<Torn-off Menus> - -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. - -=back - -=head1 DEFAULT BINDINGS - -Tk automatically creates class bindings for menus that give them -the following default behavior: - -=over 4 - -=item [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. - -=item [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. - -=item [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. - -=item [4] - -The Space and Return keys invoke the active entry and -unpost the menu. - -=item [5] - -If any of the entries in a menu have letters underlined with -with B<-underline> option, then pressing one of the underlined -letters (or its upper-case or lower-case equivalent) invokes that -entry and unposts the menu. - -=item [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. - -=item [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. - -=item [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. - -=item [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. - -Disabled menu entries are non-responsive: they don't activate and -they ignore mouse button presses and releases. - -The behavior of menus can be changed by defining new bindings for -individual widgets or by redefining the class bindings. - -=back - -=head1 BUGS - -At present it isn't possible to use the -option database to specify values for the options to individual -entries. - -=head1 SEE ALSO - -L<Tk::callbacks|Tk::callbacks> - -=head1 KEYWORDS - -menu, widget - -=cut - |