Struct gtk::Label

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

Label as Buildable

The Label implementation of the Buildable 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 pango::Attribute values for this label.

An example of a UI definition fragment specifying Pango attributes:

    use gtk::{Button, Label};
    use gtk::prelude::*;

    // Pressing Alt+H will activate this button
    let button = Button::new();
    let label = Label::with_mnemonic(Some("_Hello"));
    button.add(&label);

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

    use gtk::Button;

    // Pressing Alt+H will activate this button
    let button = Button::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 Label::set_mnemonic_widget:

    use gtk::{Entry, Label};
    use gtk::prelude::*;

    // Pressing Alt+H will focus the entry
    let entry = Entry::new();
    let label = Label::with_mnemonic(Some("_Hello"));
    label.set_mnemonic_widget(Some(&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:

    use gtk::Label;
    use gtk::prelude::*;

    let label = Label::new(None);
    label.set_markup("<small>Small text</small>");

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

The markup passed to Label::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 Label::set_markup, you’ll want to escape it with g_markup_escape_text or g_markup_printf_escaped.

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

Selectable labels

Labels can be made selectable with Label::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 # {label-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::set_line_wrap.

Label::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 Widget::halign and Widget:valign properties.

The Label:width-chars and Label: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 Label:width-chars and Label: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:

    use gtk::Label;
    use gtk::prelude::*;

    let label = Label::new(None);
    let text =
r#"Go to the
 <a href="http://www.gtk.org" title="&lt;i&gt;Our&lt;/i&gt; website">
 GTK+ website</a> for more..."#;
    label.set_markup(text);

It is possible to implement custom handling for links and their tooltips with the Label::activate-link signal and the Label::get_current_uri function.

Implements

MiscExt, WidgetExt

Implementations

impl Label

pub fn new(str: Option<&str>) -> Label

Creates a new label with the given text inside it. You can pass None to get an empty label widget.

str

The text of the label

Returns

the new Label

pub fn with_mnemonic(str: Option<&str>) -> Label

Trait Implementations

impl Clone for Label

fn clone(&self) -> Label

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Label

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for Label

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Eq for Label

impl Hash for Label

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given [Hasher].

fn hash_slice<H>(data: &[Self], state: &mut H) where
    H: Hasher, 

Feeds a slice of this type into the given [Hasher].

impl IsA<Buildable> for Label

impl IsA<Label> for AccelLabel

impl IsA<Misc> for Label

impl IsA<Widget> for Label

impl Ord for Label

fn cmp(&self, other: &Label) -> Ordering

This method returns an [Ordering] between self and other.

#[must_use]fn max(self, other: Self) -> Self

Compares and returns the maximum of two values.

#[must_use]fn min(self, other: Self) -> Self

Compares and returns the minimum of two values.

#[must_use]fn clamp(self, min: Self, max: Self) -> Self

🔬 This is a nightly-only experimental API. (clamp)

Restrict a value to a certain interval.

impl<T: ObjectType> PartialEq<T> for Label

fn eq(&self, other: &T) -> bool

This method tests for self and other values to be equal, and is used by ==.

#[must_use]fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<T: ObjectType> PartialOrd<T> for Label

fn partial_cmp(&self, other: &T) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

#[must_use]fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

#[must_use]fn le(&self, other: &Rhs) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

#[must_use]fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

#[must_use]fn ge(&self, other: &Rhs) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl StaticType for Label

fn static_type() -> Type

Returns the type identifier of Self.