diff options
Diffstat (limited to 'Master/tlpkg/tlperl/lib/Tk/Menubutton.pod')
| -rwxr-xr-x | Master/tlpkg/tlperl/lib/Tk/Menubutton.pod | 249 |
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 100755 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 + |