[]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::new_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::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 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::new_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 &lt;, &gt;, and &amp;. 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

Methods

impl Label
[src]

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

Creates a new Label, containing the text in str.

If characters in str are preceded by an underscore, they are underlined. If you need a literal underscore character in a label, use '__' (two underscores). The first underlined character represents a keyboard accelerator called a mnemonic. The mnemonic key can be used to activate another widget, chosen automatically, or explicitly using LabelExt::set_mnemonic_widget.

If LabelExt::set_mnemonic_widget is not called, then the first activatable ancestor of the Label will be chosen as the mnemonic widget. For instance, if the label is inside a button or menu item, the button or menu item will automatically become the mnemonic widget and be activated by the mnemonic.

str

The text of the label, with an underscore in front of the mnemonic character

Returns

the new Label

Trait Implementations

impl<T: IsA<Object>> PartialOrd<T> for Label

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

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

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

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

impl Ord for Label

Compares and returns the maximum of two values. Read more

Compares and returns the minimum of two values. Read more

impl<T: IsA<Object>> PartialEq<T> for Label

This method tests for !=.

impl Clone for Label

Performs copy-assignment from source. Read more

impl Eq for Label

impl Debug for Label

impl Hash for Label

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

impl IsA<Label> for AccelLabel

impl IsA<Misc> for Label

impl IsA<Widget> for Label

impl IsA<Buildable> for Label

impl IsA<Object> for Label

impl StaticType for Label

Auto Trait Implementations

impl !Send for Label

impl !Sync for Label

Blanket Implementations

impl<T, U> Into for T where
    U: From<T>, 
[src]

impl<T> ToOwned for T where
    T: Clone
[src]

impl<T> From for T
[src]

impl<T, U> TryFrom for T where
    T: From<U>, 
[src]

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

The type returned in the event of a conversion error.

impl<T> Borrow for T where
    T: ?Sized
[src]

impl<T> BorrowMut for T where
    T: ?Sized
[src]

impl<T, U> TryInto for T where
    U: TryFrom<T>, 
[src]

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

The type returned in the event of a conversion error.

impl<T> Any for T where
    T: 'static + ?Sized
[src]

impl<'a, T> ToGlibContainerFromSlice for T where
    T: GlibPtrDefault + ToGlibPtr<'a, <T as GlibPtrDefault>::GlibType>, 
[src]

impl<'a, T> ToGlibContainerFromSlice for T where
    T: GlibPtrDefault + ToGlibPtr<'a, <T as GlibPtrDefault>::GlibType>, 
[src]

impl<'a, T> ToGlibContainerFromSlice for T where
    T: GlibPtrDefault + ToGlibPtr<'a, <T as GlibPtrDefault>::GlibType>, 
[src]

impl<T> Cast for T where
    T: IsA<Object>, 
[src]

Upcasts an object to a superclass or interface T. Read more

Upcasts an object to a reference of its superclass or interface T. Read more

Tries to downcast to a subclass or interface implementor T. Read more

Tries to downcast to a reference of its subclass or interface implementor T. Read more

Returns true if the object is an instance of (can be cast to) T.

Tries to cast to an object of type T. This handles upcasting, downcasting and casting between interface and interface implementors. All checks are performed at runtime, while downcast and upcast will do many checks at compile-time already. Read more

Tries to cast to reference to an object of type T. This handles upcasting, downcasting and casting between interface and interface implementors. All checks are performed at runtime, while downcast and upcast will do many checks at compile-time already. Read more

impl<T> IsA for T where
    T: StaticType + Wrapper + Into<ObjectRef> + UnsafeFrom<ObjectRef> + ToGlibPtr<'a, *mut <T as Wrapper>::GlibType>, 
[src]

impl<Super, Sub> Downcast for Super where
    Sub: IsA<Super>,
    Super: IsA<Super>, 
[src]

impl<T> ObjectExt for T where
    T: IsA<Object> + SetValue
[src]

impl<T> ToValue for T where
    T: SetValue + ?Sized
[src]