Name

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()

Ancestry

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

Properties

"label"Read-WriteThe text of the label
"attributes"Read-WriteA list of Pango style attributes to apply to the text of the label.
"use-markup"Read-WriteIf TRUE, the text of the label includes XML markup.
"use-underline"Read-WriteIf TRUE, an underscore in the text indicates the next character should be used for the mnemonic accelerator key
"justify"Read-WriteThe 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.
"pattern"WriteA string with _ characters in positions used to identify to characters in the text to underline.
"wrap"Read-WriteIf TRUE, wrap lines if the text becomes too wide.
"selectable"Read-WriteIf TRUE, the label text can be selected with the mouse.
"mnemonic-keyval"ReadThe mnemonic accelerator key for this label.
"mnemonic-widget"Read-WriteThe widget to be activated when the label's mnemonic key is pressed.
"cursor-position"ReadThe current position of the insertion cursor in chars.
"selection-bound"ReadThe position of the opposite end of the selection from the cursor in chars.

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.

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.

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.

The label text layout can be modified using methods that affect line wrapping and justification. A label can be made selectable so the user can copy the text to a clipboard.

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.

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.