1mNAME0m
       checkbutton - Create and manipulate checkbutton widgets

1mSYNOPSIS0m
       1mcheckbutton 4m22mpathName24m ?4moptions24m?

1mSTANDARD OPTIONS0m
       1m-activebackground     -cursor              -highlightthickness-takefocus0m
       1m-activeforeground     -disabledforeground  -image-text0m
       1m-anchor               -font                -justify-textvariable0m
       1m-background           -foreground          -padx-underline0m
       1m-bitmap               -highlightbackground -pady-wraplength0m
       1m-borderwidth          -highlightcolor      -relief0m

       See the 1moptions 22mmanual entry for details on the standard options.

1mWIDGET-SPECIFIC OPTIONS0m
       Command-Line Name:1m-command0m
       Database Name:  1mcommand0m
       Database Class: 1mCommand0m

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

       Command-Line Name:1m-height0m
       Database Name:  1mheight0m
       Database Class: 1mHeight0m

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

       Command-Line Name:1m-indicatoron0m
       Database Name:  1mindicatorOn0m
       Database Class: 1mIndicatorOn0m

              Specifies whether or not the indicator should be drawn.  Must be
              a proper boolean value.  If false, the 1mrelief 22moption is  ignored
              and  the  widget's  relief  is  always  sunken  if the widget is
              selected and raised otherwise.

       Command-Line Name:1m-offvalue0m
       Database Name:  1moffValue0m
       Database Class: 1mValue0m

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

       Command-Line Name:1m-onvalue0m
       Database Name:  1monValue0m
       Database Class: 1mValue0m

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

       Command-Line Name:1m-selectcolor0m
       Database Name:  1mselectColor0m
       Database Class: 1mBackground0m

              Specifies a background color to use when the button is selected.
              If  1mindicatorOn 22mis true then the color applies to the indicator.
              Under Windows, this color is used  as  the  background  for  the
              indicator  regardless  of  the  select state.  If 1mindicatorOn 22mis
              false, this color is used as the background for the entire  wid-
              get,  in  place  of 1mbackground 22mor 1mactiveBackground22m, whenever the
              widget is selected.  If specified as an  empty  string  then  no
              special  color  is  used  for  displaying  when  the  widget  is
              selected.

       Command-Line Name:1m-selectimage0m
       Database Name:  1mselectImage0m
       Database Class: 1mSelectImage0m

              Specifies an image to display (in place  of  the  1mimage  22moption)
              when the checkbutton is selected.  This option is ignored unless
              the 1mimage 22moption has been specified.

       Command-Line Name:1m-state0m
       Database Name:  1mstate0m
       Database Class: 1mState0m

              Specifies one of three  states  for  the  checkbutton:   1mnormal22m,
              1mactive22m,  or  1mdisabled22m.   In normal state the checkbutton is dis-
              played using the 1mforeground 22mand 1mbackground 22moptions.  The  active
              state  is  typically used when the pointer is over the checkbut-
              ton.  In active state the checkbutton  is  displayed  using  the
              1mactiveForeground  22mand  1mactiveBackground 22moptions.  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 1mdisabledForeground  22mand
              1mbackground 22moptions determine how the checkbutton is displayed.

       Command-Line Name:1m-variable0m
       Database Name:  1mvariable0m
       Database Class: 1mVariable0m

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

       Command-Line Name:1m-width0m
       Database Name:  1mwidth0m
       Database Class: 1mWidth0m

              Specifies a desired width for the button.  If an image or bitmap
              is  being  displayed  in  the button then the value is in screen
              units (i.e. any of the forms acceptable  to  1mTk_GetPixels22m);  for
              text  it  is in characters.  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.


1mDESCRIPTION0m
       The  1mcheckbutton  22mcommand  creates  a new window (given by the 4mpathName0m
       argument) and makes it into a checkbutton widget.  Additional  options,
       described  above, may be specified on the command line or in the option
       database to configure aspects of the checkbutton such  as  its  colors,
       font,  text,  and  initial relief.  The 1mcheckbutton 22mcommand returns its
       4mpathName24m argument.  At the time this command is invoked, there must not
       exist a window named 4mpathName24m, but 4mpathName24m's parent must exist.

       A  checkbutton  is  a  widget that displays a textual string, bitmap or
       image and a square called an 4mindicator24m.  If text is displayed, it  must
       all be in a single font, but it can occupy multiple lines on the screen
       (if  it  contains  newlines  or  if  wrapping  occurs  because  of  the
       1mwrapLength  22moption)  and one of the characters may optionally be under-
       lined using the 1munderline 22moption.  A checkbutton has all of the  behav-
       ior  of a simple button, including the following: it can display itself
       in either of three different ways, according to the  1mstate  22moption;  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 checkbutton.

       In  addition,  checkbuttons  can  be  4mselected24m.   If  a  checkbutton is
       selected then the indicator is normally drawn with a  selected  appear-
       ance,  and  a  Tcl variable associated with the checkbutton is set to a
       particular value (normally 1).  Under Unix, the indicator is drawn with
       a  sunken  relief and a special color.  Under Windows, the indicator is
       drawn with a check mark inside.  If the checkbutton  is  not  selected,
       then the indicator is drawn with a deselected appearance, and the asso-
       ciated variable is set to a different value (typically 0).  Under Unix,
       the  indicator  is  drawn  with  a  raised relief and no special color.
       Under Windows, the indicator is drawn without a check mark inside.   By
       default,  the name of the variable associated with a checkbutton is the
       same as the 4mname24m used to create the checkbutton.   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.   Configuration
       options  may  also be used to modify the way the indicator is displayed
       (or whether it is displayed at all).  By default a checkbutton is  con-
       figured  to  select and deselect itself on alternate button clicks.  In
       addition, each checkbutton monitors its associated variable  and  auto-
       matically selects and deselects itself when the variables value changes
       to and from the button's ``on'' value.


1mWIDGET COMMAND0m
       The 1mcheckbutton 22mcommand creates a new Tcl command whose name  is  4mpath-0m
       4mName24m.   This  command  may  be used to invoke various operations on the
       widget.  It has the following general form:
              4mpathName24m 4moption24m ?4marg24m 4marg24m 4m...24m?
       4mOption24m and the 4marg24ms determine the exact behavior of the  command.   The
       following commands are possible for checkbutton widgets:

       4mpathName24m 1mcget 4m22moption0m
              Returns  the  current value of the configuration option given by
              4moption24m.  4mOption24m may have any  of  the  values  accepted  by  the
              1mcheckbutton 22mcommand.

       4mpathName24m 1mconfigure 22m?4moption24m? ?4mvalue24m 4moption24m 4mvalue24m 4m...24m?
              Query  or modify the configuration options of the widget.  If no
              4moption24m is specified, returns a list describing all of the avail-
              able  options for 4mpathName24m (see 1mTk_ConfigureInfo 22mfor information
              on the format of this list).  If 4moption24m  is  specified  with  no
              4mvalue24m,  then the command returns a list describing the one named
              option (this list will be identical to the corresponding sublist
              of  the  value  returned  if no 4moption24m is specified).  If one or
              more 4moption-value24m 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.  4mOption24m may  have  any
              of the values accepted by the 1mcheckbutton 22mcommand.

       4mpathName24m 1mdeselect0m
              Deselects  the  checkbutton  and sets the associated variable to
              its ``off'' value.

       4mpathName24m 1mflash0m
              Flashes the checkbutton.  This is accomplished  by  redisplaying
              the  checkbutton  several  times, alternating between active and
              normal colors.  At the end of the flash the checkbutton is  left
              in the same normal/active state as when the command was invoked.
              This command is ignored if the checkbutton's state is  1mdisabled22m.

       4mpathName24m 1minvoke0m
              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 Tcl command associated with the checkbut-
              ton, if there is one.  The return value is the return value from
              the Tcl command, or an empty string if there is no command asso-
              ciated with the checkbutton.  This command  is  ignored  if  the
              checkbutton's state is 1mdisabled22m.

       4mpathName24m 1mselect0m
              Selects  the checkbutton and sets the associated variable to its
              ``on'' value.

       4mpathName24m 1mtoggle0m
              Toggles the selection state of the button, redisplaying  it  and
              modifying its associated variable to reflect the new state.


1mBINDINGS0m
       Tk automatically creates class bindings for checkbuttons that give them
       the following default behavior:

       [1]    On Unix systems, a  checkbutton  activates  whenever  the  mouse
              passes  over  it  and  deactivates whenever the mouse leaves the
              checkbutton.  On Mac and Windows systems, when mouse button 1 is
              pressed  over  a  checkbutton, the button activates whenever the
              mouse pointer is inside the button, and deactivates whenever the
              mouse pointer leaves the 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).

       [3]    When a checkbutton has the input focus, the space key causes the
              checkbutton to be invoked.  Under Windows, there are  additional
              key  bindings;  plus  (+)  and  equal (=) select the button, and
              minus (-) deselects the button.

       If the checkbutton's state is 1mdisabled 22mthen none of the  above  actions
       occur:  the checkbutton is completely non-responsive.

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


1mKEYWORDS0m
