1radiobutton(n)               Tk Built-In Commands               radiobutton(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       radiobutton - Create and manipulate 'radiobutton' pick-one widgets
9

SYNOPSIS

11       radiobutton pathName ?options?
12

STANDARD OPTIONS

14       -activebackground     -disabledforeground  -padx
15       -activeforeground     -font                -pady
16       -anchor               -foreground          -relief
17       -background           -highlightbackground -takefocus
18       -bitmap               -highlightcolor      -text
19       -borderwidth          -highlightthickness  -textvariable
20       -compound             -image               -underline
21       -cursor               -justify             -wraplength
22
23       See the options manual entry for details on the standard options.
24

WIDGET-SPECIFIC OPTIONS

26       Command-Line Name:-command
27       Database Name:  command
28       Database Class: Command
29
30              Specifies a Tcl command to associate with the button.  This com‐
31              mand is typically invoked when mouse button 1 is  released  over
32              the  button  window.   The  button's  global variable (-variable
33              option) will be updated before the command is invoked.
34
35       Command-Line Name:-height
36       Database Name:  height
37       Database Class: Height
38
39              Specifies a desired height for the button.  If an image or  bit‐
40              map is being displayed in the button then the value is in screen
41              units (i.e. any of the forms acceptable  to  Tk_GetPixels);  for
42              text  it  is in lines of text.  If this option is not specified,
43              the button's desired height is computed from  the  size  of  the
44              image or bitmap or text being displayed in it.
45
46       Command-Line Name:-indicatoron
47       Database Name:  indicatorOn
48       Database Class: IndicatorOn
49
50              Specifies whether or not the indicator should be drawn.  Must be
51              a proper boolean value.  If false, the -relief option is ignored
52              and  the  widget's  relief  is  always  sunken  if the widget is
53              selected and raised otherwise.
54
55       Command-Line Name:-offrelief
56       Database Name:  offRelief
57       Database Class: OffRelief
58
59              Specifies the relief for the checkbutton when the  indicator  is
60              not  drawn  and  the  checkbutton  is off.  The default value is
61              “raised”.  By setting this option to “flat” and setting -indica‐
62              toron  to  false  and  -overrelief  to  “raised”,  the effect is
63              achieved of having a flat button that raises on  mouse-over  and
64              which  is  depressed when activated.  This is the behavior typi‐
65              cally exhibited  by  the  Align-Left,  Align-Right,  and  Center
66              radiobuttons on the toolbar of a word-processor, for example.
67
68       Command-Line Name:-overrelief
69       Database Name:  overRelief
70       Database Class: OverRelief
71
72              Specifies  an alternative relief for the radiobutton, to be used
73              when the mouse cursor is over the widget.  This  option  can  be
74              used to make toolbar buttons, by configuring -relief flat -over‐
75              relief raised.  If the value of this option is the empty string,
76              then no alternative relief is used when the mouse cursor is over
77              the radiobutton.  The empty string is the default value.
78
79       Command-Line Name:-selectcolor
80       Database Name:  selectColor
81       Database Class: Background
82
83              Specifies a background color to use when the button is selected.
84              If  indicatorOn is true then the color is used as the background
85              for the indicator regardless of the select state.   If  -indica‐
86              toron  is  false,  this  color is used as the background for the
87              entire widget, in place  of  -background  or  -activeBackground,
88              whenever  the  widget  is  selected.   If  specified as an empty
89              string then no special color is used  for  displaying  when  the
90              widget is selected.
91
92       Command-Line Name:-selectimage
93       Database Name:  selectImage
94       Database Class: SelectImage
95
96              Specifies  an  image  to display (in place of the -image option)
97              when the radiobutton is selected.  This option is ignored unless
98              the -image option has been specified.
99
100       Command-Line Name:-state
101       Database Name:  state
102       Database Class: State
103
104              Specifies  one  of  three  states  for the radiobutton:  normal,
105              active, or disabled.  In normal state the  radiobutton  is  dis‐
106              played  using  the  -foreground  and  -background  options.  The
107              active state is typically used when  the  pointer  is  over  the
108              radiobutton.  In active state the radiobutton is displayed using
109              the -activeforeground and -activebackground  options.   Disabled
110              state  means  that  the  radiobutton should be insensitive:  the
111              default bindings will refuse to activate  the  widget  and  will
112              ignore  mouse  button presses.  In this state the -disabledfore‐
113              ground and -background options determine how the radiobutton  is
114              displayed.
115
116       Command-Line Name:-tristateimage
117       Database Name:  tristateImage
118       Database Class: TristateImage
119
120              Specifies  an  image  to display (in place of the -image option)
121              when the radiobutton is selected.  This option is ignored unless
122              the -image option has been specified.
123
124       Command-Line Name:-tristatevalue
125       Database Name:  tristateValue
126       Database Class: Value
127
128              Specifies  the  value that causes the radiobutton to display the
129              multi-value  selection,  also  known  as  the  tri-state   mode.
130              Defaults to “”.
131
132       Command-Line Name:-value
133       Database Name:  value
134       Database Class: Value
135
136              Specifies  value  to  store  in the button's associated variable
137              whenever this button is selected.
138
139       Command-Line Name:-variable
140       Database Name:  variable
141       Database Class: Variable
142
143              Specifies the name of a global variable  to  set  whenever  this
144              button  is  selected.   Changes  in this variable also cause the
145              button to select or deselect  itself.   Defaults  to  the  value
146              selectedButton.
147
148       Command-Line Name:-width
149       Database Name:  width
150       Database Class: Width
151
152              Specifies a desired width for the button.  If an image or bitmap
153              is being displayed in the button, the value is in  screen  units
154              (i.e.  any of the forms acceptable to Tk_GetPixels); for text it
155              is in characters.  If this option is not specified, the button's
156              desired  width  is computed from the size of the image or bitmap
157              or text being displayed in it.
158______________________________________________________________________________
159

DESCRIPTION

161       The radiobutton command creates a new window  (given  by  the  pathName
162       argument)  and makes it into a radiobutton widget.  Additional options,
163       described above, may be specified on the command line or in the  option
164       database  to  configure  aspects of the radiobutton such as its colors,
165       font, text, and initial relief.  The radiobutton  command  returns  its
166       pathName argument.  At the time this command is invoked, there must not
167       exist a window named pathName, but pathName's parent must exist.
168
169       A radiobutton is a widget that displays a  textual  string,  bitmap  or
170       image  and  a  diamond  or circle called an indicator.  If text is dis‐
171       played, it must all be in a single font, but  it  can  occupy  multiple
172       lines  on  the  screen  (if  it contains newlines or if wrapping occurs
173       because of the -wraplength  option)  and  one  of  the  characters  may
174       optionally  be  underlined  using the -underline option.  A radiobutton
175       has all of the behavior of a simple button: it can  display  itself  in
176       either  of three different ways, according to the -state option; it can
177       be made to appear raised, sunken, or flat; it can be made to flash; and
178       it  invokes  a  Tcl command whenever mouse button 1 is clicked over the
179       check button.
180
181       In addition,  radiobuttons  can  be  selected.   If  a  radiobutton  is
182       selected,  the  indicator is normally drawn with a selected appearance,
183       and a Tcl variable associated with the radiobutton is set to a particu‐
184       lar  value  (normally  1).   Under  Unix, the indicator is drawn with a
185       sunken relief and a special color.  Under  Windows,  the  indicator  is
186       drawn  with  a  round mark inside.  If the radiobutton is not selected,
187       then the indicator is drawn with a deselected appearance, and the asso‐
188       ciated variable is set to a different value (typically 0).  The indica‐
189       tor is drawn without a round mark inside.  Typically, several radiobut‐
190       tons  share  a  single variable and the value of the variable indicates
191       which radiobutton is to be selected.  When a radiobutton is selected it
192       sets the value of the variable to indicate that fact;  each radiobutton
193       also monitors the value of the variable and automatically  selects  and
194       deselects  itself when the variable's value changes.  If the variable's
195       value matches the -tristatevalue, then the radiobutton is  drawn  using
196       the  tri-state  mode.   This mode is used to indicate mixed or multiple
197       values.  (This is used when the radiobutton  represents  the  state  of
198       multiple  items.)  By default the variable selectedButton is used;  its
199       contents give the name of the button that is  selected,  or  the  empty
200       string  if  no  button  associated with that variable is selected.  The
201       name of the variable for a radiobutton, plus the variable to be  stored
202       into  it,  may  be  modified with options on the command line or in the
203       option database.  Configuration options may also be used to modify  the
204       way the indicator is displayed (or whether it is displayed at all).  By
205       default a radiobutton is configured to select itself on button clicks.
206

WIDGET COMMAND

208       The radiobutton command creates a new Tcl command whose name  is  path‐
209       Name.   This  command  may  be used to invoke various operations on the
210       widget.  It has the following general form:
211              pathName option ?arg arg ...?
212       Option and the args determine the exact behavior of the  command.   The
213       following commands are possible for radiobutton widgets:
214
215       pathName cget option
216              Returns  the  current value of the configuration option given by
217              option.  Option may have any  of  the  values  accepted  by  the
218              radiobutton command.
219
220       pathName configure ?option? ?value option value ...?
221              Query  or modify the configuration options of the widget.  If no
222              option is specified, returns a list describing all of the avail‐
223              able  options for pathName (see Tk_ConfigureInfo for information
224              on the format of this list).  If option  is  specified  with  no
225              value,  the  command  returns  a  list  describing the one named
226              option (this list will be identical to the corresponding sublist
227              of  the  value  returned  if no option is specified).  If one or
228              more option-value pairs are specified, the command modifies  the
229              given widget option(s) to have the given value(s);  in this case
230              the command returns an empty string.  Option may have any of the
231              values accepted by the radiobutton command.
232
233       pathName deselect
234              Deselects the radiobutton and sets the associated variable to an
235              empty string.  If this radiobutton was not  currently  selected,
236              the command has no effect.
237
238       pathName flash
239              Flashes  the  radiobutton.  This is accomplished by redisplaying
240              the radiobutton several times, alternating  between  active  and
241              normal  colors.  At the end of the flash the radiobutton is left
242              in the same normal/active state as when the command was invoked.
243              This command is ignored if the radiobutton's state is disabled.
244
245       pathName invoke
246              Does  just  what  would  have  happened  if the user invoked the
247              radiobutton with the mouse: selects the button and  invokes  its
248              associated  Tcl  command,  if there is one.  The return value is
249              the return value from the Tcl command, or  an  empty  string  if
250              there  is no command associated with the radiobutton.  This com‐
251              mand is ignored if the radiobutton's state is disabled.
252
253       pathName select
254              Selects the radiobutton and sets the associated variable to  the
255              value corresponding to this widget.
256

BINDINGS

258       Tk automatically creates class bindings for radiobuttons that give them
259       the following default behavior:
260
261       [1]    On Unix systems, a  radiobutton  activates  whenever  the  mouse
262              passes  over  it  and  deactivates whenever the mouse leaves the
263              radiobutton.  On Mac and Windows systems, when mouse button 1 is
264              pressed  over  a  radiobutton, the button activates whenever the
265              mouse pointer is inside the button, and deactivates whenever the
266              mouse pointer leaves the button.
267
268       [2]    When  mouse button 1 is pressed over a radiobutton it is invoked
269              (it becomes selected and the command associated with the  button
270              is invoked, if there is one).
271
272       [3]    When a radiobutton has the input focus, the space key causes the
273              radiobutton to be invoked.
274
275       If the radiobutton's state is disabled then none of the  above  actions
276       occur:  the radiobutton is completely non-responsive.
277
278       The  behavior  of  radiobuttons can be changed by defining new bindings
279       for individual widgets or by redefining the class bindings.
280

SEE ALSO

282       checkbutton(n),  labelframe(n),   listbox(n),   options(n),   scale(n),
283       ttk::radiobutton(n)
284

KEYWORDS

286       radiobutton, widget
287
288
289
290Tk                                    4.4                       radiobutton(n)
Impressum