gtk.Label
Prev | The gtk Class Reference | Next

## gtk.Label

gtk.Label — a widget that displays a limited amount of read-only text

## Synopsis

    class gtk.Label(gtk.Misc):
        gtk.Label(str=None)
        def set_text(str)
        def get_text()
        def set_attributes(attrs)
        def get_attributes()
        def set_label(str)
        def get_label()
        def set_markup(str)
        def set_use_markup(setting)
        def get_use_markup()
        def set_use_underline(setting)
        def get_use_underline()
        def set_markup_with_mnemonic(str)
        def get_mnemonic_keyval()
        def set_mnemonic_widget(widget)
        def get_mnemonic_widget()
        def set_text_with_mnemonic(str)
        def set_justify(jtype)
        def get_justify()
        def set_pattern(pattern)
        def set_line_wrap(wrap)
        def get_line_wrap()
        def set_selectable(setting)
        def get_selectable()
        def select_region(start_offset, end_offset)
        def get_selection_bounds()
        def get_layout()
        def get_layout_offsets()
        def set_ellipsize(mode)
        def get_ellipsize()
        def set_width_chars(n_chars)
        def get_width_chars()
        def set_single_line_mode(single_line_mode)
        def get_single_line_mode()
        def get_max_width_chars()
        def set_max_width_chars(n_chars)
        def get_angle()
        def set_angle(angle)

## Ancestry

    +-- gobject.GObject
      +-- gtk.Object
        +-- gtk.Widget
          +-- gtk.Misc
            +-- gtk.Label

## gtk.Label Properties

gtk.Object Properties

gtk.Widget Properties

gtk.Misc Properties

"angle" | Read-Write | The angle that the baseline of the label makes with the horizontal, in degrees, measured counterclockwise. An angle of 90 reads from from bottom to top, an angle of 270, from top to bottom. Ignored if the label is selectable, wrapped, or ellipsized. Allowed values: [0,360] Default value: 0. Available in GTK+ 2.6 and above.
"attributes" | Read-Write | A list of Pango style attributes to apply to the text of the label.
"cursor-position" | Read | The current position of the insertion cursor in chars. Allowed values: >= 0. Default value: 0

"ellipsize"

Read-Write

The preferred place to ellipsize the string, if the label does not have enough room to display the entire string, specified as one of the Pango Ellipsize Mode Constants. Note that setting this property to a value other than `pango.ELLIPSIZE_NONE` has the side-effect that the label requests only enough space to display the ellipsis "...". In particular, this means that ellipsizing labels don't work well in notebook tabs, unless the tab's "tab-expand" property is set to `True`. Other means to set a label's width are with the `gtk.Widget.set_size_request`() and `set_width_chars`() methods. Default value: `pango.ELLIPSIZE_NONE`. Available in GTK+ 2.6 and above.

"justify" | Read-Write | The alignment of the lines in the text of the label relative to each other. The possible values are: `gtk.JUSTIFY_LEFT`, `gtk.JUSTIFY_RIGHT`, `gtk.JUSTIFY_CENTER`, `gtk.JUSTIFY_FILL`. This does NOT affect the alignment of the label within its allocation. Default value: `gtk.JUSTIFY_LEFT`
"label" | Read-Write | The text of the label. Default value: `None`

"max-width-chars"

Read-Write

The desired maximum width of the label, in characters. If this property is set to -1, the width will be calculated automatically, otherwise the label will request space for no more than the requested number of characters. If the "width-chars" property is set to a positive value, then the "max-width-chars" property is ignored. Allowed values: >= -1. Default value: -1. Available in GTK+ 2.6 and above.

"mnemonic-keyval" | Read | The mnemonic accelerator key for this label. Default value: 16777215
"mnemonic-widget" | Read-Write | The widget to be activated when the label's mnemonic key is pressed.
"pattern" | Write | A string with _ characters in positions used to identify to characters in the text to underline. Default value: `None`
"selectable" | Read-Write | If `True`, the label text can be selected with the mouse. Default value: `False`
"selection-bound" | Read | The position of the opposite end of the selection from the cursor in chars. Allowed values: >= 0. Default value: 0.
"single-line-mode" | Read-Write | If `True` the label is in single line mode. In single line mode, the height of the label does not depend on the actual text, it is always set to ascent + descent of the font. This can be an advantage in situations where resizing the label because of text changes would be distracting, e.g. in a statusbar. Default value: `False`. Available in GTK+ 2.6 and above.
"use-markup" | Read-Write | If `True`, the text of the label includes XML markup. Default value: `False`
"use-underline" | Read-Write | If `True`, an underscore in the text indicates the next character should be used for the mnemonic accelerator key. Default value: `False`
"width-chars" | Read-Write | The desired width of the label, in characters. If this property is set to -1, the width will be calculated automatically, otherwise the label will request either 3 characters or the property value, whichever is greater. Allowed values: >= -1. Default value: -1. Available in GTK+ 2.6 and above.
"wrap" | Read-Write | If `True`, wrap lines if the text becomes too wide. Default value: `False`

## gtk.Label Style Properties

gtk.Widget Style Properties

## gtk.Label Signal Prototypes

gobject.GObject Signal Prototypes

gtk.Object Signal Prototypes

gtk.Widget Signal Prototypes

"copy-clipboard" | `def callback(`label`, `user_param1`, `...`)`
"move-cursor" | `def callback(`label`, `step`, `count`, `extend_selection`, `user_param1`, `...`)`
"populate-popup" | `def callback(`label`, `menu`, `user_param1`, `...`)`

## Description

The `gtk.Label` is a widget class that displays a limited amount of read-only text. Labels are used by several widgets (e.g. `gtk.Button`, and its subclasses, `gtk.MenuItem`, etc.) to provide text display as well as by applications to display messages, etc, to the user. Most of the functionality of a `gtk.Label` is directed at modifying the style and layout of the text within the widget allocation. A `gtk.Label` is a "windowless" object which means that it cannot receive events directly. A `gtk.EventBox` can be used to provide event handling capabilities to a `gtk.Label` widget if needed.

### Mnemonics

Label text may be specified with embedded underscore characters that are used to indicate that the following character should be underlined and used as the mnemonic accelerator (if it's the first underlined character). The `set_text_with_mnemonic`() method is used to parse the label text for a mnemonic characters. Mnemonics automatically activate any activatable widget the label is inside, such as a `gtk.Button`; if the label is not inside an activatable widget, you have to tell the label about the target using the `set_mnemonic_widget`() method. Here's a simple example where the label is inside a button:

      # Pressing Alt+H will activate this button
      button = gtk.Button()
      label = gtk.Label("_Hello")
      label.set_use_underline(True)
      button.add(label)

As a convenience you can create a button with a mnemonic label as follows:

      # Pressing Alt+H will activate this button
      button = gtk.Button(label="_Hello", use_underline=True)

To create a mnemonic for a widget alongside the label, such as a `gtk.Entry`, you have to point the label at the entry with the `set_mnemonic_widget`() method:

      # Pressing Alt+H will focus the entry
      entry = gtk.Entry()
      label = gtk.Label("_Hello")
      label.set_use_underline(True)
      label.set_mnemonic_widget(entry)

### Markup (styled text)

To make it easy to format text in a label (changing colors, fonts, etc.), the label text can be provided in the Pango markup format which is a simple XML markup format. The `gtk.Label.set_markup`() method sets the label using text in valid markup format (e.g. '<', '>' and '&' characters must be replaced by &lt;, &gt; and &amp; respectively. For example:

      label = gtk.Label()
      label.set_markup("<small>Small text</small>");

The markup passed to the `set_markup`() method must be valid. For example, the literal <>& characters must be escaped as &lt;, &gt;, and &amp;. If you pass text obtained from the user, file, or a network to the `set_markup`() method, you'll want to escape it with the Python Library `xml.sax.saxutils.escape`() function.

Markup strings are just a convenient way to set the `pango.AttrList` on a label. Using the `set_attributes`() method 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 because 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 the `set_selectable`() method. 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 the `set_line_wrap`() method.

The `set_justify`() method 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 `gtk.Misc.set_alignment`() method.

## Constructor

        gtk.Label(str=None)

`str` : | The text of the label or `None` for a blank label
Returns : | the new `gtk.Label` widget

Creates a new `gtk.Label` with the text specified by `str` inside it. You can pass `None` to get a blank label.

## Methods

### gtk.Label.set_text

        def set_text(str)

`str` : | The new text for the label.

The `set_text`() method sets the text within the `gtk.Label` widget. It replaces any text that was there before and will clear any previously set mnemonic accelerators.

### gtk.Label.get_text

        def get_text()

Returns : | the text in the label widget.

The `get_text`() method fetches the text from a label widget, as displayed on the screen. This does not include any Pango markup or embedded underscore characters indicating mnemonics. (See `get_label`()).

### gtk.Label.set_attributes

        def set_attributes(attrs)

`attrs` : | a `pango.AttrList`

The `set_attributes`() method applies a `pango.AttrList` list of attributes to the label text. The attributes set with this function will be ignored if either the "use-underline" or "use-markup" attributes is `True`.

### gtk.Label.get_attributes

        def get_attributes()

Returns : | the attribute list, or `None` if no attributes were set.

The `get_attributes`() method returns the attribute list that was set on the label using `set_attributes`(), if any. This function does not reflect attributes that come from the labels markup (see `set_markup`()).

### gtk.Label.set_label

        def set_label(str)

`str` : | the new text (including mnemonics or markup) to set for the label

The `set_label`() method sets the text of the label. The label is parsed for embedded underscores and Pango markup depending on the values of the "use-underline" and "use-markup" properties.

### gtk.Label.get_label

        def get_label()

Returns : | the text of the label widget.

The `get_label`() method returns the text from a label widget including any Pango markup and embedded underscores indicating mnemonics. (See `get_text`() that just returns the text).

### gtk.Label.set_markup

        def set_markup(str)

`str` : | a markup string

The `set_markup`() method parses `str`, which is marked up with the Pango text markup language, and sets the label's text and attribute list.

### gtk.Label.set_use_markup

        def set_use_markup(setting)

`setting` : | if `True` the label's text should be parsed for markup.

The `set_use_markup`() method sets the "use-markup" property to the value of `setting`. If `True` the text of the label should be parsed as markup.

### gtk.Label.get_use_markup

        def get_use_markup()

Returns : | `True` if the label's text will be parsed for markup.

The `get_user_markup`() method returns the value of the "use-markup" property. If `True` the label's text is parsed as markup. See `set_use_markup`().

### gtk.Label.set_use_underline

        def set_use_underline(setting)

`setting` : | if `True` underscores in the text indicate mnemonics

The `set_use_underline`() method sets the "use-underline" property to the value of `setting`. If `setting` is `True`, an underscore in the text indicates the next character should be used for the mnemonic accelerator key.

### gtk.Label.get_use_underline

        def get_use_underline()

Returns : | `True` if an embedded underscore in the label indicates the mnemonic accelerator.

The `get_use_underline`() method returns the value of the "use-underline" property. If `True` an embedded underscore in the label indicates the next character is a mnemonic. See `set_use_underline`().

### gtk.Label.set_markup_with_mnemonic

        def set_markup_with_mnemonic(str)

`str` : | a markup string including embedded underscores

The `set_markup_with_mnemonic`() method parses `str` as markup, 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 mnemonic accelerator. The mnemonic key can be used to activate another widget, chosen automatically, or explicitly using the `set_mnemonic_widget`() method.

### gtk.Label.get_mnemonic_keyval

        def get_mnemonic_keyval()

Returns : | a keyval, or the void symbol keyval

The `get_mnemonic_keyval`() method returns the value of the "mnemonic-keyval" property that contains the keyval used for the mnemonic accelerator if one has been set on the label. If there is no mnemonic set up it returns the void symbol keyval.

### gtk.Label.set_mnemonic_widget

        def set_mnemonic_widget(widget)

`widget` : | the widget to be activated when the mnemonic is pressed

The `set_mnemonic_widget`() method sets the "mnemonic-widget" property using the value of `widget`. This method associates the label mnemonic with a widget that will be activated when the mnemonic accelerator is pressed. When the label is inside a widget (like a `gtk.Button` or a `gtk.Notebook` tab) it is automatically associated with the correct widget, but sometimes (i.e. when the target is a `gtk.Entry` next to the label) you need to set it explicitly using this function. The target widget will be activated by emitting "mnemonic_activate" on it.

### gtk.Label.get_mnemonic_widget

        def get_mnemonic_widget()

Returns : | the target of the label's mnemonic, or `None` if none has been set and the default algorithm will be used.

The `get_mnemonic_widget`() method retrieves the value of the "mnemonic-widget" property which is the target of the mnemonic accelerator of this label. See `set_mnemonic_widget`().

### gtk.Label.set_text_with_mnemonic

        def set_text_with_mnemonic(str)

`str` : | the label text with embedded underscore characters indicating the mnemonic characters

The `set_text_with_mnemonic`() method 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 mnemonic accelerator. The mnemonic key can be used to activate another widget, chosen automatically, or explicitly using the `set_mnemonic_widget`() method.

### gtk.Label.set_justify

        def set_justify(jtype)

`jtype` : | justification type

The `set_justify`() method sets the alignment of the lines in the text of the label relative to each other using the value of `jtype`. The possible values of `jtype` are: `gtk.JUSTIFY_LEFT`, `gtk.JUSTIFY_RIGHT`, `gtk.JUSTIFY_CENTER` and `gtk.JUSTIFY_FILL`. `gtk.JUSTIFY_LEFT` is the default value when the widget is first created. If you want to set the alignment of the label as a whole, use the `gtk.Misc.set_alignment`() method instead. The `set_justify`() has no effect on labels containing only a single line.

### gtk.Label.get_justify

        def get_justify()

Returns : | the label justification

The `get_justify`() method returns the justification of the label; one of: `gtk.JUSTIFY_LEFT`, `gtk.JUSTIFY_RIGHT`, `gtk.JUSTIFY_CENTER` or `gtk.JUSTIFY_FILL`. See `set_justify`().

### gtk.Label.set_pattern

        def set_pattern(pattern)

`pattern` : | the pattern of underlines

The `set_pattern`() method sets the "pattern" property with the value of `pattern`. The pattern contains an underscore or space for each character in the label text. Any characters omitted are assumed to be spaces. For example, if the label text is "XXX Label" and the pattern is "___" then only the "XXX" will be underlined.

### gtk.Label.set_line_wrap

        def set_line_wrap(wrap)

`wrap` : | if True the label lines will wrap if too big for the widget size.

The `set_wrap`() method sets the "wrap" property tot he value of `wrap`. If `wrap` is `True` the label text will wrap if it is wider than the widget size; otherwise, the text gets cut off at the edge of the widget.

### gtk.Label.get_line_wrap

        def get_line_wrap()

Returns : | `True` if the lines of the label are automatically wrapped.

The `get_line_wrap`() method returns the value of the "wrap" property. If "wrap" is `True` the lines in the label are automatically wrapped. See `set_line_wrap`().

### gtk.Label.set_selectable

        def set_selectable(setting)

`setting` : | if `True` allow the text in the label to be selected

The `set_selectable`() method sets the "selectable" property with the value of `setting`. If `setting` is `True` the user is allowed to select text from the label, for copy-and-paste.

### gtk.Label.get_selectable

        def get_selectable()

Returns : | `True` if the user can select the label text

The `get_selectable`() method gets the value of the "selectable" property set by the `set_selectable`() method.

### gtk.Label.select_region

        def select_region(start_offset, end_offset)

`start_offset` : | start offset in characters
`end_offset` : | end offset in characters

The `select_region`() method selects a range of characters in the label, if the label is selectable. The selected region is the range of characters between `start_offset` and `end_offset`. See `set_selectable`(). If the label is not selectable, this method has no effect. If `start_offset` or `end_offset` are -1, then the end of the label will be substituted.

### gtk.Label.get_selection_bounds

        def get_selection_bounds()

Returns : | a tuple containing the start and end character offsets of the selection

The `get_selection_bounds`() method returns a tuple that contains the start and end character offsets of the selected text in the label if the selection exists. If there is no selection or the label is not selectable, an empty tuple is returned.

### gtk.Label.get_layout

        def get_layout()

Returns : | the `pango.Layout` for this label

The `get_layout`() method returns the `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`().

### gtk.Label.get_layout_offsets

        def get_layout_offsets()

Returns : | a tuple containing the X offset of the layout, or `None` and the Y offset of layout, or `None`

The `get_layout_offsets`() method returns a tuple containing the coordinates where the label will draw the `pango.Layout` representing the text in the label. This method is useful for converting mouse events into coordinates inside the `pango.Layout`, e.g. to take some action if some part of the label is clicked. Of course you will need to create a `gtk.EventBox` to receive the events, and pack the label inside it, since labels are a "windowless" (`gtk.NO_WINDOW`) widget. Remember when using the `pango.Layout` functions you need to convert to and from pixels using `pango.PIXELS()` or `pango.SCALE`.

### gtk.Label.set_ellipsize

        def set_ellipsize(mode)

`mode` : | one of the Pango Ellipsize Mode Constants to use

### Note

This method is available in PyGTK 2.6 and above.

The `set_ellipsize`() method sets the "ellipsize" property to the value of `mode`. `mode` should be one of the Pango Ellipsize Mode Constants. The "ellipsize" property specifies if and where an ellipse should be used if there is not enough room for the label text.

### gtk.Label.get_ellipsize

        def get_ellipsize()

Returns : | the current ellipsize mode

### Note

This method is available in PyGTK 2.6 and above.

The `get_ellipsize`() method returns the value of the "ellipsize" property which contains one of the Pango Ellipsize Mode Constants. The "ellipsize" property specifies if and where an ellipse should be used if there is not enough room for the label text.

### gtk.Label.set_width_chars

        def set_width_chars(n_chars)

`n_chars` : | the new desired width, in characters.

### Note

This method is available in PyGTK 2.6 and above.

The `set_width_chars`() method sets the "width-chars" property to the value of `n_chars`. The "width-chars" property specifies the desired width of the label in characters.

### gtk.Label.get_width_chars

        def get_width_chars()

Returns : | the desired width of the label in characters.

### Note

This method is available in PyGTK 2.6 and above.

The `get_width_chars`() method returns the value of the "width-chars" property that specifies the desired width of the label in characters.

### gtk.Label.set_single_line_mode

        def set_single_line_mode(single_line_mode)

`single_line_mode` : | if `True` the label is in single line mode.

### Note

This method is available in PyGTK 2.6 and above.

The `set_single_line_mode`() method sets the "single-line-mode" property to the value of `single_line_mode`. If `single_line_mode` is `True` the label is in single line mode where the height of the label does not depend on the actual text, it is always set to ascent + descent of the font.

### gtk.Label.get_single_line_mode

        def get_single_line_mode()

Returns : |

### Note

This method is available in PyGTK 2.6 and above.

The `get_single_line_mode`() method returns the value of the "single-line-mode" property. See the `set_single_line_mode`() method for more information.

### gtk.Label.set_max_width_chars

        def set_max_width_chars(n_chars)

`n_chars` : | the new desired maximum width, in characters.

### Note

This method is available in PyGTK 2.6 and above.

The `set_max_width_chars`() method sets the "max-width-chars" property to the value of `n_chars`.

### gtk.Label.get_max_width_chars

        def get_max_width_chars()

Returns : |

### Note

This method is available in PyGTK 2.6 and above.

The `get_max_width_chars`() method returns the value of the "max-width-chars" property which is the desired maximum width of the label in characters.

### gtk.Label.set_angle

        def set_angle(angle)

`angle` : | the angle that the baseline of the label makes with the horizontal, in degrees, measured counterclockwise

### Note

This method is available in PyGTK 2.6 and above.

The `set_angle`() method sets the "angle" property to the value of `angle`. `angle` is 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.

### gtk.Label.get_angle

        def get_angle()

Returns : |

### Note

This method is available in PyGTK 2.6 and above.

The `get_angle`() method returns the value of the "angle" property. See the `set_angle`() method for more information.

## Signals

### The "copy-clipboard" gtk.Label Signal

        def callback(label, user_param1, ...)

`label` : | the label that received the signal
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)

The "copy-clipboard" signal is emitted when text is copied from the label to the clipboard.

### The "move-cursor" gtk.Label Signal

        def callback(label, step, count, extend_selection, user_param1, ...)

`label` : | the label that received the signal
`step` : | the step size of the move: `gtk.MOVEMENT_LOGICAL_POSITIONS`, `gtk.MOVEMENT_VISUAL_POSITIONS`, `gtk.MOVEMENT_WORDS`, `gtk.MOVEMENT_DISPLAY_LINES`, `gtk.MOVEMENT_DISPLAY_LINE_ENDS`, `gtk.MOVEMENT_PARAGRAPHS`, `gtk.MOVEMENT_PARAGRAPH_ENDS`, `gtk.MOVEMENT_PAGES` and `gtk.MOVEMENT_BUFFER_ENDS`
`count` : | the number of steps to take
`extend_selection` : | if `True` extend the range of the selection
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)

The "move-cursor" signal is emitted when the cursor is being moved `count` steps or size `step`. The step size is one of:

      gtk.MOVEMENT_LOGICAL_POSITIONS,    move by graphemes
      gtk.MOVEMENT_VISUAL_POSITIONS,     move by graphemes
      gtk.MOVEMENT_WORDS,                move by words
      gtk.MOVEMENT_DISPLAY_LINES,        move by lines(wrapped lines)
      gtk.MOVEMENT_DISPLAY_LINE_ENDS,    move to line ends(wrapped lines)
      gtk.MOVEMENT_PARAGRAPHS,           move by paragraphs(newline-ended lines)
      gtk.MOVEMENT_PARAGRAPH_ENDS,       move to ends of a paragraph
      gtk.MOVEMENT_PAGES,	             move by pages
      gtk.MOVEMENT_BUFFER_ENDS           move to ends of the buffer

If `extend_selection` is `True` the selection will be extended to include the text moved over.

### The "populate-popup" gtk.Label Signal

        def callback(label, menu, user_param1, ...)

`label` : | the label that received the signal
`menu` : | the menu to be populated
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)

The "populate-popup" signal is emitted when a menu needs to be populated on the fly.

Prev | Up | Next
gtk.ItemFactory | Home | gtk.Layout