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
13 -borderwidth -compound -cursor -disabledforeground -font -foreground
14 -highlightbackground -highlightcolor -highlightthickness -image
15 -justify -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
53 -overrelief raised, the effect is achieved of having a flat button
54 that raises on mouse-over and which is depressed when activated.
55 This is the behavior typically exhibited by the Bold, Italic, and
56 Underline checkbuttons on the toolbar of a word-processor, for
57 example.
58 Name: offValue
60 Class: Value
61 Switch: -offvalue
62 Specifies value to store in the button's associated variable
63 whenever this button is deselected. Defaults to ``0''.
64 Name: onValue
66 Class: Value
67 Switch: -onvalue
68 Specifies value to store in the button's associated variable
69 whenever this button is selected. Defaults to ``1''.
70 Command-Line Name: -overrelief
72 Database Name: overRelief
73 Database Class: OverRelief
74 Specifies an alternative relief for the button, to be used when
75 the mouse cursor is over the widget. This option can be used to
76 make toolbar buttons, by configuring -relief flat -overrelief
77 raised. If the value of this option is the empty string, then no
78 alternative relief is used when the mouse cursor is over the
79 button. The empty string is the default value.
80 Name: selectColor
82 Class: Background
83 Switch: -selectcolor
84 Specifies a background color to use when the button is selected.
85 If indicatorOn is true then the color applies to the indicator.
86 Under Windows, this color is used as the background for the
87 indicator regardless of the select state. If indicatorOn is false,
88 this color is used as the background for the entire widget, in
89 place of background or activeBackground, whenever the widget is
90 selected. If specified as an empty string then no special color is
91 used for displaying when the widget is selected.
92 Name: selectImage
94 Class: SelectImage
95 Switch: -selectimage
96 Specifies an image to display (in place of the image option) when
97 the checkbutton is selected. This option is ignored unless the
98 image option has been specified.
99 Name: state
101 Class: State
102 Switch: -state
103 Specifies one of three states for the checkbutton: normal, active,
104 or disabled. In normal state the checkbutton is displayed using
105 the foreground and background options. The active state is
106 typically used when the pointer is over the checkbutton. In active
107 state the checkbutton is displayed using the activeForeground and
108 activeBackground options. Disabled state means that the
109 checkbutton should be insensitive: the default bindings will
110 refuse to activate the widget and will ignore mouse button presses.
111 In this state the disabledForeground and background options
112 determine how the checkbutton is displayed.
113 Name: variable
115 Class: Variable
116 Switch: -variable
117 Specifies reference to a variable to set to indicate whether or not
118 this button is selected. Defaults to "\$widget->{'Value'}" member
119 of the widget's hash. In general perl variables are "undef" unless
120 specifically initialized which will not match either default
121 -onvalue or default -offvalue.
122 Name: width
124 Class: Width
125 Switch: -width
126 Specifies a desired width for the button. If an image or bitmap is
127 being displayed in the button then the value is in screen units
128 (i.e. any of the forms acceptable to Tk_GetPixels); for text it is
129 in characters. If this option isn't specified, the button's
130 desired width is computed from the size of the image or bitmap or
131 text being displayed in it.
132
134 The Checkbutton method creates a new window (given by the $widget
135 argument) and makes it into a checkbutton widget. Additional options,
136 described above, may be specified on the command line or in the option
137 database to configure aspects of the checkbutton such as its colors,
138 font, text, and initial relief. The checkbutton command returns its
139 $widget argument. At the time this command is invoked, there must not
140 exist a window named $widget, but $widget's parent must exist.
141 A checkbutton is a widget that displays a textual string, bitmap or
143 image and a square called an indicator. If text is displayed, it must
144 all be in a single font, but it can occupy multiple lines on the screen
145 (if it contains newlines or if wrapping occurs because of the
146 wrapLength option) and one of the characters may optionally be
147 underlined using the underline option. A checkbutton has all of the
148 behavior of a simple button, including the following: it can display
149 itself in either of three different ways, according to the state
150 option; it can be made to appear raised, sunken, or flat; it can be
151 made to flash; and it invokes a perl/Tk callback whenever mouse button
152 1 is clicked over the checkbutton.
153 In addition, checkbuttons can be selected. If a checkbutton is
155 selected then the indicator is normally drawn with a selected
156 appearance, and a Tcl variable associated with the checkbutton is set
157 to a particular value (normally 1). Under Unix, the indicator is drawn
158 with a sunken relief and a special color. Under Windows, the indicator
159 is drawn with a check mark inside. If the checkbutton is not selected,
160 then the indicator is drawn with a deselected appearance, and the
161 associated variable is set to a different value (typically 0). Under
162 Unix, the indicator is drawn with a raised relief and no special color.
163 Under Windows, the indicator is drawn without a check mark inside. By
164 default, the name of the variable associated with a checkbutton is the
165 same as the name used to create the checkbutton. The variable name,
166 and the ``on'' and ``off'' values stored in it, may be modified with
167 options on the command line or in the option database. Configuration
168 options may also be used to modify the way the indicator is displayed
169 (or whether it is displayed at all). By default a checkbutton is
170 configured to select and deselect itself on alternate button clicks.
171 In addition, each checkbutton monitors its associated variable and
172 automatically selects and deselects itself when the variables value
173 changes to and from the button's ``on'' value.
174
176 The Checkbutton method creates a widget object. This object supports
177 the configure and cget methods described in Tk::options which can be
178 used to enquire and modify the options described above. The widget
179 also inherits all the methods provided by the generic Tk::Widget class.
180 The following additional methods are available for checkbutton widgets:
182 $checkbutton->deselect
184 Deselects the checkbutton and sets the associated variable to its
185 ``off'' value.
186 $checkbutton->flash
188 Flashes the checkbutton. This is accomplished by redisplaying the
189 checkbutton several times, alternating between active and normal
190 colors. At the end of the flash the checkbutton is left in the
191 same normal/active state as when the command was invoked. This
192 command is ignored if the checkbutton's state is disabled.
193 $checkbutton->invoke
195 Does just what would have happened if the user invoked the
196 checkbutton with the mouse: toggle the selection state of the
197 button and invoke the perl/Tk callback associated with the
198 checkbutton, if there is one. The return value is the return value
199 from the perl/Tk callback, or an empty string if there is no
200 command associated with the checkbutton. This command is ignored
201 if the checkbutton's state is disabled.
202 $checkbutton->select
204 Selects the checkbutton and sets the associated variable to its
205 ``on'' value.
206 $checkbutton->toggle
208 Toggles the selection state of the button, redisplaying it and
209 modifying its associated variable to reflect the new state.
210
212 Tk automatically creates class bindings for checkbuttons that give them
213 the following default behavior:
214 [1] On Unix systems, a checkbutton activates whenever the mouse passes
216 over it and deactivates whenever the mouse leaves the checkbutton.
217 On Mac and Windows systems, when mouse button 1 is pressed over a
218 checkbutton, the button activates whenever the mouse pointer is
219 inside the button, and deactivates whenever the mouse pointer
220 leaves the button.
221 [2] When mouse button 1 is pressed over a checkbutton, it is invoked
223 (its selection state toggles and the command associated with the
224 button is invoked, if there is one).
225 [3] When a checkbutton has the input focus, the space key causes the
227 checkbutton to be invoked. Under Windows, there are additional key
228 bindings; plus (+) and equal (=) select the button, and minus (-)
229 deselects the button.
230 If the checkbutton's state is disabled then none of the above
232 actions occur: the checkbutton is completely non-responsive.
233 The behavior of checkbuttons can be changed by defining new
235 bindings for individual widgets or by redefining the class
236 bindings.
237
239 checkbutton, widget
240perl v5.36.0 2023-01-20 Checkbutton(3)