Next: , Previous: item, Up: Widgets

6.2.52 label

— Class: label

Superclass: misc atk-implementor-iface buildable

Subclasses: accel-label

The label widget displays a small amount of text. As the name implies, most labels are used to label another widget such as a button, or a menu-item.


Labels may contain mnemonics. Mnemonics are underlined characters in the label, used for keyboard navigation. Mnemonics are created by providing a string with an underscore before the mnemonic character, such as "_File", to label-label and setting label-use-underline to True.

Mnemonics automatically activate any activatable widget the label is inside, such as a button; if the label is not inside the mnemonic's target widget, you have to tell the label about the target by settings label-mnemonic-widget. Here's a simple example where the label is inside a button:

Markup (styled text)

To make it easy to format text in a label (changing colors, fonts, etc.), label text can be provided in a simple markup format. Set label-use-markup to True if label-label contains markup. Here's how to create a label with a small font:

     (make-instance 'label :label "<small>Small text</small>" :use-markup t)

(See complete documentation of available tags in the Pango manual.)

The markup passed to label-label must be valid; for example, literal </>/& characters must be escaped as &lt;, &gt;, and &amp;. If you pass text obtained from the user, file, or a network, you'll want to escape it with g_markup_escape_text() or g_markup_printf_escaped(). (TODO: these functions are not supported yet in cl-gtk2)

Markup strings are just a convenient way to set the PangoAttrList on a label; label-attributes may be a simpler way to set attributes in some cases. Be careful though; PangoAttrList tends to cause internationalization problems, unless you're applying attributes to the entire string (i.e. unless you set the range of each attribute to [0, G_MAXINT)). The reason is that specifying the start_index and end_index for a PangoAttribute requires knowledge of the exact string being displayed, so translations will cause problems.

Selectable labels

Labels can be made selectable with label-selectable. Selectable labels allow the user to copy the label contents to the clipboard. Only labels that contain useful-to-copy information - such as error messages - should be made selectable.

Text layout

A label can contain any number of paragraphs, but will have performance problems if it contains more than a small number. Paragraphs are separated by newlines or other paragraph separators understood by Pango.

Labels can automatically wrap text if you call label-line-wrap.

label-justify sets how the lines in a label align with one another. If you want to set how the label as a whole aligns in its available space, see misc-xalign and misc-yalign.