


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


NAME
       radiobutton - Create and manipulate radiobutton widgets

SYNOPSIS
       (radiobutton                   widget-name                   ?options?-
       :activebackground   :cursor   :highlightthickness :takefocus
       :activeforeground   :disabledforeground :image    :text
       :anchor   :font     :justify  :textvariable
       :background    :foreground    :padx     :underline
       :bitmap   :highlightbackground     :pady     :wraplength
       :borderwidth   :highlightcolor     :relief

WIDGET-SPECIFIC OPTIONS
       Specifies a STk procedure to associate with the button.  This procedure
       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 procedure is invoked.  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.  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.   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 activeBackground, whenever the widget  is  selected.   If
       specified  as  an empty string, no special color is used for displaying
       when the widget is selected.  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.  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  back-
       ground  options  determine how the radiobutton is displayed.  Specifies
       if the value set to variable by :value  must  be  stringified.  Default
       value  for  this  option is #t.  See checkbutton for a similar example.
       Specifies value to store in the button's associated  variable  whenever
       this  button  is  selected.   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
       *selected-button*.  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.



STk                            3.1                              1





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


DESCRIPTION
       The  radiobutton  procedure  creates  a  new  window (given by the wid-
       get-name argument) and makes it into a radiobutton widget.   Additional
       options,  described above, may be specified on the procedure line or in
       the option database to configure aspects of the radiobutton such as its
       colors,  font,  text,  and  initial  relief.  The radiobutton procedure
       returns its widget-name  argument.   At  the  time  this  procedure  is
       invoked,  there  must  not  exist  a window named widget-name, but wid-
       get-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 behav-
       ior of a simple button: it can display itself in either of  three  dif-
       ferent  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  STk
       procedure 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 sunken  relief  and  a
       special  color,  and  a STk 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  variable'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  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 procedure 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 radio button is configured to select itself on button clicks.


WIDGET PROCEDURE
       The  radiobutton  procedure  creates  a new STk procedure whose name is
       widget-name.  This procedure may be used to invoke  various  operations
       on  the widget.  It has the following general form: (widget-name option
       ?arg arg ...?)  Option and the args determine the exact behavior of the
       procedure.   The following procedures are possible for radiobutton wid-
       gets:

       (widget-name 'cget option)
              Returns the current value of the configuration option  given  by
              option.   Option  may  have  any  of  the values accepted by the
              radiobutton procedure.




STk                            3.1                              2





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


       (widget-name '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 widget-name (see Tk_ConfigureInfo for  informa-
              tion  on  the format of this list).  If option is specified with
              no value, the procedure 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 procedure modifies
              the given widget option(s) to have the given value(s);  in  this
              case the procedure returns an empty string.  Option may have any
              of the values accepted by the radiobutton procedure.

       (widget-name 'deselect)
              Deselects the radiobutton and sets the associated variable to an
              empty  string.   If this radiobutton was not currently selected,
              the procedure has no effect.

       (widget-name '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 procedure was
              invoked.  This procedure is ignored if the  radiobutton's  state
              is disabled.

       (widget-name 'invoke)
              Does  just  what  would  have  happened  if the user invoked the
              radiobutton with the mouse: selects the button and  invokes  its
              associated  STk  procedure,  if  there  is  one (return value is
              undifined)..  This procedure is  ignored  if  the  radiobutton's
              state is disabled.

       (widget-name '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 procedure associated with the but-
              ton 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.



STk                            3.1                              3





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


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


SEE ALSO
       button, checkbutton



















































STk                            3.1                              4


