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