34. ttk.Label

34. ttk`.Label`

The purpose of this widget is to display text, an image, or both. Generally the content is static, but your program can change the text or the image.

To create a ttk.Label widget as the child of a given parent widget:

    w = ttk.Label(parent, option=value, ...)

Options include:

Table 44. ttk.Label options

anchor If the text and/or image are smaller than the specified width, you can use the anchor option to specify where to position them: tk.W, tk.CENTER, or tk.E for left, centered, or right alignment, respectively. You may also specify this option using a style.

background Use this option to set the background color. You may also specify this option using a style.

borderwidth To add a border around the label, set this option to the width dimension. You may also specify this option using a style.

class_ You may provide a widget class name when you create this widget. This name may be used to customize the widget's appearance; see Section 27, “Standardizing appearance”. Once the widget is created, the widget class name cannot be changed.

compound

If you provide both text and image options, the compound option specifies how to display them.

`'bottom'`	Display the image below the text.
`'image'`	Display only the image, not the text.
`'left'`	Display the image to the left of the text.
`'none'`	Display the image if there is one, otherwise display the text. This is the default value.
`'right'`	Display the image to the right of the text.
`'text'`	Display the text, not the image.
`'top'`	Display the image above the text.

cursor Use this option to specify the appearance of the mouse cursor when it is over the widget; see Section 5.8, “Cursors”. The default value (an empty string) specifies that the cursor is inherited from the parent widget.

font Use this option to specify the font style for the displayed text. You may also specify this option using a style.

foreground Use this option to specify the color of the displayed text. You may also specify this option using a style.

image

This option specifies an image or images to be displayed either in addition to or instead of text. The value must be an image as specified in Section 5.9, “Images”. See the compound option above for what happens when you supply both image and text.

You may specify multiple images that will appear on the widget depending on the state of the widget (see Section 50.2, “ttk style maps: dynamic appearance changes” for a discussion of widget states). To do this, supply as the value of this option a tuple (i₀, s₁, i₁, s₂, i₂, ...), where:

i₀ is the default image to be displayed on the widget.
For each pair of values after the first, s_i specifies a state or combination of states, and i₁ specifies the image to be displayed when the widget's state matches s_i.
Each state specifier s_i may be a single state name, optionally preceded by '!', or a sequence of such names. The ! specifies that the widget must not be in that state.
For example, suppose you have three PhotoImage instances named im1, im2, and im3, and in your call to the Label constructor you include this option:
```
    self.w = ttk.Label(self, ...,
         image=(im1,
                'selected', im2,
                ('!disabled', 'alternate'), im3), ...)
```
The widget will display image im2 if it is in the selected state. If it is not in the selected state or the disabled state but it is in the alternate state, it will display image im3. Otherwise it will display image im1.

justify If the text you provide contains newline ('\n') characters, this option specifies how each line will be positioned horizontally: tk.LEFT to left-justify; tk.CENTER to center; or tk.RIGHT to right-justify each line. You may also specify this option using a style.

padding To add more space around all four sides of the text and/or image, set this option to the desired dimension. You may also specify this option using a style.

relief Set this option to a relief style to create a 3-d effect. You will need to increase the borderwidth to make this effect appear. You may also specify this option using a style.

style Use this option to specify a custom widget style name; see Section 47, “Customizing and creating ttk themes and styles”.

takefocus

Use this option to specify whether the widget is visited during focus traversal; see Section 53, “Focus: routing keyboard input”. Specify takefocus=True if you want the visit to accept focus; specify takefocus=False if the widget is not to accept focus.

The default value is an empty string; by default, ttk.Label widgets do not get focus.

text A string of text to be displayed in the widget.

textvariable A StringVar instance (see Section 52, “Control variables: the values behind the widgets”); the text displayed on the widget will be its value. If both text and textvariable are specified, the text option will be ignored.

underline

You can request that one of the letters in the text string be underline by setting this option to the position of that letter. For example, the options text='Quit' and underline=0 would underline the Q.

Using this option doesn't change anything functionally. If you want the application to react to the Q key or some variation like control-shift-Q, you'll need to set up the bindings using the event system.

width

To specify a fixed width, set this option to the number of characters. To specify a minimum width, set this option to minus the number of characters. If you don't specify this option, the size of the label area will be just enough to accommodate the current text and/or image.

For text displayed in a proportional font, the actual width of the widget will be based on the average width of a character in the font, and not a specific number of characters.

This option may also be specified through a style.

wraplength If you set this option to some dimension, all the text will be chopped into lines no longer than this dimension. This option may also be specified through a style.

The following options of the Tkinter version of Label are not supported by the ttk.Label constructor.

Table 45. Tkinter Label options not in ttk.Label

`activebackground`	Use a style map to control the `background` option; see Section 50.2, “ttk style maps: dynamic appearance changes”.
`activeforeground`	Use a style map to control the `foreground` option.
`bitmap`	Not supported.
`disabledforeground`	Use a style map for the `foreground` option; see Section 50.2, “ttk style maps: dynamic appearance changes”.
`height`	Not supported.
`highlightbackground`	To control the color of the focus highlight when the label does not have focus, use a style map to control the `highlightcolor` option; see Section 50.2, “ttk style maps: dynamic appearance changes”.
`highlightcolor`	You may specify the default focus highlight color by setting this option in a style. You may also control the focus highlight color using a style map.
`highlightthickness`	Configure this option using a style. This option may not work in all themes.
`padx`	Not supported.
`pady`	Not supported.

Tkinter 8.5 reference: a GUI for Python

34. ttk.Label

34. ttk`.Label`