checkbutton(n)		     Ck Built-In Commands		checkbutton(n)



______________________________________________________________________________

NAME
       checkbutton - Create and manipulate checkbutton widgets

SYNOPSIS
       checkbutton pathName ?options?

STANDARD OPTIONS
       activeAttributes		     attributes	    disabledForegroundtextVariable
       activeBackground		     background	    foregroundunderline
       activeForeground		     disabledAttributestakeFocusunderlineAttributes
       anchor	      disabledBackground	    textunderlineForeground

       See the ``options'' manual entry for details on the standard options.

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

	      Specifies a Tcl command to associate with the button.  This com-
	      mand is typically invoked when mouse button 1 is pressed on  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 in screen  lines.   If
	      this  option  isn't  specified, the button's desired height is 1
	      line.

       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:	       selectColor
       Class:	       Background
       Command-Line Switch:-selectcolor

	      Specifies a background color to use when the button is selected.
	      If  indicatorOn  is true then the color applicies to the indica-
	      tor.

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

	      Specifies one of three states for the checkbutton:  normal,  ac-
	      tive, or disabled.  In normal state the checkbutton is displayed
	      using the attributes, foreground and  background	options.   The
	      active state is used when the input focus is in the checkbutton.
	      In active state the checkbutton is displayed using the activeAt-
	      tributes,	 activeForeground, and activeBackground options.  Dis-
	      abled 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  disabledAt-
	      tributes, disabledForeground, and disabledBackground options de-
	      termine how the checkbutton is displayed.

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

	      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).

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

	      Specifies	 a desired width for the button in screen columns.  If
	      this option isn't specified, the button's desired width is  com-
	      puted from the size of the text being displayed in it.
_________________________________________________________________


DESCRIPTION
       The checkbutton command creates a new window (given by the pathName ar-
       gument) 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 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  checkbutton  is a widget that displays a textual string and a square
       called an indicator. One of the characters of the string may optionally
       be  underlined using the underline, underlineAttributes, and underline-
       Foreground options. A checkbutton has all of the behavior of  a	simple
       button,	including  the	following:  it can display itself in either of
       three different ways, according to the state option, and it  invokes  a
       Tcl 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 drawn with a special color, and  a	 Tcl  variable
       associated  with the checkbutton is set to a particular value (normally
       1).  If the checkbutton is not selected, then the  indicator  is	 drawn
       with  no special color, and the associated variable is set to a differ-
       ent value (typically 0).	 By default, the name of the variable  associ-
       ated  with  a  checkbutton  is  the same as the name 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. By default a checkbutton is configured  to	select
       and  deselect  itself  on  alternate  button clicks.  In addition, each
       checkbutton 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	 path-
       Name.   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 behavior of the command.
       The following commands are possible for checkbutton 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 widget.	If  no
	      option is specified, returns a list describing all of the avail-
	      able options for pathName. If option is specified with no value,
	      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 option is specified).  If one or more op-
	      tion-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 deselect
	      Deselects	 the  checkbutton  and sets the associated variable 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 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 disabled.

       pathName select
	      Selects the checkbutton and sets the associated variable to  its
	      ``on'' value.

       pathName toggle
	      Toggles  the  selection state of the button, redisplaying it and
	      modifying its associated variable to reflect the new state.


BINDINGS
       Ck automatically creates class bindings for checkbuttons that give them
       the following default behavior:

       [1]    A checkbutton activates whenever it gets the input focus and de-
	      activates whenever it loses the input focus.

       [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 or return keys
	      cause the checkbutton to be invoked.

       If  the	checkbutton's state is disabled then 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.


KEYWORDS
       checkbutton, widget



Ck				      8.0			checkbutton(n)
