


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


NAME
       checkbutton - Create and manipulate checkbutton widgets

SYNOPSIS
       (checkbutton                   widget-name                   ?options?)
       :activebackground   :cursor   :highlightthickness :takefocus
       :activeforeground   :disabledforeground :image    :text
       :anchor   :font     :justify  :textvariable
       :background    :foreground    :padx     :underline
       :bitmap   :highlightbackground     :pady     :wraplength
       :borderwidth   :highlightcolor     :relief

WIDGET-SPECIFIC OPTIONS
       Specifies a STk procedure to associate with the button.  This procedure
       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 procedure is invoked.  Specifies the environment  in
       which  the  :textvariable must be taken.  By default, the value of this
       option is the STk global environment.  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
       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
       image  or  bitmap  or text being displayed in it.  Specifies whether or
       not the indicator should be drawn.  Must be a proper boolean value.  If
       false,  the  relief option is ignored and the widget's relief is always
       sunken if the widget is selected and raised otherwise.  Specifies value
       to  store  in  the button's associated variable whenever this button is
       deselected.  Defaults to #f.  Specifies value to store in the  button's
       associated  variable whenever this button is selected.  Defaults to #t.
       Specifies a background color to use when the button  is  selected.   If
       indicatorOn  is  true  then  the color applies to the indicator.  Under
       Windows, this color is used as the background for the indicator regard-
       less  of the select state.  If indicatorOn is false, this color is used
       as the background for the entire widget,  in  place  of  background  or
       activeBackground,  whenever the widget is selected.  If specified as an
       empty string then no special color is used for displaying when the wid-
       get  is selected.  Specifies an image to display (in place of the image
       option) when the checkbutton  is  selected.   This  option  is  ignored
       unless  the  image  option  has been specified.  Specifies one of three
       states for the checkbutton:  normal, active, or  disabled.   In  normal
       state  the checkbutton is displayed using the foreground and background
       options.  The active state is typically used when the pointer  is  over
       the  checkbutton.   In  active state the checkbutton is displayed using
       the activeForeground  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.  Specifies if the value set
       to variable by :offvalue or :onvalue must be stringified. For instance,
       with
              (checkbutton '.c :text "Try" :variable 'x :stringvalue #t
                               :onvalue 10 :offvalue 20) the variabe x var  is
              set  to  "10" or "20", whereas with (checkbutton '.c :text "Try"



STk                            4.0                              1





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


              :variable 'x :stringvalue #f
                               :onvalue 10 :offvalue 20) it is set  to  10  or
              20. Default value for :stringvalue is #t.
       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).  Spec-
       ifies 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 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 image or bitmap or text being displayed in it.


DESCRIPTION
       The checkbutton procedure creates a  new  window  (given  by  the  wid-
       get-name  argument) and makes it into a checkbutton widget.  Additional
       options, described above, may be specified on the procedure line or  in
       the option database to configure aspects of the checkbutton such as its
       colors, font, text, and  initial  relief.   The  checkbutton  procedure
       returns  its  widget-name  argument.   At  the  time  this procedure is
       invoked, there must not exist a  window  named  widget-name,  but  wid-
       get-name'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  newlines  or  if  wrapping  occurs  because  of  the
       wrapLength  option)  and one of the characters may optionally be under-
       lined using the underline option.  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  state  option;  it
       can be made to appear raised, sunken, or flat; it can be made to flash;
       and it invokes a STk procedure 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  selected  appear-
       ance,  and  a  STk variable associated with the checkbutton is set to a
       particular value (normally #t).  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  #f).   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 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 procedure 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



STk                            4.0                              2





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


       to and from the button's ``on'' value.


WIDGET PROCEDURE
       The checkbutton procedure creates a new STk  procedure  whose  name  is
       widget-name.   This  procedure may be used to invoke various operations
       on the widget.  It has the following general form: (widget-name  option
       ?arg arg ...?)  Option and the args determine the exact behavior of the
       procedure.  The following procedures are possible for checkbutton  wid-
       gets:

       (widget-name 'cget option)
              Returns  the  current value of the configuration option given by
              option.  Option may have any  of  the  values  accepted  by  the
              checkbutton procedure.

       (widget-name '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 widget-name (see Tk_ConfigureInfo for informa-
              tion on the format of this list).  If option is  specified  with
              no  value,  then the procedure 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 option-value pairs are specified, then the procedure
              modifies  the given widget option(s) to have the given value(s);
              in this case the procedure returns an empty  list.   Option  may
              have any of the values accepted by the checkbutton procedure.

       (widget-name 'deselect)
              Deselects  the  checkbutton  and sets the associated variable to
              its ``off'' value.

       (widget-name 'flash)
              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 procedure was
              invoked.  This procedure is ignored if the  checkbutton's  state
              is disabled.

       (widget-name '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 STk procedure associated with the check-
              button, if there is one (return value is undefined) This  proce-
              dure is ignored if the checkbutton's state is disabled.

       (widget-name 'select)
              Selects  the checkbutton and sets the associated variable to its
              ``on'' value.

       (widget-name 'toggle)
              Toggles the selection state of the button, redisplaying  it  and



STk                            4.0                              3





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


              modifying its associated variable to reflect the new state.


BINDINGS
       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 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 procedure  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 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.


SEE ALSO
       button, radiobutton

























STk                            4.0                              4


