1checkbutton(n)               Tk Built-In Commands               checkbutton(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       checkbutton  -  Create  and  manipulate 'checkbutton' boolean selection
9       widgets
10

SYNOPSIS

12       checkbutton pathName ?options?
13

STANDARD OPTIONS

15       -activebackground     -disabledforeground  -padx
16       -activeforeground     -font                -pady
17       -anchor               -foreground          -relief
18       -background           -highlightbackground -takefocus
19       -bitmap               -highlightcolor      -text
20       -borderwidth          -highlightthickness  -textvariable
21       -compound             -image               -underline
22       -cursor               -justify             -wraplength
23
24       See the options manual entry for details on the standard options.
25

WIDGET-SPECIFIC OPTIONS

27       Command-Line Name:-command
28       Database Name:  command
29       Database Class: Command
30
31              Specifies a Tcl command to associate with the button.  This com‐
32              mand  is  typically invoked when mouse button 1 is released over
33              the button window.   The  button's  global  variable  (-variable
34              option) will be updated before the command is invoked.
35
36       Command-Line Name:-height
37       Database Name:  height
38       Database Class: Height
39
40              Specifies  a desired height for the button.  If an image or bit‐
41              map is being displayed in the button then the value is in screen
42              units  (i.e.  any  of the forms acceptable to Tk_GetPixels); for
43              text it is in lines of text.  If this option is  not  specified,
44              the  button's  desired  height  is computed from the size of the
45              image or bitmap or text being displayed in it.
46
47       Command-Line Name:-indicatoron
48       Database Name:  indicatorOn
49       Database Class: IndicatorOn
50
51              Specifies whether or not the indicator should be drawn.  Must be
52              a proper boolean value.  If false, the -relief option is ignored
53              and the widget's relief  is  always  sunken  if  the  widget  is
54              selected and raised otherwise.
55
56       Command-Line Name:-offrelief
57       Database Name:  offRelief
58       Database Class: OffRelief
59
60              Specifies  the  relief for the checkbutton when the indicator is
61              not drawn and the checkbutton is  off.   The  default  value  is
62              “raised”.  By setting this option to “flat” and setting -indica‐
63              toron to false  and  -overrelief  to  “raised”,  the  effect  is
64              achieved  of  having a flat button that raises on mouse-over and
65              which is depressed when activated.  This is the  behavior  typi‐
66              cally  exhibited by the Bold, Italic, and Underline checkbuttons
67              on the toolbar of a word-processor, for example.
68
69       Command-Line Name:-offvalue
70       Database Name:  offValue
71       Database Class: Value
72
73              Specifies value to store in  the  button's  associated  variable
74              whenever this button is deselected.  Defaults to “0”.
75
76       Command-Line Name:-onvalue
77       Database Name:  onValue
78       Database Class: Value
79
80              Specifies  value  to  store  in the button's associated variable
81              whenever this button is selected.  Defaults to “1”.
82
83       Command-Line Name:-overrelief
84       Database Name:  overRelief
85       Database Class: OverRelief
86
87              Specifies an alternative relief for the checkbutton, to be  used
88              when  the  mouse  cursor is over the widget.  This option can be
89              used to make toolbar buttons, by configuring -relief flat -over‐
90              relief raised.  If the value of this option is the empty string,
91              then no alternative relief is used when the mouse cursor is over
92              the checkbutton.  The empty string is the default value.
93
94       Command-Line Name:-selectcolor
95       Database Name:  selectColor
96       Database Class: Background
97
98              Specifies a background color to use when the button is selected.
99              If indicatorOn is true then the color is used as the  background
100              for  the  indicator  regardless of the select state.  If indica‐
101              torOn is false, this color is used as  the  background  for  the
102              entire widget, in place of background or activeBackground, when‐
103              ever the widget is selected.  If specified as  an  empty  string
104              then  no special color is used for displaying when the widget is
105              selected.
106
107       Command-Line Name:-selectimage
108       Database Name:  selectImage
109       Database Class: SelectImage
110
111              Specifies an image to display (in place of  the  -image  option)
112              when the checkbutton is selected.  This option is ignored unless
113              the -image option has been specified.
114
115       Command-Line Name:-state
116       Database Name:  state
117       Database Class: State
118
119              Specifies one of three  states  for  the  checkbutton:   normal,
120              active,  or  disabled.   In normal state the checkbutton is dis‐
121              played using  the  -foreground  and  -background  options.   The
122              active  state  is  typically  used  when the pointer is over the
123              checkbutton.  In active state the checkbutton is displayed using
124              the  -activeforeground  and -activebackground options.  Disabled
125              state means that the checkbutton  should  be  insensitive:   the
126              default  bindings  will  refuse  to activate the widget and will
127              ignore mouse button presses.  In this state  the  -disabledfore‐
128              ground  and -background options determine how the checkbutton is
129              displayed.
130
131       Command-Line Name:-tristateimage
132       Database Name:  tristateImage
133       Database Class: TristateImage
134
135              Specifies an image to display (in place of  the  -image  option)
136              when  the  checkbutton  is  in  tri-state  mode.  This option is
137              ignored unless the -image option has been specified.
138
139       Command-Line Name:-tristatevalue
140       Database Name:  tristateValue
141       Database Class: Value
142
143              Specifies the value that causes the checkbutton to  display  the
144              multi-value   selection,  also  known  as  the  tri-state  mode.
145              Defaults to “”.
146
147       Command-Line Name:-variable
148       Database Name:  variable
149       Database Class: Variable
150
151              Specifies the name of a  global  variable  to  set  to  indicate
152              whether or not this button is selected.  Defaults to the name of
153              the button within its parent (i.e. the last element of the  but‐
154              ton window's path name).
155
156       Command-Line Name:-width
157       Database Name:  width
158       Database Class: Width
159
160              Specifies a desired width for the button.  If an image or bitmap
161              is being displayed in the button then the  value  is  in  screen
162              units  (i.e.  any  of the forms acceptable to Tk_GetPixels); for
163              text it is in characters.  If this option is not specified,  the
164              button's desired width is computed from the size of the image or
165              bitmap or text being displayed in it.
166______________________________________________________________________________
167

DESCRIPTION

169       The checkbutton command creates a new window  (given  by  the  pathName
170       argument)  and makes it into a checkbutton widget.  Additional options,
171       described above, may be specified on the command line or in the  option
172       database  to  configure  aspects of the checkbutton such as its colors,
173       font, text, and initial relief.  The checkbutton  command  returns  its
174       pathName argument.  At the time this command is invoked, there must not
175       exist a window named pathName, but pathName's parent must exist.
176
177       A checkbutton is a widget that displays a  textual  string,  bitmap  or
178       image  and a square called an indicator.  If text is displayed, it must
179       all be in a single font, but it can occupy multiple lines on the screen
180       (if  it  contains  newlines  or  if  wrapping  occurs  because  of  the
181       -wraplength option) and one of the characters may optionally be  under‐
182       lined using the -underline option.  A checkbutton has all of the behav‐
183       ior of a simple button, including the following: it can display  itself
184       in  either  of three different ways, according to the -state option; it
185       can be made to appear raised, sunken, or flat; it can be made to flash;
186       and  it  invokes  a Tcl command whenever mouse button 1 is clicked over
187       the checkbutton.
188
189       In addition,  checkbuttons  can  be  selected.   If  a  checkbutton  is
190       selected  then  the indicator is normally drawn with a selected appear‐
191       ance, and a Tcl variable associated with the checkbutton is  set  to  a
192       particular  value  (normally  1).   The indicator is drawn with a check
193       mark inside.  If the checkbutton is not selected, then the indicator is
194       drawn  with a deselected appearance, and the associated variable is set
195       to a different value (typically 0).  The indicator is drawn  without  a
196       check  mark  inside.  In the special case where the variable (if speci‐
197       fied) has a value that matches  the  tristatevalue,  the  indicator  is
198       drawn with a tri-state appearance and is in the tri-state mode indicat‐
199       ing mixed or multiple values.  (This is used when the check box  repre‐
200       sents  the state of multiple items.)  The indicator is drawn in a plat‐
201       form dependent manner.  Under Unix and Windows, the background interior
202       of  the box is “grayed”.  Under Mac, the indicator is drawn with a dash
203       mark inside.  By default, the name of the variable  associated  with  a
204       checkbutton  is  the  same  as the name used to create the checkbutton.
205       The variable name, and the “on”, “off” and “tristate” values stored  in
206       it,  may  be modified with options on the command line or in the option
207       database.  Configuration options may also be used to modify the way the
208       indicator is displayed (or whether it is displayed at all).  By default
209       a checkbutton is configured to select and deselect itself on  alternate
210       button  clicks.   In addition, each checkbutton monitors its associated
211       variable and automatically selects and deselects itself when the  vari‐
212       ables value changes to and from the button's “on”, “off” and “tristate”
213       values.
214

WIDGET COMMAND

216       The checkbutton command creates a new Tcl command whose name  is  path‐
217       Name.   This  command  may  be used to invoke various operations on the
218       widget.  It has the following general form:
219              pathName option ?arg arg ...?
220       Option and the args determine the exact behavior of the  command.   The
221       following commands are possible for checkbutton widgets:
222
223       pathName cget option
224              Returns  the  current value of the configuration option given by
225              option.  Option may have any  of  the  values  accepted  by  the
226              checkbutton command.
227
228       pathName configure ?option? ?value option value ...?
229              Query  or modify the configuration options of the widget.  If no
230              option is specified, returns a list describing all of the avail‐
231              able  options for pathName (see Tk_ConfigureInfo for information
232              on the format of this list).  If option  is  specified  with  no
233              value,  then the command returns a list describing the one named
234              option (this list will be identical to the corresponding sublist
235              of  the  value  returned  if no option is specified).  If one or
236              more option-value pairs are specified, then the command modifies
237              the  given widget option(s) to have the given value(s);  in this
238              case the command returns an empty string.  Option may  have  any
239              of the values accepted by the checkbutton command.
240
241       pathName deselect
242              Deselects  the  checkbutton  and sets the associated variable to
243              its “off” value.
244
245       pathName flash
246              Flashes the checkbutton.  This is accomplished  by  redisplaying
247              the  checkbutton  several  times, alternating between active and
248              normal colors.  At the end of the flash the checkbutton is  left
249              in the same normal/active state as when the command was invoked.
250              This command is ignored if the checkbutton's state is disabled.
251
252       pathName invoke
253              Does just what would have  happened  if  the  user  invoked  the
254              checkbutton  with  the  mouse: toggle the selection state of the
255              button and invoke the Tcl command associated with the  checkbut‐
256              ton, if there is one.  The return value is the return value from
257              the Tcl command, or an empty string if there is no command asso‐
258              ciated  with  the  checkbutton.   This command is ignored if the
259              checkbutton's state is disabled.
260
261       pathName select
262              Selects the checkbutton and sets the associated variable to  its
263              “on” value.
264
265       pathName toggle
266              Toggles  the  selection state of the button, redisplaying it and
267              modifying its associated variable to reflect the new state.
268

BINDINGS

270       Tk automatically creates class bindings for checkbuttons that give them
271       the following default behavior:
272
273       [1]    On  Unix  systems,  a  checkbutton  activates whenever the mouse
274              passes over it and deactivates whenever  the  mouse  leaves  the
275              checkbutton.  On Mac and Windows systems, when mouse button 1 is
276              pressed over a checkbutton, the button  activates  whenever  the
277              mouse pointer is inside the button, and deactivates whenever the
278              mouse pointer leaves the button.
279
280       [2]    When mouse button 1 is pressed over a checkbutton, it is invoked
281              (its selection state toggles and the command associated with the
282              button is invoked, if there is one).
283
284       [3]    When a checkbutton has the input focus, the space key causes the
285              checkbutton  to be invoked.  Under Windows, there are additional
286              key bindings; plus (+) and equal  (=)  select  the  button,  and
287              minus (-) deselects the button.
288
289       If  the  checkbutton's state is disabled then none of the above actions
290       occur:  the checkbutton is completely non-responsive.
291
292       The behavior of checkbuttons can be changed by  defining  new  bindings
293       for individual widgets or by redefining the class bindings.
294

EXAMPLE

296       This example shows a group of uncoupled checkbuttons.
297
298              labelframe .lbl -text "Steps:"
299              checkbutton .c1 -text Lights  -variable lights
300              checkbutton .c2 -text Cameras -variable cameras
301              checkbutton .c3 -text Action! -variable action
302              pack .c1 .c2 .c3 -in .lbl
303              pack .lbl
304

SEE ALSO

306       button(n), options(n), radiobutton(n), ttk::checkbutton(n)
307

KEYWORDS

309       checkbutton, widget
310
311
312
313Tk                                    4.4                       checkbutton(n)
Impressum