1checkbutton(n) Tk Built-In Commands checkbutton(n)
2______________________________________________________________________________
6
8 checkbutton - Create and manipulate checkbutton widgets
9
11 checkbutton pathName ?options?
12
14 -activebackground -disabledforeground -padx
15 -activeforeground -font -pady
16 -anchor -foreground -relief
17 -background -highlightbackground -takefocus
18 -bitmap -highlightcolor -text
19 -borderwidth -highlightthickness -textvariable
20 -compound -image -underline
21 -cursor -justify -wraplength
22 See the options manual entry for details on the standard options.
24
26 [-command command] Specifies a Tcl command to associate with the but‐
27 ton. This command is typically invoked when mouse button 1 is released
28 over the button window. The button's global variable (-variable
29 option) will be updated before the command is invoked.
30 [-height height] Specifies a desired height for the button. If an
31 image or bitmap is being displayed in the button then the value is in
32 screen units (i.e. any of the forms acceptable to Tk_GetPixels); for
33 text it is in lines of text. If this option isn't specified, the but‐
34 ton's desired height is computed from the size of the image or bitmap
35 or text being displayed in it. [-indicatoron indicatorOn] Specifies
36 whether or not the indicator should be drawn. Must be a proper boolean
37 value. If false, the relief option is ignored and the widget's relief
38 is always sunken if the widget is selected and raised otherwise. │
39 [-offrelief offRelief] Specifies the relief for the checkbutton when │
40 the indicator is not drawn and the checkbutton is off. The default │
41 value is "raised". By setting this option to "flat" and setting -indi‐ │
42 catoron to false and -overrelief to raised, the effect is achieved of │
43 having a flat button that raises on mouse-over and which is depressed │
44 when activated. This is the behavior typically exhibited by the Bold, │
45 Italic, and Underline checkbuttons on the toolbar of a word-processor, │
46 for example. [-offvalue offValue] Specifies value to store in the but‐
47 ton's associated variable whenever this button is deselected. Defaults
48 to ``0''. [-onvalue onValue] Specifies value to store in the button's
49 associated variable whenever this button is selected. Defaults to
50 ``1''. [-overrelief overRelief] Specifies an alternative relief for │
51 the checkbutton, to be used when the mouse cursor is over the widget. │
52 This option can be used to make toolbar buttons, by configuring -relief │
53 flat -overrelief raised. If the value of this option is the empty │
54 string, then no alternative relief is used when the mouse cursor is │
55 over the checkbutton. The empty string is the default value.
56 [-selectcolor selectColor] Specifies a background color to use when the
57 button is selected. If indicatorOn is true then the color applies to
58 the indicator. Under Windows, this color is used as the background for
59 the indicator regardless of the select state. If indicatorOn is false,
60 this color is used as the background for the entire widget, in place of
61 background or activeBackground, whenever the widget is selected. If
62 specified as an empty string then no special color is used for display‐
63 ing when the widget is selected. [-selectimage selectImage] Specifies
64 an image to display (in place of the image option) when the checkbutton
65 is selected. This option is ignored unless the image option has been
66 specified. [-state state] Specifies one of three states for the check‐
67 button: normal, active, or disabled. In normal state the checkbutton
68 is displayed using the foreground and background options. The active
69 state is typically used when the pointer is over the checkbutton. In
70 active state the checkbutton is displayed using the activeForeground
71 and activeBackground options. Disabled state means that the checkbut‐
72 ton should be insensitive: the default bindings will refuse to acti‐
73 vate the widget and will ignore mouse button presses. In this state
74 the disabledForeground and background options determine how the check‐
75 button is displayed. [-variable variable] Specifies name of global
76 variable to set to indicate whether or not this button is selected.
77 Defaults to the name of the button within its parent (i.e. the last
78 element of the button window's path name). [-width width] Specifies a
79 desired width for the button. If an image or bitmap is being displayed
80 in the button then the value is in screen units (i.e. any of the forms
81 acceptable to Tk_GetPixels); for text it is in characters. If this
82 option isn't specified, the button's desired width is computed from the
83 size of the image or bitmap or text being displayed in it.
84_________________________________________________________________
85
88 The checkbutton command creates a new window (given by the pathName
89 argument) and makes it into a checkbutton widget. Additional options,
90 described above, may be specified on the command line or in the option
91 database to configure aspects of the checkbutton such as its colors,
92 font, text, and initial relief. The checkbutton command returns its
93 pathName argument. At the time this command is invoked, there must not
94 exist a window named pathName, but pathName's parent must exist.
95 A checkbutton is a widget that displays a textual string, bitmap or
97 image and a square called an indicator. If text is displayed, it must
98 all be in a single font, but it can occupy multiple lines on the screen
99 (if it contains newlines or if wrapping occurs because of the
100 wrapLength option) and one of the characters may optionally be under‐
101 lined using the underline option. A checkbutton has all of the behav‐
102 ior of a simple button, including the following: it can display itself
103 in either of three different ways, according to the state option; it
104 can be made to appear raised, sunken, or flat; it can be made to flash;
105 and it invokes a Tcl command whenever mouse button 1 is clicked over
106 the checkbutton.
107 In addition, checkbuttons can be selected. If a checkbutton is
109 selected then the indicator is normally drawn with a selected appear‐ │
110 ance, and a Tcl variable associated with the checkbutton is set to a │
111 particular value (normally 1). Under Unix, the indicator is drawn with │
112 a sunken relief and a special color. Under Windows, the indicator is │
113 drawn with a check mark inside. If the checkbutton is not selected, │
114 then the indicator is drawn with a deselected appearance, and the asso‐ │
115 ciated variable is set to a different value (typically 0). Under Unix, │
116 the indicator is drawn with a raised relief and no special color. │
117 Under Windows, the indicator is drawn without a check mark inside. By
118 default, the name of the variable associated with a checkbutton is the
119 same as the name used to create the checkbutton. The variable name,
120 and the ``on'' and ``off'' values stored in it, may be modified with
121 options on the command line or in the option database. Configuration
122 options may also be used to modify the way the indicator is displayed
123 (or whether it is displayed at all). By default a checkbutton is con‐
124 figured to select and deselect itself on alternate button clicks. In
125 addition, each checkbutton monitors its associated variable and auto‐
126 matically selects and deselects itself when the variables value changes
127 to and from the button's ``on'' value.
128
130 The checkbutton command creates a new Tcl command whose name is path‐
131 Name. This command may be used to invoke various operations on the
132 widget. It has the following general form:
133 pathName option ?arg arg ...?
134 Option and the args determine the exact behavior of the command. The
135 following commands are possible for checkbutton widgets:
136 pathName cget option
138 Returns the current value of the configuration option given by
139 option. Option may have any of the values accepted by the
140 checkbutton command.
141 pathName configure ?option? ?value option value ...?
143 Query or modify the configuration options of the widget. If no
144 option is specified, returns a list describing all of the avail‐
145 able options for pathName (see Tk_ConfigureInfo for information
146 on the format of this list). If option is specified with no
147 value, then the command returns a list describing the one named
148 option (this list will be identical to the corresponding sublist
149 of the value returned if no option is specified). If one or
150 more option-value pairs are specified, then the command modifies
151 the given widget option(s) to have the given value(s); in this
152 case the command returns an empty string. Option may have any
153 of the values accepted by the checkbutton command.
154 pathName deselect
156 Deselects the checkbutton and sets the associated variable to
157 its ``off'' value.
158 pathName flash
160 Flashes the checkbutton. This is accomplished by redisplaying
161 the checkbutton several times, alternating between active and
162 normal colors. At the end of the flash the checkbutton is left
163 in the same normal/active state as when the command was invoked.
164 This command is ignored if the checkbutton's state is disabled.
165 pathName invoke
167 Does just what would have happened if the user invoked the
168 checkbutton with the mouse: toggle the selection state of the
169 button and invoke the Tcl command associated with the checkbut‐
170 ton, if there is one. The return value is the return value from
171 the Tcl command, or an empty string if there is no command asso‐
172 ciated with the checkbutton. This command is ignored if the
173 checkbutton's state is disabled.
174 pathName select
176 Selects the checkbutton and sets the associated variable to its
177 ``on'' value.
178 pathName toggle
180 Toggles the selection state of the button, redisplaying it and
181 modifying its associated variable to reflect the new state.
182
184 Tk automatically creates class bindings for checkbuttons that give them
185 the following default behavior: │
186 [1] │
188 On Unix systems, a checkbutton activates whenever the mouse │
189 passes over it and deactivates whenever the mouse leaves the │
190 checkbutton. On Mac and Windows systems, when mouse button 1 is │
191 pressed over a checkbutton, the button activates whenever the │
192 mouse pointer is inside the button, and deactivates whenever the │
193 mouse pointer leaves the button.
194 [2] When mouse button 1 is pressed over a checkbutton, it is invoked
196 (its selection state toggles and the command associated with the
197 button is invoked, if there is one). │
198 [3] │
200 When a checkbutton has the input focus, the space key causes the │
201 checkbutton to be invoked. Under Windows, there are additional │
202 key bindings; plus (+) and equal (=) select the button, and │
203 minus (-) deselects the button.
204 If the checkbutton's state is disabled then none of the above actions
206 occur: the checkbutton is completely non-responsive.
207 The behavior of checkbuttons can be changed by defining new bindings
209 for individual widgets or by redefining the class bindings.
210
213 button(n), options(n), radiobutton(n)
214
217 checkbutton, widget
218Tk 4.4 checkbutton(n)