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