Commit | Line | Data |
---|---|---|
86530b38 AT |
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 |