CHECKBUTTON(9) CHECKBUTTON(9)
NAME
checkbutton - Create and manipulate checkbutton widgets
SYNOPSIS
checkbutton pathname ?options?
STANDARD OPTIONS
-activebackground -borderwidth -padx
-activeforeground -font -pady
-anchor -foreground -relief
-background -image -text
-bitmap -justify -underline
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.
-selectcolor colour
Specifies a background colour to use when the button is
selected. If specified as an empty string then no spe-
cial colour is used for displaying 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 disabledforeground and background options determine
how the checkbutton is displayed.
-width dist
Specifies a desired width for the button. If this
option isn't specified, the button's desired width is
Page 1 Plan 9 (printed 12/21/24)
CHECKBUTTON(9) CHECKBUTTON(9)
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, but pathname's parent must exist.
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; it can be made to flash; and it
invokes a Tk command whenever mouse button 1 is clicked over
the checkbutton.
In addition, checkbuttons can be selected. If a checkbutton
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 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 0. The variable name may be modified with options on
the command line (-variable option). Configuration options
may also be used to modify the way the indicator is dis-
played (or whether it is displayed at all). By default a
checkbutton 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
Page 2 Plan 9 (printed 12/21/24)
CHECKBUTTON(9) CHECKBUTTON(9)
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.
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.
Page 3 Plan 9 (printed 12/21/24)
CHECKBUTTON(9) CHECKBUTTON(9)
The behaviour of checkbuttons can be changed by defining new
bindings for individual widgets.
SEE ALSO
options(9), types(9)
Page 4 Plan 9 (printed 12/21/24)