NAME
       radiobutton - Create and manipulate radio-button widgets

SYNOPSIS
       radiobutton pathName ?options?

STANDARD OPTIONS
       activeBackground               bitmap          fontrelief
       activeForeground               borderWidth     foregroundtext
       anchor          cursor         padX            textVariable
       background      disabledForeground             padX

       See  the ``options'' manual entry for details on the stan-
       dard options.

WIDGET-SPECIFIC OPTIONS
       Name:           command
       Class:          Command
       Command-Line Switch:-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.

       Name:           height
       Class:          Height
       Command-Line Switch:-height

              Specifies a desired height for the  button.   If  a
              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 bitmap or text being displayed in it.

       Name:           selector
       Class:          Foreground
       Command-Line Switch:-selector

              Specifies the color to draw in  the  selector  when
              this  button is selected.  If specified as an empty
              string then no selector is drawn for the button.

       Name:           state
       Class:          State
       Command-Line Switch:-state

              Specifies one of three states for the radio button:
              normal,  active,  or disabled.  In normal state the
              radio button is displayed using the foreground  and
              background  options.  The active state is typically
              used when the pointer is over the radio button.  In
              active  state  the  radio button is displayed using
              the activeForeground and activeBackground  options.
              Disabled  state  means  that  the  radio  button is
              insensitive:   it  doesn't  activate  and   doesn't
              respond to mouse button presses.  In this state the
              disabledForeground and background options determine
              how the radio button is displayed.

       Name:           value
       Class:          Value
       Command-Line Switch:-value

              Specifies value to store in the button's associated
              variable  whenever   this   button   is   selected.
              Defaults to the name of the radio button.

       Name:           variable
       Class:          Variable
       Command-Line Switch:-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.

       Name:           width
       Class:          Width
       Command-Line Switch:-width

              Specifies a desired width for  the  button.   If  a
              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
              characters.  If this option  isn't  specified,  the
              button's desired width is computed from the size of
              the 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 radio button  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 radio button is a widget that displays a textual  string
       or bitmap and a diamond called a selector.  A radio button
       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 com-
       mand whenever mouse button 1 is  clicked  over  the  check
       button.

       In  addition,  radio  buttons can be selected.  If a radio
       button is selected then a special highlight appears in the
       selector and a Tcl variable associated with the radio but-
       ton is set to a particular value.  If the radio button  is
       not  selected  then  the  selector is drawn in a different
       fashion.  Typically, several radio buttons share a  single
       variable  and  the  value  of the variable indicates which
       radio button is to be selected.  When a  radio  button  is
       selected  it  sets  the  value of the variable to indicate
       that fact;  each radio button 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  radio  button,  plus  the
       variable  to  be  stored  into  it,  may  be modified with
       options on the command line or in the option database.  By
       default  a  radio button 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  radio-
       button widgets:

       pathName activate
              Change  the  radio  button's  state  to  active and
              redisplay the button using  its  active  foreground
              and  background  colors  instead  of normal colors.
              This command is ignored if the radio button's state
              is  disabled.   This  command  is obsolete and will
              eventually be  removed;  use  ``pathName  configure
              -state active'' instead.

       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,  then  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,  then  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 deactivate
              Change the  radio  button's  state  to  normal  and
              redisplay  the  button  using its normal foreground
              and background colors.  This command is ignored  if
              the radio button's state is disabled.  This command
              is obsolete and will  eventually  be  removed;  use
              ``pathName configure -state normal'' instead.

       pathName deselect
              Deselect  the radio button:  redisplay it without a
              highlight in the selector and  set  the  associated
              variable  to an empty string.  If this radio button
              was not currently selected, then the command has no
              effect.

       pathName flash
              Flash  the  radio  button.  This is accomplished by
              redisplaying the radio button several times, alter-
              nating  between  active  and normal colors.  At the
              end of the flash the radio button is  left  in  the
              same  normal/active  state  as when the command was
              invoked.  This command is ignored if the radio but-
              ton's state is disabled.

       pathName invoke
              Does  just  what  would  have  happened if the user
              invoked the radio button with the mouse: select the
              button  and  invoke  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  radio  button.
              This command is ignored if the radio button's state
              is disabled.

       pathName select
              Select the radio button:  display it with  a  high-
              lighted selector and set the associated variable to
              the value corresponding to this widget.


BINDINGS
       Tk automatically creates class bindings for radio  buttons
       that give them the following default behavior:

       [1]    The  radio  button  activates  whenever  the  mouse
              passes over it and deactivates whenever  the  mouse
              leaves the radio button.

       [2]    The  radio  button's  relief  is  changed to sunken
              whenever mouse button 1 is pressed over it, and the
              relief  is restored to its original value when but-
              ton 1 is later released.

       [3]    If mouse button 1 is pressed over the radio  button
              and later released over the radio button, the radio
              button is invoked (i.e. it is selected and the com-
              mand  associated  with  the  button  is invoked, if
              there is one).  However, if the mouse is  not  over
              the radio button when button 1 is released, then no
              invocation occurs.

       The behavior of radio buttons can be changed  by  defining
       new  bindings  for individual widgets or by redefining the
       class bindings.


KEYWORDS
       radio button, widget
