tk/doc/radiobutton.n

   1 '\"
   2 '\" Copyright (c) 1990-1994 The Regents of the University of California.
   3 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
   4 '\"
   5 '\" See the file "license.terms" for information on usage and redistribution
   6 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
   7 '\"
   8 '\" RCS: @(#) $Id$
   9 '\"
  10 .so man.macros
  11 .TH radiobutton n 4.4 Tk "Tk Built-In Commands"
  12 .BS
  13 '\" Note:  do not modify the .SH NAME line immediately below!
  14 .SH NAME
  15 radiobutton \- Create and manipulate radiobutton widgets
  16 .SH SYNOPSIS
  17 \fBradiobutton\fR \fIpathName \fR?\fIoptions\fR?
  18 .SO
  19 \-activebackground      \-cursor        \-highlightthickness    \-takefocus
  20 \-activeforeground      \-disabledforeground    \-image \-text
  21 \-anchor        \-font  \-justify       \-textvariable
  22 \-background    \-foreground    \-padx  \-underline
  23 \-bitmap        \-highlightbackground   \-pady  \-wraplength
  24 \-borderwidth   \-highlightcolor        \-relief
  25 .SE
  26 .SH "WIDGET-SPECIFIC OPTIONS"
  27 .OP \-command command Command
  28 Specifies a Tcl command to associate with the button.  This command
  29 is typically invoked when mouse button 1 is released over the button
  30 window.  The button's global variable (\fB\-variable\fR option) will
  31 be updated before the command is invoked.
  32 .OP \-height height Height
  33 Specifies a desired height for the button.
  34 If an image or bitmap is being displayed in the button then the value is in
  35 screen units (i.e. any of the forms acceptable to \fBTk_GetPixels\fR);
  36 for text it is in lines of text.
  37 If this option isn't specified, the button's desired height is computed
  38 from the size of the image or bitmap or text being displayed in it.
  39 .OP \-indicatoron indicatorOn IndicatorOn
  40 Specifies whether or not the indicator should be drawn.  Must be a
  41 proper boolean value.  If false, the \fBrelief\fR option is
  42 ignored and the widget's relief is always sunken if the widget is
  43 selected and raised otherwise.
  44 .OP \-selectcolor selectColor Background
  45 Specifies a background color to use when the button is selected.
  46 If \fBindicatorOn\fR is true then the color applies to the indicator.
  47 Under Windows, this color is used as the background for the indicator
  48 regardless of the select state.
  49 If \fBindicatorOn\fR is false, this color is used as the background
  50 for the entire widget, in place of \fBbackground\fR or \fBactiveBackground\fR,
  51 whenever the widget is selected.
  52 If specified as an empty string then no special color is used for
  53 displaying when the widget is selected.
  54 .OP \-selectimage selectImage SelectImage
  55 Specifies an image to display (in place of the \fBimage\fR option)
  56 when the radiobutton is selected.
  57 This option is ignored unless the \fBimage\fR option has been
  58 specified.
  59 .OP \-state state State
  60 Specifies one of three states for the radiobutton:  \fBnormal\fR, \fBactive\fR,
  61 or \fBdisabled\fR.  In normal state the radiobutton is displayed using the
  62 \fBforeground\fR and \fBbackground\fR options.  The active state is
  63 typically used when the pointer is over the radiobutton.  In active state
  64 the radiobutton is displayed using the \fBactiveForeground\fR and
  65 \fBactiveBackground\fR options.  Disabled state means that the radiobutton
  66 should be insensitive:  the default bindings will refuse to activate
  67 the widget and will ignore mouse button presses.
  68 In this state the \fBdisabledForeground\fR and
  69 \fBbackground\fR options determine how the radiobutton is displayed.
  70 .OP \-value value Value
  71 Specifies value to store in the button's associated variable whenever
  72 this button is selected.
  73 .OP \-variable variable Variable
  74 Specifies name of global variable to set whenever this button is
  75 selected.  Changes in this variable also cause the button to select
  76 or deselect itself.
  77 Defaults to the value \fBselectedButton\fR.
  78 .OP \-width width Width
  79 Specifies a desired width for the button.
  80 If an image or bitmap is being displayed in the button, the value is in
  81 screen units (i.e. any of the forms acceptable to \fBTk_GetPixels\fR);
  82 for text it is in characters.
  83 If this option isn't specified, the button's desired width is computed
  84 from the size of the image or bitmap or text being displayed in it.
  85 .BE
  86
  87 .SH DESCRIPTION
  88 .PP
  89 The \fBradiobutton\fR command creates a new window (given by the
  90 \fIpathName\fR argument) and makes it into a radiobutton widget.
  91 Additional
  92 options, described above, may be specified on the command line
  93 or in the option database
  94 to configure aspects of the radiobutton such as its colors, font,
  95 text, and initial relief.  The \fBradiobutton\fR command returns its
  96 \fIpathName\fR argument.  At the time this command is invoked,
  97 there must not exist a window named \fIpathName\fR, but
  98 \fIpathName\fR's parent must exist.
  99 .PP
 100 .VS
 101 A radiobutton is a widget that displays a textual string, bitmap or image
 102 and a diamond or circle called an \fIindicator\fR.
 103 .VE
 104 If text is displayed, it must all be in a single font, but it
 105 can occupy multiple lines on the screen (if it contains newlines
 106 or if wrapping occurs because of the \fBwrapLength\fR option) and
 107 one of the characters may optionally be underlined using the
 108 \fBunderline\fR option.  A radiobutton has
 109 all of the behavior of a simple button: it can display itself in either
 110 of three different ways, according to the \fBstate\fR option;
 111 it can be made to appear
 112 raised, sunken, or flat; it can be made to flash; and it invokes
 113 a Tcl command whenever mouse button 1 is clicked over the
 114 check button.
 115 .PP
 116 In addition, radiobuttons can be \fIselected\fR.
 117 If a radiobutton is selected, the indicator is normally
 118 .VS
 119 drawn with a selected appearance, and
 120 a Tcl variable associated with the radiobutton is set to a particular
 121 value (normally 1).
 122 Under Unix, the indicator is drawn with a sunken relief and a special
 123 color.  Under Windows, the indicator is drawn with a round mark inside.
 124 If the radiobutton is not selected, then the indicator is drawn with a
 125 deselected appearance, and the associated variable is
 126 set to a different value (typically 0).
 127 Under Unix, the indicator is drawn with a raised relief and no special
 128 color.  Under Windows, the indicator is drawn without a round mark inside.
 129 .VE
 130 Typically, several radiobuttons share a single variable and the
 131 value of the variable indicates which radiobutton is to be selected.
 132 When a radiobutton is selected it sets the value of the variable to
 133 indicate that fact;  each radiobutton also monitors the value of
 134 the variable and automatically selects and deselects itself when the
 135 variable's value changes.
 136 By default the variable \fBselectedButton\fR
 137 is used;  its contents give the name of the button that is
 138 selected, or the empty string if no button associated with that
 139 variable is selected.
 140 The name of the variable for a radiobutton,
 141 plus the variable to be stored into it, may be modified with options
 142 on the command line or in the option database.
 143 Configuration options may also be used to modify the way the
 144 indicator is displayed (or whether it is displayed at all).
 145 By default a radiobutton is configured to select itself on button clicks.
 146
 147 .SH "WIDGET COMMAND"
 148 .PP
 149 The \fBradiobutton\fR command creates a new Tcl command whose
 150 name is \fIpathName\fR.  This
 151 command may be used to invoke various
 152 operations on the widget.  It has the following general form:
 153 .CS
 154 \fIpathName option \fR?\fIarg arg ...\fR?
 155 .CE
 156 \fIOption\fR and the \fIarg\fRs
 157 determine the exact behavior of the command.  The following
 158 commands are possible for radiobutton widgets:
 159 .TP
 160 \fIpathName \fBcget\fR \fIoption\fR
 161 Returns the current value of the configuration option given
 162 by \fIoption\fR.
 163 \fIOption\fR may have any of the values accepted by the \fBradiobutton\fR
 164 command.
 165 .TP
 166 \fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR?
 167 Query or modify the configuration options of the widget.
 168 If no \fIoption\fR is specified, returns a list describing all of
 169 the available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for
 170 information on the format of this list).  If \fIoption\fR is specified
 171 with no \fIvalue\fR, the command returns a list describing the
 172 one named option (this list will be identical to the corresponding
 173 sublist of the value returned if no \fIoption\fR is specified).  If
 174 one or more \fIoption\-value\fR pairs are specified, the command
 175 modifies the given widget option(s) to have the given value(s);  in
 176 this case the command returns an empty string.
 177 \fIOption\fR may have any of the values accepted by the \fBradiobutton\fR
 178 command.
 179 .TP
 180 \fIpathName \fBdeselect\fR
 181 Deselects the radiobutton and sets the associated variable to an
 182 empty string.
 183 If this radiobutton was not currently selected, the command has
 184 no effect.
 185 .TP
 186 \fIpathName \fBflash\fR
 187 Flashes the radiobutton.  This is accomplished by redisplaying the radiobutton
 188 several times, alternating between active and normal colors.  At
 189 the end of the flash the radiobutton is left in the same normal/active
 190 state as when the command was invoked.
 191 This command is ignored if the radiobutton's state is \fBdisabled\fR.
 192 .TP
 193 \fIpathName \fBinvoke\fR
 194 Does just what would have happened if the user invoked the radiobutton
 195 with the mouse: selects the button and invokes
 196 its associated Tcl command, if there is one.
 197 The return value is the return value from the Tcl command, or an
 198 empty string if there is no command associated with the radiobutton.
 199 This command is ignored if the radiobutton's state is \fBdisabled\fR.
 200 .TP
 201 \fIpathName \fBselect\fR
 202 Selects the radiobutton and sets the associated variable to the
 203 value corresponding to this widget.
 204
 205 .SH BINDINGS
 206 .PP
 207 Tk automatically creates class bindings for radiobuttons that give them
 208 the following default behavior:
 209 .VS
 210 .IP [1]
 211 On Unix systems, a radiobutton activates whenever the mouse passes
 212 over it and deactivates whenever the mouse leaves the radiobutton.  On
 213 Mac and Windows systems, when mouse button 1 is pressed over a
 214 radiobutton, the button activates whenever the mouse pointer is inside
 215 the button, and deactivates whenever the mouse pointer leaves the
 216 button.
 217 .VE
 218 .IP [2]
 219 When mouse button 1 is pressed over a radiobutton it is invoked (it
 220 becomes selected and the command associated with the button is
 221 invoked, if there is one).
 222 .IP [3]
 223 When a radiobutton has the input focus, the space key causes the radiobutton
 224 to be invoked.
 225 .PP
 226 If the radiobutton's state is \fBdisabled\fR then none of the above
 227 actions occur:  the radiobutton is completely non-responsive.
 228 .PP
 229 The behavior of radiobuttons can be changed by defining new bindings for
 230 individual widgets or by redefining the class bindings.
 231
 232 .SH KEYWORDS
 233 radiobutton, widget
 234