summaryrefslogtreecommitdiff
path: root/Master/tlpkg/tlperl/lib/Tk/Checkbutton.pod
diff options
context:
space:
mode:
Diffstat (limited to 'Master/tlpkg/tlperl/lib/Tk/Checkbutton.pod')
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/Checkbutton.pod347
1 files changed, 347 insertions, 0 deletions
diff --git a/Master/tlpkg/tlperl/lib/Tk/Checkbutton.pod b/Master/tlpkg/tlperl/lib/Tk/Checkbutton.pod
new file mode 100644
index 00000000000..710e1192055
--- /dev/null
+++ b/Master/tlpkg/tlperl/lib/Tk/Checkbutton.pod
@@ -0,0 +1,347 @@
+# 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::Checkbutton - Create and manipulate Checkbutton widgets
+
+=for category Tk Widget Classes
+
+=head1 SYNOPSIS
+
+I<$checkbutton> = I<$parent>-E<gt>B<Checkbutton>(?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 Name: B<offValue>
+
+=item Class: B<Value>
+
+=item Switch: B<-offvalue>
+
+Specifies value to store in the button's associated variable whenever
+this button is deselected. Defaults to ``0''.
+
+=item Name: B<onValue>
+
+=item Class: B<Value>
+
+=item Switch: B<-onvalue>
+
+Specifies value to store in the button's associated variable whenever
+this button is selected. Defaults to ``1''.
+
+=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 checkbutton 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 checkbutton: B<normal>, B<active>,
+or B<disabled>. In normal state the checkbutton is displayed using the
+B<foreground> and B<background> options. The active state is
+typically used when the pointer is over the checkbutton. In active state
+the checkbutton is displayed using the B<activeForeground> and
+B<activeBackground> options. Disabled state means that the checkbutton
+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 checkbutton is displayed.
+
+=item Name: B<variable>
+
+=item Class: B<Variable>
+
+=item Switch: B<-variable>
+
+Specifies reference to a variable to set to indicate whether
+or not this button is selected. Defaults to C<\$widget-E<gt>{'Value'}>
+member of the widget's hash. In general perl variables are C<undef> unless
+specifically initialized which will not match either default B<-onvalue> or
+default B<-offvalue>.
+
+=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 then 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<Checkbutton> method creates a new window (given by the
+$widget argument) and makes it into a checkbutton widget.
+Additional
+options, described above, may be specified on the command line
+or in the option database
+to configure aspects of the checkbutton such as its colors, font,
+text, and initial relief. The B<checkbutton> 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 checkbutton is a widget
+that displays a textual string, bitmap or image
+and a square 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 checkbutton has
+all of the behavior of a simple button, including the
+following: 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
+checkbutton.
+
+In addition, checkbuttons can be I<selected>.
+If a checkbutton is selected then the indicator is normally
+drawn with a selected appearance, and
+a Tcl variable associated with the checkbutton 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 check mark inside.
+If the checkbutton 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 check mark inside.
+By default, the name of the variable associated with a checkbutton is the
+same as the I<name> used to create the checkbutton.
+The variable name, and the ``on'' and ``off'' values stored in 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 checkbutton is configured to select and deselect
+itself on alternate button clicks.
+In addition, each checkbutton monitors its associated variable and
+automatically selects and deselects itself when the variables value
+changes to and from the button's ``on'' value.
+
+=head1 WIDGET METHODS
+
+The B<Checkbutton> 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 checkbutton widgets:
+
+=over 4
+
+=item I<$checkbutton>-E<gt>B<deselect>
+
+Deselects the checkbutton and sets the associated variable to its ``off''
+value.
+
+=item I<$checkbutton>-E<gt>B<flash>
+
+Flashes the checkbutton. This is accomplished by redisplaying the checkbutton
+several times, alternating between active and normal colors. At
+the end of the flash the checkbutton is left in the same normal/active
+state as when the command was invoked.
+This command is ignored if the checkbutton's state is B<disabled>.
+
+=item I<$checkbutton>-E<gt>B<invoke>
+
+Does just what would have happened if the user invoked the checkbutton
+with the mouse: toggle the selection state of the button and invoke
+the L<perlE<sol>Tk callback|Tk::callbacks> associated with the checkbutton, if there is one.
+The return value is the return value from the L<perlE<sol>Tk callback|Tk::callbacks>, or an
+empty string if there is no command associated with the checkbutton.
+This command is ignored if the checkbutton's state is B<disabled>.
+
+=item I<$checkbutton>-E<gt>B<select>
+
+Selects the checkbutton and sets the associated variable to its ``on''
+value.
+
+=item I<$checkbutton>-E<gt>B<toggle>
+
+Toggles the selection state of the button, redisplaying it and
+modifying its associated variable to reflect the new state.
+
+=back
+
+=head1 BINDINGS
+
+Tk automatically creates class bindings for checkbuttons that give them
+the following default behavior:
+
+=over 4
+
+=item [1]
+
+On Unix systems, a checkbutton activates whenever the mouse passes
+over it and deactivates whenever the mouse leaves the checkbutton. On
+Mac and Windows systems, when mouse button 1 is pressed over a
+checkbutton, 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 checkbutton, it is invoked (its
+selection state toggles and the command associated with the button is
+invoked, if there is one).
+
+=item [3]
+
+When a checkbutton has the input focus, the space key causes the checkbutton
+to be invoked. Under Windows, there are additional key bindings; plus
+(+) and equal (=) select the button, and minus (-) deselects the button.
+
+If the checkbutton's state is B<disabled> then none of the above
+actions occur: the checkbutton is completely non-responsive.
+
+The behavior of checkbuttons can be changed by defining new bindings for
+individual widgets or by redefining the class bindings.
+
+=back
+
+=head1 KEYWORDS
+
+checkbutton, widget
+
+=cut
+