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

NAME

8       checkbutton - Create and manipulate checkbutton widgets
9

SYNOPSIS

11       checkbutton pathName ?options?
12

STANDARD OPTIONS

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
23       See the options manual entry for details on the standard options.
24

WIDGET-SPECIFIC OPTIONS

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 is not 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 “1”.
50       [-overrelief overRelief] Specifies an alternative relief for the check‐
51       button, to be used when the mouse cursor  is  over  the  widget.   This
52       option can be used to make toolbar buttons, by configuring -relief flat
53       -overrelief raised.  If the value of this option is the  empty  string,
54       then  no  alternative  relief is used when the mouse cursor is over the
55       checkbutton.   The  empty  string  is  the  default  value.   [-select‐
56       color selectColor]  Specifies a background color to use when the button
57       is selected.  If indicatorOn is true then the  color  is  used  as  the
58       background  for the indicator regardless of the select state.  If indi‐
59       catorOn is false, this color is used as the background for  the  entire
60       widget, in place of background or activeBackground, whenever the widget
61       is selected.  If specified as an empty string then no special color  is
62       used  for displaying when the widget is selected.  [-selectimage selec‐
63       tImage] Specifies an image to display (in place of  the  image  option)
64       when  the  checkbutton  is selected.  This option is ignored unless the
65       image option has been specified.  [-state state] Specifies one of three
66       states  for  the  checkbutton:  normal, active, or disabled.  In normal
67       state the checkbutton is displayed using the foreground and  background
68       options.   The  active state is typically used when the pointer is over
69       the checkbutton.  In active state the checkbutton  is  displayed  using
70       the  activeForeground  and  activeBackground  options.   Disabled state
71       means that the checkbutton should be insensitive:  the default bindings
72       will  refuse  to  activate  the  widget  and  will  ignore mouse button
73       presses.  In this state the disabledForeground and  background  options
74       determine  how  the  checkbutton  is  displayed.  [-tristateimage tris‐
75       tateImage] Specifies an image to display (in place of the image option) │
76       when  the  checkbutton  is  in  tri-state mode.  This option is ignored │
77       unless the image option has been specified.   [-tristatevalue tristate‐
78       Value]  Specifies  the value that causes the checkbutton to display the │
79       multi-value selection, also known as the tri-state mode.   Defaults  to │
80       “”.   [-variable variable]  Specifies  the name of a global variable to
81       set to indicate whether or not this button is  selected.   Defaults  to
82       the  name of the button within its parent (i.e. the last element of the
83       button window's path name).  [-width width] Specifies a  desired  width
84       for the button.  If an image or bitmap is being displayed in the button
85       then the value is in screen units (i.e. any of the forms acceptable  to
86       Tk_GetPixels);  for  text  it  is in characters.  If this option is not
87       specified, the button's desired width is computed from the size of  the
88       image or bitmap or text being displayed in it.
89_________________________________________________________________
90

DESCRIPTION

92       The  checkbutton  command  creates  a new window (given by the pathName
93       argument) and makes it into a checkbutton widget.  Additional  options,
94       described  above, may be specified on the command line or in the option
95       database to configure aspects of the checkbutton such  as  its  colors,
96       font,  text,  and  initial relief.  The checkbutton command returns its
97       pathName argument.  At the time this command is invoked, there must not
98       exist a window named pathName, but pathName's parent must exist.
99
100       A  checkbutton  is  a  widget that displays a textual string, bitmap or
101       image and a square called an indicator.  If text is displayed, it  must
102       all be in a single font, but it can occupy multiple lines on the screen
103       (if  it  contains  newlines  or  if  wrapping  occurs  because  of  the
104       wrapLength  option)  and one of the characters may optionally be under‐
105       lined using the underline option.  A checkbutton has all of the  behav‐
106       ior  of a simple button, including the following: it can display itself
107       in either of three different ways, according to the  state  option;  it
108       can be made to appear raised, sunken, or flat; it can be made to flash;
109       and it invokes a Tcl command whenever mouse button 1  is  clicked  over
110       the checkbutton.
111
112       In  addition,  checkbuttons  can  be  selected.   If  a  checkbutton is
113       selected then the indicator is normally drawn with a  selected  appear‐
114       ance,  and  a  Tcl variable associated with the checkbutton is set to a
115       particular value (normally 1).  The indicator is  drawn  with  a  check │
116       mark inside.  If the checkbutton is not selected, then the indicator is │
117       drawn with a deselected appearance, and the associated variable is  set │
118       to  a  different value (typically 0).  The indicator is drawn without a │
119       check mark inside.  In the special case where the variable  (if  speci‐ │
120       fied)  has  a  value  that  matches the tristatevalue, the indicator is │
121       drawn with a tri-state appearance and is in the tri-state mode indicat‐ │
122       ing  mixed or multiple values.  (This is used when the check box repre‐ │
123       sents the state of multiple items.)  The indicator is drawn in a  plat‐ │
124       form dependent manner.  Under Unix and Windows, the background interior │
125       of the box is “grayed”.  Under Mac, the indicator is drawn with a  dash │
126       mark  inside.   By  default, the name of the variable associated with a │
127       checkbutton is the same as the name used  to  create  the  checkbutton. │
128       The  variable name, and the “on”, “off” and “tristate” values stored in │
129       it, may be modified with options on the command line or in  the  option │
130       database.  Configuration options may also be used to modify the way the │
131       indicator is displayed (or whether it is displayed at all).  By default │
132       a  checkbutton is configured to select and deselect itself on alternate │
133       button clicks.  In addition, each checkbutton monitors  its  associated │
134       variable  and automatically selects and deselects itself when the vari‐ │
135       ables value changes to and from the button's “on”, “off” and “tristate” │
136       values.
137

WIDGET COMMAND

139       The  checkbutton  command creates a new Tcl command whose name is path‐
140       Name.  This command may be used to invoke  various  operations  on  the
141       widget.  It has the following general form:
142              pathName option ?arg arg ...?
143       Option  and  the args determine the exact behavior of the command.  The
144       following commands are possible for checkbutton widgets:
145
146       pathName cget option
147              Returns the current value of the configuration option  given  by
148              option.   Option  may  have  any  of  the values accepted by the
149              checkbutton command.
150
151       pathName configure ?option? ?value option value ...?
152              Query or modify the configuration options of the widget.  If  no
153              option is specified, returns a list describing all of the avail‐
154              able options for pathName (see Tk_ConfigureInfo for  information
155              on  the  format  of  this list).  If option is specified with no
156              value, then the command returns a list describing the one  named
157              option (this list will be identical to the corresponding sublist
158              of the value returned if no option is  specified).   If  one  or
159              more option-value pairs are specified, then the command modifies
160              the given widget option(s) to have the given value(s);  in  this
161              case  the  command returns an empty string.  Option may have any
162              of the values accepted by the checkbutton command.
163
164       pathName deselect
165              Deselects the checkbutton and sets the  associated  variable  to
166              its “off” value.
167
168       pathName flash
169              Flashes  the  checkbutton.  This is accomplished by redisplaying
170              the checkbutton several times, alternating  between  active  and
171              normal  colors.  At the end of the flash the checkbutton is left
172              in the same normal/active state as when the command was invoked.
173              This command is ignored if the checkbutton's state is disabled.
174
175       pathName invoke
176              Does  just  what  would  have  happened  if the user invoked the
177              checkbutton with the mouse: toggle the selection  state  of  the
178              button  and invoke the Tcl command associated with the checkbut‐
179              ton, if there is one.  The return value is the return value from
180              the Tcl command, or an empty string if there is no command asso‐
181              ciated with the checkbutton.  This command  is  ignored  if  the
182              checkbutton's state is disabled.
183
184       pathName select
185              Selects  the checkbutton and sets the associated variable to its
186              “on” value.
187
188       pathName toggle
189              Toggles the selection state of the button, redisplaying  it  and
190              modifying its associated variable to reflect the new state.
191

BINDINGS

193       Tk automatically creates class bindings for checkbuttons that give them
194       the following default behavior:
195
196       [1]    On Unix systems, a  checkbutton  activates  whenever  the  mouse
197              passes  over  it  and  deactivates whenever the mouse leaves the
198              checkbutton.  On Mac and Windows systems, when mouse button 1 is
199              pressed  over  a  checkbutton, the button activates whenever the
200              mouse pointer is inside the button, and deactivates whenever the
201              mouse pointer leaves the button.
202
203       [2]    When mouse button 1 is pressed over a checkbutton, it is invoked
204              (its selection state toggles and the command associated with the
205              button is invoked, if there is one).
206
207       [3]    When a checkbutton has the input focus, the space key causes the
208              checkbutton to be invoked.  Under Windows, there are  additional
209              key  bindings;  plus  (+)  and  equal (=) select the button, and
210              minus (-) deselects the button.
211
212       If the checkbutton's state is disabled then none of the  above  actions
213       occur:  the checkbutton is completely non-responsive.
214
215       The  behavior  of  checkbuttons can be changed by defining new bindings
216       for individual widgets or by redefining the class bindings.
217

EXAMPLE

219       This example shows a group of uncoupled checkbuttons.
220
221                  labelframe .lbl -text "Steps:"
222                  checkbutton .c1 -text Lights  -variable lights
223                  checkbutton .c2 -text Cameras -variable cameras
224                  checkbutton .c3 -text Action! -variable action
225                  pack .c1 .c2 .c3 -in .lbl
226                  pack .lbl
227

SEE ALSO

229       button(n), options(n), radiobutton(n), ttk::checkbutton(n)
230

KEYWORDS

232       checkbutton, widget
233
234
235
236Tk                                    4.4                       checkbutton(n)
Impressum