Commit | Line | Data |
---|---|---|
86530b38 AT |
1 | # Copyright (c) 1990-1994 The Regents of the University of California. |
2 | # Copyright (c) 1994-1996 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::Checkbutton - Create and manipulate Checkbutton widgets | |
11 | ||
12 | =for category Tk Widget Classes | |
13 | ||
14 | =head1 SYNOPSIS | |
15 | ||
16 | I<$checkbutton> = I<$parent>-E<gt>B<Checkbutton>(?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<command> | |
34 | ||
35 | =item Class: B<Command> | |
36 | ||
37 | =item Switch: B<-command> | |
38 | ||
39 | Specifies a L<perl/Tk callback|Tk::callbacks> to associate with the button. This command | |
40 | is typically invoked when mouse button 1 is released over the button | |
41 | window. The button's global variable (B<-variable> option) will | |
42 | be updated before the command is invoked. | |
43 | ||
44 | =item Name: B<height> | |
45 | ||
46 | =item Class: B<Height> | |
47 | ||
48 | =item Switch: B<-height> | |
49 | ||
50 | Specifies a desired height for the button. | |
51 | If an image or bitmap is being displayed in the button then the value is in | |
52 | screen units (i.e. any of the forms acceptable to B<Tk_GetPixels>); | |
53 | for text it is in lines of text. | |
54 | If this option isn't specified, the button's desired height is computed | |
55 | from the size of the image or bitmap or text being displayed in it. | |
56 | ||
57 | =item Name: B<indicatorOn> | |
58 | ||
59 | =item Class: B<IndicatorOn> | |
60 | ||
61 | =item Switch: B<-indicatoron> | |
62 | ||
63 | Specifies whether or not the indicator should be drawn. Must be a | |
64 | proper boolean value. If false, the B<relief> option is | |
65 | ignored and the widget's relief is always sunken if the widget is | |
66 | selected and raised otherwise. | |
67 | ||
68 | =item Name: B<offValue> | |
69 | ||
70 | =item Class: B<Value> | |
71 | ||
72 | =item Switch: B<-offvalue> | |
73 | ||
74 | Specifies value to store in the button's associated variable whenever | |
75 | this button is deselected. Defaults to ``0''. | |
76 | ||
77 | =item Name: B<onValue> | |
78 | ||
79 | =item Class: B<Value> | |
80 | ||
81 | =item Switch: B<-onvalue> | |
82 | ||
83 | Specifies value to store in the button's associated variable whenever | |
84 | this button is selected. Defaults to ``1''. | |
85 | ||
86 | =item Name: B<selectColor> | |
87 | ||
88 | =item Class: B<Background> | |
89 | ||
90 | =item Switch: B<-selectcolor> | |
91 | ||
92 | Specifies a background color to use when the button is selected. | |
93 | If B<indicatorOn> is true then the color applies to the indicator. | |
94 | Under Windows, this color is used as the background for the indicator | |
95 | regardless of the select state. | |
96 | If B<indicatorOn> is false, this color is used as the background | |
97 | for the entire widget, in place of B<background> or B<activeBackground>, | |
98 | whenever the widget is selected. | |
99 | If specified as an empty string then no special color is used for | |
100 | displaying when the widget is selected. | |
101 | ||
102 | =item Name: B<selectImage> | |
103 | ||
104 | =item Class: B<SelectImage> | |
105 | ||
106 | =item Switch: B<-selectimage> | |
107 | ||
108 | Specifies an image to display (in place of the B<image> option) | |
109 | when the checkbutton is selected. | |
110 | This option is ignored unless the B<image> option has been | |
111 | specified. | |
112 | ||
113 | =item Name: B<state> | |
114 | ||
115 | =item Class: B<State> | |
116 | ||
117 | =item Switch: B<-state> | |
118 | ||
119 | Specifies one of three states for the checkbutton: B<normal>, B<active>, | |
120 | or B<disabled>. In normal state the checkbutton is displayed using the | |
121 | B<foreground> and B<background> options. The active state is | |
122 | typically used when the pointer is over the checkbutton. In active state | |
123 | the checkbutton is displayed using the B<activeForeground> and | |
124 | B<activeBackground> options. Disabled state means that the checkbutton | |
125 | should be insensitive: the default bindings will refuse to activate | |
126 | the widget and will ignore mouse button presses. | |
127 | In this state the B<disabledForeground> and | |
128 | B<background> options determine how the checkbutton is displayed. | |
129 | ||
130 | =item Name: B<variable> | |
131 | ||
132 | =item Class: B<Variable> | |
133 | ||
134 | =item Switch: B<-variable> | |
135 | ||
136 | Specifies reference to a variable to set to indicate whether | |
137 | or not this button is selected. Defaults to C<\$widget-E<gt>{'Value'}> | |
138 | member of the widget's hash. In general perl variables are C<undef> unless | |
139 | specifically initialized which will not match either default B<-onvalue> or | |
140 | default B<-offvalue>. | |
141 | ||
142 | =item Name: B<width> | |
143 | ||
144 | =item Class: B<Width> | |
145 | ||
146 | =item Switch: B<-width> | |
147 | ||
148 | Specifies a desired width for the button. | |
149 | If an image or bitmap is being displayed in the button then the value is in | |
150 | screen units (i.e. any of the forms acceptable to B<Tk_GetPixels>); | |
151 | for text it is in characters. | |
152 | If this option isn't specified, the button's desired width is computed | |
153 | from the size of the image or bitmap or text being displayed in it. | |
154 | ||
155 | =back | |
156 | ||
157 | =head1 DESCRIPTION | |
158 | ||
159 | The B<Checkbutton> method creates a new window (given by the | |
160 | $widget argument) and makes it into a checkbutton widget. | |
161 | Additional | |
162 | options, described above, may be specified on the command line | |
163 | or in the option database | |
164 | to configure aspects of the checkbutton such as its colors, font, | |
165 | text, and initial relief. The B<checkbutton> command returns its | |
166 | $widget argument. At the time this command is invoked, | |
167 | there must not exist a window named $widget, but | |
168 | $widget's parent must exist. | |
169 | ||
170 | A checkbutton is a widget | |
171 | that displays a textual string, bitmap or image | |
172 | and a square called an I<indicator>. | |
173 | If text is displayed, it must all be in a single font, but it | |
174 | can occupy multiple lines on the screen (if it contains newlines | |
175 | or if wrapping occurs because of the B<wrapLength> option) and | |
176 | one of the characters may optionally be underlined using the | |
177 | B<underline> option. | |
178 | A checkbutton has | |
179 | all of the behavior of a simple button, including the | |
180 | following: it can display itself in either of three different | |
181 | ways, according to the B<state> option; | |
182 | it can be made to appear | |
183 | raised, sunken, or flat; it can be made to flash; and it invokes | |
184 | a L<perl/Tk callback|Tk::callbacks> whenever mouse button 1 is clicked over the | |
185 | checkbutton. | |
186 | ||
187 | In addition, checkbuttons can be I<selected>. | |
188 | If a checkbutton is selected then the indicator is normally | |
189 | drawn with a selected appearance, and | |
190 | a Tcl variable associated with the checkbutton is set to a particular | |
191 | value (normally 1). | |
192 | Under Unix, the indicator is drawn with a sunken relief and a special | |
193 | color. Under Windows, the indicator is drawn with a check mark inside. | |
194 | If the checkbutton is not selected, then the indicator is drawn with a | |
195 | deselected appearance, and the associated variable is | |
196 | set to a different value (typically 0). | |
197 | Under Unix, the indicator is drawn with a raised relief and no special | |
198 | color. Under Windows, the indicator is drawn without a check mark inside. | |
199 | By default, the name of the variable associated with a checkbutton is the | |
200 | same as the I<name> used to create the checkbutton. | |
201 | The variable name, and the ``on'' and ``off'' values stored in it, | |
202 | may be modified with options on the command line or in the option | |
203 | database. | |
204 | Configuration options may also be used to modify the way the | |
205 | indicator is displayed (or whether it is displayed at all). | |
206 | By default a checkbutton is configured to select and deselect | |
207 | itself on alternate button clicks. | |
208 | In addition, each checkbutton monitors its associated variable and | |
209 | automatically selects and deselects itself when the variables value | |
210 | changes to and from the button's ``on'' value. | |
211 | ||
212 | =head1 WIDGET METHODS | |
213 | ||
214 | The B<Checkbutton> method creates a widget object. | |
215 | This object supports the B<configure> and B<cget> methods | |
216 | described in L<Tk::options> which can be used to enquire and | |
217 | modify the options described above. | |
218 | The widget also inherits all the methods provided by the generic | |
219 | L<Tk::Widget|Tk::Widget> class. | |
220 | ||
221 | The following additional methods are available for checkbutton widgets: | |
222 | ||
223 | =over 4 | |
224 | ||
225 | =item I<$checkbutton>-E<gt>B<deselect> | |
226 | ||
227 | Deselects the checkbutton and sets the associated variable to its ``off'' | |
228 | value. | |
229 | ||
230 | =item I<$checkbutton>-E<gt>B<flash> | |
231 | ||
232 | Flashes the checkbutton. This is accomplished by redisplaying the checkbutton | |
233 | several times, alternating between active and normal colors. At | |
234 | the end of the flash the checkbutton is left in the same normal/active | |
235 | state as when the command was invoked. | |
236 | This command is ignored if the checkbutton's state is B<disabled>. | |
237 | ||
238 | =item I<$checkbutton>-E<gt>B<invoke> | |
239 | ||
240 | Does just what would have happened if the user invoked the checkbutton | |
241 | with the mouse: toggle the selection state of the button and invoke | |
242 | the L<perl/Tk callback|Tk::callbacks> associated with the checkbutton, if there is one. | |
243 | The return value is the return value from the L<perl/Tk callback|Tk::callbacks>, or an | |
244 | empty string if there is no command associated with the checkbutton. | |
245 | This command is ignored if the checkbutton's state is B<disabled>. | |
246 | ||
247 | =item I<$checkbutton>-E<gt>B<select> | |
248 | ||
249 | Selects the checkbutton and sets the associated variable to its ``on'' | |
250 | value. | |
251 | ||
252 | =item I<$checkbutton>-E<gt>B<toggle> | |
253 | ||
254 | Toggles the selection state of the button, redisplaying it and | |
255 | modifying its associated variable to reflect the new state. | |
256 | ||
257 | =back | |
258 | ||
259 | =head1 BINDINGS | |
260 | ||
261 | Tk automatically creates class bindings for checkbuttons that give them | |
262 | the following default behavior: | |
263 | ||
264 | =over 4 | |
265 | ||
266 | =item [1] | |
267 | ||
268 | On Unix systems, a checkbutton activates whenever the mouse passes | |
269 | over it and deactivates whenever the mouse leaves the checkbutton. On | |
270 | Mac and Windows systems, when mouse button 1 is pressed over a | |
271 | checkbutton, the button activates whenever the mouse pointer is inside | |
272 | the button, and deactivates whenever the mouse pointer leaves the | |
273 | button. | |
274 | ||
275 | =item [2] | |
276 | ||
277 | When mouse button 1 is pressed over a checkbutton, it is invoked (its | |
278 | selection state toggles and the command associated with the button is | |
279 | invoked, if there is one). | |
280 | ||
281 | =item [3] | |
282 | ||
283 | When a checkbutton has the input focus, the space key causes the checkbutton | |
284 | to be invoked. Under Windows, there are additional key bindings; plus | |
285 | (+) and equal (=) select the button, and minus (-) deselects the button. | |
286 | ||
287 | If the checkbutton's state is B<disabled> then none of the above | |
288 | actions occur: the checkbutton is completely non-responsive. | |
289 | ||
290 | The behavior of checkbuttons can be changed by defining new bindings for | |
291 | individual widgets or by redefining the class bindings. | |
292 | ||
293 | =back | |
294 | ||
295 | =head1 KEYWORDS | |
296 | ||
297 | checkbutton, widget | |
298 | ||
299 | =cut | |
300 |