Memory-managed wrapper type.

Type class for types which can be safely cast to Label, for instance with toLabel.

Cast to Label, for types for which this is known to be safe. For general casts, use castTo.

A convenience alias for Nothing :: Maybe Label.

Gets the angle of rotation for the label. See labelSetAngle.

Since: 2.6

Gets the attribute list that was set on the label using labelSetAttributes, if any. This function does not reflect attributes that come from the labels markup (see labelSetMarkup). If you want to get the effective attributes for the label, use pango_layout_get_attribute (gtk_label_get_layout (label)).

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 Label::activate-link handler or for use in a Widget::query-tooltip handler.

Since: 2.18

Returns the ellipsizing position of the label. See labelSetEllipsize.

Since: 2.6

Returns the justification of the label. See labelSetJustify.

Fetches the text from a label widget including any embedded underlines indicating mnemonics and Pango markup. (See labelGetText).

Gets the Layout used to display the label. The layout is useful to e.g. convert text positions to pixel positions, in combination with labelGetLayoutOffsets. 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.

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.g. to take some action if some part of the label is clicked. Of course you will need to create a EventBox to receive the events, and pack the label inside it, since labels are windowless (they return False from widgetGetHasWindow). Remember when using the Layout functions you need to convert to and from pixels using PANGO_PIXELS() or SCALE.

Returns whether lines in the label are automatically wrapped. See labelSetLineWrap.

Returns line wrap mode used by the label. See labelSetLineWrapMode.

Since: 2.10

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

Since: 3.10

Retrieves the desired maximum width of label, in characters. See labelSetWidthChars.

Since: 2.6

If the label has been set so that it has an mnemonic key this function returns the keyval used for the mnemonic accelerator. If there is no mnemonic set up it returns KEY_VoidSymbol.

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

Gets the value set by labelSetSelectable.

Gets the selected range of characters in the label, returning True if there’s a selection.

Returns whether the label is in single line mode.

Since: 2.6

Fetches the text from a label widget, as displayed on the screen. This does not include any embedded underlines indicating mnemonics or Pango markup. (See labelGetLabel)

Returns whether the label is currently keeping track of clicked links.

Since: 2.18

Returns whether the label’s text is interpreted as marked up with the [Pango text markup language][PangoMarkupFormat]. See gtk_label_set_use_markup ().

Returns whether an embedded underline in the label indicates a mnemonic. See labelSetUseUnderline.

Retrieves the desired width of label, in characters. See labelSetWidthChars.

Since: 2.6

Gets the Label:xalign property for label.

Since: 3.16

Gets the Label:yalign property for label.

Since: 3.16

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

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 labelSetMnemonicWidget.

If labelSetMnemonicWidget 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.

Selects a range of characters in the label, if the label is selectable. See labelSetSelectable. If the label is not selectable, this function has no effect. If startOffset or endOffset are -1, then the end of the label will be substituted.

Sets the angle of rotation for the label. An angle of 90 reads from from bottom to top, an angle of 270, from top to bottom. The angle setting for the label is ignored if the label is selectable, wrapped, or ellipsized.

Since: 2.6

Sets a AttrList; the attributes in the list are applied 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 Label:use-underline or Label: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.

Sets the mode used to ellipsize (add an ellipsis: "...") to the text if there is not enough space to render the entire string.

Since: 2.6

Sets the alignment of the lines in the text of the label relative to each other. JustificationLeft is the default value when the widget is first created with labelNew. If you instead want to set the alignment of the label as a whole, use widgetSetHalign instead. labelSetJustify has no effect on labels containing only a single line.

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

Toggles line wrapping within the 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 widgetSetSizeRequest.

If line wrapping is on (see labelSetLineWrap) this controls how the line wrapping is done. The default is WrapModeWord which means wrap on word boundaries.

Since: 2.10

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.

Since: 3.10

Parses str which is marked up with the [Pango text markup language][PangoMarkupFormat], setting the label’s text and attribute list based on the parse results.

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

C code

GtkWidget *label = gtk_label_new (NULL);
const char *str = "some text";
const char *format = "<span style=\"italic\">\%s</span>";
char *markup;

markup = g_markup_printf_escaped (format, str);
gtk_label_set_markup (GTK_LABEL (label), markup);
g_free (markup);

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

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

See also: labelSetText

Parses str which is marked up with the [Pango text markup language][PangoMarkupFormat], 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 labelSetMnemonicWidget.

Sets the desired maximum width in characters of label to nChars.

Since: 2.6

If the label has been set so that it has an mnemonic key (using i.e. labelSetMarkupWithMnemonic, labelSetTextWithMnemonic, labelNewWithMnemonic 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 Button or a Notebook tab) it is automatically associated with the correct widget, but sometimes (i.e. when the target is a Entry next to the label) you need to set it explicitly using this function.

The target widget will be accelerated by emitting the GtkWidget::mnemonic-activate 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.

The pattern of underlines you want under the existing text within the Label widget. For example if the current text of the label says “FooBarBaz” passing a pattern of “_ _” will underline “Foo” and “Baz” but not “Bar”.

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

Sets whether the label is in single line mode.

Since: 2.6

Sets the text within the Label widget. It overwrites any text that was there before.

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

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

See also: labelSetMarkup

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 labelSetMnemonicWidget.

Sets whether the label should keep track of clicked links (and use a different color for them).

Since: 2.18

Sets whether the text of the label contains markup in [Pango’s text markup language][PangoMarkupFormat]. See labelSetMarkup.

If true, an underline in the text indicates the next character should be used for the mnemonic accelerator key.

Sets the desired width in characters of label to nChars.

Since: 2.6

Sets the Label:xalign property for label.

Since: 3.16

Sets the Label:yalign property for label.

Since: 3.16

Construct a GValueConstruct with valid value for the “angle” property. This is rarely needed directly, but it is used by new.

Get the value of the “angle” property. When overloading is enabled, this is equivalent to

get label #angle

Set the value of the “angle” property. When overloading is enabled, this is equivalent to

set label [ #angle := value ]

Set the value of the “attributes” property to Nothing. When overloading is enabled, this is equivalent to

clear #attributes

Construct a GValueConstruct with valid value for the “attributes” property. This is rarely needed directly, but it is used by new.

Get the value of the “attributes” property. When overloading is enabled, this is equivalent to

get label #attributes

Set the value of the “attributes” property. When overloading is enabled, this is equivalent to

set label [ #attributes := value ]

Get the value of the “cursor-position” property. When overloading is enabled, this is equivalent to

get label #cursorPosition

Construct a GValueConstruct with valid value for the “ellipsize” property. This is rarely needed directly, but it is used by new.

Get the value of the “ellipsize” property. When overloading is enabled, this is equivalent to

get label #ellipsize

Set the value of the “ellipsize” property. When overloading is enabled, this is equivalent to

set label [ #ellipsize := value ]

Construct a GValueConstruct with valid value for the “justify” property. This is rarely needed directly, but it is used by new.

Get the value of the “justify” property. When overloading is enabled, this is equivalent to

get label #justify

Set the value of the “justify” property. When overloading is enabled, this is equivalent to

set label [ #justify := value ]

Construct a GValueConstruct with valid value for the “label” property. This is rarely needed directly, but it is used by new.

Get the value of the “label” property. When overloading is enabled, this is equivalent to

get label #label

Set the value of the “label” property. When overloading is enabled, this is equivalent to

set label [ #label := value ]

Construct a GValueConstruct with valid value for the “lines” property. This is rarely needed directly, but it is used by new.

Get the value of the “lines” property. When overloading is enabled, this is equivalent to

get label #lines

Set the value of the “lines” property. When overloading is enabled, this is equivalent to

set label [ #lines := value ]

Construct a GValueConstruct with valid value for the “max-width-chars” property. This is rarely needed directly, but it is used by new.

Get the value of the “max-width-chars” property. When overloading is enabled, this is equivalent to

get label #maxWidthChars

Set the value of the “max-width-chars” property. When overloading is enabled, this is equivalent to

set label [ #maxWidthChars := value ]

Get the value of the “mnemonic-keyval” property. When overloading is enabled, this is equivalent to

get label #mnemonicKeyval

Set the value of the “mnemonic-widget” property to Nothing. When overloading is enabled, this is equivalent to

clear #mnemonicWidget

Construct a GValueConstruct with valid value for the “mnemonic-widget” property. This is rarely needed directly, but it is used by new.

Get the value of the “mnemonic-widget” property. When overloading is enabled, this is equivalent to

get label #mnemonicWidget

Set the value of the “mnemonic-widget” property. When overloading is enabled, this is equivalent to

set label [ #mnemonicWidget := value ]

Construct a GValueConstruct with valid value for the “pattern” property. This is rarely needed directly, but it is used by new.

Set the value of the “pattern” property. When overloading is enabled, this is equivalent to

set label [ #pattern := value ]

Construct a GValueConstruct with valid value for the “selectable” property. This is rarely needed directly, but it is used by new.

Get the value of the “selectable” property. When overloading is enabled, this is equivalent to

get label #selectable

Set the value of the “selectable” property. When overloading is enabled, this is equivalent to

set label [ #selectable := value ]

Get the value of the “selection-bound” property. When overloading is enabled, this is equivalent to

get label #selectionBound

Construct a GValueConstruct with valid value for the “single-line-mode” property. This is rarely needed directly, but it is used by new.

Get the value of the “single-line-mode” property. When overloading is enabled, this is equivalent to

get label #singleLineMode

Set the value of the “single-line-mode” property. When overloading is enabled, this is equivalent to

set label [ #singleLineMode := value ]

Construct a GValueConstruct with valid value for the “track-visited-links” property. This is rarely needed directly, but it is used by new.

Get the value of the “track-visited-links” property. When overloading is enabled, this is equivalent to

get label #trackVisitedLinks

Set the value of the “track-visited-links” property. When overloading is enabled, this is equivalent to

set label [ #trackVisitedLinks := value ]

Construct a GValueConstruct with valid value for the “use-markup” property. This is rarely needed directly, but it is used by new.

Get the value of the “use-markup” property. When overloading is enabled, this is equivalent to

get label #useMarkup

Set the value of the “use-markup” property. When overloading is enabled, this is equivalent to

set label [ #useMarkup := value ]

Construct a GValueConstruct with valid value for the “use-underline” property. This is rarely needed directly, but it is used by new.

Get the value of the “use-underline” property. When overloading is enabled, this is equivalent to

get label #useUnderline

Set the value of the “use-underline” property. When overloading is enabled, this is equivalent to

set label [ #useUnderline := value ]

Construct a GValueConstruct with valid value for the “width-chars” property. This is rarely needed directly, but it is used by new.

Get the value of the “width-chars” property. When overloading is enabled, this is equivalent to

get label #widthChars

Set the value of the “width-chars” property. When overloading is enabled, this is equivalent to

set label [ #widthChars := value ]

Construct a GValueConstruct with valid value for the “wrap” property. This is rarely needed directly, but it is used by new.

Get the value of the “wrap” property. When overloading is enabled, this is equivalent to

get label #wrap

Set the value of the “wrap” property. When overloading is enabled, this is equivalent to

set label [ #wrap := value ]

Construct a GValueConstruct with valid value for the “wrap-mode” property. This is rarely needed directly, but it is used by new.

Get the value of the “wrap-mode” property. When overloading is enabled, this is equivalent to

get label #wrapMode

Set the value of the “wrap-mode” property. When overloading is enabled, this is equivalent to

set label [ #wrapMode := value ]

Construct a GValueConstruct with valid value for the “xalign” property. This is rarely needed directly, but it is used by new.

Get the value of the “xalign” property. When overloading is enabled, this is equivalent to

get label #xalign

Set the value of the “xalign” property. When overloading is enabled, this is equivalent to

set label [ #xalign := value ]

Construct a GValueConstruct with valid value for the “yalign” property. This is rarely needed directly, but it is used by new.

Get the value of the “yalign” property. When overloading is enabled, this is equivalent to

get label #yalign

Set the value of the “yalign” property. When overloading is enabled, this is equivalent to

set label [ #yalign := value ]

Type for the callback on the (unwrapped) C side.

A [keybinding signal][GtkBindingSignal] which gets emitted when the user activates a link in the label.

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 Enter key.

Since: 2.18

Connect a signal handler for the “activate-current-link” signal, to be run after the default handler. When overloading is enabled, this is equivalent to

after label #activateCurrentLink callback

Wrap the callback into a Closure.

Generate a function pointer callable from C code, from a C_LabelActivateCurrentLinkCallback.

A convenience synonym for Nothing :: Maybe LabelActivateCurrentLinkCallback.

Connect a signal handler for the “activate-current-link” signal, to be run before the default handler. When overloading is enabled, this is equivalent to

on label #activateCurrentLink callback

Wrap a LabelActivateCurrentLinkCallback into a C_LabelActivateCurrentLinkCallback.

Type for the callback on the (unwrapped) C side.

The signal which gets emitted to activate a URI. Applications may connect to it to override the default behaviour, which is to call showUriOnWindow.

Since: 2.18

Connect a signal handler for the “activate-link” signal, to be run after the default handler. When overloading is enabled, this is equivalent to

after label #activateLink callback

Wrap the callback into a Closure.

Generate a function pointer callable from C code, from a C_LabelActivateLinkCallback.

A convenience synonym for Nothing :: Maybe LabelActivateLinkCallback.

Connect a signal handler for the “activate-link” signal, to be run before the default handler. When overloading is enabled, this is equivalent to

on label #activateLink callback

Wrap a LabelActivateLinkCallback into a C_LabelActivateLinkCallback.

Type for the callback on the (unwrapped) C side.

The ::copy-clipboard signal is a [keybinding signal][GtkBindingSignal] which gets emitted to copy the selection to the clipboard.

The default binding for this signal is Ctrl-c.

Connect a signal handler for the “copy-clipboard” signal, to be run after the default handler. When overloading is enabled, this is equivalent to

after label #copyClipboard callback

Wrap the callback into a Closure.

Generate a function pointer callable from C code, from a C_LabelCopyClipboardCallback.

A convenience synonym for Nothing :: Maybe LabelCopyClipboardCallback.

Connect a signal handler for the “copy-clipboard” signal, to be run before the default handler. When overloading is enabled, this is equivalent to

on label #copyClipboard callback

Wrap a LabelCopyClipboardCallback into a C_LabelCopyClipboardCallback.

Type for the callback on the (unwrapped) C side.

The ::move-cursor signal is a [keybinding signal][GtkBindingSignal] which gets emitted when the user initiates a cursor movement. 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 modifer does not. There are too many key combinations to list them all here.

• Arrow keys move by individual characters/lines
• Ctrl-arrow key combinations move by words/paragraphs
• Home/End keys move to the ends of the buffer

Connect a signal handler for the “move-cursor” signal, to be run after the default handler. When overloading is enabled, this is equivalent to

after label #moveCursor callback

Wrap the callback into a Closure.

Generate a function pointer callable from C code, from a C_LabelMoveCursorCallback.

A convenience synonym for Nothing :: Maybe LabelMoveCursorCallback.

Connect a signal handler for the “move-cursor” signal, to be run before the default handler. When overloading is enabled, this is equivalent to

on label #moveCursor callback

Wrap a LabelMoveCursorCallback into a C_LabelMoveCursorCallback.

Type for the callback on the (unwrapped) C side.

The ::populate-popup signal gets emitted before showing the context menu of the label. Note that only selectable labels have context menus.

If you need to add items to the context menu, connect to this signal and append your menuitems to the menu.

Connect a signal handler for the “populate-popup” signal, to be run after the default handler. When overloading is enabled, this is equivalent to

after label #populatePopup callback

Wrap the callback into a Closure.

Generate a function pointer callable from C code, from a C_LabelPopulatePopupCallback.

A convenience synonym for Nothing :: Maybe LabelPopulatePopupCallback.

Connect a signal handler for the “populate-popup” signal, to be run before the default handler. When overloading is enabled, this is equivalent to

on label #populatePopup callback

Wrap a LabelPopulatePopupCallback into a C_LabelPopulatePopupCallback.