CHECKBUTTON(9) CHECKBUTTON(9)
NAME
checkbutton - Create and manipulate checkbutton widgets
SYNOPSIS
checkbutton pathname ?options?
STANDARD OPTIONS
-activebackground -disabledcolor -justify
-activeforeground -font -relief
-anchor -foreground -takefocus
-background -highlightcolor -text
-bitmap -highlightthickness -underline
-borderwidth -image
WIDGET-SPECIFIC OPTIONS
-command command
Specifies a Tk command to associate with the button.
This command is typically invoked when mouse button 1
is released over the button window. The button's glo-
bal variable (-variable option) will be updated before
the command is invoked.
-height dist
Specifies a desired height for the button. If this
option isn't specified, the button's desired height is
computed from the size of the image or bitmap or text
being displayed in it.
-indicatoron boolean
Specifies whether or not the indicator should be drawn.
If false, the relief option is ignored and the widget's
relief is always sunken if the widget is selected and
raised otherwise.
-offvalue string
Specifies value to store in the button's associated
variable whenever this button is deselected. Defaults
to ``0''.
-onvalue string
Specifies value to store in the button's associated
variable whenever this button is selected. Defaults to
``1''.
-selectcolor colour
Specifies a background colour to use when the button is
selected. If indicatoron is true then the colour
applies to the indicator. If indicatoron is false,
this colour is used as the background for the entire
widget, in place of background or activebackground,
CHECKBUTTON(9) CHECKBUTTON(9)
whenever the widget is selected. If specified as an
empty string then no special colour is used for dis-
playing when the widget is selected.
-state state
Specifies one of three states for the checkbutton:
normal, active, or disabled. In normal state the
checkbutton is displayed using the foreground and back-
ground options. The active state is typically used
when the pointer is over the checkbutton. In active
state the checkbutton is displayed using the active-
foreground and activebackground options. Disabled
state means that the checkbutton should be insensitive:
the default bindings will refuse to activate the widget
and will ignore mouse button presses. In this state
the disabledcolor and background options determine how
the checkbutton is displayed.
-variable string
Specifies name of global variable to set whenever this
button is selected. Changes in this variable also
cause the button to select or deselect itself.
-width dist
Specifies a desired width for the button. If this
option isn't specified, the button's desired width is
computed from the size of the image or bitmap or text
being displayed in it.
DESCRIPTION
The checkbutton command creates a new window (given by the
pathname argument) and makes it into a checkbutton widget.
Additional options, described above, may be specified on the
command line to configure aspects of the checkbutton such as
its colours, font, text, and initial relief. The checkbut-
ton command returns its pathname argument. At the time this
command is invoked, there must not exist a window named
pathname.
A checkbutton is a widget that displays a textual string,
bitmap or image and a square called an indicator. If text
is displayed, it must all be in a single font, but it can
occupy multiple lines on the screen (if it contains new-
lines) and one of the characters may optionally be under-
lined using the underline option. A checkbutton has all of
the behaviour of a simple button, including the following:
it can display itself in either of three different ways,
according to the state option; it can be made to appear
raised, sunken, or flat; and it invokes a Tk command when-
ever mouse button 1 is clicked over the checkbutton.
In addition, checkbuttons can be selected. If a checkbutton
CHECKBUTTON(9) CHECKBUTTON(9)
is selected then the indicator is normally drawn with a
sunken relief and a special colour, and a Tk variable asso-
ciated with the checkbutton is set to the onvalue (normally
1). If the checkbutton is not selected, then the indicator
is drawn with a raised relief and no special colour, and the
associated variable is set to the offvalue (normally 0).
The variable name may be modified with options on the com-
mand line (-variable option). Configuration options may
also be used to modify the way the indicator is displayed
(or whether it is displayed at all). By default a checkbut-
ton is configured to select and deselect itself on alternate
button clicks.
WIDGET COMMAND
The checkbutton command creates a new Tk command whose name
is pathname. This command may be used to invoke various
operations on the widget. It has the following general
form:
pathname option ?arg arg ...?
Option and the args determine the exact behaviour of the
command. The following commands are possible for checkbut-
ton widgets:
pathname cget option
Returns the current value of the configuration option
given by option. Option may have any of the values
accepted by the checkbutton command.
pathname configure ?option? ?value option value ...?
Query or modify the configuration options of the wid-
get. If no option is specified, returns a list of all
of the available options for pathname. If one or more
option-value pairs are specified, then the command mod-
ifies the given widget option(s) to have the given
value(s); in this case the command returns an empty
string. Option may have any of the values accepted by
the checkbutton command.
pathname deselect
Deselects the checkbutton and sets the associated vari-
able to its ``off'' value.
pathname invoke
Does just what would have happened if the user invoked
the checkbutton with the mouse: toggle the selection
state of the button and invoke the Tk command associ-
ated with the checkbutton, if there is one. The return
value is the return value from the Tk command, or an
empty string if there is no command associated with the
checkbutton. This command is ignored if the
checkbutton's state is disabled.
CHECKBUTTON(9) CHECKBUTTON(9)
pathname select
Selects the checkbutton and sets the associated vari-
able to 1.
pathname toggle
Toggles the selection state of the button, redisplaying
it and modifying its associated variable to reflect the
new state.
BINDINGS
Tk automatically creates bindings for checkbuttons that give
them the following default behaviour:
[1] A checkbutton activates whenever the mouse passes over
it and deactivates whenever the mouse leaves the check-
button.
[2] When mouse button 1 is pressed over a checkbutton it is
invoked (its selection state toggles and the command
associated with the button is invoked, if there is
one).
If the checkbutton's state is disabled then none of the
above actions occur: the checkbutton is completely non-
responsive.
The behaviour of checkbuttons can be changed by defining new
bindings for individual widgets.
SEE ALSO
button(9), choicebutton(9), options(9), radiobutton(9),
types(9)