Description

The Gnome::Gtk4::Label widget displays a small amount of text.

As the name implies, most labels are used to label another widget such as a Gnome::Gtk4::Button.

CSS nodes

# Pressing Alt+H will activate this button
my Gnome::Gtk4::Button $button .= new-button;
my Gnome::Gtk4::Label $label .= new-with-mnemonic("_Hello");
$button.set-child($label);

Gnome::Gtk4::Label has a single 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 Gnome::Gtk4::ShortcutsWindow, labels are used with 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. In this case, label node also gets a .link style class.

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 Gnome::Pango::N-Attribute values for this label.

An example of a UI definition fragment specifying Pango attributes:

# Pressing Alt+H will activate this button
my Gnome::Gtk4::Button $button .= new_with_mnemonic("_Hello");

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.

Accessibility

Gnome::Gtk4::Label uses the GTK_ACCESSIBLE_ROLE_LABEL role.

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 .new-with-mnemonic() or .set-text-with-mnemonic().

Mnemonics automatically activate any activatable widget the label is inside, such as a Gnome::Gtk4::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 focus the entry
my Gnome::Gtk4::Entry $entry .= new-entry;
my Gnome::Gtk4::Label $label .= new-with-mnemonic("_Hello");
$label.set-mnemonic-widget($entry);

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

my Gnome::Gtk4::Label $label .= new-label(Str);
$label.set-markup("<small>Small text</small>");

To create a mnemonic for a widget alongside the label, such as a Gnome::Gtk4::Entry, you have to point the label at the entry with .set-mnemonic-widget():

my Str $text = [~] 'Go to the ',
  '<a href="http://www.gtk.org" title="<i>Our</i> website">',
  'GTK website', '</a>', ' for more...';
my Gnome::Gtk4::Label $label .= new-label(Str);
$label.set_markup($text);

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:

(See the Pango manual for complete documentation] of available tags, .parse-markup() in package Gnome::Pango)

The markup passed to .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 .set-markup(), you’ll want to escape it with .markup-escape-text() in package Gnome::GLib or .markup-printf-escaped() in package Gnome::GLib.

Markup strings are just a convenient way to set the Gnome::Pango::N-AttrList on a label; .set-attributes() may be a simpler way to set attributes in some cases. Be careful though; Gnome::Pango::N-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 Gnome::Pango::N-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-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 defined in Gnome::Gtk4::Widget and valign defined in Gnome::Gtk4::Widget 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.

Links

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“, “title“ and “class“ 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. The “class“ attribute is used as style class on the CSS node for the link.

An example of inline links looks like this:

It is possible to implement custom handling for links and their tooltips with the activate-link signal and the .get-current-uri() function.

Class initialization

new

:native-object

Create an object using a native object from elsewhere. See also Gnome::N::TopLevelSupportClass.

multi method new ( N-Object :$native-object! )

new-label

Creates a new label with the given text inside it.

You can pass undefined to get an empty label widget.

method new-label ( Str $str --> Gnome::Gtk4::Label \)

• $str; The text of the label.

new-with-mnemonic

Creates a new Gnome::Gtk4::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 .set-mnemonic-widget().

If .set-mnemonic-widget() is not called, then the first activatable ancestor of the Gnome::Gtk4::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.

method new-with-mnemonic ( Str $str --> Gnome::Gtk4::Label \)

• $str; The text of the label, with an underscore in front of the mnemonic character.

Methods

get-attributes

Gets the label's attribute list.

This is the Gnome::Pango::N-AttrList that was set on the label using .set-attributes(), if any. This function does not reflect attributes that come from the label's markup (see .set-markup()). If you want to get the effective attributes for the label, use pango_layout_get_attributes (gtk_label_get_layout (self))`.

method get-attributes (--> N-Object )

Return value; the attribute list.

get-current-uri

Returns the URI for the currently active link in the label.

The active link is the one under the mouse pointer or, in a selectable label, the link in which the text cursor is currently positioned.

This function is intended for use in a activate-link handler or for use in a query-tooltip defined in Widget handler.

method get-current-uri (--> Str )

Return value; the currently active URI.

get-ellipsize

Returns the ellipsizing position of the label.

See .set-ellipsize().

method get-ellipsize (--> PangoEllipsizeMode )

Return value; enumeration PangoEllipsizeMode defined in Gnome::Pango::T-layout.

get-extra-menu

Gets the extra menu model of $label.

See .set-extra-menu().

method get-extra-menu (--> N-Object )

Return value; the menu model.

get-justify

Returns the justification of the label.

See .set-justify().

method get-justify (--> GtkJustification )

Return value; enumeration GtkJustification defined in Gnome::Gtk4::T-enums.

get-label

Fetches the text from a label.

The returned text includes any embedded underlines indicating mnemonics and Pango markup. (See .get-text()).

method get-label (--> Str )

Return value; the text of the label widget. This string is owned by the widget and must not be modified or freed..

get-layout

Gets the Gnome::Pango::Layout used to display the label.

The layout is useful to e.g. convert text positions to pixel positions, in combination with .get-layout-offsets(). The returned layout is owned by the $label so need not be freed by the caller. The $label is free to recreate its layout at any time, so it should be considered read-only.

method get-layout (--> N-Object )

Return value; the Gnome::Pango::Layout for this label.

get-layout-offsets

Obtains the coordinates where the label will draw its Gnome::Pango::Layout.

The coordinates are useful to convert mouse events into coordinates inside the Gnome::Pango::Layout, e.g. to take some action if some part of the label is clicked. Remember when using the Gnome::Pango::Layout functions you need to convert to and from pixels using PANGO_PIXELS() or [const $Pango.SCALE].

method get-layout-offsets ( Array[Int] $x, Array[Int] $y )

• $x; (transfer ownership: full) location to store X offset of layout.

• $y; (transfer ownership: full) location to store Y offset of layout.

get-lines

Gets the number of lines to which an ellipsized, wrapping label should be limited.

See .set-lines().

method get-lines (--> Int )

Return value; The number of lines.

get-max-width-chars

Retrieves the desired maximum width of $label, in characters.

See .set-width-chars().

method get-max-width-chars (--> Int )

Return value; the maximum width of the label in characters..

get-mnemonic-keyval

Return the mnemonic accelerator.

If the label has been set so that it has a mnemonic key this function returns the keyval used for the mnemonic accelerator. If there is no mnemonic set up it returns Gnome::Gdk4::T-keysyms.

method get-mnemonic-keyval (--> UInt )

Return value; GDK keyval usable for accelerators, or Gnome::Gdk4::T-keysyms.

get-mnemonic-widget

Retrieves the target of the mnemonic (keyboard shortcut) of this label.

See .set-mnemonic-widget().

method get-mnemonic-widget (--> N-Object )

Return value; the target of the label’s mnemonic, or undefined if none has been set and the default algorithm will be used..

get-natural-wrap-mode

Returns line wrap mode used by the label.

See .set-natural-wrap-mode().

method get-natural-wrap-mode (--> GtkNaturalWrapMode )

Return value; the natural line wrap mode.

get-selectable

Returns whether the label is selectable.

method get-selectable (--> Bool )

Return value; True if the user can copy text from the label.

get-selection-bounds

Gets the selected range of characters in the label.

method get-selection-bounds ( Array[Int] $start, Array[Int] $end --> Bool )

• $start; (transfer ownership: full) return location for start of selection, as a character offset.

• $end; (transfer ownership: full) return location for end of selection, as a character offset.

Return value; True if selection is non-empty.

get-single-line-mode

Returns whether the label is in single line mode.

method get-single-line-mode (--> Bool )

Return value; True when the label is in single line mode..

get-tabs

Gets the tabs for $self.

The returned array will be undefined if “standard” (8-space) tabs are used. Free the return value with .free() in class Gnome::Pango::N-TabArray.

method get-tabs (--> N-Object )

Return value; copy of default tab array, or undefined if standard tabs are used; must be freed with .free() in class Gnome::Pango::N-TabArray..

get-text

Fetches the text from a label.

The returned text is as it appears on screen. This does not include any embedded underlines indicating mnemonics or Pango markup. (See .get-label())

method get-text (--> Str )

Return value; the text in the label widget. This is the internal string used by the label, and must not be modified..

get-use-markup

Returns whether the label’s text is interpreted as Pango markup.

See .set-use-markup().

method get-use-markup (--> Bool )

Return value; True if the label’s text will be parsed for markup..

get-use-underline

Returns whether an embedded underlines in the label indicate mnemonics.

See .set-use-underline().

method get-use-underline (--> Bool )

Return value; True whether an embedded underline in the label indicates the mnemonic accelerator keys..

get-width-chars

Retrieves the desired width of $label, in characters.

See .set-width-chars().

method get-width-chars (--> Int )

Return value; the width of the label in characters..

get-wrap

Returns whether lines in the label are automatically wrapped.

See .set-wrap().

method get-wrap (--> Bool )

Return value; True if the lines of the label are automatically wrapped..

get-wrap-mode

Returns line wrap mode used by the label.

See .set-wrap-mode().

method get-wrap-mode (--> PangoWrapMode )

Return value; the line wrap mode.

get-xalign

Gets the xalign of the label.

See the xalign property.

method get-xalign (--> Num )

Return value; the xalign property.

get-yalign

Gets the yalign of the label.

See the yalign property.

method get-yalign (--> Num )

Return value; the yalign property.

select-region

Selects a range of characters in the label, if the label is selectable.

See .set-selectable(). If the label is not selectable, this function has no effect. If $start-offset or $end-offset are -1, then the end of the label will be substituted.

method select-region ( Int() $start-offset, Int() $end-offset )

• $start-offset; start offset (in characters not bytes).

• $end-offset; end offset (in characters not bytes).

set-attributes

Apply attributes to the label text.

The attributes set with this function will be applied and merged with any other attributes previously effected by way of the use-underline or use-markup properties. While it is not recommended to mix markup strings with manually set attributes, if you must; know that the attributes will be applied to the label after the markup string is parsed.

method set-attributes ( N-Object $attrs )

• $attrs; a Gnome::Pango::N-AttrList

set-ellipsize

Sets the mode used to ellipsize the text.

The text will be ellipsized if there is not enough space to render the entire string.

method set-ellipsize ( PangoEllipsizeMode $mode )

• $mode; a enumeration PangoEllipsizeMode defined in Gnome::Pango::T-layout.

set-extra-menu

Sets a menu model to add when constructing the context menu for $label.

method set-extra-menu ( N-Object() $model )

• $model; a Gnome::Gio::MenuModel.

set-justify

Sets the alignment of the lines in the text of the label relative to each other.

GTK_JUSTIFY_LEFT is the default value when the widget is first created with .newlabel(). If you instead want to set the alignment of the label as a whole, use .set-halign() in class Gnome::Gtk4::Widget instead. .set-justify() has no effect on labels containing only a single line.

method set-justify ( GtkJustification $jtype )

• $jtype; a enumeration GtkJustification defined in Gnome::Gtk4::T-enums.

set-label

Sets the text of the label.

The label is interpreted as including embedded underlines and/or Pango markup depending on the values of the use-underline and use-markup properties.

method set-label ( Str $str )

• $str; the new text to set for the label.

set-lines

Sets the number of lines to which an ellipsized, wrapping label should be limited.

This has no effect if the label is not wrapping or ellipsized. Set this to -1 if you don’t want to limit the number of lines.

method set-lines ( Int() $lines )

• $lines; the desired number of lines, or -1.

set-markup

Sets the labels text and attributes from markup.

The string must be marked up with Pango markup (see .parse-markup() in package Gnome::Pango).

If the $str is external data, you may need to escape it with g_markup_escape_text() or g_markup_printf_escaped():

This function will set the use-markup property to True as a side effect.

If you set the label contents using the label property you should also ensure that you set the use-markup property accordingly.

See also: .set-text()

method set-markup ( Str $str )

• $str; a markup string.

set-markup-with-mnemonic

Sets the labels text, attributes and mnemonic from markup.

Parses $str which is marked up with Pango markup (see .parse-markup() in package Gnome::Pango), setting the label’s text and attribute list based on the parse results. If characters in $str are preceded by an underscore, they are underlined indicating that they represent a keyboard accelerator called a mnemonic.

The mnemonic key can be used to activate another widget, chosen automatically, or explicitly using .set-mnemonic-widget().

method set-markup-with-mnemonic ( Str $str )

• $str; a markup string.

set-max-width-chars

Sets the desired maximum width in characters of $label to $n-chars.

method set-max-width-chars ( Int() $n-chars )

• $n-chars; the new desired maximum width, in characters..

set-mnemonic-widget

Associate the label with its mnemonic target.

If the label has been set so that it has a mnemonic key (using i.e. .set-markup-with-mnemonic(), .set-text-with-mnemonic(), .new-with-mnemonic() or the use_underline property) the label can be associated with a widget that is the target of the mnemonic. When the label is inside a widget (like a Gnome::Gtk4::Button or a Gnome::Gtk4::Notebook tab) it is automatically associated with the correct widget, but sometimes (i.e. when the target is a Gnome::Gtk4::Entry next to the label) you need to set it explicitly using this function.

The target widget will be accelerated by emitting the mnemonic-activate defined in Widget signal on it. The default handler for this signal will activate the widget if there are no mnemonic collisions and toggle focus between the colliding widgets otherwise.

method set-mnemonic-widget ( N-Object() $widget )

• $widget; the target Gnome::Gtk4::Widget, or undefined to unset.

set-natural-wrap-mode

Select the line wrapping for the natural size request.

This only affects the natural size requested, for the actual wrapping used, see the wrap-mode property.

method set-natural-wrap-mode ( GtkNaturalWrapMode $wrap-mode )

• $wrap-mode; the line wrapping mode.

set-selectable

Makes text in the label selectable.

Selectable labels allow the user to select text from the label, for copy-and-paste.

method set-selectable ( Bool() $setting )

• $setting; True to allow selecting text in the label.

set-single-line-mode

Sets whether the label is in single line mode.

method set-single-line-mode ( Bool() $single-line-mode )

• $single-line-mode; True if the label should be in single line mode.

set-tabs

Sets the default tab stops for paragraphs in $self.

method set-tabs ( N-Object $tabs )

• $tabs; tabs as a Gnome::Pango::N-TabArray

set-text

Sets the text within the Gnome::Gtk4::Label widget.

It overwrites any text that was there before.

This function will clear any previously set mnemonic accelerators, and set the use-underline property to False as a side effect.

This function will set the use-markup property to False as a side effect.

See also: .set-markup()

method set-text ( Str $str )

• $str; The text you want to set.

set-text-with-mnemonic

Sets the label’s text from the string $str.

If characters in $str are preceded by an underscore, they are underlined indicating that they represent a keyboard accelerator called a mnemonic. The mnemonic key can be used to activate another widget, chosen automatically, or explicitly using .set-mnemonic-widget().

method set-text-with-mnemonic ( Str $str )

• $str; a string.

set-use-markup

Sets whether the text of the label contains markup.

See .set-markup().

method set-use-markup ( Bool() $setting )

• $setting; True if the label’s text should be parsed for markup..

set-use-underline

Sets whether underlines in the text indicate mnemonics.

method set-use-underline ( Bool() $setting )

• $setting; True if underlines in the text indicate mnemonics.

set-width-chars

Sets the desired width in characters of $label to $n-chars.

method set-width-chars ( Int() $n-chars )

• $n-chars; the new desired width, in characters..

set-wrap

Toggles line wrapping within the Gnome::Gtk4::Label widget.

True makes it break lines if text exceeds the widget’s size. False lets the text get cut off by the edge of the widget if it exceeds the widget size.

Note that setting line wrapping to True does not make the label wrap at its parent container’s width, because GTK widgets conceptually can’t make their requisition depend on the parent container’s size. For a label that wraps at a specific position, set the label’s width using .set-size-request() in class Gnome::Gtk4::Widget.

method set-wrap ( Bool() $wrap )

• $wrap; the setting.

set-wrap-mode

Controls how line wrapping is done.

This only affects the label if line wrapping is on. (See .set-wrap()) The default is PANGO_WRAP_WORD which means wrap on word boundaries.

For sizing behavior, also consider the natural-wrap-mode property.

method set-wrap-mode ( PangoWrapMode $wrap-mode )

• $wrap-mode; the line wrapping mode.

set-xalign

Sets the xalign of the label.

See the xalign property.

method set-xalign ( Num() $xalign )

• $xalign; the new xalign value, between 0 and 1.

set-yalign

Sets the yalign of the label.

See the yalign property.

method set-yalign ( Num() $yalign )

• $yalign; the new yalign value, between 0 and 1.

Signals

activate-current-link

Gets emitted when the user activates a link in the label.

The activate-current-link is a [keybinding signal](class.SignalAction.html).

Applications may also emit the signal with g_signal_emit_by_name() if they need to control activation of URIs programmatically.

The default bindings for this signal are all forms of the <kbd>Enter</kbd> key.

method handler (
  Int :$_handle_id,
  N-GObject :$_native-object,
  Gnome::Gtk4::Label :$_widget,
  *C<user>-options
)

• $_handle_id; The registered event handler id.

• $_native-object; The native object provided by the Raku object which registered this event. This a native Gnome::Gtk4::Label object.

• $_widget; The object which registered the signal. User code may have left the object going out of scope.

• user-options; A list of named arguments provided at the .register-signal() method from Gnome::GObject::Object.

activate-link

Gets emitted to activate a URI.

Applications may connect to it to override the default behaviour, which is to call .launch() in class Gnome::Gtk4::FileLauncher.

method handler (
  Str $uri,
  Int :$_handle_id,
  N-GObject :$_native-object,
  Gnome::Gtk4::Label :$_widget,
  *C<user>-options
  --> gboolean
)

• $uri; the URI that is activated.

• $_handle_id; The registered event handler id.

• $_native-object; The native object provided by the Raku object which registered this event. This a native Gnome::Gtk4::Label object.

• $_widget; The object which registered the signal. User code may have left the object going out of scope.

• user-options; A list of named arguments provided at the .register-signal() method from Gnome::GObject::Object.

Return value; True if the link has been activated

copy-clipboard

Gets emitted to copy the selection to the clipboard.

The copy-clipboard signal is a [keybinding signal](class.SignalAction.html).

The default binding for this signal is <kbd>Ctrl</kbd>+<kbd>c</kbd>.

method handler (
  Int :$_handle_id,
  N-GObject :$_native-object,
  Gnome::Gtk4::Label :$_widget,
  *C<user>-options
)

• $_handle_id; The registered event handler id.

• $_native-object; The native object provided by the Raku object which registered this event. This a native Gnome::Gtk4::Label object.

• $_widget; The object which registered the signal. User code may have left the object going out of scope.

• user-options; A list of named arguments provided at the .register-signal() method from Gnome::GObject::Object.

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

move-cursor

Gets emitted when the user initiates a cursor movement.

The move-cursor signal is a [keybinding signal](class.SignalAction.html). If the cursor is not visible in $entry, this signal causes the viewport to be moved instead.

Applications should not connect to it, but may emit it with g_signal_emit_by_name() if they need to control the cursor programmatically.

The default bindings for this signal come in two variants, the variant with the Shift modifier extends the selection, the variant without the Shift modifier does not. There are too many key combinations to list them all here.

• <kbd>←</kbd>, <kbd>→</kbd>, <kbd>↑</kbd>, <kbd>↓</kbd> move by individual characters/lines

• <kbd>Ctrl</kbd>+<kbd>←</kbd>, etc. move by words/paragraphs

• <kbd>Home</kbd> and <kbd>End</kbd> move to the ends of the buffer

method handler (
   $step,
  gint $count,
  gboolean $extend-selection,
  Int :$_handle_id,
  N-GObject :$_native-object,
  Gnome::Gtk4::Label :$_widget,
  *C<user>-options
)

• $step; the granularity of the move, as a enumeration GtkMovementStep defined in Gnome::Gtk4::T-enums.

• $count; the number of $step units to move.

• $extend-selection; True if the move should extend the selection.

• $_handle_id; The registered event handler id.

• $_native-object; The native object provided by the Raku object which registered this event. This a native Gnome::Gtk4::Label object.

• $_widget; The object which registered the signal. User code may have left the object going out of scope.

• user-options; A list of named arguments provided at the .register-signal() method from Gnome::GObject::Object.

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