A. Tk Widget Reference

Contents:
Button
Canvas
Entry
Listbox
Menus
Scrollbars and Scrolling
Scale
HList - Hierarchical List

The least flexible component of any system is the user.

- Lowell Jay Arthur

This appendix covers the most commonly used properties and methods of Tk widgets. Please refer to the extensive online documentation accompanying the Tk distribution for more details.

Table A.1 shows all the properties and methods shared by almost all widgets.

Table A.1: Generic Widget Properties
Properties	Description
font	Discussed in the section "Fonts" .
background, foreground	A name ("red") or an RGB value ("#FF00FA"). The options can also be abbreviated to `bg` and `fg` . Discussed in the section "Colors" .
text	The string to be displayed inside the widget. This is displayed in the foreground color in the font specified above.
image, bitmap	Specifies a bitmap to be displayed inside the widget. Refer to the section "Images" for a discussion on creating and managing bitmaps.
relief	Border style: one of `raised` , `sunken` , `flat` , `ridge` , or `groove` . Should be accompanied by a nonzero borderwidth option.
height, width	Typically the height and width in pixels, except for labels, buttons, and text widgets, in which it is in number of characters (a multiple of average character width and height in that widget's font).
textvariable	Specifies the name of a variable. When the value of a widget changes, this variable is updated, and vice versa.
anchor	Specifies how the widget or the information within it is positioned. Must be one of `n` , `ne` , `e` , `se` , `s` , `sw` , `w` , `nw` , or `center` . For example, an anchor value of "`nw` " tells a label widget to display its label text at its top-left corner.
Methods
configure( )	Change many attributes at once: `$widget->configure ('bg' =>'red','width' => 20);`
cget( )	Get the current value for a given option: `$color = $widget->cget('bg');`

Note that properties such as text and textvariable are not applicable to all widgets; for example, text is wasted on a scrollbar. The properties can optionally be preceded by a hyphen (it is necessary to do so in Tcl/Tk but is optional in Perl/Tk).

A.1 Button

Buttons are labels with one additional property: the command option, shown in Table A.2 . As was mentioned earlier, these properties are in addition to many of the ones mentioned in Table A.1 .

Table A.2: Button Methods and Properties
Properties	Description
command	Specifies a reference to a Perl subroutine, which is called when mouse button 1 (by default) is released over the button.
width, height	Specifies the width and height in characters.
Methods
flash( )	Flashes the button by briefly toggling its colors.
invoke( )	Invokes the Perl subroutine associated with the button, if any.

A.1.1 Radiobutton

Table A.3: Radiobutton Properties and Methods
Properties	Description
command	Specifies a reference to a Perl subroutine, which is called when mouse button 1 (by default) is released over the radiobutton. The variable associated with "variable" is updated before the command is invoked.
variable	Takes a reference to a variable and updates it with the "value" property's value when the button is clicked. Conversely, when it is updated to have the same value as the "value" property, it selects the button (or deselects it in all other cases).
value	Specifies the value to store in the button's associated variable whenever this button is selected.
Methods
select( )	Selects the radiobutton and sets the associated variable to the value corresponding to this widget.
flash( )	Flashes the button by briefly toggling its colors.
invoke( )	Invokes the Perl subroutine associated with the button, if any.

A.1.2 Checkbutton

Table A.4: Checkbutton Properties and Methods
Properties	Description
command	Specifies a reference to a Perl subroutine, which is called when mouse button 1 (by default) is released over the button. The variable associated with "variable" is updated before the command is invoked.
variable	Takes a reference to a variable and updates it with the "onvalue" or "offvalue" property's value, depending upon the state of the indicator. Conversely, when it is updated, it matches itself with one of these values and appropriately selects or deselects itself.
onvalue, offvalue	Toggles the indicator depending upon which of these values match the variable's value. They default to 1 and 0, respectively.
indicatoron	If false, it does not display the indicator. Instead, it toggles the "relief" property of the entire widget (which makes it looked like a pressed button).
Methods
select( )	Selects the checkbutton and sets the associated variable to the "onvalue" value.
flash( )	Flashes the button by briefly toggling its colors.
invoke( )	Invokes the Perl subroutine associated with the command property, if any.
toggle( )	Toggles the selection state and the variables value of the button.