Each Tk widget has a number of attributes that affect its appearance and behavior. This chapter describes attributes in general, and covers some of the size and appearance-related attributes. The next two chapters cover the attributes associated with colors, images, and text.
This chapter describes some of the attributes that are in common among many Tk widgets. A widget always provides a default value for its attributes, so you can avoid specifying most of them. If you want to fine-tune things, however, you'll need to know about all the widget attributes.
The native widgets implemented in Tk 8.0 ignore some of the original Tk attributes. This is because there is no support for them in the system widgets. For example, the buttons on Macintosh do not honor the borderWidth attribute, and they do not display a highlight focus. The native scrollbars on Windows and Macintosh have similar limitations. This chapter notes these limitations in the discussion of each attribute.
You specify attributes for Tk widgets when you create them. You can also change them dynamically at any time after that. In both cases the syntax uses pairs of arguments. The first item in the pair identifies the attribute, the second provides the value. For example, a button can be created like this:
button .doit -text Doit -command DoSomething
The name of the button is .doit, and two attributes are specified: the text and the command. You can change the .doit button later with the configure widget operation:
.doit configure -text Stop -command StopIt
The current configuration of a widget can be queried with another form of the configure operation. If you just supply an attribute, the settings associated with that attribute are returned:
.doit configure -text
=> -text text Text { } Stop
This command returns several pieces of information: the command line switch, the resource name, the resource class, the default value, and the current value. If you don't give any options to configure, then the configuration information for all the attributes is returned. The following loop formats the information:
foreach item [$w configure] {
puts "[lindex $item 0] [lindex $item 4]"
}
If you just want the current value, use the cget operation:
You can also configure widget attributes indirectly by using the resource database. An advantage of using the resource database is that users can reconfigure your application without touching the code. Otherwise, if you specify attribute values explicitly in the code, they cannot be overridden by resource settings. This is especially important for attributes like fonts and colors.
The tables in this chapter list the attributes by their resource name, which may have a capital letter at an internal word boundary (e.g., activeBackground). When you specify attributes in a Tcl command, use all lowercase instead, plus a leading dash. Compare:
option add *Button.activeBackground red $button configure -activebackground red
The first command defines a resource that affects all buttons created after that point, and the second command changes an existing button. Command-line settings override resource database specifications. Chapter 31 describes the use of resources in detail.
Most widgets have a width and height attribute that specifies their desired size, although there are some special cases. For most widgets, if an explicit size isn't specified, or the size provided is 0 or less, then the widget automatically sizes itself to be just large enough to display its contents. As of Tk 8.4, on Windows, the width attribute for simple button widgets (not checkbuttons, radiobuttons, or menubuttons) accepts a negative value to specify a minimum width, enabling better compliance with native Windows look-and-feel. In all cases, the geometry manager for a widget might modify the size to some degree. The winfo operations described on page 659 return the current size of a widget.
Most of the text-related widgets interpret their sizes in units of characters for width and lines for height. All other widgets, including the message widget, interpret their dimensions in screen units, which are pixels by default. The tk scale command, which is described on page 669, controls the scale between pixels and the other measures. You can suffix the dimension with a unit specifier to get a particular measurement unit:
c centimeters i inch m millimeters p printer points (1/72 inches)
Scales and scrollbars can have two orientations as specified by the orient attribute, so width and height are somewhat ambiguous. These widgets do not support a height attribute, and they interpret their width attribute to mean the size of their narrow dimension. The scale has a length attribute that determines its long dimension. Scrollbars do not even have a length. Instead, a scrollbar is assumed to be packed next to the widget it controls, and the fill packing attribute is used to extend the scrollbar to match the length of its adjacent widget. Example 33-1 on page 500 shows how to arrange scrollbars with another widget.
The message widget displays a fixed string on multiple lines, and it uses one of two attributes to constrain its size: its aspect or its width. The aspect ratio is defined to be 100*width/height, and it formats its text to honor this constraint. However, if a width is specified, it just uses that and uses as many lines (i.e., as much height) as needed. Example 32-6 on page 493 shows how message widgets display text. Table 40-1 summarizes the attributes used to specify the size for widgets:
Table 40-1. Size attribute resource names
It is somewhat unfortunate that text-oriented widgets only take character- and line-oriented dimensions. These sizes change with the font used, and if you want a precise size you might be frustrated. Both pack and grid let the widgets decide how big to be. One trick is to put each widget, such as a label, in its own frame. Specify the size you want for the frame, and then pack the label and turn off size propagation. For example:
Example 40-1. Equal-sized labels
proc EqualSizedLabels { parent width height strings args } {
set l 0
foreach s $strings {
frame $parent.$l -width $width -height $height
pack propagate $parent.$l false
pack $parent.$l -side left
eval {label $parent.$l.l -text $s} $args
pack $parent.$l.l -fill both -expand true
incr l
}
}
frame .f ; pack .f
EqualSizedLabels .f 1i 1c {apple orange strawberry kiwi}
-relief raised
The frames $parent.$l are all created with the same size. The pack propagate command prevents these frames from changing size when the labels are packed into them later. The labels are packed with fill and expand turned on so that they fill up the fixed-sized frames around them.
Another way to get equal sized widgets is with the -uniform column configuration that was added to grid in Tk 8.4. This is described on page 418.
Example 40-2 illustrates the different relief options, which control the way the border around a widget is drawn:
Example 40-2. 3D relief sampler
frame .f -borderwidth 10
pack .f
foreach relief {raised sunken flat ridge groove solid} {
label .f.$relief -text $relief -relief $relief
-bd 2 -padx 3
pack .f.$relief -side left -padx 4
}
The three-dimensional appearance of widgets is determined by two attributes: borderWidth and relief. The borderWidth adds extra space around the edge of a widget's display, and this area can be displayed in a number of ways according to the relief attribute. The solid relief was added in Tk 8.0 to support the Macintosh look for entry widget, and it works well against white backgrounds. Macintosh buttons do not support different reliefs or honor border width.
The activeBorderWidth attribute defines the border width for the menu entries. The relief of a menu is not configurable. It probably is not worth adjusting the menu border width attributes because the default looks OK. The native menus on Windows and Macintosh do not honor this attribute.
The activeRelief attribute applies to the elements of a scrollbar (the elevator and two arrows) when the mouse is over them. The elementBorderWidth sets the size of the relief on these elements. Changing the activeRelief does not look good. The native scrollbars on Macintosh and Windows do not honor this attribute.
The offRelief and overRelief attributes describe a relief style to use when a widget is in the "off state" and its indicator is not drawn, or the mouse cursor is over the widget. They were added in Tk 8.4 to provide better support for creating toolbars. The overRelief attribute applies to buttons, checkbuttons, and radiobuttons. The offRelief attribute applies only to checkbuttons and radiobuttons. Table 40-2 lists the attributes for borders and relief.
Table 40-2. Border and relief attribute resource names
Each widget can have a focus highlight indicating which widget currently has the input focus. This is a thin rectangle around each widget that is displayed in the highlight background color by default. When the widget gets the input focus, the highlight rectangle is displayed in an alternate color. The addition of the highlight adds a small amount of space outside the border described in the previous section. The attributes in Table 40-3 control the width and color of this rectangle. If the width is zero, no highlight is displayed.
By default, only the widgets that normally expect input focus have a nonzero width highlight border. This includes the text, entry, and listbox widgets. It also includes the button and menu widgets because there is a set of keyboard traversal bindings that focus input on these widgets, too. You can define nonzero highlight thicknesses for all widgets except Macintosh buttons.
Table 40-4 lists padding and anchor attributes that are similar in spirit to some packing attributes described in Chapter 25. However, they are distinct from the packing attributes, and this section explains how they work together with the packer.
Table 40-4. Layout attribute resource names
The padding attributes for a widget define space that is never occupied by the display of the widget's contents. For example, if you create a label with the following attributes and pack it into a frame by itself, you will see the text is still centered, despite the anchor attribute.
Example 40-3. Padding provided by labels and buttons
label .foo -text Foo -padx 20 -anchor e pack .foo
The anchor attribute only affects the display if there is extra room for another reason. One way to get extra room is to specify a width attribute that is longer than the text. The following label has right-justified text. You can see the default padX value for labels, which is one pixel:
Another way to get extra display space is with the -ipadx and -ipady packing parameters. The example in the next section illustrates this effect. Chapter 25 has several more examples of the packing parameters.
Example 40-5. Borders and padding
frame .f -bg white label .f.one -text One -relief raised -bd 2 -padx 3m -pady 2m pack .f.one -side top label .f.two -text Two -highlightthickness 4 -highlightcolor red -borderwidth 5 -relief raised -padx 0 -pady 0 -width 10 -anchor nw pack .f.two -side top -pady 10 -ipady 10 -fill both focus .f.two pack .f
The first label uses a raised relief, so you can see the two-pixel border. There is no highlight on a label by default. There is internal padding so that the text is spaced away from the edge of the label. The second label adds a highlight rectangle by specifying a nonzero thickness. Widgets like buttons, entries, listboxes, and text have a highlight rectangle by default.
The second label's padding attributes are reduced to zero. The anchor positions the text right next to the border in the upper-left (nw) corner. Note the effect of the padding provided by the packer. There is both external and internal padding in the Y direction. The external padding (from pack -pady) results in unfilled space. The internal packing (pack -ipady) is used by the label for its display. This is different from the label's own -pady attribute, which keeps the text away from the top edge of the widget.