Implemented Interfaces

gtk.Label Properties

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.

"track-visited-links"

Read-Write

If True the label tracks which links have been clicked.
It will then apply the "visited-link-color" color, instead of "link-color".
False. Available in GTK+ 2.18 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.

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:

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.

Constructor

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

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_use_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

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

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

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.

gtk.Label.get_current_uri

def get_current_uri()

Note

This method is available in PyGTK 2.22 and above.

The get_current_uri() method 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" handler.

gtk.Label.set_track_visited_links

def set_track_visited_links(track_links)

track_links :

True to track visited links, False otherwise.

Note

This method is available in PyGTK 2.22 and above.

The set_track_visited_links() method sets
whether the label should keep track of clicked links (and use a different color for them).

gtk.Label.get_track_visited_links

def get_track_visited_links()

Returns :

True if clicked links are remembered, False otherwise.

Note

This method is available in PyGTK 2.22 and above.

The get_track_visited_links() method returns
whether the label is currently keeping track of clicked links.

gtk.Label.set_line_wrap_mode

def set_line_wrap_mode(wrap_mode)

wrap_mode :

the line wrapping mode.

The set_line_wrap_mode() method controls how line
wrapping is done (if it is enabled, see
refetch()).
The default is pango.WRAP_WORD which means wrap on word boundaries.

gtk.Label.get_line_wrap_mode

def get_line_wrap_mode()

Returns :

True if the lines of the label are automatically wrapped.

The get_line_wrap_mode() method returns
the line wrap mode used by the label.

Signals

The "activate-current-link" 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)

Note

This signal is available in GTK+ 2.18 and above.

The "activate-current-link" is a "keybinding signal" signal which gets emitted when the user activates a link in the label.

The "activate-link" gtk.Label Signal

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

label :

the label that received the signal

uri :

the URI that is activated

user_param1 :

the first user parameter (if any) specified with the connect() method

... :

additional user parameters (if any)

Note

This signal is available in GTK+ 2.18 and above.

The "activate-link" signal is emitted to activate a URI. Applications may connect to it to override the default behaviour,
which is to call gtk.show_uri().

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.