summaryrefslogtreecommitdiff
path: root/Master/tlpkg/tlperl/lib/Tk/Menubutton.pod
diff options
context:
space:
mode:
Diffstat (limited to 'Master/tlpkg/tlperl/lib/Tk/Menubutton.pod')
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/Menubutton.pod249
1 files changed, 249 insertions, 0 deletions
diff --git a/Master/tlpkg/tlperl/lib/Tk/Menubutton.pod b/Master/tlpkg/tlperl/lib/Tk/Menubutton.pod
new file mode 100644
index 00000000000..fcda3e958aa
--- /dev/null
+++ b/Master/tlpkg/tlperl/lib/Tk/Menubutton.pod
@@ -0,0 +1,249 @@
+# 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::Menubutton - Create and manipulate Menubutton widgets
+
+=for category Tk Widget Classes
+
+=head1 SYNOPSIS
+
+I<$menubutton> = I<$parent>-E<gt>B<Menubutton>(?I<options>?);
+
+=head1 STANDARD OPTIONS
+
+B<-activebackground> B<-cursor> B<-highlightthickness> B<-takefocus>
+B<-activeforeground> B<-disabledforeground> B<-image> B<-text>
+B<-anchor> B<-font> B<-justify> B<-textvariable>
+B<-background> B<-foreground> B<-padx> B<-underline>
+B<-bitmap> B<-highlightbackground> B<-pady> B<-wraplength>
+B<-borderwidth> B<-highlightcolor> B<-relief>
+
+See L<Tk::options> for details of the standard options.
+
+=head1 WIDGET-SPECIFIC OPTIONS
+
+=over 4
+
+=item Command-Line Name: B<-compound>
+
+=item Database Name: B<compound>
+
+=item Database Class: B<Compound>
+
+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 Name: B<direction>
+
+=item Class: B<Height>
+
+=item Switch: B<-direction>
+
+Specifies where the menu is going to be popup up. B<above> tries to
+pop the menu above the menubutton. B<below> tries to pop the menu
+below the menubutton. B<left> tries to pop the menu to the left of
+the menubutton. B<right> tries to pop the menu to the right of the
+menu button. B<flush> pops the menu directly over the menubutton.
+
+=item Name: B<height>
+
+=item Class: B<Height>
+
+=item Switch: B<-height>
+
+Specifies a desired height for the menubutton.
+If an image or bitmap is being displayed in the menubutton then the value is in
+screen units (i.e. any of the forms acceptable to B<Tk_GetPixels>);
+for text it is in lines of text.
+If this option isn't specified, the menubutton's desired height is computed
+from the size of the image or bitmap or text being displayed in it.
+
+=item Name: B<indicatorOn>
+
+=item Class: B<IndicatorOn>
+
+=item Switch: B<-indicatoron>
+
+The value must be a proper boolean value. If it is true then
+a small indicator rectangle will be displayed on the right side
+of the menubutton and the default menu bindings will treat this
+as an option menubutton. If false then no indicator will be
+displayed.
+
+=item Name: B<menu>
+
+=item Class: B<MenuName>
+
+=item Switch: B<-menu>
+
+Specifies the path name of the menu associated with this menubutton.
+The menu must be a child of the menubutton.
+
+=item Name: B<state>
+
+=item Class: B<State>
+
+=item Switch: B<-state>
+
+Specifies one of three states for the menubutton: B<normal>, B<active>,
+or B<disabled>. In normal state the menubutton is displayed using the
+B<foreground> and B<background> options. The active state is
+typically used when the pointer is over the menubutton. In active state
+the menubutton is displayed using the B<activeForeground> and
+B<activeBackground> options. Disabled state means that the menubutton
+should be insensitive: the default bindings will refuse to activate
+the widget and will ignore mouse button presses.
+In this state the B<disabledForeground> and
+B<background> options determine how the button is displayed.
+
+=item Name: B<width>
+
+=item Class: B<Width>
+
+=item Switch: B<-width>
+
+Specifies a desired width for the menubutton.
+If an image or bitmap is being displayed in the menubutton then the value is in
+screen units (i.e. any of the forms acceptable to B<Tk_GetPixels>);
+for text it is in characters.
+If this option isn't specified, the menubutton's desired width is computed
+from the size of the image or bitmap or text being displayed in it.
+
+=back
+
+=head1 DESCRIPTION
+
+The B<Menubutton> method creates a new window (given by the
+$widget argument) and makes it into a menubutton widget.
+Additional
+options, described above, may be specified on the command line
+or in the option database
+to configure aspects of the menubutton such as its colors, font,
+text, and initial relief. The B<menubutton> 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 menubutton is a widget that displays a textual string, bitmap, or image
+and is associated with a menu widget.
+If text is displayed, it must all be in a single font, but it
+can occupy multiple lines on the screen (if it contains newlines
+or if wrapping occurs because of the B<wrapLength> option) and
+one of the characters may optionally be underlined using the
+B<underline> option. In normal usage, pressing
+mouse button 1 over the menubutton causes the associated menu to
+be posted just underneath the menubutton. If the mouse is moved over
+the menu before releasing the mouse button, the button release
+causes the underlying menu entry to be invoked. When the button
+is released, the menu is unposted.
+
+Menubuttons are typically organized into groups called menu bars
+that allow scanning:
+if the mouse button is pressed over one menubutton (causing it
+to post its menu) and the mouse is moved over another menubutton
+in the same menu bar without releasing the mouse button, then the
+menu of the first menubutton is unposted and the menu of the
+new menubutton is posted instead.
+
+There are several interactions between menubuttons and menus; see
+the B<menu> manual entry for information on various menu configurations,
+such as pulldown menus and option menus.
+
+=head1 WIDGET METHODS
+
+The B<Menubutton> 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 B<menu> method returns the menu associated with the widget.
+The widget also inherits all the methods provided by the generic
+L<Tk::Widget|Tk::Widget> class.
+
+=head1 DEFAULT BINDINGS
+
+Tk automatically creates class bindings for menubuttons that give them
+the following default behavior:
+
+=over 4
+
+=item [1]
+
+A menubutton activates whenever the mouse passes over it and deactivates
+whenever the mouse leaves it.
+
+=item [2]
+
+Pressing mouse button 1 over a menubutton posts the menubutton:
+its relief changes to raised and its associated menu is posted
+under the menubutton. If the mouse is dragged down into the menu
+with the button still down, and if the mouse button is then
+released over an entry in the menu, the menubutton is unposted
+and the menu entry is invoked.
+
+=item [3]
+
+If button 1 is pressed over a menubutton and then released over that
+menubutton, the menubutton stays posted: you can still move the mouse
+over the menu and click button 1 on an entry to invoke it.
+Once a menu entry has been invoked, the menubutton unposts itself.
+
+=item [4]
+
+If button 1 is pressed over a menubutton and then dragged over some
+other menubutton, the original menubutton unposts itself and the
+new menubutton posts.
+
+=item [5]
+
+If button 1 is pressed over a menubutton and released outside
+any menubutton or menu, the menubutton unposts without invoking
+any menu entry.
+
+=item [6]
+
+When a menubutton is posted, its associated menu claims the input
+focus to allow keyboard traversal of the menu and its submenus.
+See the B<menu> documentation for details on these bindings.
+
+=item [7]
+
+If the B<underline> option has been specified for a menubutton
+then keyboard traversal may be used to post the menubutton:
+Alt+I<x>, where I<x> is the underlined character (or its
+lower-case or upper-case equivalent), may be typed in any window
+under the menubutton's toplevel to post the menubutton.
+
+=item [8]
+
+The F10 key may be typed in any window to post the first menubutton
+under its toplevel window that isn't disabled.
+
+=item [9]
+
+If a menubutton has the input focus, the space and return keys
+post the menubutton.
+
+If the menubutton's state is B<disabled> then none of the above
+actions occur: the menubutton is completely non-responsive.
+
+The behavior of menubuttons can be changed by defining new bindings for
+individual widgets or by redefining the class bindings.
+
+=back
+
+=head1 KEYWORDS
+
+menubutton, widget
+
+=cut
+