Tkinter reference: a GUI for Python |  |
Tkinter reference: a GUI for Python | |
The purpose of a checkbutton widget (sometimes called “checkbox”) is to allow the user to read and select a two-way choice. The graphic above shows how checkbuttons look in the off (0) and on (1) state in one implementation: this is a screen shot of two checkbuttons using 24-point Times font.
The indicator is the part of the checkbutton that shows its state, and the label is the text that appears beside it.
You will need to create a control variable, an
instance of the IntVar class, so
your program can query and set the state of the
checkbutton. See Section 22, “Control variables: the values behind the widgets”,
below.
You can also use event bindings to react to user actions on the checkbutton; see Section 24, “Events”, below.
You can disable a checkbutton. This changes its appearance to “grayed out” and makes it unresponsive to the mouse.
You can get rid of the checkbutton indicator and make the whole widget a “push-push” button that looks recessed when it is set, and looks raised when it is cleared.
To create a checkbutton in an existing parent window or
frame
master
w= Checkbutton (master,option, ... )
The constructor returns a new
Checkbutton object. Options
include:
activebackground | Background color when the checkbutton is under the cursor. See Section 4.3, “Colors”. |
activeforeground | Foreground color when the checkbutton is under the cursor. |
anchor | If the widget inhabits a space larger than it
needs, this option specifies where the checkbutton
will sit in that space. The default is
anchor=CENTER. See Section 4.5, “Anchors” for the allowable values. For
example, if you use
anchor=NW, the widget will
be placed in the upper left corner of the space. |
bg or
background | The normal background color displayed behind the label and indicator. See Section 4.3, “Colors”. |
bitmap | To display a monochrome image on a button, set this option to a bitmap; see Section 4.7, “Bitmaps”. |
bd or
borderwidth | The size of the border around the indicator. Default is 2 pixels. For possible values, see Section 4.1, “Dimensions”. |
command | A procedure to be called every time the user changes the state of this checkbutton. |
cursor | If you set this option to a cursor name (see Section 4.8, “Cursors”), the mouse cursor will change to that pattern when it is over the checkbutton. |
disabledforeground | The foreground color used to render the text of a disabled checkbutton. The default is a stippled version of the default foreground color. |
font | The font used for the
|
fg or
foreground | The color used
to render the
|
height | The number of lines of text on the checkbutton. Default is 1. |
highlightbackground | The color of the focus highlight when the checkbutton does not have focus. See Section 23, “Focus: routing keyboard input”. |
highlightcolor | The color of the focus highlight when the checkbutton has the focus. |
highlightthickness | The thickness of the focus highlight. Default is 1. Set to 0 to suppress display of the focus highlight. |
image | To display a graphic image on the button, set this option to an image object. See Section 4.9, “Images”. |
indicatoron | Normally a checkbutton displays as its
indicator a box that shows whether the checkbutton
is set or not. You can get this behavior by
setting indicatoron=1.
However, if you set
indicatoron=0, the indicator
disappears, and the entire widget becomes a
push-push button that looks raised when it is
cleared and sunken when it is set. You may want to
increase the borderwidth
value to make it easier to see the state of such a
control. |
justify | If the
CENTER,
LEFT, or
RIGHT. |
offvalue | Normally, a checkbutton's associated control
variable will be set to 0 when it is cleared (off).
You can supply an alternate value for the off state
by setting offvalue to that
value. |
onvalue | Normally, a checkbutton's associated control
variable will be set to 1 when it is set (on). You
can supply an alternate value for the on state by
setting onvalue to that
value. |
padx | How much space to leave to the left and right of the checkbutton and text. Default is 1 pixel. For possible values, see Section 4.1, “Dimensions”. |
pady | How much space to leave above and below the checkbutton and text. Default is 1 pixel. |
relief | With the default value,
relief=FLAT, the checkbutton
does not stand out from its background. You may
set this option to any of the other styles (see
Section 4.6, “Relief styles”), or use
relief=SOLID, which gives
you a solid black frame around it. |
selectcolor | The color of the
checkbutton when it is set. Default is
selectcolor="red". |
selectimage | If you set this option to an image, that image will appear in the checkbutton when it is set. See Section 4.9, “Images”. |
state | The default is
state=NORMAL, but you can use
state=DISABLED to gray out
the control and make it unresponsive. If the
cursor is currently over the checkbutton, the state
is ACTIVE. |
takefocus | The default is that the input focus (see Section 23, “Focus: routing keyboard input”) will pass through a checkbutton.
If you set takefocus=0,
focus will not pass through it. |
text | The label displayed next to the checkbutton.
Use newlines ("\n") to
display multiple lines of text. |
textvariable | If you need to change the label on a checkbutton during execution, create a StringVar (see Section 22, “Control variables: the values behind the widgets”) to manage the current value, and set this option to that control variable. Whenever the control variable's value changes, the checkbutton's annotation will automatically change as well. |
underline | With the default value of -1, none of the characters of the text label are underlined. Set this option to the index of a character in the text (counting from zero) to underline that character. |
variable | The control variable that tracks the current
state of the checkbutton; see Section 22, “Control variables: the values behind the widgets”. Normally this
variable is an IntVar, and
0 means cleared and
1 means set, but see the
offvalue and
onvalue options above. |
width | The default width of a checkbutton is determined by the size of the displayed image or text. You can set this option to a number of characters and the checkbutton will always have room for that many characters. |
wraplength | Normally, lines are not wrapped. You can set this option to a number of characters and all lines will be broken into pieces no longer than that number. |
Methods on checkbuttons include:
.deselect()Clears (turns off) the checkbutton.
.flash()Flashes the checkbutton a few times between its active and normal colors, but leaves it the way it started.
.invoke()You can call this method to get the same actions that would occur if the user clicked on the checkbutton to change its state.
.select()Sets (turns on) the checkbutton.
.toggle()Clears the checkbutton if set, sets it if cleared.