Label

Object Hierarchy:

Description:

[ CCode ( type_id = "gtk_label_get_type ()" ) ]
public class Label : Misc, Implementor, Buildable

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, a MenuItem, or a ComboBox.

CSS nodes

label
├── [selection]
├── [link]
┊
╰── [link]

gle CSS node with the name label. A wide variety of style classes may be applied to labels, such as .title, .subtitle, .dim-label, etc. In the ShortcutsWindow, labels are used wth the .keycap style class.

If the label has a selection, it gets a subnode with name selection.

If the label has links, there is one subnode per link. These subnodes carry the link or visited state depending on whether they have been visited.

GtkLabel as GtkBuildable

The GtkLabel implementation of the GtkBuildable interface supports a custom `<attributes>` element, which supports any number of `< attribute>` elements. The `<attribute>` element has attributes named “name“, “value“, “start“ and “end“ and allows you to specify Attribute values for this label.

An example of a UI definition fragment specifying Pango attributes:

<object class="GtkLabel">
  <attributes>
    <attribute name="weight" value="PANGO_WEIGHT_BOLD"/>
    <attribute name="background" value="red" start="5" end="10"/>
  </attributes>
</object>

The start and end attributes specify the range of characters to which the Pango attribute applies. If start and end are not specified, the attribute is applied to the whole text. Note that specifying ranges does not make much sense with translatable attributes. Use markup embedded in the translatable content instead.

Mnemonics

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 the functions Label.with_mnemonic or set_text_with_mnemonic.

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 using set_mnemonic_widget. Here’s a simple example where the label is inside a button:

  // Pressing Alt+H will activate this button
  GtkWidget *button = gtk_button_new ();
  GtkWidget *label = gtk_label_new_with_mnemonic ("_Hello");
  gtk_container_add (GTK_CONTAINER (button), label);

There’s a convenience function to create buttons with a mnemonic label already inside:

  // Pressing Alt+H will activate this button
  GtkWidget *button = gtk_button_new_with_mnemonic ("_Hello");

To create a mnemonic for a widget alongside the label, such as a Entry, you have to point the label at the entry with set_mnemonic_widget:

  // Pressing Alt+H will focus the entry
  GtkWidget *entry = gtk_entry_new ();
  GtkWidget *label = gtk_label_new_with_mnemonic ("_Hello");
  gtk_label_set_mnemonic_widget (GTK_LABEL (label), entry);

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.

Here’s how to create a label with a small font:

  GtkWidget *label = gtk_label_new (NULL);
  gtk_label_set_markup (GTK_LABEL (label), "<small>Small text</small>");

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

The markup passed to set_markup must be valid; for example, literal <, > and & characters must be escaped as <, >, and &. If you pass text obtained from the user, file, or a network to set_markup, you’ll want to escape it with escape_text or printf_escaped.

Markup strings are just a convenient way to set the AttrList on a label; set_attributes may be a simpler way to set attributes in some cases. Be careful though; AttrList 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 Attribute requires knowledge of the exact string being displayed, so translations will cause problems.

Selectable labels

Labels can be made selectable with set_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 set_line_wrap.

set_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 the halign and valign properties.

The width_chars and max_width_chars properties can be used to control the size allocation of ellipsized or wrapped labels. For ellipsizing labels, if either is specified (and less than the actual text size), it is used as the minimum width, and the actual text size is used as the natural width of the label. For wrapping labels, width-chars is used as the minimum width, if specified, and max-width-chars is used as the natural width. Even if max-width-chars specified, wrapping labels will be rewrapped to use all of the available width.

Note that the interpretation of width_chars and max_width_chars has changed a bit with the introduction of width-for-height geometry management.

Links

Since 2.18, GTK+ supports markup for clickable hyperlinks in addition to regular Pango markup. The markup for links is borrowed from HTML, using the `<a>` with “href“ and “title“ attributes. GTK+ renders links similar to the way they appear in web browsers, with colored, underlined text. The “title“ attribute is displayed as a tooltip on the link.

An example looks like this:

const gchar *text =
"Go to the"
"<a href=\"http://www.gtk.org title=\"&lt;i&gt;Our&lt;/i&gt; website\">"
"GTK+ website</a> for more...";
GtkWidget *label = gtk_label_new (NULL);
gtk_label_set_markup (GTK_LABEL (label), text);

It is possible to implement custom handling for links and their tooltips with the activate_link signal and the get_current_uri function.

Example: Label:

public class Application : Gtk.Window {

	public Application () {
		// Prepare Gtk.Window:
		this.title = "My Gtk.Label";
		this.window_position = Gtk.WindowPosition.CENTER;
		this.destroy.connect (Gtk.main_quit);
		this.set_default_size (350, 70);

		// The Label:
		Gtk.Label label = new Gtk.Label ("<b>Hello, world!</b>");
		label.set_use_markup (true);
		label.set_line_wrap (true);
		this.add (label);
	}

	public static int main (string[] args) {
		Gtk.init (ref args);

		Application app = new Application ();
		app.show_all ();
		Gtk.main ();
		return 0;
	}
}

valac --pkg gtk+-3.0 Gtk.Label.vala

All known sub-classes:

AccelLabel

Namespace: Gtk

Package: gtk+-3.0

Content:

Properties:

public double angle { get; set; }
The angle that the baseline of the label makes with the horizontal, in degrees, measured counterclockwise.
public AttrList attributes { get; set; }
public int cursor_position { get; }
public EllipsizeMode ellipsize { get; set; }
The preferred place to ellipsize the string, if the label does not have enough room to display the entire string, specified as a EllipsizeMode.
public Justification justify { get; set; }
public string label { get; set; }
The contents of the label.
public int lines { get; set; }
The number of lines to which an ellipsized, wrapping label should be limited.
public int max_width_chars { get; set; }
The desired maximum width of the label, in characters.
public uint mnemonic_keyval { get; }
public Widget mnemonic_widget { get; set; }
public string pattern { set; }
public bool selectable { get; set; }
public int selection_bound { get; }
public bool single_line_mode { get; set; }
Whether the label is in single line mode.
public bool track_visited_links { get; set; }
Set this property to true to make the label track which links have been visited.
public bool use_markup { get; set; }
public bool use_underline { get; set; }
public int width_chars { get; set; }
The desired width of the label, in characters.
public bool wrap { get; set; }
public WrapMode wrap_mode { get; set; }
If line wrapping is on (see the wrap property) this controls how the line wrapping is done.
public float xalign { get; set; }
public float yalign { get; set; }

Creation methods:

public Label (string? str)
Creates a new label with the given text inside it.
public Label.with_mnemonic (string? str)
Creates a new Label, containing the text in str.

Methods:

public double get_angle ()
Gets the angle of rotation for the label.
public unowned AttrList? get_attributes ()
Gets the attribute list that was set on the label using set_attributes, if any.
public unowned string get_current_uri ()
Returns the URI for the currently active link in the label.
public EllipsizeMode get_ellipsize ()
Returns the ellipsizing position of the label.
public Justification get_justify ()
Returns the justification of the label.
public unowned string get_label ()
Fetches the text from a label widget including any embedded underlines indicating mnemonics and Pango markup.
public unowned Layout get_layout ()
Gets the Layout used to display the label.
public void get_layout_offsets (out int x, out int y)
Obtains the coordinates where the label will draw the Layout representing the text in the label; useful to convert mouse events into coordinates inside the Layout, e.
public bool get_line_wrap ()
Returns whether lines in the label are automatically wrapped.
public WrapMode get_line_wrap_mode ()
Returns line wrap mode used by the label.
public int get_lines ()
Gets the number of lines to which an ellipsized, wrapping label should be limited.
public int get_max_width_chars ()
Retrieves the desired maximum width of this , in characters.
public uint get_mnemonic_keyval ()
If the label has been set so that it has an mnemonic key this function returns the keyval used for the mnemonic accelerator.
public unowned Widget? get_mnemonic_widget ()
Retrieves the target of the mnemonic (keyboard shortcut) of this label.
public bool get_selectable ()
Gets the value set by set_selectable.
public bool get_selection_bounds (out int start, out int end)
Gets the selected range of characters in the label, returning true if there’s a selection.
public bool get_single_line_mode ()
Returns whether the label is in single line mode.
public unowned string get_text ()
Fetches the text from a label widget, as displayed on the screen.
public bool get_track_visited_links ()
Returns whether the label is currently keeping track of clicked links.
public bool get_use_markup ()
Returns whether the label’s text is interpreted as marked up with the Pango text markup language.
public bool get_use_underline ()
Returns whether an embedded underline in the label indicates a mnemonic.
public int get_width_chars ()
Retrieves the desired width of this, in characters.
public float get_xalign ()
Gets the xalign property for this.
public float get_yalign ()
Gets the yalign property for this.
public void select_region (int start_offset, int end_offset)
Selects a range of characters in the label, if the label is selectable.
public void set_angle (double angle)
Sets the angle of rotation for the label.
public void set_attributes (AttrList? attrs)
Sets a AttrList; the attributes in the list are applied to the label text.
public void set_ellipsize (EllipsizeMode mode)
Sets the mode used to ellipsize (add an ellipsis: "...") to the text if there is not enough space to render the entire string.
public void set_justify (Justification jtype)
Sets the alignment of the lines in the text of the label relative to each other.
public void set_label (string str)
Sets the text of the label.
public void set_line_wrap (bool wrap)
Toggles line wrapping within the Label widget.
public void set_line_wrap_mode (WrapMode wrap_mode)
If line wrapping is on (see set_line_wrap) this controls how the line wrapping is done.
public void set_lines (int lines)
Sets the number of lines to which an ellipsized, wrapping label should be limited.
public void set_markup (string str)
Parses str which is marked up with the Pango text markup language, setting the label’s text and attribute list based on the parse results.
public void set_markup_with_mnemonic (string str)
Parses str which is marked up with the Pango text markup language, setting the label’s text and attribute list based on the parse results.
public void set_max_width_chars (int n_chars)
Sets the desired maximum width in characters of this to n_chars.
public void set_mnemonic_widget (Widget? widget)
If the label has been set so that it has an mnemonic key (using i.
public void set_pattern (string pattern)
The pattern of underlines you want under the existing text within the Label widget.
public void set_selectable (bool setting)
Selectable labels allow the user to select text from the label, for copy-and-paste.
public void set_single_line_mode (bool single_line_mode)
Sets whether the label is in single line mode.
public void set_text (string str)
Sets the text within the Label widget.
public void set_text_with_mnemonic (string str)
Sets the label’s text from the string str.
public void set_track_visited_links (bool track_links)
Sets whether the label should keep track of clicked links (and use a different color for them).
public void set_use_markup (bool setting)
Sets whether the text of the label contains markup in Pango’s text markup language.
public void set_use_underline (bool setting)
If true, an underline in the text indicates the next character should be used for the mnemonic accelerator key.
public void set_width_chars (int n_chars)
Sets the desired width in characters of this to n_chars.
public void set_xalign (float xalign)
Sets the xalign property for this.
public void set_yalign (float yalign)
Sets the yalign property for this.

Signals:

public signal void activate_current_link ()
A keybinding signal which gets emitted when the user activates a link in the label.
public virtual signal bool activate_link (string uri)
The signal which gets emitted to activate a URI.
public virtual signal void copy_clipboard ()
The copy_clipboard signal is a keybinding signal which gets emitted to copy the selection to the clipboard.
public virtual signal void move_cursor (MovementStep step, int count, bool extend_selection)
The move_cursor signal is a keybinding signal which gets emitted when the user initiates a cursor movement.
public virtual signal void populate_popup (Menu menu)
The populate_popup signal gets emitted before showing the context menu of the label.

Inherited Members:

All known members inherited from class Gtk.Misc

yalign
ypad

All known members inherited from class Gtk.Widget

All known members inherited from class GLib.Object

All known members inherited from interface Atk.Implementor

ref_accessible

All known members inherited from interface Gtk.Buildable