Next / Previous / Contents / Shipman's homepage

30. ttk.Checkbutton

This widget is the ttk version of Section 9, “The Checkbutton widget”. To create a ttk.Checkbutton widget as the child of a given parent widget:

    w = ttk.Checkbutton(parent, option=value, ...)

Here are the options for the ttk.Checkbutton widget. Compare these to the Tkinter version discussed in Section 7, “The Button widget”.

Table 37. ttk.Checkbutton options

class_ The widget class name. This may be specified when the widget is created, but cannot be changed later. For an explanation of widget classes, see Section 27, “Standardizing appearance”.
command A function to be called whenever the state of this checkbutton changes.
compound This option specifies the relative position of the image relative to the text when you specify both. The value may be tk.TOP (image above text), tk.BOTTOM (image below text), tk.LEFT (image to the left of the text), or tk.RIGHT (image to the right of the text). If you provide both image and text options but do not specify a value for compound, only the image will appear.
cursor The cursor that will appear when the mouse is over the checkbutton; see Section 5.8, “Cursors”.
image An image to appear on the checkbutton; see Section 5.9, “Images”.
offvalue By default, when a checkbutton is in the off (unchecked) state, the value of the associated variable is 0. You can use the offvalue option to specify a different value for the off state.
onvalue By default, when a checkbutton is in the on (checked) state, the value of the associated variable is 1. You can use the onvalue option to specify a different value for the on state.
style The style to be used in rendering this checkbutton; see Section 49, “Using and customizing ttk styles”.
takefocus By default, a ttk.Checkbutton will be included in focus traversal; see Section 53, “Focus: routing keyboard input”. To remove the widget from focus traversal, use takefocus=False.
text The text to appear on the checkbutton, as a string.
textvariable A variable that controls the text that appears on the checkbutton; see Section 52, “Control variables: the values behind the widgets”.
underline If this option has a nonnegative value n, an underline will appear under the text character at position n.
variable A control variable that tracks the current state of the checkbutton; see Section 52, “Control variables: the values behind the widgets”. Normally you will use an IntVar here, and the off and on values are 0 and 1, respectively. However, you may use a different control variable type, and specify the offvalue and onvalue options using values of that type.
width

Use this option to specify a fixed width or a minimum width. The value is specified in characters; a positive value sets a fixed width of that many average characters, while a negative width sets a minimum width.

For example, if an average character in the selected font is 10 pixels wide, option width=8 will make the text label exactly 80 pixels wide; option width=-8 will use 80 pixels or the length of the text, whichever is larger.

You may also specify a width value in an associated style. If values are specified both in the widget constructor call and in the style, the former takes priority.


These options of the Tkinter Checkbutton widget are not supported by the ttk.Checkbutton widget constructor:

Table 38. Tkinter Checkbutton options not in ttk.Checkbutton

activebackground Use a style map to control the background option; see Section 50.2, “ttk style maps: dynamic appearance changes”.
activeforeground Use a style map to control the foreground option.
anchor

Configure this option using a style; see Section 49, “Using and customizing ttk styles”. Use this option to specify the position of the text when the width option allocates extra horizontal space.

For example, if you specify options width=20 and compound=tk.TOP on a checkbutton that displays both text and and image, and a style that specifies anchor=tk.E (east), the image will be at the right-hand end of the twenty-character space, with the text just below it.

When a checkbutton displays an image but no text, this option is ignored.

background or bg Configure the background option using a style. The bg abbreviation is not supported.
bitmap Not supported.
borderwidth or bd Configure this option using a style.
disabledforeground Use a style map for the foreground option; see Section 50.2, “ttk style maps: dynamic appearance changes”.
font Configure this option using a style.
foreground or fg Configure this option using a style.
height Not supported.
highlightbackground To control the color of the focus highlight when the checkbutton does not have focus, use a style map to control the highlightcolor option; see Section 50.2, “ttk style maps: dynamic appearance changes”.
highlightcolor You may specify the default focus highlight color by setting this option in a style. You may also control the focus highlight color using a style map.
highlightthickness Configure this option using a style. This option may not work in all themes.
indicatoron Not supported.
justify Controls how multiple lines are positioned horizontally relative to each other. Configure this option using a style; values may be tk.LEFT, tk.CENTER, or tk.RIGHT for left-aligned, centered, or right-aligned, respectively.
offrelief Not supported.
overrelief Use a style map to control the relief option; see Section 50.2, “ttk style maps: dynamic appearance changes”.
padx Not supported.
pady Not supported.
relief Use a style map to control the relief option; see Section 50.2, “ttk style maps: dynamic appearance changes”.
selectcolor Not supported.
selectimage Not supported.
state In ttk, there is no option with this name. The state mechanism has been generalized; see Section 50.2, “ttk style maps: dynamic appearance changes”.
wraplength If you use a style that has this option set to some dimension, the text will be sliced into pieces no longer than that dimension.

Methods on a ttk.Checkbutton include all those described in Section 46, “Methods common to all ttk widgets”, plus:

.invoke()

This method toggles the state of the checkbutton. If there is a command callback, it calls that callback, and returns whatever value the callback returned.

Not supported are the following methods of the Tkinter Checkbutton widget: .deselect(), .flash(), .select(), and .toggle(). To change the state of a checkbutton through program control, use the .set() method of the associated control variable.