doc/radiobutton.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 radiobutton 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 radiobutton \- Create and manipulate radiobutton widgets
  15 .SH SYNOPSIS
  16 \fBradiobutton\fI \fIpathName \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 in 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:   \fBselectColor\fR
  53 Class:  \fBBackground\fR
  54 Command-Line Switch:    \fB\-selectcolor\fR
  55 .fi
  56 .IP
  57 Specifies a background color to use when the button is selected.
  58 If \fBindicatorOn\fR is true, the color applicies to the indicator.
  59 .LP
  60 .nf
  61 Name:   \fBstate\fR
  62 Class:  \fBState\fR
  63 Command-Line Switch:    \fB\-state\fR
  64 .fi
  65 .IP
  66 Specifies one of three states for the radiobutton:  \fBnormal\fR, \fBactive\fR,
  67 or \fBdisabled\fR.  In normal state the radiobutton is displayed using the
  68 \fBattributes\fR, \fBforeground\fR, and \fBbackground\fR options.
  69 The active state is used when the input focus is in the radiobutton.
  70 In active state the radiobutton is displayed using the
  71 \fBactiveAttributes\fR, \fBactiveForeground\fR, and
  72 \fBactiveBackground\fR options.
  73 Disabled state means that the radiobutton should be insensitive:
  74 the default bindings will refuse to activate the widget and will ignore mouse
  75 button presses.
  76 In this state the \fBdisabledAttributes\fR, \fBdisabledForeground\fR and
  77 \fBdisabledBackground\fR options determine how the radiobutton is displayed.
  78 .LP
  79 .nf
  80 Name:   \fBvalue\fR
  81 Class:  \fBValue\fR
  82 Command-Line Switch:    \fB\-value\fR
  83 .fi
  84 .IP
  85 Specifies value to store in the button's associated variable whenever
  86 this button is selected.
  87 .LP
  88 .nf
  89 Name:   \fBvariable\fR
  90 Class:  \fBVariable\fR
  91 Command-Line Switch:    \fB\-variable\fR
  92 .fi
  93 .IP
  94 Specifies name of global variable to set whenever this button is
  95 selected.  Changes in this variable also cause the button to select
  96 or deselect itself. Defaults to the value \fBselectedButton\fR.
  97 .LP
  98 .nf
  99 Name:   \fBwidth\fR
 100 Class:  \fBWidth\fR
 101 Command-Line Switch:    \fB\-width\fR
 102 .fi
 103 .IP
 104 Specifies a desired width for the button in screen columns.
 105 If this option isn't specified, the button's desired width is computed
 106 from the size of the text being displayed in it.
 107 .BE
 108
 109 .SH DESCRIPTION
 110 .PP
 111 The \fBradiobutton\fR command creates a new window (given by the
 112 \fIpathName\fR argument) and makes it into a radiobutton widget.
 113 Additional options, described above, may be specified on the command line
 114 or in the option database to configure aspects of the radiobutton such as
 115 its colors, attributes, and text. The \fBradiobutton\fR command returns its
 116 \fIpathName\fR argument.  At the time this command is invoked,
 117 there must not exist a window named \fIpathName\fR, but
 118 \fIpathName\fR's parent must exist.
 119 .PP
 120 A radiobutton is a widget that displays a textual string
 121 and a circle called an \fIindicator\fR.
 122 One of the characters of the string may optionally be underlined
 123 using the \fBunderline\fR, \fBunderlineAttributes\fR, and
 124 \fBunderlineForeground\fR options.
 125 A radiobutton has all of the behavior of a simple button:
 126 it can display itself in either of three different ways,
 127 according to the \fBstate\fR option, and it invokes
 128 a Tcl command whenever mouse button 1 is clicked over the
 129 check button.
 130 .PP
 131 In addition, radiobuttons can be \fIselected\fR.
 132 If a radiobutton is selected, the indicator is normally
 133 drawn with a special color, and a Tcl variable associated with the
 134 radiobutton is set to a particular value.
 135 If the radiobutton is not selected, the indicator is drawn with no
 136 special color. Typically, several radiobuttons share a single variable
 137 and the value of the variable indicates which radiobutton is to be selected.
 138 When a radiobutton is selected it sets the value of the variable to
 139 indicate that fact;  each radiobutton also monitors the value of
 140 the variable and automatically selects and deselects itself when the
 141 variable's value changes.
 142 By default the variable \fBselectedButton\fR
 143 is used;  its contents give the name of the button that is
 144 selected, or the empty string if no button associated with that
 145 variable is selected.
 146 The name of the variable for a radiobutton,
 147 plus the variable to be stored into it, may be modified with options
 148 on the command line or in the option database.
 149 Configuration options may also be used to modify the way the
 150 indicator is displayed.
 151 By default a radio button is configured to select itself on button clicks.
 152
 153 .SH "WIDGET COMMAND"
 154 .PP
 155 The \fBradiobutton\fR command creates a new Tcl command whose
 156 name is \fIpathName\fR.  This
 157 command may be used to invoke various
 158 operations on the widget.  It has the following general form:
 159 .DS C
 160 \fIpathName option \fR?\fIarg arg ...\fR?
 161 .DE
 162 \fIOption\fR and the \fIarg\fRs
 163 determine the exact behavior of the command.  The following
 164 commands are possible for radiobutton widgets:
 165 .TP
 166 \fIpathName \fBcget\fR \fIoption\fR
 167 Returns the current value of the configuration option given
 168 by \fIoption\fR.
 169 \fIOption\fR may have any of the values accepted by the \fBradiobutton\fR
 170 command.
 171 .TP
 172 \fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR?
 173 Query or modify the configuration options of the widget.
 174 If no \fIoption\fR is specified, returns a list describing all of
 175 the available options for \fIpathName\fR. If \fIoption\fR is specified
 176 with no \fIvalue\fR, the command returns a list describing the
 177 one named option (this list will be identical to the corresponding
 178 sublist of the value returned if no \fIoption\fR is specified).  If
 179 one or more \fIoption\-value\fR pairs are specified, the command
 180 modifies the given widget option(s) to have the given value(s);  in
 181 this case the command returns an empty string.
 182 \fIOption\fR may have any of the values accepted by the \fBradiobutton\fR
 183 command.
 184 .TP
 185 \fIpathName \fBdeselect\fR
 186 Deselects the radiobutton and sets the associated variable to an
 187 empty string.
 188 If this radiobutton was not currently selected, the command has
 189 no effect.
 190 .TP
 191 \fIpathName \fBinvoke\fR
 192 Does just what would have happened if the user invoked the radiobutton
 193 with the mouse: selects the button and invokes
 194 its associated Tcl command, if there is one.
 195 The return value is the return value from the Tcl command, or an
 196 empty string if there is no command associated with the radiobutton.
 197 This command is ignored if the radiobutton's state is \fBdisabled\fR.
 198 .TP
 199 \fIpathName \fBselect\fR
 200 Selects the radiobutton and sets the associated variable to the
 201 value corresponding to this widget.
 202
 203 .SH BINDINGS
 204 .PP
 205 Ck automatically creates class bindings for radiobuttons that give them
 206 the following default behavior:
 207 .IP [1]
 208 The radiobutton activates whenever it gets the input focus and deactivates
 209 whenever it loses the input focus.
 210 .IP [2]
 211 When mouse button 1 is pressed over a radiobutton it is invoked (it
 212 becomes selected and the command associated with the button is
 213 invoked, if there is one).
 214 .IP [3]
 215 When a radiobutton has the input focus, the space or return keys cause
 216 the radiobutton to be invoked.
 217 .PP
 218 If the radiobutton's state is \fBdisabled\fR then none of the above
 219 actions occur:  the radiobutton is completely non-responsive.
 220 .PP
 221 The behavior of radiobuttons can be changed by defining new bindings for
 222 individual widgets or by redefining the class bindings.
 223
 224 .SH KEYWORDS
 225 radiobutton, widget