radiobutton(n) Tk (4.4) radiobutton(n)
_________________________________________________________________
NAME
radiobutton - Create and manipulate radiobutton widgets
SYNOPSIS
radiobutton pathName ?options?
STANDARD OPTIONS
-activebackground-cursor-highlightthickness-takefocus
-activeforeground-disabledforeground-image-text
-anchor-font-justify-textvariable
-background-foreground-padx-underline
-bitmap-highlightbackground-pady-wraplength
-borderwidth-highlightcolor-relief
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 command 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 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 lines of
text. If this option isn't 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:-selectcolor
Page 1 (printed 2/26/99)
radiobutton(n) Tk (4.4) radiobutton(n)
Database Name: selectColor
Database Class: Background
Specifies a background color to use when the button is
selected. If indicatorOn is true then the color
applies to the indicator. Under Windows, this color is
used as the background for the indicator regardless of
the select state. If indicatorOn is false, this color
is used as the background for the entire widget, in
place of background or activeBackground, whenever 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 radiobutton 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 radiobutton:
normal, active, or disabled. In normal state the
radiobutton is displayed using the foreground and
background options. The active state is typically used
when the pointer is over the radiobutton. In active
state the radiobutton is displayed using the
activeForeground and activeBackground options.
Disabled state means that the radiobutton should be
insensitive: the default bindings will refuse to
activate the widget and will ignore mouse button
presses. In this state the disabledForeground and
background options determine how the radiobutton is
displayed.
Command-Line Name:-value
Database Name: value
Database Class: Value
Specifies value to store in the button's associated
variable whenever this button is selected.
Command-Line Name:-variable
Database Name: variable
Database Class: Variable
Specifies name of global variable to set whenever this
Page 2 (printed 2/26/99)
radiobutton(n) Tk (4.4) radiobutton(n)
button is selected. Changes in this variable also
cause the button to select or deselect itself.
Defaults to the value selectedButton.
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, 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 isn't specified, the button's desired width is
computed from the size of the image or bitmap or text
being displayed in it.
_________________________________________________________________
DESCRIPTION
The radiobutton command creates a new window (given by the
pathName argument) and makes it into a radiobutton widget.
Additional options, described above, may be specified on the
command line or in the option database to configure aspects
of the radiobutton such as its colors, font, text, and
initial relief. The radiobutton 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 radiobutton is a widget that displays a textual string, |
bitmap or image and a diamond or circle 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
underlined using the underline option. A radiobutton has
all of the behavior of a simple button: 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 check button.
In addition, radiobuttons can be selected. If a radiobutton
is selected, the indicator is normally drawn with a selected |
appearance, and a Tcl variable associated with the |
radiobutton is set to a particular value (normally 1). |
Under Unix, the indicator is drawn with a sunken relief and |
a special color. Under Windows, the indicator is drawn with |
a round mark inside. If the radiobutton is not selected, |
then the indicator is drawn with a deselected appearance, |
and the associated variable is set to a different value |
(typically 0). Under Unix, the indicator is drawn with a |
Page 3 (printed 2/26/99)
radiobutton(n) Tk (4.4) radiobutton(n)
raised relief and no special color. Under Windows, the |
indicator is drawn without a round mark inside. Typically,
several radiobuttons share a single variable and the value
of the variable indicates which radiobutton is to be
selected. When a radiobutton is selected it sets the value
of the variable to indicate that fact; each radiobutton
also monitors the value of the variable and automatically
selects and deselects itself when the variable's value
changes. By default the variable selectedButton is used;
its contents give the name of the button that is selected,
or the empty string if no button associated with that
variable is selected. The name of the variable for a
radiobutton, plus the variable to be stored into 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 radiobutton is configured
to select itself on button clicks.
WIDGET COMMAND
The radiobutton command creates a new Tcl command whose name
is pathName. 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
radiobutton 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 radiobutton 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 available options for pathName
(see Tk_ConfigureInfo for information on the format of
this list). If option is specified with no value, 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, 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 radiobutton command.
pathName deselect
Deselects the radiobutton and sets the associated
Page 4 (printed 2/26/99)
radiobutton(n) Tk (4.4) radiobutton(n)
variable to an empty string. If this radiobutton was
not currently selected, the command has no effect.
pathName flash
Flashes the radiobutton. This is accomplished by
redisplaying the radiobutton several times, alternating
between active and normal colors. At the end of the
flash the radiobutton is left in the same normal/active
state as when the command was invoked. This command is
ignored if the radiobutton's state is disabled.
pathName invoke
Does just what would have happened if the user invoked
the radiobutton with the mouse: selects the button and
invokes its associated Tcl command, if there is one.
The return value is the return value from the Tcl
command, or an empty string if there is no command
associated with the radiobutton. This command is
ignored if the radiobutton's state is disabled.
pathName select
Selects the radiobutton and sets the associated
variable to the value corresponding to this widget.
BINDINGS
Tk automatically creates class bindings for radiobuttons
that give them the following default behavior: |
[1] ||
On Unix systems, a radiobutton activates whenever the |
mouse passes over it and deactivates whenever the mouse |
leaves the radiobutton. On Mac and Windows systems, |
when mouse button 1 is pressed over a radiobutton, 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 radiobutton it is
invoked (it becomes selected and the command associated
with the button is invoked, if there is one).
[3] When a radiobutton has the input focus, the space key
causes the radiobutton to be invoked.
If the radiobutton's state is disabled then none of the
above actions occur: the radiobutton is completely non-
responsive.
The behavior of radiobuttons can be changed by defining new
bindings for individual widgets or by redefining the class
bindings.
Page 5 (printed 2/26/99)
radiobutton(n) Tk (4.4) radiobutton(n)
KEYWORDS
radiobutton, widget
Page 6 (printed 2/26/99)
