1Checkbutton(3)        User Contributed Perl Documentation       Checkbutton(3)
2
3
4

NAME

6       Tk::Checkbutton - Create and manipulate Checkbutton widgets
7

SYNOPSIS

9       $checkbutton = $parent->Checkbutton(?options?);
10

STANDARD OPTIONS

12       -activebackground -activeforeground -anchor -background -bitmap
13       -borderwidth -compound -cursor -disabledforeground -font -foreground
14       -highlightbackground -highlightcolor -highlightthickness -image
15       -justify -padx -pady -relief -takefocus -text -textvariable -underline
16       -wraplength
17
18       See Tk::options for details of the standard options.
19

WIDGET-SPECIFIC OPTIONS

21       Name:     command
22       Class:    Command
23       Switch:   -command
24           Specifies a perl/Tk callback to associate with the button.  This
25           command is typically invoked when mouse button 1 is released over
26           the button window.  The button's global variable (-variable option)
27           will be updated before the command is invoked.
28
29       Name:     height
30       Class:    Height
31       Switch:   -height
32           Specifies a desired height for the button.  If an image or bitmap
33           is being displayed in the button then the value is in screen units
34           (i.e. any of the forms acceptable to Tk_GetPixels); for text it is
35           in lines of text.  If this option isn't specified, the button's
36           desired height is computed from the size of the image or bitmap or
37           text being displayed in it.
38
39       Name:     indicatorOn
40       Class:    IndicatorOn
41       Switch:   -indicatoron
42           Specifies whether or not the indicator should be drawn.  Must be a
43           proper boolean value.  If false, the relief option is ignored and
44           the widget's relief is always sunken if the widget is selected and
45           raised otherwise.
46
47       Command-Line Name: -offrelief
48       Database Name:  offRelief
49       Database Class: OffRelief
50           Specifies the relief for the checkbutton when the indicator is not
51           drawn and the checkbutton is off.  The default value is raised.  By
52           setting this option to flat and setting -indicatoron false
53           -overrelief raised, the effect is achieved of having a flat button
54           that raises on mouse-over and which is depressed when activated.
55           This is the behavior typically exhibited by the Bold, Italic, and
56           Underline checkbuttons on the toolbar of a word-processor, for
57           example.
58
59       Name:     offValue
60       Class:    Value
61       Switch:   -offvalue
62           Specifies value to store in the button's associated variable
63           whenever this button is deselected.  Defaults to ``0''.
64
65       Name:     onValue
66       Class:    Value
67       Switch:   -onvalue
68           Specifies value to store in the button's associated variable
69           whenever this button is selected.  Defaults to ``1''.
70
71       Command-Line Name: -overrelief
72       Database Name:  overRelief
73       Database Class: OverRelief
74           Specifies  an alternative relief for the button, to be used when
75           the mouse cursor is over the widget.  This option can be used to
76           make  toolbar  buttons,  by configuring -relief flat -overrelief
77           raised.  If the value of this option is the empty  string,  then no
78           alternative relief is used when the mouse cursor is over the
79           button.  The empty string is the default value.
80
81       Name:     selectColor
82       Class:    Background
83       Switch:   -selectcolor
84           Specifies a background color to use when the button is selected.
85           If indicatorOn is true then the color applies to the indicator.
86           Under Windows, this color is used as the background for the
87           indicator regardless of the select state.  If indicatorOn is false,
88           this color is used as the background for the entire widget, in
89           place of background or activeBackground, whenever the widget is
90           selected.  If specified as an empty string then no special color is
91           used for displaying when the widget is selected.
92
93       Name:     selectImage
94       Class:    SelectImage
95       Switch:   -selectimage
96           Specifies an image to display (in place of the image option) when
97           the checkbutton is selected.  This option is ignored unless the
98           image option has been specified.
99
100       Name:     state
101       Class:    State
102       Switch:   -state
103           Specifies one of three states for the checkbutton:  normal, active,
104           or disabled.  In normal state the checkbutton is displayed using
105           the foreground and background options.  The active state is
106           typically used when the pointer is over the checkbutton.  In active
107           state the checkbutton is displayed using the activeForeground and
108           activeBackground options.  Disabled state means that the
109           checkbutton should be insensitive:  the default bindings will
110           refuse to activate the widget and will ignore mouse button presses.
111           In this state the disabledForeground and background options
112           determine how the checkbutton is displayed.
113
114       Name:     variable
115       Class:    Variable
116       Switch:   -variable
117           Specifies reference to a variable to set to indicate whether or not
118           this button is selected.  Defaults to "\$widget->{'Value'}" member
119           of the widget's hash. In general perl variables are "undef" unless
120           specifically initialized which will not match either default
121           -onvalue or default -offvalue.
122
123       Name:     width
124       Class:    Width
125       Switch:   -width
126           Specifies a desired width for the button.  If an image or bitmap is
127           being displayed in the button then the value is in screen units
128           (i.e. any of the forms acceptable to Tk_GetPixels); for text it is
129           in characters.  If this option isn't specified, the button's
130           desired width is computed from the size of the image or bitmap or
131           text being displayed in it.
132

DESCRIPTION

134       The Checkbutton method creates a new window (given by the $widget
135       argument) and makes it into a checkbutton widget.  Additional options,
136       described above, may be specified on the command line or in the option
137       database to configure aspects of the checkbutton such as its colors,
138       font, text, and initial relief.  The checkbutton command returns its
139       $widget argument.  At the time this command is invoked, there must not
140       exist a window named $widget, but $widget's parent must exist.
141
142       A checkbutton is a widget that displays a textual string, bitmap or
143       image and a square called an indicator.  If text is displayed, it must
144       all be in a single font, but it can occupy multiple lines on the screen
145       (if it contains newlines or if wrapping occurs because of the
146       wrapLength option) and one of the characters may optionally be
147       underlined using the underline option.  A checkbutton has all of the
148       behavior of a simple button, including the following: it can display
149       itself in either of three different ways, according to the state
150       option; it can be made to appear raised, sunken, or flat; it can be
151       made to flash; and it invokes a perl/Tk callback whenever mouse button
152       1 is clicked over the checkbutton.
153
154       In addition, checkbuttons can be selected.  If a checkbutton is
155       selected then the indicator is normally drawn with a selected
156       appearance, and a Tcl variable associated with the checkbutton is set
157       to a particular value (normally 1).  Under Unix, the indicator is drawn
158       with a sunken relief and a special color.  Under Windows, the indicator
159       is drawn with a check mark inside.  If the checkbutton is not selected,
160       then the indicator is drawn with a deselected appearance, and the
161       associated variable is set to a different value (typically 0).  Under
162       Unix, the indicator is drawn with a raised relief and no special color.
163       Under Windows, the indicator is drawn without a check mark inside.  By
164       default, the name of the variable associated with a checkbutton is the
165       same as the name used to create the checkbutton.  The variable name,
166       and the ``on'' and ``off'' values stored in it, may be modified with
167       options on the command line or in the option database.  Configuration
168       options may also be used to modify the way the indicator is displayed
169       (or whether it is displayed at all).  By default a checkbutton is
170       configured to select and deselect itself on alternate button clicks.
171       In addition, each checkbutton monitors its associated variable and
172       automatically selects and deselects itself when the variables value
173       changes to and from the button's ``on'' value.
174

WIDGET METHODS

176       The Checkbutton method creates a widget object.  This object supports
177       the configure and cget methods described in Tk::options which can be
178       used to enquire and modify the options described above.  The widget
179       also inherits all the methods provided by the generic Tk::Widget class.
180
181       The following additional methods are available for checkbutton widgets:
182
183       $checkbutton->deselect
184           Deselects the checkbutton and sets the associated variable to its
185           ``off'' value.
186
187       $checkbutton->flash
188           Flashes the checkbutton.  This is accomplished by redisplaying the
189           checkbutton several times, alternating between active and normal
190           colors.  At the end of the flash the checkbutton is left in the
191           same normal/active state as when the command was invoked.  This
192           command is ignored if the checkbutton's state is disabled.
193
194       $checkbutton->invoke
195           Does just what would have happened if the user invoked the
196           checkbutton with the mouse: toggle the selection state of the
197           button and invoke the perl/Tk callback associated with the
198           checkbutton, if there is one.  The return value is the return value
199           from the perl/Tk callback, or an empty string if there is no
200           command associated with the checkbutton.  This command is ignored
201           if the checkbutton's state is disabled.
202
203       $checkbutton->select
204           Selects the checkbutton and sets the associated variable to its
205           ``on'' value.
206
207       $checkbutton->toggle
208           Toggles the selection state of the button, redisplaying it and
209           modifying its associated variable to reflect the new state.
210

BINDINGS

212       Tk automatically creates class bindings for checkbuttons that give them
213       the following default behavior:
214
215       [1] On Unix systems, a checkbutton activates whenever the mouse passes
216           over it and deactivates whenever the mouse leaves the checkbutton.
217           On Mac and Windows systems, when mouse button 1 is pressed over a
218           checkbutton, the button activates whenever the mouse pointer is
219           inside the button, and deactivates whenever the mouse pointer
220           leaves the button.
221
222       [2] When mouse button 1 is pressed over a checkbutton, it is invoked
223           (its selection state toggles and the command associated with the
224           button is invoked, if there is one).
225
226       [3] When a checkbutton has the input focus, the space key causes the
227           checkbutton to be invoked.  Under Windows, there are additional key
228           bindings; plus (+) and equal (=) select the button, and minus (-)
229           deselects the button.
230
231           If the checkbutton's state is disabled then none of the above
232           actions occur:  the checkbutton is completely non-responsive.
233
234           The behavior of checkbuttons can be changed by defining new
235           bindings for individual widgets or by redefining the class
236           bindings.
237

KEYWORDS

239       checkbutton, widget
240

POD ERRORS

242       Hey! The above document had some coding errors, which are explained
243       below:
244
245       Around line 57:
246           alternative text 'perl/Tk callback' contains non-escaped | or /
247
248       Around line 217:
249           alternative text 'perl/Tk callback' contains non-escaped | or /
250
251       Around line 287:
252           alternative text 'perl/Tk callback' contains non-escaped | or /
253
254           alternative text 'perl/Tk callback' contains non-escaped | or /
255
256
257
258perl v5.16.3                      2014-06-10                    Checkbutton(3)
Impressum