


radiobutton(n)         Tk Built-In Commands        radiobutton(n)


NAME
       radiobutton - Create and manipulate radiobutton widgets

SYNOPSIS
       radiobutton pathName ?options?

STANDARD OPTIONS
       activeBackground               cursor          highlightThicknesstakeFocus
       activeForeground               disabledForegroundimagetext
       anchor          font           justify         textVariable
       background      foreground     padX            underline
       bitmap          highlightColor padY            wrapLength
       borderWidth     highlightBackground            relief

       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  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.

       Name:           indicatorOn
       Class:          IndicatorOn
       Command-Line Switch:-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.

       Name:           selectColor
       Class:          Background
       Command-Line Switch:-selectcolor



Tk                             4.0                              1





radiobutton(n)         Tk Built-In Commands        radiobutton(n)


              Specifies a background color to use when the button
              is selected.  If indicatorOn  is  true,  the  color
              applicies  to  the  indicator.   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, no special color is
              used for displaying when the widget is selected.

       Name:           selectImage
       Class:          SelectImage
       Command-Line Switch:-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.

       Name:           state
       Class:          State
       Command-Line Switch:-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.

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

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

       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



Tk                             4.0                              2





radiobutton(n)         Tk Built-In Commands        radiobutton(n)


       Command-Line Switch:-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 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 under-
       lined 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
       sunken relief and a special  color,  and  a  Tcl  variable
       associated  with  the  radiobutton  is set to a particular
       value.  If the radiobutton is not selected, the  indicator
       is drawn with a raised relief and no special color.  Typi-
       cally, 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 vari-
       able's value changes.  By default the  variable  selected-
       Button  is used;  its contents give the name of the button
       that is selected, or the empty string if no button associ-
       ated  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



Tk                             4.0                              3





radiobutton(n)         Tk Built-In Commands        radiobutton(n)


       be  used  to modify the way the indicator is displayed (or
       whether it is displayed at all).  By default a radio  but-
       ton 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.





Tk                             4.0                              4





radiobutton(n)         Tk Built-In Commands        radiobutton(n)


       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]    The radiobutton activates whenever the mouse passes
              over  it  and deactivates whenever the mouse leaves
              the radiobutton.

       [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
