The Label Widget

The label widget provides a read-only text label, and it has attributes that let you control the position of the label within the display space. Most commonly, however, you just need to specify the text for the label:

label .version -text "MyApp v1.0"

The text can be specified indirectly by using a Tcl variable to hold the text. In this case the label is updated whenever the value of the Tcl variable changes. The variable is used from the global scope, even if there happens to be a local variable by the same name when you create the widget inside a procedure:

set version "MyApp v1.0"
label .version -textvariable version

You can change the appearance of a label dynamically by using the configure widget operation. If you change the text or font of a label, you are liable to change the size of the widget, and this causes the packer to shuffle window positions. You can avoid this by specifying a width for the label that is large enough to hold all the strings you plan to display in it. The width is specified in characters, not screen coordinates:

Example 32-5 A label that displays different strings

proc FixedWidthLabel { name values } {
   # name is a widget name to be created
   # values is a list of strings
   set maxWidth 0
   foreach value $values {
      if {[string length $value] > $maxWidth} {
         set maxWidth [string length $value]
      }
   }
   # Use -anchor w to left-justify short strings
   label $name -width $maxWidth -anchor w \
      -text [lindex $values 0]
   return $name
}

The FixedWidthLabel example is used to create a label with a width big enough to hold a set of different strings. It uses the -anchor w attribute to left-justify strings that are shorter than the maximum. You can change the text for the label later by using the configure widget operation, which can be abbreviated to config:

FixedWidthLabel .status {OK Busy Error}
.status config -text Busy

A label can display a bitmap or image instead of a text string, which is described in Chapter 41 and the section on Bitmaps and Images.

This example could use the font metrics facilities of Tk 8.0 to get more accurate sizes of the text for different strings. It is possible, for example, that a three-character string like OOO is wider than a four-character string like llll in a variable-width font. The font metrics command is described on page 640.

Label Width and Wrap Length

When a label is displaying text, its width attribute is interpreted as a number of characters. The label is made wide enough to hold this number of averaged width characters in the label's font. However, if the label is holding a bitmap or an image, then the width is in pixels or another screen unit.

The wrapLength attribute determines when a label's text is wrapped onto multiple lines. The wrap length is always screen units. If you need to compute a wrapLength based on the font metrics, then you can use the font metrics command. If you use Tk 4.2 or earlier, then you have to measure text using a text widget with the same font. Chapter 36 describes the text widget operations that return size information for characters.

You can force line breaks by including newlines (\n) in the label's text. This lets you create labels that have multiple lines of text.

Label Attributes

Table 32-2 lists the widget attributes for the label widget. The attributes are named according to their resource name, which includes a capital letter at internal word boundaries. When you specify an attribute as an option in a Tcl command when creating or reconfiguring a widget, however, you specify the attribute with a dash and all lowercase letters. Chapter 31 explains how to use resource specifications for attributes. Chapters 40, 41, and 42 discuss many of these attributes in more detail.

Table 32-2. Label Attributes

activeBackground	Background color when the label is in the active state. (Tk 8.3.2)
activeForeground	Text color when the label is in the active state. (Tk 8.3.2)
anchor	Relative position of the label within its packing space.
background	Background color (also bg).
bitmap	Name of a bitmap to display instead of a text string.
borderWidth	Extra space around the edge of the label.
compound	Where the image or bitmap should be placed relative to the text: bottom, center, left, none (default), right and top. (Tk 8.4)
cursor	Cursor to display when mouse is over the label.
disabledForeground	Foreground (text) color when the label is disabled. (Tk 8.3.1)
font	Font for the label's text.
foreground	Foreground color (also fg).
height	In screen units for bitmaps, in lines for text.
highlightBackground	Focus highlight color when widget does not have focus.
highlightColor	Focus highlight color when widget has focus.
highlightThickness	Thickness of focus highlight rectangle.
image	Specifies image to display instead of bitmap or text.
justify	Text justification: left, right, or center.
padX	Extra space to the left and right of the label.
padY	Extra space above and below the label.
relief	flat, sunken, raised, groove, solid or ridge.
state	normal (enabled), disabled (deactivated), or active. (Tk 8.3.1)
takeFocus	Controls focus changes from keyboard traversal.
text	Text to display.
textVariable	Name of Tcl variable. Its value is displayed.
underline	Index of character to underline.
width	Width. In characters for text labels.
wrapLength	Length at which text is wrapped in screen units.