diff options
Diffstat (limited to 'Master/tlpkg/tlperl/lib/Tk/Radiobutton.pod')
| -rw-r--r-- | Master/tlpkg/tlperl/lib/Tk/Radiobutton.pod | 333 |
1 files changed, 333 insertions, 0 deletions
diff --git a/Master/tlpkg/tlperl/lib/Tk/Radiobutton.pod b/Master/tlpkg/tlperl/lib/Tk/Radiobutton.pod new file mode 100644 index 00000000000..4a1cee57d20 --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Tk/Radiobutton.pod @@ -0,0 +1,333 @@ +# Copyright (c) 1990-1994 The Regents of the University of California. +# Copyright (c) 1994-1996 Sun Microsystems, Inc. +# See the file "license.terms" for information on usage and redistribution +# of this file, and for a DISCLAIMER OF ALL WARRANTIES. +# +# + +=head1 NAME + +Tk::Radiobutton - Create and manipulate Radiobutton widgets + +=for category Tk Widget Classes + +=head1 SYNOPSIS + +I<$radiobutton> = I<$parent>-E<gt>B<Radiobutton>(?I<options>?); + +=head1 STANDARD OPTIONS + +B<-activebackground> +B<-activeforeground> +B<-anchor> +B<-background> +B<-bitmap> +B<-borderwidth> +B<-compound> +B<-cursor> +B<-disabledforeground> +B<-font> +B<-foreground> +B<-highlightbackground> +B<-highlightcolor> +B<-highlightthickness> +B<-image> +B<-justify> +B<-padx> +B<-pady> +B<-relief> +B<-takefocus> +B<-text> +B<-textvariable> +B<-underline> +B<-wraplength> + +See L<Tk::options> for details of the standard options. + +=head1 WIDGET-SPECIFIC OPTIONS + +=over 4 + +=item Name: B<command> + +=item Class: B<Command> + +=item Switch: B<-command> + +Specifies a L<perlE<sol>Tk callback|Tk::callbacks> to associate with the button. This command +is typically invoked when mouse button 1 is released over the button +window. The button's global variable (B<-variable> option) will +be updated before the command is invoked. + +=item Name: B<height> + +=item Class: B<Height> + +=item Switch: B<-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 B<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. + +=item Name: B<indicatorOn> + +=item Class: B<IndicatorOn> + +=item Switch: B<-indicatoron> + +Specifies whether or not the indicator should be drawn. Must be a +proper boolean value. If false, the B<relief> option is +ignored and the widget's relief is always sunken if the widget is +selected and raised otherwise. + +=item Command-Line Name: B<-offrelief> + +=item Database Name: B<offRelief> + +=item Database Class: B<OffRelief> + +Specifies the relief for the checkbutton when the indicator is not +drawn and the checkbutton is off. The default value is B<raised>. By +setting this option to B<flat> and setting +B<-indicatoron false -overrelief raised>, the effect is achieved of +having a flat button +that raises on mouse-over and which is depressed when activated. This +is the behavior typically exhibited by the Bold, Italic, and +Underline checkbuttons on the toolbar of a word-processor, for +example. + +=item Command-Line Name: B<-overrelief> + +=item Database Name: B<overRelief> + +=item Database Class: B<OverRelief> + +Specifies an alternative relief for the button, to be used when +the mouse cursor is over the widget. This option can be used to +make toolbar buttons, by configuring B<-relief flat -overrelief +raised>. If the value of this option is the empty string, then +no alternative relief is used when the mouse cursor is over the +button. The empty string is the default value. + +=item Name: B<selectColor> + +=item Class: B<Background> + +=item Switch: B<-selectcolor> + +Specifies a background color to use when the button is selected. +If B<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 B<indicatorOn> is false, this color is used as the background +for the entire widget, in place of B<background> or B<activeBackground>, +whenever the widget is selected. +If specified as an empty string then no special color is used for +displaying when the widget is selected. + +=item Name: B<selectImage> + +=item Class: B<SelectImage> + +=item Switch: B<-selectimage> + +Specifies an image to display (in place of the B<image> option) +when the radiobutton is selected. +This option is ignored unless the B<image> option has been +specified. + +=item Name: B<state> + +=item Class: B<State> + +=item Switch: B<-state> + +Specifies one of three states for the radiobutton: B<normal>, B<active>, +or B<disabled>. In normal state the radiobutton is displayed using the +B<foreground> and B<background> options. The active state is +typically used when the pointer is over the radiobutton. In active state +the radiobutton is displayed using the B<activeForeground> and +B<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 B<disabledForeground> and +B<background> options determine how the radiobutton is displayed. + +=item Name: B<value> + +=item Class: B<Value> + +=item Switch: B<-value> + +Specifies value to store in the button's associated variable whenever +this button is selected. + +=item Name: B<variable> + +=item Class: B<Variable> + +=item Switch: B<-variable> + +Specifies reference to a 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 C<\$Tk::selectedButton>. + +=item Name: B<width> + +=item Class: B<Width> + +=item Switch: B<-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 B<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. + +=back + +=head1 DESCRIPTION + +The B<Radiobutton> method creates a new window (given by the +$widget 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 B<radiobutton> command returns its +$widget argument. At the time this command is invoked, +there must not exist a window named $widget, but +$widget's parent must exist. + +A radiobutton is a widget that displays a textual string, bitmap or image +and a diamond or circle called an I<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 B<wrapLength> option) and +one of the characters may optionally be underlined using the +B<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 B<state> option; +it can be made to appear +raised, sunken, or flat; it can be made to flash; and it invokes +a L<perlE<sol>Tk callback|Tk::callbacks> whenever mouse button 1 is clicked over the +check button. + +In addition, radiobuttons can be I<selected>. +If a radiobutton 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 different 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 B<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. +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. + +=head1 WIDGET METHODS + +The B<Radiobutton> method creates a widget object. +This object supports the B<configure> and B<cget> methods +described in L<Tk::options> which can be used to enquire and +modify the options described above. +The widget also inherits all the methods provided by the generic +L<Tk::Widget|Tk::Widget> class. + +The following additional methods are available for radiobutton widgets: + +=over 4 + +=item I<$radiobutton>-E<gt>B<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. + +=item I<$radiobutton>-E<gt>B<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 B<disabled>. + +=item I<$radiobutton>-E<gt>B<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 B<disabled>. + +=item I<$radiobutton>-E<gt>B<select> + +Selects the radiobutton and sets the associated variable to the +value corresponding to this widget. + +=back + +=head1 BINDINGS + +Tk automatically creates class bindings for radiobuttons that give them +the following default behavior: + +=over 4 + +=item [1] + +On Unix systems, a radiobutton activates whenever the mouse passes +over it and deactivates whenever the mouse leaves the radiobutton. On +Mac and Windows 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. + +=item [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). + +=item [3] + +When a radiobutton has the input focus, the space key causes the radiobutton +to be invoked. + +If the radiobutton's state is B<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. + +=back + +=head1 KEYWORDS + +radiobutton, widget + +=cut + |