NAME
       checkbutton - Create and manipulate check-button widgets

SYNOPSIS
       checkbutton pathName ?options?

STANDARD OPTIONS
       activeBackground               bitmap          fontrelief
       activeForeground               borderWidth     foregroundtext
       anchor          cursor         padX            textVariable
       background      disabledForeground             padY

       See  the ``options'' manual entry for details on the stan-
       dard options.

WIDGET-SPECIFIC OPTIONS
       Name:           command
       Class:          Command
       Command-Line Switch:-command

              Specifies a Tcl command to associate with the  but-
              ton.   This command is typically invoked when mouse
              button 1 is released over the button  window.   The
              button's global variable (-variable option) will be
              updated before the command is invoked.

       Name:           height
       Class:          Height
       Command-Line Switch:-height

              Specifies a desired height for the  button.   If  a
              bitmap  is  being  displayed in the button then the
              value is in screen units (i.e.  any  of  the  forms
              acceptable  to  Tk_GetPixels);  for  text  it is in
              lines of text.  If this option isn't specified, the
              button's  desired  height is computed from the size
              of the bitmap or text being displayed in it.

       Name:           offValue
       Class:          Value
       Command-Line Switch:-offvalue

              Specifies value to store in the button's associated
              variable   whenever   this  button  is  deselected.
              Defaults to ``0''.

       Name:           onValue
       Class:          Value
       Command-Line Switch:-onvalue

              Specifies value to store in the button's associated
              variable   whenever   this   button   is  selected.
              Defaults to ``1''.
       Name:           selector
       Class:          Foreground
       Command-Line Switch:-selector

              Specifies the color to draw in  the  selector  when
              this  button is selected.  If specified as an empty
              string then no selector is drawn for the button.

       Name:           state
       Class:          State
       Command-Line Switch:-state

              Specifies one of three states for the check button:
              normal,  active,  or disabled.  In normal state the
              check button is displayed using the foreground  and
              background  options.  The active state is typically
              used when the pointer is over the check button.  In
              active  state  the  check button is displayed using
              the activeForeground and activeBackground  options.
              Disabled  state  means  that  the  check  button is
              insensitive:   it  doesn't  activate  and   doesn't
              respond to mouse button presses.  In this state the
              disabledForeground and background options determine
              how the check button is displayed.

       Name:           variable
       Class:          Variable
       Command-Line Switch:-variable

              Specifies  name  of global variable to set to indi-
              cate  whether  or  not  this  button  is  selected.
              Defaults  to the name of the button within its par-
              ent (i.e. the last element of the  button  window's
              path name).

       Name:           width
       Class:          Width
       Command-Line Switch:-width

              Specifies  a  desired  width  for the button.  If a
              bitmap is being displayed in the  button  then  the
              value  is  in  screen  units (i.e. any of the forms
              acceptable to Tk_GetPixels);  for  text  it  is  in
              characters.   If  this  option isn't specified, the
              button's desired width is computed from the size of
              the 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  check-button  wid-
       get.   Additional  options, described above, may be speci-
       fied on the command line or in the option database to con-
       figure  aspects  of  the  check button such as its colors,
       font, text, and initial relief.  The  checkbutton  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  check button is a widget that displays a textual string
       or bitmap and a square called a selector.  A check  button
       has  all of the behavior of a simple button, including the
       following: it can display itself in either of  three  dif-
       ferent 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 Tcl command whenever mouse button
       1 is clicked over the check button.

       In addition, check buttons can be selected.   If  a  check
       button is selected then a special highlight appears in the
       selector, and a Tcl variable  associated  with  the  check
       button  is set to a particular value (normally 1).  If the
       check button is not selected, then the selector  is  drawn
       in  a different fashion and the associated variable is set
       to a different value (typically 0).  By default, the  name
       of the variable associated with a check button is the same
       as the name used to create the check button.  The variable
       name,  and the ``on'' and ``off'' values stored in it, may
       be modified with options on the command  line  or  in  the
       option  database.  By default a check button is configured
       to select and deselect itself on alternate button  clicks.
       In  addition,  each  check  button monitors its associated
       variable and automatically selects  and  deselects  itself
       when  the variables value changes to and from the button's
       ``on'' value.


WIDGET COMMAND
       The checkbutton command creates a new  Tcl  command  whose
       name is pathName.  This command may be used to invoke var-
       ious operations on the widget.  It has the following  gen-
       eral form:

              pathName option ?arg arg ...?
       Option  and  the  args determine the exact behavior of the
       command.  The following commands are  possible  for  check
       button widgets:

       pathName activate
              Change  the  check  button's  state  to  active and
              redisplay the button using  its  active  foreground
              and  background  colors  instead  of normal colors.
              This command is ignored if the check button's state
              is  disabled.   This  command  is obsolete and will
              eventually be  removed;  use  ``pathName  configure
              -state active'' instead.
       pathName configure ?option? ?value option value ...?
              Query  or  modify  the configuration options of the
              widget.  If no option is specified, returns a  list
              describing  all  of the available options for path-
              Name (see Tk_ConfigureInfo for information  on  the
              format  of this list).  If option is specified with
              no value, then the command returns a list  describ-
              ing the one named option (this list will be identi-
              cal to  the  corresponding  sublist  of  the  value
              returned  if  no  option  is specified).  If one or
              more option-value pairs  are  specified,  then  the
              command modifies 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 deactivate
              Change the  check  button's  state  to  normal  and
              redisplay  the  button  using its normal foreground
              and background colors.  This command is ignored  if
              the check button's state is disabled.  This command
              is obsolete and will  eventually  be  removed;  use
              ``pathName configure -state normal'' instead.

       pathName deselect
              Deselect  the check button:  redisplay it without a
              highlight in the selector and  set  the  associated
              variable to its ``off'' value.

       pathName flash
              Flash  the  check  button.  This is accomplished by
              redisplaying the check button several times, alter-
              nating  between  active  and normal colors.  At the
              end of the flash the check button is  left  in  the
              same  normal/active  state  as when the command was
              invoked.  This command is ignored if the check but-
              ton's state is disabled.

       pathName invoke
              Does  just  what  would  have  happened if the user
              invoked the check button with the mouse: toggle the
              selection  state  of  the button and invoke the Tcl
              command associated with the check button, if  there
              is  one.  The return value is the return value from
              the Tcl command, or an empty string if there is  no
              command  associated  with  the  check button.  This
              command is ignored if the check button's  state  is
              disabled.

       pathName select
              Select  the  check button:  display it with a high-
              lighted selector and set the associated variable to
              its ``on'' value.
       pathName toggle
              Toggle  the  selection  state of the button, redis-
              playing it and modifying its associated variable to
              reflect the new state.


BINDINGS
       Tk  automatically creates class bindings for check buttons
       that give them the following default behavior:

       [1]    The  check  button  activates  whenever  the  mouse
              passes  over  it and deactivates whenever the mouse
              leaves the check button.

       [2]    The check button's  relief  is  changed  to  sunken
              whenever mouse button 1 is pressed over it, and the
              relief is restored to its original value when  but-
              ton 1 is later released.

       [3]    If  mouse button 1 is pressed over the check button
              and later released over the check button, the check
              button is invoked (i.e. its selection state toggles
              and the  command  associated  with  the  button  is
              invoked,  if  there is one).  However, if the mouse
              is not over the  check  button  when  button  1  is
              released, then no invocation occurs.

       If  the  check button's state is disabled then none of the
       above actions occur:  the check button is completely  non-
       responsive.

       The  behavior  of check buttons can be changed by defining
       new bindings for individual widgets or by  redefining  the
       class bindings.


KEYWORDS
       check button, widget
