tk4.2 User Commands - radiobutton






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  button.
          This  command  is typically invoked when mouse button 1
          is released over the button window.  The button's  glo-
          bal  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 accept-
          able 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, 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.

     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 back-
          ground  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.   Dis-
          abled state means that the radiobutton should be insen-
          sitive:  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  ini-
     tial  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 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 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 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.  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 moni-
     tors 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.  Con-
     figuration 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 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 com-
     mand.   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  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  sub-
          list  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 vari-
          able  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 com-
          mand, or an empty string if there is no command associ-
          ated  with the radiobutton.  This command is ignored if
          the radiobutton's state is disabled.

     pathName select
          Selects the radiobutton and sets the  associated  vari-
          able 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