summaryrefslogtreecommitdiff
path: root/Master/tlpkg/tlperl/lib/Tk/Radiobutton.pod
diff options
context:
space:
mode:
Diffstat (limited to 'Master/tlpkg/tlperl/lib/Tk/Radiobutton.pod')
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/Radiobutton.pod333
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..82fad4893fd
--- /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<perl/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<perl/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
+