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  but-
              ton.   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
       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 active-
              Background, 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 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  path-
       Name's parent must exist.

       A  radiobutton is a widget that displays a textual string,
       bitmap or image and a diamond or circle called an  indica-
       tor.   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  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 radiobut-
       ton 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 dif-
       ferent 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 vari-
       able 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 var-
       ious  operations on the widget.  It has the following gen-
       eral 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  path-
              Name  (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 modi-
              fies 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, alter-
              nating 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 radiobut-
              ton'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  Win-
              dows 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.


KEYWORDS
       radiobutton, widget
