summaryrefslogtreecommitdiff
path: root/Master/tlpkg/tlperl/lib/Tk/Menu.pod
diff options
context:
space:
mode:
Diffstat (limited to 'Master/tlpkg/tlperl/lib/Tk/Menu.pod')
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/Menu.pod876
1 files changed, 876 insertions, 0 deletions
diff --git a/Master/tlpkg/tlperl/lib/Tk/Menu.pod b/Master/tlpkg/tlperl/lib/Tk/Menu.pod
new file mode 100644
index 00000000000..b7414e57510
--- /dev/null
+++ b/Master/tlpkg/tlperl/lib/Tk/Menu.pod
@@ -0,0 +1,876 @@
+# 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
+