| 1 | # Copyright (c) 1990-1994 The Regents of the University of California. |
| 2 | # Copyright (c) 1994-1997 Sun Microsystems, Inc. |
| 3 | # See the file "license.terms" for information on usage and redistribution |
| 4 | # of this file, and for a DISCLAIMER OF ALL WARRANTIES. |
| 5 | # |
| 6 | # |
| 7 | |
| 8 | =head1 NAME |
| 9 | |
| 10 | Tk::Menubutton - Create and manipulate Menubutton widgets |
| 11 | |
| 12 | =for category Tk Widget Classes |
| 13 | |
| 14 | =head1 SYNOPSIS |
| 15 | |
| 16 | I<$menubutton> = I<$parent>-E<gt>B<Menubutton>(?I<options>?); |
| 17 | |
| 18 | =head1 STANDARD OPTIONS |
| 19 | |
| 20 | B<-activebackground> B<-cursor> B<-highlightthickness> B<-takefocus> |
| 21 | B<-activeforeground> B<-disabledforeground> B<-image> B<-text> |
| 22 | B<-anchor> B<-font> B<-justify> B<-textvariable> |
| 23 | B<-background> B<-foreground> B<-padx> B<-underline> |
| 24 | B<-bitmap> B<-highlightbackground> B<-pady> B<-wraplength> |
| 25 | B<-borderwidth> B<-highlightcolor> B<-relief> |
| 26 | |
| 27 | See L<Tk::options> for details of the standard options. |
| 28 | |
| 29 | =head1 WIDGET-SPECIFIC OPTIONS |
| 30 | |
| 31 | =over 4 |
| 32 | |
| 33 | =item Name: B<direction> |
| 34 | |
| 35 | =item Class: B<Height> |
| 36 | |
| 37 | =item Switch: B<-direction> |
| 38 | |
| 39 | Specifies where the menu is going to be popup up. B<above> tries to |
| 40 | pop the menu above the menubutton. B<below> tries to pop the menu |
| 41 | below the menubutton. B<left> tries to pop the menu to the left of |
| 42 | the menubutton. B<right> tries to pop the menu to the right of the |
| 43 | menu button. B<flush> pops the menu directly over the menubutton. |
| 44 | |
| 45 | =item Name: B<height> |
| 46 | |
| 47 | =item Class: B<Height> |
| 48 | |
| 49 | =item Switch: B<-height> |
| 50 | |
| 51 | Specifies a desired height for the menubutton. |
| 52 | If an image or bitmap is being displayed in the menubutton then the value is in |
| 53 | screen units (i.e. any of the forms acceptable to B<Tk_GetPixels>); |
| 54 | for text it is in lines of text. |
| 55 | If this option isn't specified, the menubutton's desired height is computed |
| 56 | from the size of the image or bitmap or text being displayed in it. |
| 57 | |
| 58 | =item Name: B<indicatorOn> |
| 59 | |
| 60 | =item Class: B<IndicatorOn> |
| 61 | |
| 62 | =item Switch: B<-indicatoron> |
| 63 | |
| 64 | The value must be a proper boolean value. If it is true then |
| 65 | a small indicator rectangle will be displayed on the right side |
| 66 | of the menubutton and the default menu bindings will treat this |
| 67 | as an option menubutton. If false then no indicator will be |
| 68 | displayed. |
| 69 | |
| 70 | =item Name: B<menu> |
| 71 | |
| 72 | =item Class: B<MenuName> |
| 73 | |
| 74 | =item Switch: B<-menu> |
| 75 | |
| 76 | Specifies the path name of the menu associated with this menubutton. |
| 77 | The menu must be a child of the menubutton. |
| 78 | |
| 79 | =item Name: B<state> |
| 80 | |
| 81 | =item Class: B<State> |
| 82 | |
| 83 | =item Switch: B<-state> |
| 84 | |
| 85 | Specifies one of three states for the menubutton: B<normal>, B<active>, |
| 86 | or B<disabled>. In normal state the menubutton is displayed using the |
| 87 | B<foreground> and B<background> options. The active state is |
| 88 | typically used when the pointer is over the menubutton. In active state |
| 89 | the menubutton is displayed using the B<activeForeground> and |
| 90 | B<activeBackground> options. Disabled state means that the menubutton |
| 91 | should be insensitive: the default bindings will refuse to activate |
| 92 | the widget and will ignore mouse button presses. |
| 93 | In this state the B<disabledForeground> and |
| 94 | B<background> options determine how the button is displayed. |
| 95 | |
| 96 | =item Name: B<width> |
| 97 | |
| 98 | =item Class: B<Width> |
| 99 | |
| 100 | =item Switch: B<-width> |
| 101 | |
| 102 | Specifies a desired width for the menubutton. |
| 103 | If an image or bitmap is being displayed in the menubutton then the value is in |
| 104 | screen units (i.e. any of the forms acceptable to B<Tk_GetPixels>); |
| 105 | for text it is in characters. |
| 106 | If this option isn't specified, the menubutton's desired width is computed |
| 107 | from the size of the image or bitmap or text being displayed in it. |
| 108 | |
| 109 | =back |
| 110 | |
| 111 | =head1 DESCRIPTION |
| 112 | |
| 113 | The B<Menubutton> method creates a new window (given by the |
| 114 | $widget argument) and makes it into a menubutton widget. |
| 115 | Additional |
| 116 | options, described above, may be specified on the command line |
| 117 | or in the option database |
| 118 | to configure aspects of the menubutton such as its colors, font, |
| 119 | text, and initial relief. The B<menubutton> command returns its |
| 120 | $widget argument. At the time this command is invoked, |
| 121 | there must not exist a window named $widget, but |
| 122 | $widget's parent must exist. |
| 123 | |
| 124 | A menubutton is a widget that displays a textual string, bitmap, or image |
| 125 | and is associated with a menu widget. |
| 126 | If text is displayed, it must all be in a single font, but it |
| 127 | can occupy multiple lines on the screen (if it contains newlines |
| 128 | or if wrapping occurs because of the B<wrapLength> option) and |
| 129 | one of the characters may optionally be underlined using the |
| 130 | B<underline> option. In normal usage, pressing |
| 131 | mouse button 1 over the menubutton causes the associated menu to |
| 132 | be posted just underneath the menubutton. If the mouse is moved over |
| 133 | the menu before releasing the mouse button, the button release |
| 134 | causes the underlying menu entry to be invoked. When the button |
| 135 | is released, the menu is unposted. |
| 136 | |
| 137 | Menubuttons are typically organized into groups called menu bars |
| 138 | that allow scanning: |
| 139 | if the mouse button is pressed over one menubutton (causing it |
| 140 | to post its menu) and the mouse is moved over another menubutton |
| 141 | in the same menu bar without releasing the mouse button, then the |
| 142 | menu of the first menubutton is unposted and the menu of the |
| 143 | new menubutton is posted instead. |
| 144 | |
| 145 | There are several interactions between menubuttons and menus; see |
| 146 | the B<menu> manual entry for information on various menu configurations, |
| 147 | such as pulldown menus and option menus. |
| 148 | |
| 149 | =head1 WIDGET METHODS |
| 150 | |
| 151 | The B<Menubutton> method creates a widget object. |
| 152 | This object supports the B<configure> and B<cget> methods |
| 153 | described in L<Tk::options> which can be used to enquire and |
| 154 | modify the options described above. |
| 155 | The B<menu> method returns the menu associated with the widget. |
| 156 | The widget also inherits all the methods provided by the generic |
| 157 | L<Tk::Widget|Tk::Widget> class. |
| 158 | |
| 159 | =head1 DEFAULT BINDINGS |
| 160 | |
| 161 | Tk automatically creates class bindings for menubuttons that give them |
| 162 | the following default behavior: |
| 163 | |
| 164 | =over 4 |
| 165 | |
| 166 | =item [1] |
| 167 | |
| 168 | A menubutton activates whenever the mouse passes over it and deactivates |
| 169 | whenever the mouse leaves it. |
| 170 | |
| 171 | =item [2] |
| 172 | |
| 173 | Pressing mouse button 1 over a menubutton posts the menubutton: |
| 174 | its relief changes to raised and its associated menu is posted |
| 175 | under the menubutton. If the mouse is dragged down into the menu |
| 176 | with the button still down, and if the mouse button is then |
| 177 | released over an entry in the menu, the menubutton is unposted |
| 178 | and the menu entry is invoked. |
| 179 | |
| 180 | =item [3] |
| 181 | |
| 182 | If button 1 is pressed over a menubutton and then released over that |
| 183 | menubutton, the menubutton stays posted: you can still move the mouse |
| 184 | over the menu and click button 1 on an entry to invoke it. |
| 185 | Once a menu entry has been invoked, the menubutton unposts itself. |
| 186 | |
| 187 | =item [4] |
| 188 | |
| 189 | If button 1 is pressed over a menubutton and then dragged over some |
| 190 | other menubutton, the original menubutton unposts itself and the |
| 191 | new menubutton posts. |
| 192 | |
| 193 | =item [5] |
| 194 | |
| 195 | If button 1 is pressed over a menubutton and released outside |
| 196 | any menubutton or menu, the menubutton unposts without invoking |
| 197 | any menu entry. |
| 198 | |
| 199 | =item [6] |
| 200 | |
| 201 | When a menubutton is posted, its associated menu claims the input |
| 202 | focus to allow keyboard traversal of the menu and its submenus. |
| 203 | See the B<menu> documentation for details on these bindings. |
| 204 | |
| 205 | =item [7] |
| 206 | |
| 207 | If the B<underline> option has been specified for a menubutton |
| 208 | then keyboard traversal may be used to post the menubutton: |
| 209 | Alt+I<x>, where I<x> is the underlined character (or its |
| 210 | lower-case or upper-case equivalent), may be typed in any window |
| 211 | under the menubutton's toplevel to post the menubutton. |
| 212 | |
| 213 | =item [8] |
| 214 | |
| 215 | The F10 key may be typed in any window to post the first menubutton |
| 216 | under its toplevel window that isn't disabled. |
| 217 | |
| 218 | =item [9] |
| 219 | |
| 220 | If a menubutton has the input focus, the space and return keys |
| 221 | post the menubutton. |
| 222 | |
| 223 | If the menubutton's state is B<disabled> then none of the above |
| 224 | actions occur: the menubutton is completely non-responsive. |
| 225 | |
| 226 | The behavior of menubuttons can be changed by defining new bindings for |
| 227 | individual widgets or by redefining the class bindings. |
| 228 | |
| 229 | =back |
| 230 | |
| 231 | =head1 KEYWORDS |
| 232 | |
| 233 | menubutton, widget |
| 234 | |
| 235 | =cut |
| 236 | |