Modern Tkinter
Widget Pictures

Checkbutton Widgets

The widget roundup provides you with a quick and easy reference to the most important features and options for each Tk widget.


Widget Essentials

When to use: To allow the user to choose between two mutually exclusive choices.
Python:destructFlag = StringVar()
cb = ttk.Checkbutton(parent, text="Self-destruct on close", 
Tcl:ttk::checkbutton .cb -text "Self-destruct on close" 
   -variable destructFlag
Ruby:$destructFlag = ( initialValue );
cb = { 
   text "Self-destruct on close"; variable $destructFlag}
Perl:my $cb = parent->new_ttk__checkbutton
   -text => "Self-destruct on close", -variable => $destructFlag);

Common Options

text The text label to be shown next to the checkbox.
variable A variable linked to the checkbutton; when the variable is changed, the checkbutton will reflect the new value, while if the user toggles the checkbutton, the variable's value will be updated.
Values reflecting the checked (default 1) and unchecked (default 0), which are held in the linked variable. If the variable contains neither of these values, the checkbutton is put into an indeterminate state, which usually implies that the choice has not yet been made (and that a default choice is inappropriate).

How do I...

See if the checkbutton is checked? Look at the linked variable.
Check or uncheck it? Change the linked variable to either the onvalue or offvalue.
See if it's in the indeterminate state? Check if the variable holds a value other than the onvalue and offvalue.
You can also use the "instate alternate" method.
Disable the checkbutton? Use the "state disabled" method.
You can reenable this with "state !disabled".
Check with "instate disabled" (returns 1 if disabled, else 0).

Less Common Options

textvariable As an alternative to text, get the string from a variable, updating when the variable changes.
command The script to invoke when the checkbutton is pressed.
Specify a Tk Image object (not the path to an image file) instead of the text label. If compound is center, top, bottom, left, or right, display the text and the image.