NAME
       radiobutton - Create and manipulate radiobutton widgets

SYNOPSIS
       radiobutton pathName ?options?

STANDARD OPTIONS
       -activebackground     -disabledforeground  -padx
       -activeforeground     -font                -pady
       -anchor               -foreground          -relief
       -background           -highlightbackground -takefocus
       -bitmap               -highlightcolor      -text
       -borderwidth          -highlightthickness  -textvariable
       -compound             -image               -underline
       -cursor               -justify             -wraplength

       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 com-
              mand 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  bit-
              map 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
       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  wid-
              get,  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:-offrelief
       Database Name:  offRelief
       Database Class: OffRelief

              Specifies the relief for the checkbutton when the  indicator  is
              not  drawn  and  the  checkbutton  is off.  The default value is
              "raised".  By setting this option to "flat" and setting -indica-
              toron to false and -overrelief to raised, the effect is achieved
              of having a flat button that raises on mouse-over and  which  is
              depressed when activated.  This is the behavior typically exhib-
              ited by the Align-Left, Align-Right, and Center radiobuttons  on
              the toolbar of a word-processor, for example.

       Command-Line Name:-overrelief
       Database Name:  overRelief
       Database Class: OverRelief

              Specifies  an alternative relief for the radiobutton, to be used
              when the mouse cursor is over the widget.  This  option  can  be
              used to make toolbar buttons, by configuring -relief flat -over-
              relief raised.  If the value of this option is the empty string,
              then no alternative relief is used when the mouse cursor is over
              the radiobutton.  The empty string is the default value.

       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 dis-
              played using the foreground and background options.  The  active
              state  is  typically used when the pointer is over the radiobut-
              ton.  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 button is
              selected.   Changes  in  this  variable also cause the button to
              select or deselect itself.  Defaults to the  value  selectedBut-
              ton.

       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 dis-
       played, 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 option-
       ally  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 particu-
       lar  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 asso-
       ciated variable is set to a different value (typically 0).  Under Unix,
       the indicator is drawn with a  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 path-
       Name.  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 avail-
              able 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 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 com-
              mand 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.


SEE ALSO
       checkbutton(n), labelframe(n), listbox(n), options(n), scale(n)


KEYWORDS
