1Checkbutton(3) User Contributed Perl Documentation Checkbutton(3)
2
6 Tk::Checkbutton - Create and manipulate Checkbutton widgets
7
9 $checkbutton = $parent->Checkbutton(?options?);
10
12 -activebackground -activeforeground -anchor -background -bitmap -bor‐
13 derwidth -compound -cursor -disabledforeground -font -foreground -high‐
14 lightbackground -highlightcolor -highlightthickness -image -justify
15 -padx -pady -relief -takefocus -text -textvariable -underline
16 -wraplength
17 See Tk::options for details of the standard options.
19
21 Name: command
22 Class: Command
23 Switch: -command
24 Specifies a perl/Tk callback to associate with the button. This
25 command is typically invoked when mouse button 1 is released over
26 the button window. The button's global variable (-variable option)
27 will be updated before the command is invoked.
28 Name: height
30 Class: Height
31 Switch: -height
32 Specifies a desired height for the button. If an image or bitmap
33 is being displayed in the button then the value is in screen units
34 (i.e. any of the forms acceptable to Tk_GetPixels); for text it is
35 in lines of text. If this option isn't specified, the button's
36 desired height is computed from the size of the image or bitmap or
37 text being displayed in it.
38 Name: indicatorOn
40 Class: IndicatorOn
41 Switch: -indicatoron
42 Specifies whether or not the indicator should be drawn. Must be a
43 proper boolean value. If false, the relief option is ignored and
44 the widget's relief is always sunken if the widget is selected and
45 raised otherwise.
46 Command-Line Name: -offrelief
48 Database Name: offRelief
49 Database Class: OffRelief
50 Specifies the relief for the checkbutton when the indicator is not
51 drawn and the checkbutton is off. The default value is raised. By
52 setting this option to flat and setting -indicatoron false -overre‐
53 lief raised, the effect is achieved of having a flat button that
54 raises on mouse-over and which is depressed when activated. This
55 is the behavior typically exhibited by the Bold, Italic, and Under‐
56 line checkbuttons on the toolbar of a word-processor, for example.
57 Name: offValue
59 Class: Value
60 Switch: -offvalue
61 Specifies value to store in the button's associated variable when‐
62 ever this button is deselected. Defaults to ``0''.
63 Name: onValue
65 Class: Value
66 Switch: -onvalue
67 Specifies value to store in the button's associated variable when‐
68 ever this button is selected. Defaults to ``1''.
69 Command-Line Name: -overrelief
71 Database Name: overRelief
72 Database Class: OverRelief
73 Specifies an alternative relief for the button, to be used when
74 the mouse cursor is over the widget. This option can be used to
75 make toolbar buttons, by configuring -relief flat -overrelief
76 raised. If the value of this option is the empty string, then no
77 alternative relief is used when the mouse cursor is over the but‐
78 ton. The empty string is the default value.
79 Name: selectColor
81 Class: Background
82 Switch: -selectcolor
83 Specifies a background color to use when the button is selected.
84 If indicatorOn is true then the color applies to the indicator.
85 Under Windows, this color is used as the background for the indica‐
86 tor regardless of the select state. If indicatorOn is false, this
87 color is used as the background for the entire widget, in place of
88 background or activeBackground, whenever the widget is selected.
89 If specified as an empty string then no special color is used for
90 displaying when the widget is selected.
91 Name: selectImage
93 Class: SelectImage
94 Switch: -selectimage
95 Specifies an image to display (in place of the image option) when
96 the checkbutton is selected. This option is ignored unless the
97 image option has been specified.
98 Name: state
100 Class: State
101 Switch: -state
102 Specifies one of three states for the checkbutton: normal, active,
103 or disabled. In normal state the checkbutton is displayed using
104 the foreground and background options. The active state is typi‐
105 cally used when the pointer is over the checkbutton. In active
106 state the checkbutton is displayed using the activeForeground and
107 activeBackground options. Disabled state means that the checkbut‐
108 ton should be insensitive: the default bindings will refuse to
109 activate the widget and will ignore mouse button presses. In this
110 state the disabledForeground and background options determine how
111 the checkbutton is displayed.
112 Name: variable
114 Class: Variable
115 Switch: -variable
116 Specifies reference to a variable to set to indicate whether or not
117 this button is selected. Defaults to "\$widget->{'Value'}" member
118 of the widget's hash. In general perl variables are "undef" unless
119 specifically initialized which will not match either default -onva‐
120 lue or default -offvalue.
121 Name: width
123 Class: Width
124 Switch: -width
125 Specifies a desired width for the button. If an image or bitmap is
126 being displayed in the button then the value is in screen units
127 (i.e. any of the forms acceptable to Tk_GetPixels); for text it is
128 in characters. If this option isn't specified, the button's
129 desired width is computed from the size of the image or bitmap or
130 text being displayed in it.
131
133 The Checkbutton method creates a new window (given by the $widget argu‐
134 ment) and makes it into a checkbutton widget. Additional options,
135 described above, may be specified on the command line or in the option
136 database to configure aspects of the checkbutton such as its colors,
137 font, text, and initial relief. The checkbutton command returns its
138 $widget argument. At the time this command is invoked, there must not
139 exist a window named $widget, but $widget's parent must exist.
140 A checkbutton is a widget that displays a textual string, bitmap or
142 image and a square called an indicator. If text is displayed, it must
143 all be in a single font, but it can occupy multiple lines on the screen
144 (if it contains newlines or if wrapping occurs because of the
145 wrapLength option) and one of the characters may optionally be under‐
146 lined using the underline option. A checkbutton has all of the behav‐
147 ior of a simple button, including the following: it can display itself
148 in either of three different ways, according to the state option; it
149 can be made to appear raised, sunken, or flat; it can be made to flash;
150 and it invokes a perl/Tk callback whenever mouse button 1 is clicked
151 over the checkbutton.
152 In addition, checkbuttons can be selected. If a checkbutton is
154 selected then the indicator is normally drawn with a selected appear‐
155 ance, and a Tcl variable associated with the checkbutton is set to a
156 particular value (normally 1). Under Unix, the indicator is drawn with
157 a sunken relief and a special color. Under Windows, the indicator is
158 drawn with a check mark inside. If the checkbutton is not selected,
159 then the indicator is drawn with a deselected appearance, and the asso‐
160 ciated variable is set to a different value (typically 0). Under Unix,
161 the indicator is drawn with a raised relief and no special color.
162 Under Windows, the indicator is drawn without a check mark inside. By
163 default, the name of the variable associated with a checkbutton is the
164 same as the name used to create the checkbutton. The variable name,
165 and the ``on'' and ``off'' values stored in it, may be modified with
166 options on the command line or in the option database. Configuration
167 options may also be used to modify the way the indicator is displayed
168 (or whether it is displayed at all). By default a checkbutton is con‐
169 figured to select and deselect itself on alternate button clicks. In
170 addition, each checkbutton monitors its associated variable and auto‐
171 matically selects and deselects itself when the variables value changes
172 to and from the button's ``on'' value.
173
175 The Checkbutton method creates a widget object. This object supports
176 the configure and cget methods described in Tk::options which can be
177 used to enquire and modify the options described above. The widget
178 also inherits all the methods provided by the generic Tk::Widget class.
179 The following additional methods are available for checkbutton widgets:
181 $checkbutton->deselect
183 Deselects the checkbutton and sets the associated variable to its
184 ``off'' value.
185 $checkbutton->flash
187 Flashes the checkbutton. This is accomplished by redisplaying the
188 checkbutton several times, alternating between active and normal
189 colors. At the end of the flash the checkbutton is left in the
190 same normal/active state as when the command was invoked. This
191 command is ignored if the checkbutton's state is disabled.
192 $checkbutton->invoke
194 Does just what would have happened if the user invoked the check‐
195 button with the mouse: toggle the selection state of the button and
196 invoke the perl/Tk callback associated with the checkbutton, if
197 there is one. The return value is the return value from the
198 perl/Tk callback, or an empty string if there is no command associ‐
199 ated with the checkbutton. This command is ignored if the check‐
200 button's state is disabled.
201 $checkbutton->select
203 Selects the checkbutton and sets the associated variable to its
204 ``on'' value.
205 $checkbutton->toggle
207 Toggles the selection state of the button, redisplaying it and mod‐
208 ifying its associated variable to reflect the new state.
209
211 Tk automatically creates class bindings for checkbuttons that give them
212 the following default behavior:
213 [1] On Unix systems, a checkbutton activates whenever the mouse passes
215 over it and deactivates whenever the mouse leaves the checkbutton.
216 On Mac and Windows systems, when mouse button 1 is pressed over a
217 checkbutton, the button activates whenever the mouse pointer is
218 inside the button, and deactivates whenever the mouse pointer
219 leaves the button.
220 [2] When mouse button 1 is pressed over a checkbutton, it is invoked
222 (its selection state toggles and the command associated with the
223 button is invoked, if there is one).
224 [3] When a checkbutton has the input focus, the space key causes the
226 checkbutton to be invoked. Under Windows, there are additional key
227 bindings; plus (+) and equal (=) select the button, and minus (-)
228 deselects the button.
229 If the checkbutton's state is disabled then none of the above
231 actions occur: the checkbutton is completely non-responsive.
232 The behavior of checkbuttons can be changed by defining new bind‐
234 ings for individual widgets or by redefining the class bindings.
235
237 checkbutton, widget
238perl v5.8.8 2008-02-05 Checkbutton(3)