Go to main content

man pages section 1: User Commands

Exit Print View

Updated: Wednesday, July 27, 2022
 
 

checkbutton (1t)

Name

checkbutton - Create and manipulate 'checkbutton' boolean selection widgets

Synopsis

checkbutton pathName ?options?

Description

checkbutton(1t)              Tk Built-In Commands              checkbutton(1t)



______________________________________________________________________________

NAME
       checkbutton  -  Create  and  manipulate 'checkbutton' boolean selection
       widgets

SYNOPSIS
       checkbutton pathName ?options?

STANDARD OPTIONS
       -activebackground     -disabledforeground  -padx
       -activeforeground     -font                -pady
       -anchor               -foreground          -relief
       -background           -highlightbackground -takefocus
       -bitmap               -highlightcolor      -text
       -borderwidth          -highlightthickness  -textvariable
       -compound             -image               -underline
       -cursor               -justify             -wraplength

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

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

              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  (-variable
              option) will be updated before the command is invoked.

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

              Specifies  a desired height for the button.  If an image or bit-
              map 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 is  not  specified,
              the  button's  desired  height  is computed from the size of the
              image or bitmap or text being displayed in it.

       Command-Line Name:-indicatoron
       Database Name:  indicatorOn
       Database Class: IndicatorOn

              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.

       Command-Line Name:-offrelief
       Database Name:  offRelief
       Database Class: OffRelief

              Specifies  the  relief for the checkbutton when the indicator is
              not drawn and the checkbutton is  off.   The  default  value  is
              "raised".  By setting this option to "flat" and setting -indica-
              toron to false  and  -overrelief  to  "raised",  the  effect  is
              achieved  of  having a flat button that raises on mouse-over and
              which is depressed when activated.  This is the  behavior  typi-
              cally  exhibited by the Bold, Italic, and Underline checkbuttons
              on the toolbar of a word-processor, for example.

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

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

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

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

       Command-Line Name:-overrelief
       Database Name:  overRelief
       Database Class: OverRelief

              Specifies an alternative relief for the checkbutton, to be  used
              when  the  mouse  cursor is over the widget.  This option can be
              used to make toolbar buttons, by configuring -relief flat -over-
              relief raised.  If the value of this option is the empty string,
              then no alternative relief is used when the mouse cursor is over
              the checkbutton.  The empty string is the default value.

       Command-Line Name:-selectcolor
       Database Name:  selectColor
       Database Class: Background

              Specifies a background color to use when the button is selected.
              If indicatorOn is true then the color is used as the  background
              for  the  indicator  regardless of the select state.  If indica-
              torOn is false, this color is used as  the  background  for  the
              entire widget, in place of background or activeBackground, when-
              ever 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:-selectimage
       Database Name:  selectImage
       Database Class: SelectImage

              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.

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

              Specifies one of three  states  for  the  checkbutton:   normal,
              active,  or  disabled.   In normal state the checkbutton is dis-
              played 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  -disabledfore-
              ground  and -background options determine how the checkbutton is
              displayed.

       Command-Line Name:-tristateimage
       Database Name:  tristateImage
       Database Class: TristateImage

              Specifies an image to display (in place of  the  -image  option)
              when  the  checkbutton  is  in  tri-state  mode.  This option is
              ignored unless the -image option has been specified.

       Command-Line Name:-tristatevalue
       Database Name:  tristateValue
       Database Class: Value

              Specifies the value that causes the checkbutton to  display  the
              multi-value   selection,  also  known  as  the  tri-state  mode.
              Defaults to "".

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

              Specifies the name of a  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  but-
              ton window's path name).

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

              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 Tk_GetPixels); for
              text it is in characters.  If this option is not 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 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,  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 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 normally drawn with a selected appear-
       ance, and a Tcl variable associated with the checkbutton is  set  to  a
       particular  value  (normally  1).   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 associated variable is set
       to a different value (typically 0).  The indicator is drawn  without  a
       check  mark  inside.  In the special case where the variable (if speci-
       fied) has a value that matches  the  tristatevalue,  the  indicator  is
       drawn with a tri-state appearance and is in the tri-state mode indicat-
       ing mixed or multiple values.  (This is used when the check box  repre-
       sents  the state of multiple items.)  The indicator is drawn in a plat-
       form dependent manner.  Under Unix and Windows, the background interior
       of  the box is "grayed".  Under Mac, the indicator is drawn with a dash
       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", "off" and "tristate" 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 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  vari-
       ables value changes to and from the button's "on", "off" and "tristate"
       values.

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 (see Tk_ConfigureInfo for information
              on the format of this list).  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 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 deselect
              Deselects  the  checkbutton  and sets the associated variable to
              its "off" value.

       pathName 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 command was invoked.
              This command is ignored if the checkbutton's state is disabled.

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

EXAMPLE
       This example shows a group of uncoupled checkbuttons.

              labelframe .lbl -text "Steps:"
              checkbutton .c1 -text Lights  -variable lights
              checkbutton .c2 -text Cameras -variable cameras
              checkbutton .c3 -text Action! -variable action
              pack .c1 .c2 .c3 -in .lbl
              pack .lbl


ATTRIBUTES
       See attributes(7) for descriptions of the following attributes:


       +---------------+------------------+
       |ATTRIBUTE TYPE | ATTRIBUTE VALUE  |
       +---------------+------------------+
       |Availability   | runtime/tk-8     |
       +---------------+------------------+
       |Stability      | Uncommitted      |
       +---------------+------------------+

SEE ALSO
       button(n), options(n), radiobutton(n), ttk::checkbutton(n)

KEYWORDS
       checkbutton, widget



NOTES
       Source  code  for open source software components in Oracle Solaris can
       be found at https://www.oracle.com/downloads/opensource/solaris-source-
       code-downloads.html.

       This     software     was    built    from    source    available    at
       https://github.com/oracle/solaris-userland.   The  original   community
       source        was        downloaded        from         https://source-
       forge.net/projects/tcl/files/Tcl/8.6.7/tk8.6.7-src.tar.gz/download.

       Further information about this software can be found on the open source
       community website at https://www.tcl.tk/.



Tk                                    4.4                      checkbutton(1t)