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)