Labels

GtkLabel displays limited amounts of text.

Labels can contain plain text or markup text.

The text rendering is controlled by Pango attributes.

CPythonValaJavaScript

// A plain text label
GtkWidget *label = gtk_label_new ("Hello GNOME!");

// A markup label
GtkWidget *label = gtk_label_new ("<small>Hello</small> <b>GNOME</b>!");
gtk_label_set_use_markup (GTK_LABEL (label), TRUE);

Wrapping labels

Two properties control the wrapping of the labels text:

• GtkLabel:wrap-mode: Controls whether to wrap only at word boundaries, or anywhere

• GtkLabel:wrap: If set, wrap lines if the text becomes too wide

One normally only sets the wrap property. It is safe to leave the wrap-mode property at its default value, Pango.WrapMode.WORD.

When wrapping is enabled, the same label can appear with multiple different height/width combinations. How far the label actually wraps depends on the context in which it is used, and on the geometry management of its parent container. There are two properties that allow you to influence the amount of wrapping:

• GtkLabel::width-chars: Specifies the minimum width of a wrapping label

• GtkLabel::max-width-chars: Specified the natural width of a wrapping label

Note that both of these properties are using characters as unit. They are converted to pixels using the average character width of the current font.

Ellipsized labels

Sometimes, it is convenient to only show as much of text as fits, and indicate that there is more by using an ellipsis (…). GtkLabel supports this with this property:

• GtkLabel:ellipsize: The preferred place to ellipsize the string

Setting it to a value other than the default PANGO_ELLIPSIZE_NONE enables ellipsization. For the usual ellipsization at the end, use PANGO_ELLIPSIZE_END.

To control how much of the label can be ellipsized away, use the GtkLabel:width-chars property:

CPythonValaJavaScript

GtkWidget *label =
  gtk_label_new ("This is a long text that might need to get ellipsized");
gtk_label_set_ellipsize (GTK_LABEL (label), PANGO_ELLIPSIZE_END);
gtk_label_set_width_chars (GTK_LABEL (label), 15);

Note

The width-chars property is based on the average character with of the font, and thus the remaining text may not exactly be the number of characters you specified.

You can also use the GtkLabel:max-width-chars property to limit the natural size requested by the label widget.

Fixed number of lines

Sometimes it is necessary to keep text to a certain number of lines. One approach is to turn off automatic wrapping and rely on inserting line breaks in the text manually:

CPythonValaJavaScript

GtkWidget *label =
  gtk_label_new ("This is a long text\nthat might need\nto be wrapped");

This can be problematic because you have to balance line length yourself, and translators may inadvertently change the number of lines by removing or adding line breaks in their translations; also, text with fixed breaks is ellipsized in each line, which may look unexpected.

A better alternative is to go back to automatic wrapping, and tell the label how many lines of text you want, using the set_lines() method:

CPythonValaJavaScript

GtkWidget *label =
  gtk_label_new ("This is a long text that might need to be wrapped");
gtk_label_set_wrap (GTK_LABEL (label), TRUE);
gtk_label_set_ellipsize (GTK_LABEL (label), PANGO_ELLIPSIZE_END);
gtk_label_set_lines (GTK_LABEL (label), 3);

With this configuration, GtkLabel will automatically wrap lines to the right width and only ellipsize the last one, if needed.

Mnemonics

Labels can be used to describe other widgets, for instance:

CPythonValaJavaScript

// Add a switch to enable a feature
GtkWidget *box = gtk_box_new (GTK_ORIENTATION_HORIZONTAL, 12);
GtkWidget *sw = gtk_switch_new ();
GtkWidget *label = gtk_label_new ("Enable feature");
gtk_box_append (GTK_BOX (box), label);
gtk_box_append (GTK_BOX (box), sw);

To simplify keyboard navigation, labels can include “mnemonics”: underlined characters that are used as shortcuts for activating the widget that is described by the label:

CPythonValaJavaScript

// Add a switch to enable a feature
GtkWidget *box = gtk_box_new (GTK_ORIENTATION_HORIZONTAL, 12);
GtkWidget *sw = gtk_switch_new ();
GtkWidget *label = gtk_label_new ("Enable _feature");
gtk_label_set_use_underline (GTK_LABEL (label), TRUE);
gtk_box_append (GTK_BOX (box), label);
gtk_box_append (GTK_BOX (box), sw);
// Bind the switch to the label's mnemonic
gtk_label_set_mnemonic_widget (GTK_LABEL (label), switch);

Now, pressing Alt + F will toggle the switch.

Useful methods for a Label widget

• set_selectable() will mark the contents of the label as user selectable; the contents of selectable labels can also be copied in the clipboard.

API references

In this sample we used the following:

• GtkLabel

• GtkSwitch

• GtkBox