doc/checkbutton.n

   1 '\"
   2 '\" Copyright (c) 1990-1994 The Regents of the University of California.
   3 '\" Copyright (c) 1994-1995 Sun Microsystems, Inc.
   4 '\" Copyright (c) 1996-1999 Christian Werner
   5 '\"
   6 '\" See the file "license.terms" for information on usage and redistribution
   7 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
   8 '\"
   9 .so man.macros
  10 .TH checkbutton n 8.0 Ck "Ck Built-In Commands"
  11 .BS
  12 '\" Note:  do not modify the .SH NAME line immediately below!
  13 .SH NAME
  14 checkbutton \- Create and manipulate checkbutton widgets
  15 .SH SYNOPSIS
  16 \fBcheckbutton\fI pathName \fR?\fIoptions\fR?
  17 .SH "STANDARD OPTIONS"
  18 .LP
  19 .nf
  20 .ta 3.8c 7.6c 11.4c
  21 \fBactiveAttributes\fR  \fBattributes\fR        \fBdisabledForeground\fR        \fBtextVariable\fR
  22 \fBactiveBackground\fR  \fBbackground\fR        \fBforeground\fR        \fBunderline\fR
  23 \fBactiveForeground\fR  \fBdisabledAttributes\fR        \fBtakeFocus\fR \fBunderlineAttributes\fR
  24 \fBanchor\fR    \fBdisabledBackground\fR        \fBtext\fR      \fBunderlineForeground\fR
  25 .fi
  26 .LP
  27 See the ``options'' manual entry for details on the standard options.
  28 .SH "WIDGET-SPECIFIC OPTIONS"
  29 .ta 4c
  30 .LP
  31 .nf
  32 Name:   \fBcommand\fR
  33 Class:  \fBCommand\fR
  34 Command-Line Switch:    \fB\-command\fR
  35 .fi
  36 .IP
  37 Specifies a Tcl command to associate with the button.  This command
  38 is typically invoked when mouse button 1 is pressed on the button
  39 window.  The button's global variable (\fB\-variable\fR option) will
  40 be updated before the command is invoked.
  41 .LP
  42 .nf
  43 Name:   \fBheight\fR
  44 Class:  \fBHeight\fR
  45 Command-Line Switch:    \fB\-height\fR
  46 .fi
  47 .IP
  48 Specifies a desired height for the button in screen lines.
  49 If this option isn't specified, the button's desired height is 1 line.
  50 .LP
  51 .nf
  52 Name:   \fBoffValue\fR
  53 Class:  \fBValue\fR
  54 Command-Line Switch:    \fB\-offvalue\fR
  55 .fi
  56 .IP
  57 Specifies value to store in the button's associated variable whenever
  58 this button is deselected.  Defaults to ``0''.
  59 .LP
  60 .nf
  61 Name:   \fBonValue\fR
  62 Class:  \fBValue\fR
  63 Command-Line Switch:    \fB\-onvalue\fR
  64 .fi
  65 .IP
  66 Specifies value to store in the button's associated variable whenever
  67 this button is selected.  Defaults to ``1''.
  68 .LP
  69 .nf
  70 Name:   \fBselectColor\fR
  71 Class:  \fBBackground\fR
  72 Command-Line Switch:    \fB\-selectcolor\fR
  73 .fi
  74 .IP
  75 Specifies a background color to use when the button is selected.
  76 If \fBindicatorOn\fR is true then the color applicies to the indicator.
  77 .LP
  78 .nf
  79 Name:   \fBstate\fR
  80 Class:  \fBState\fR
  81 Command-Line Switch:    \fB\-state\fR
  82 .fi
  83 .IP
  84 Specifies one of three states for the checkbutton:  \fBnormal\fR, \fBactive\fR,
  85 or \fBdisabled\fR.  In normal state the checkbutton is displayed using the
  86 \fBattributes\fR, \fBforeground\fR and \fBbackground\fR options.
  87 The active state is used when the input focus is in the checkbutton.
  88 In active state the checkbutton is displayed using the
  89 \fBactiveAttributes\fR, \fBactiveForeground\fR, and
  90 \fBactiveBackground\fR options.  Disabled state means that the checkbutton
  91 should be insensitive:  the default bindings will refuse to activate
  92 the widget and will ignore mouse button presses.
  93 In this state the \fBdisabledAttributes\fR, \fBdisabledForeground\fR, and
  94 \fBdisabledBackground\fR options determine how the checkbutton is displayed.
  95 .LP
  96 .nf
  97 Name:   \fBvariable\fR
  98 Class:  \fBVariable\fR
  99 Command-Line Switch:    \fB\-variable\fR
 100 .fi
 101 .IP
 102 Specifies name of global variable to set to indicate whether
 103 or not this button is selected.  Defaults to the name of the
 104 button within its parent (i.e. the last element of the button
 105 window's path name).
 106 .LP
 107 .nf
 108 Name:   \fBwidth\fR
 109 Class:  \fBWidth\fR
 110 Command-Line Switch:    \fB\-width\fR
 111 .fi
 112 .IP
 113 Specifies a desired width for the button in screen columns.
 114 If this option isn't specified, the button's desired width is computed
 115 from the size of the text being displayed in it.
 116 .BE
 117
 118 .SH DESCRIPTION
 119 .PP
 120 The \fBcheckbutton\fR command creates a new window (given by the
 121 \fIpathName\fR argument) and makes it into a checkbutton widget.
 122 Additional
 123 options, described above, may be specified on the command line
 124 or in the option database
 125 to configure aspects of the checkbutton such as its colors, font,
 126 text, and initial relief.  The \fBcheckbutton\fR command returns its
 127 \fIpathName\fR argument.  At the time this command is invoked,
 128 there must not exist a window named \fIpathName\fR, but
 129 \fIpathName\fR's parent must exist.
 130 .PP
 131 A checkbutton is a widget that displays a textual string
 132 and a square called an \fIindicator\fR. One of the characters of the
 133 string may optionally be underlined using the
 134 \fBunderline\fR, \fBunderlineAttributes\fR, and \fBunderlineForeground\fR
 135 options. A checkbutton has all of the behavior of a simple button,
 136 including the following: it can display itself in either of three different
 137 ways, according to the \fBstate\fR option, and it invokes
 138 a Tcl command whenever mouse button 1 is clicked over the
 139 checkbutton.
 140 .PP
 141 In addition, checkbuttons can be \fIselected\fR. If a checkbutton is
 142 selected then the indicator is drawn with a special color, and
 143 a Tcl variable associated with the checkbutton is set to a particular
 144 value (normally 1).
 145 If the checkbutton is not selected, then the indicator is drawn with no
 146 special color, and the associated variable is set to a different value
 147 (typically 0).
 148 By default, the name of the variable associated with a checkbutton is the
 149 same as the \fIname\fR used to create the checkbutton.
 150 The variable name, and the ``on'' and ``off'' values stored in it,
 151 may be modified with options on the command line or in the option
 152 database. By default a checkbutton is configured to select and deselect
 153 itself on alternate button clicks.
 154 In addition, each checkbutton monitors its associated variable and
 155 automatically selects and deselects itself when the variables value
 156 changes to and from the button's ``on'' value.
 157
 158 .SH "WIDGET COMMAND"
 159 .PP
 160 The \fBcheckbutton\fR command creates a new Tcl command whose
 161 name is \fIpathName\fR.  This
 162 command may be used to invoke various
 163 operations on the widget.  It has the following general form:
 164 .DS C
 165 \fIpathName option \fR?\fIarg arg ...\fR?
 166 .DE
 167 \fIOption\fR and the \fIarg\fRs
 168 determine the exact behavior of the command.  The following
 169 commands are possible for checkbutton widgets:
 170 .TP
 171 \fIpathName \fBcget\fR \fIoption\fR
 172 Returns the current value of the configuration option given
 173 by \fIoption\fR.
 174 \fIOption\fR may have any of the values accepted by the \fBcheckbutton\fR
 175 command.
 176 .TP
 177 \fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR?
 178 Query or modify the configuration options of the widget.
 179 If no \fIoption\fR is specified, returns a list describing all of
 180 the available options for \fIpathName\fR. If \fIoption\fR is specified
 181 with no \fIvalue\fR, then the command returns a list describing the
 182 one named option (this list will be identical to the corresponding
 183 sublist of the value returned if no \fIoption\fR is specified).  If
 184 one or more \fIoption\-value\fR pairs are specified, then the command
 185 modifies the given widget option(s) to have the given value(s);  in
 186 this case the command returns an empty string.
 187 \fIOption\fR may have any of the values accepted by the \fBcheckbutton\fR
 188 command.
 189 .TP
 190 \fIpathName \fBdeselect\fR
 191 Deselects the checkbutton and sets the associated variable to its ``off''
 192 value.
 193 .TP
 194 \fIpathName \fBinvoke\fR
 195 Does just what would have happened if the user invoked the checkbutton
 196 with the mouse: toggle the selection state of the button and invoke
 197 the Tcl command associated with the checkbutton, if there is one.
 198 The return value is the return value from the Tcl command, or an
 199 empty string if there is no command associated with the checkbutton.
 200 This command is ignored if the checkbutton's state is \fBdisabled\fR.
 201 .TP
 202 \fIpathName \fBselect\fR
 203 Selects the checkbutton and sets the associated variable to its ``on''
 204 value.
 205 .TP
 206 \fIpathName \fBtoggle\fR
 207 Toggles the selection state of the button, redisplaying it and
 208 modifying its associated variable to reflect the new state.
 209
 210 .SH BINDINGS
 211 .PP
 212 Ck automatically creates class bindings for checkbuttons that give them
 213 the following default behavior:
 214 .IP [1]
 215 A checkbutton activates whenever it gets the input focus and deactivates
 216 whenever it loses the input focus.
 217 .IP [2]
 218 When mouse button 1 is pressed over a checkbutton it is invoked (its
 219 selection state toggles and the command associated with the button is
 220 invoked, if there is one).
 221 .IP [3]
 222 When a checkbutton has the input focus, the space or return keys cause
 223 the checkbutton to be invoked.
 224 .PP
 225 If the checkbutton's state is \fBdisabled\fR then none of the above
 226 actions occur:  the checkbutton is completely non-responsive.
 227 .PP
 228 The behavior of checkbuttons can be changed by defining new bindings for
 229 individual widgets or by redefining the class bindings.
 230
 231 .SH KEYWORDS
 232 checkbutton, widget