diff options
Diffstat (limited to 'Master/tlpkg/tlperl/site/lib/Tk/Checkbutton.pod')
| -rw-r--r-- | Master/tlpkg/tlperl/site/lib/Tk/Checkbutton.pod | 347 |
1 files changed, 347 insertions, 0 deletions
diff --git a/Master/tlpkg/tlperl/site/lib/Tk/Checkbutton.pod b/Master/tlpkg/tlperl/site/lib/Tk/Checkbutton.pod new file mode 100644 index 00000000000..710e1192055 --- /dev/null +++ b/Master/tlpkg/tlperl/site/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 + |