| 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 | |