path: root/docs/reference/pygtk-gtklabel.xml

<?xml version="1.0" standalone="no"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
    "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">

<refentry id="class-gtklabel">
  <refnamediv>
    <refname>gtk.Label</refname>
    <refpurpose>a widget that displays a limited amount of read-only
text</refpurpose>
  </refnamediv>

  <refsect1>
    <title>Synopsis</title>

    <classsynopsis language="python">
      <ooclass><classname>gtk.Label</classname></ooclass>
      <ooclass><classname><link
linkend="class-gtkmisc">gtk.Misc</link></classname></ooclass>
      <constructorsynopsis language="python">
	<methodname><link
linkend="constructor-gtklabel">gtk.Label</link></methodname>
	<methodparam><parameter
		       role="keyword">str</parameter><initializer>None</initializer></methodparam>
      </constructorsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtklabel--set-text">set_text</link></methodname>
	<methodparam><parameter role="keyword">str</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtklabel--get-text">get_text</link></methodname>
	<methodparam></methodparam>  </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtklabel--set-attributes">set_attributes</link></methodname>
	<methodparam><parameter
		       role="keyword">attrs</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtklabel--get-attributes">get_attributes</link></methodname>
	<methodparam></methodparam>  </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtklabel--set-label">set_label</link></methodname>
	<methodparam><parameter role="keyword">str</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtklabel--get-label">get_label</link></methodname>
	<methodparam></methodparam>  </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtklabel--set-markup">set_markup</link></methodname>
	<methodparam><parameter role="keyword">str</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtklabel--set-use-markup">set_use_markup</link></methodname>
	<methodparam><parameter
		       role="keyword">setting</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtklabel--get-use-markup">get_use_markup</link></methodname>
	<methodparam></methodparam>  </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtklabel--set-use-underline">set_use_underline</link></methodname>
	<methodparam><parameter
		       role="keyword">setting</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtklabel--get-use-underline">get_use_underline</link></methodname>
	<methodparam></methodparam>  </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtklabel--set-markup-with-mnemonic">set_markup_with_mnemonic</link></methodname>
	<methodparam><parameter role="keyword">str</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtklabel--get-mnemonic-keyval">get_mnemonic_keyval</link></methodname>
	<methodparam></methodparam>  </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtklabel--set-mnemonic-widget">set_mnemonic_widget</link></methodname>
	<methodparam><parameter
		       role="keyword">widget</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtklabel--get-mnemonic-widget">get_mnemonic_widget</link></methodname>
	<methodparam></methodparam>  </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtklabel--set-text-with-mnemonic">set_text_with_mnemonic</link></methodname>
	<methodparam><parameter role="keyword">str</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtklabel--set-justify">set_justify</link></methodname>
	<methodparam><parameter
		       role="keyword">jtype</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtklabel--get-justify">get_justify</link></methodname>
	<methodparam></methodparam>  </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtklabel--set-pattern">set_pattern</link></methodname>
	<methodparam><parameter
		       role="keyword">pattern</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtklabel--set-line-wrap">set_line_wrap</link></methodname>
	<methodparam><parameter
		       role="keyword">wrap</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtklabel--get-line-wrap">get_line_wrap</link></methodname>
	<methodparam></methodparam>  </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtklabel--set-selectable">set_selectable</link></methodname>
	<methodparam><parameter
		       role="keyword">setting</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtklabel--get-selectable">get_selectable</link></methodname>
	<methodparam></methodparam>  </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtklabel--select-region">select_region</link></methodname>
	<methodparam><parameter
		       role="keyword">start_offset</parameter></methodparam>
	<methodparam><parameter
		       role="keyword">end_offset</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtklabel--get-selection-bounds">get_selection_bounds</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtklabel--get-layout">get_layout</link></methodname>
	<methodparam></methodparam>  </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtklabel--get-layout-offsets">get_layout_offsets</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtklabel--set-ellipsize">set_ellipsize</link></methodname>
	<methodparam><parameter
		       role="keyword">mode</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtklabel--get-ellipsize">get_ellipsize</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtklabel--set-width-chars">set_width_chars</link></methodname>
	<methodparam><parameter
		       role="keyword">n_chars</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtklabel--get-width-chars">get_width_chars</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtklabel--set-single-line-mode">set_single_line_mode</link></methodname>
	<methodparam><parameter
		       role="keyword">single_line_mode</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtklabel--get-single-line-mode">get_single_line_mode</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtklabel--get-single-line-mode">get_max_width_chars</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtklabel--set-single-line-mode">set_max_width_chars</link></methodname>
	<methodparam><parameter
		       role="keyword">n_chars</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtklabel--get-angle">get_angle</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtklabel--set-angle">set_angle</link></methodname>
	<methodparam><parameter
		       role="keyword">angle</parameter></methodparam>
      </methodsynopsis>
    </classsynopsis>

  </refsect1>

  <refsect1>
    <title>Ancestry</title>

<synopsis>+-- <link linkend="class-gobject">gobject.GObject</link>
  +-- <link linkend="class-gtkobject">gtk.Object</link>
    +-- <link linkend="class-gtkwidget">gtk.Widget</link>
      +-- <link linkend="class-gtkmisc">gtk.Misc</link>
        +-- <link linkend="class-gtklabel">gtk.Label</link>
</synopsis>

  </refsect1>

  <refsect1 id="properties-gtklabel">
    <title>gtk.Label Properties</title>

    <para><link linkend="properties-gtkobject">gtk.Object Properties</link></para>
    <para><link linkend="properties-gtkwidget">gtk.Widget Properties</link></para>
    <para><link linkend="properties-gtkmisc">gtk.Misc Properties</link></para>

    <blockquote role="properties">
      <informaltable pgwide="1" frame="none">
	<tgroup cols="3">
	  <colspec column="1" colwidth="1in"/>
	  <colspec column="2" colwidth="1in"/>
	  <colspec column="3" colwidth="4in"/>
	  <tbody>

	    <row valign="top">
	      <entry>"angle"</entry>
	      <entry>Read-Write</entry>
	      <entry>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.</entry>
	    </row>

	    <row valign="top">
	      <entry>"attributes"</entry>
	      <entry>Read-Write</entry>
	      <entry>A list of Pango style attributes to apply to the text
of the label.</entry>
	    </row>

	    <row valign="top">
	      <entry>"cursor-position"</entry>
	      <entry>Read</entry>
	      <entry>The current position of the insertion cursor in
chars. Allowed values: >= 0. Default value: 0</entry>
	    </row>

	    <row valign="top">
	      <entry>"ellipsize"</entry>
	      <entry>Read-Write</entry>

	      <entry>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 <xref linkend="pango-ellipsize-mode-constants"
endterm="pango-ellipsize-mode-constants-title"></xref>. Note that setting
this property to a value other than <literal>pango.ELLIPSIZE_NONE</literal>
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
<literal>True</literal>. Other means to set a label's width are with the
<link
linkend="method-gtkwidget--set-size-request"><methodname>gtk.Widget.set_size_request</methodname>()</link>
and <link
linkend="method-gtklabel--set-width-chars"><methodname>set_width_chars</methodname>()</link>
methods. Default value: <literal>pango.ELLIPSIZE_NONE</literal>. Available
in GTK+ 2.6 and above.</entry>
	    </row>

	    <row valign="top">
	      <entry>"justify"</entry>
	      <entry>Read-Write</entry>
	      <entry>The alignment of the lines in the text of the label
relative to each other. The possible values are:
<literal>gtk.JUSTIFY_LEFT</literal>, <literal>gtk.JUSTIFY_RIGHT</literal>,
<literal>gtk.JUSTIFY_CENTER</literal>, <literal>gtk.JUSTIFY_FILL</literal>.
This does NOT affect the alignment of the label within its
allocation. Default value: <literal>gtk.JUSTIFY_LEFT</literal></entry>
	    </row>

	    <row valign="top">
	      <entry>"label"</entry>
	      <entry>Read-Write</entry>
	      <entry>The text of the label. Default value:
<literal>None</literal></entry>
	    </row>

	    <row valign="top">
	      <entry>"max-width-chars"</entry>
	      <entry>Read-Write</entry>
	      <entry>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.</entry>
	    </row>

	    <row valign="top">
	      <entry>"mnemonic-keyval"</entry>
	      <entry>Read</entry>
	      <entry>The mnemonic accelerator key for this label. Default
value: 16777215</entry>
	    </row>

	    <row valign="top">
	      <entry>"mnemonic-widget"</entry>
	      <entry>Read-Write</entry>
	      <entry>The widget to be activated when the label's mnemonic
key is pressed.</entry>
	    </row>

	    <row valign="top">
	      <entry>"pattern"</entry>
	      <entry>Write</entry>
	      <entry>A string with _ characters in positions used to
identify to characters in the text to underline. Default value:
<literal>None</literal></entry>
	    </row>

	    <row valign="top">
	      <entry>"selectable"</entry>
	      <entry>Read-Write</entry>
	      <entry>If <literal>True</literal>, the label text can be
selected with the mouse. Default value: <literal>False</literal></entry>
	    </row>

	    <row valign="top">
	      <entry>"selection-bound"</entry>
	      <entry>Read</entry>
	      <entry>The position of the opposite end of the selection from
the cursor in chars. Allowed values: >= 0. Default value: 0.</entry>
	    </row>

	    <row valign="top">
	      <entry>"single-line-mode"</entry>
	      <entry>Read-Write</entry>

	      <entry>If <literal>True</literal> 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:
<literal>False</literal>. Available in GTK+ 2.6 and above.</entry>
	    </row>

	    <row valign="top">
	      <entry>"use-markup"</entry>
	      <entry>Read-Write</entry>
	      <entry>If <literal>True</literal>, the text of the label
includes XML markup. Default value: <literal>False</literal></entry>
	    </row>

	    <row valign="top">
	      <entry>"use-underline"</entry>
	      <entry>Read-Write</entry>
	      <entry>If <literal>True</literal>, an underscore in the text
indicates the next character should be used for the mnemonic accelerator
key. Default value: <literal>False</literal></entry>
	    </row>

	    <row valign="top">
	      <entry>"width-chars"</entry>
	      <entry>Read-Write</entry>

	      <entry>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.</entry>
	    </row>

	    <row valign="top">
	      <entry>"wrap"</entry>
	      <entry>Read-Write</entry>
	      <entry>If <literal>True</literal>, wrap lines if the text
becomes too wide. Default value: <literal>False</literal></entry>
	    </row>

	  </tbody>
	</tgroup>
      </informaltable>
    </blockquote>

  </refsect1>

  <refsect1 id="style-properties-gtklabel">
    <title>gtk.Label Style Properties</title>

    <para><link linkend="style-properties-gtkwidget">gtk.Widget Style Properties</link></para>

  </refsect1>

  <refsect1 id="signal-prototypes-gtklabel">
    <title>gtk.Label Signal Prototypes</title>

    <para><link linkend="signal-prototypes-gobject">gobject.GObject Signal Prototypes</link></para>
    <para><link linkend="signal-prototypes-gtkobject">gtk.Object Signal Prototypes</link></para>
    <para><link linkend="signal-prototypes-gtkwidget">gtk.Widget Signal Prototypes</link></para>

    <variablelist>
      <varlistentry>
        <term>"<link
linkend="signal-gtklabel--copy-clipboard">copy-clipboard</link>"</term>
        <listitem>
          <methodsynopsis
	    language="python"><methodname>callback</methodname>
            <methodparam><parameter>label</parameter>
            </methodparam>
            <methodparam><parameter>user_param1</parameter>
            </methodparam>
            <methodparam><parameter>...</parameter>
            </methodparam>
          </methodsynopsis>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>"<link
linkend="signal-gtklabel--move-cursor">move-cursor</link>"</term>
        <listitem>
          <methodsynopsis
	    language="python"><methodname>callback</methodname>
            <methodparam><parameter>label</parameter>
            </methodparam>
            <methodparam><parameter>step</parameter>
            </methodparam>
            <methodparam><parameter>count</parameter>
            </methodparam>
            <methodparam><parameter>extend_selection</parameter>
            </methodparam>
            <methodparam><parameter>user_param1</parameter>
            </methodparam>
            <methodparam><parameter>...</parameter>
            </methodparam>
          </methodsynopsis>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>"<link
linkend="signal-gtklabel--populate-popup">populate-popup</link>"</term>
        <listitem>
          <methodsynopsis
	    language="python"><methodname>callback</methodname>
            <methodparam><parameter>label</parameter>
            </methodparam>
            <methodparam><parameter>menu</parameter>
            </methodparam>
            <methodparam><parameter>user_param1</parameter>
            </methodparam>
            <methodparam><parameter>...</parameter>
            </methodparam>
          </methodsynopsis>
        </listitem>
      </varlistentry>
    </variablelist>

  </refsect1>

  <refsect1>
    <title>Description</title>

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

    <refsect2>
      <title>Mnemonics</title>

      <para>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 <link
linkend="method-gtklabel--set-text-with-mnemonic"><methodname>set_text_with_mnemonic</methodname>()</link>
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
<link linkend="class-gtkbutton"><classname>gtk.Button</classname></link>; if
the label is not inside an activatable widget, you have to tell the label
about the target using the <link
linkend="method-gtklabel--set-mnemonic-widget"><methodname>set_mnemonic_widget</methodname>()</link>
method. Here's a simple example where the label is inside a button:</para>

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

      <para>As a convenience you can create a button with a mnemonic label
as follows:</para>

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

      <para>To create a mnemonic for a widget alongside the label, such as a
<link linkend="class-gtkentry"><classname>gtk.Entry</classname></link>, you
have to point the label at the entry with the <link
linkend="method-gtklabel--set-mnemonic-widget"><methodname>set_mnemonic_widget</methodname>()</link>
method:</para>

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

    </refsect2>

    <refsect2>
      <title>Markup (styled text)</title>

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

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

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

      <para>Markup strings are just a convenient way to set the <link
linkend="class-pangoattrlist"><classname>pango.AttrList</classname></link>
on a label. Using the <link
linkend="method-gtklabel--set-attributes"><methodname>set_attributes</methodname>()</link>
method may be a simpler way to set attributes in some cases. Be careful
though; <link
linkend="class-pangoattrlist"><classname>pango.AttrList</classname></link>
tends to cause internationalization problems, unless you're applying
attributes to the entire string because specifying the start_index and
end_index for a <link
linkend="class-pangoattribute"><classname>pango.Attribute</classname></link>
requires knowledge of the exact string being displayed, so translations will
cause problems.</para>

    </refsect2>

    <refsect2>
      <title>Selectable labels</title>

      <para>Labels can be made selectable with the <link
linkend="method-gtklabel--set-selectable"><methodname>set_selectable</methodname>()</link>
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.</para>

    </refsect2>

    <refsect2>
      <title>Text layout</title>

      <para>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.</para>

      <para>Labels can automatically wrap text if you call the <link
linkend="method-gtklabel--set-line-wrap"><methodname>set_line_wrap</methodname>()</link>
method.</para>

      <para>The <link
linkend="method-gtklabel--set-justify"><methodname>set_justify</methodname>()</link>
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 <link
linkend="method-gtkmisc--set-alignment"><methodname>gtk.Misc.set_alignment</methodname>()</link>
method.</para>

    </refsect2>

  </refsect1>

  <refsect1 id="constructor-gtklabel">
    <title>Constructor</title>

    <programlisting><constructorsynopsis language="python">
	<methodname>gtk.Label</methodname>
	<methodparam><parameter
		       role="keyword">str</parameter><initializer>None</initializer></methodparam>
      </constructorsynopsis></programlisting>
    <variablelist>
      <varlistentry>
	<term><parameter role="keyword">str</parameter>&nbsp;:</term>
	<listitem><simpara>The text of the label or <literal>None</literal>
for a blank label</simpara></listitem>
      </varlistentry>
      <varlistentry>
	<term><emphasis>Returns</emphasis>&nbsp;:</term>
	<listitem><simpara>the new <link
linkend="class-gtklabel"><classname>gtk.Label</classname></link>
widget</simpara></listitem>
      </varlistentry>
    </variablelist>

    <para>Creates a new <link
linkend="class-gtklabel"><classname>gtk.Label</classname></link> with the
text specified by <parameter>str</parameter> inside it. You can pass
<literal>None</literal> to get a blank label.</para>

  </refsect1>

  <refsect1>
    <title>Methods</title>

    <refsect2 id="method-gtklabel--set-text">
      <title>gtk.Label.set_text</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_text</methodname>
	  <methodparam><parameter
			 role="keyword">str</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">str</parameter>&nbsp;:</term>
	  <listitem><simpara>The new text for the
label.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>set_text</methodname>() method sets the text
within the <link
linkend="class-gtklabel"><classname>gtk.Label</classname></link> widget.  It
replaces any text that was there before and will clear any previously set
mnemonic accelerators.</para>

    </refsect2>

    <refsect2 id="method-gtklabel--get-text">
      <title>gtk.Label.get_text</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_text</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>the text in the label
widget.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>get_text</methodname>() 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
<link
linkend="method-gtklabel--get-label"><methodname>get_label</methodname>()</link>).</para>

    </refsect2>

    <refsect2 id="method-gtklabel--set-attributes">
      <title>gtk.Label.set_attributes</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_attributes</methodname>
	  <methodparam><parameter
			 role="keyword">attrs</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">attrs</parameter>&nbsp;:</term>
	  <listitem><simpara>a <link
linkend="class-pangoattrlist"><classname>pango.AttrList</classname></link></simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>set_attributes</methodname>() method applies a
<link
linkend="class-pangoattrlist"><classname>pango.AttrList</classname></link>
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
<literal>True</literal>.</para>

    </refsect2>

    <refsect2 id="method-gtklabel--get-attributes">
      <title>gtk.Label.get_attributes</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_attributes</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>the attribute list, or <literal>None</literal>
if no attributes were set.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>get_attributes</methodname>() method returns the
attribute list that was set on the label using <link
linkend="method-gtklabel--set-attributes"><methodname>set_attributes</methodname>()</link>, 
if any. This function does not reflect attributes that come from the labels
markup (see <link
linkend="method-gtklabel--set-markup"><methodname>set_markup</methodname>()</link>).</para>

    </refsect2>

    <refsect2 id="method-gtklabel--set-label">
      <title>gtk.Label.set_label</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_label</methodname>
	  <methodparam><parameter
			 role="keyword">str</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">str</parameter>&nbsp;:</term>
	  <listitem><simpara>the new text (including mnemonics or markup) to
set for the label</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>set_label</methodname>() 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.</para>

    </refsect2>

    <refsect2 id="method-gtklabel--get-label">
      <title>gtk.Label.get_label</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_label</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>the text of the label
widget.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>get_label</methodname>() method returns the text
from a label widget including any Pango markup and embedded underscores
indicating mnemonics. (See <link
linkend="method-gtklabel--get-text"><methodname>get_text</methodname>()</link> 
that just returns the text).</para>

    </refsect2>

    <refsect2 id="method-gtklabel--set-markup">
      <title>gtk.Label.set_markup</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_markup</methodname>
	  <methodparam><parameter
			 role="keyword">str</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">str</parameter>&nbsp;:</term>
	  <listitem><simpara>a markup string</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>set_markup</methodname>() method parses
<parameter>str</parameter>, which is marked up with the Pango text markup
language, and sets the label's text and attribute list.</para>

    </refsect2>

    <refsect2 id="method-gtklabel--set-use-markup">
      <title>gtk.Label.set_use_markup</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_use_markup</methodname>
	  <methodparam><parameter
			 role="keyword">setting</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">setting</parameter>&nbsp;:</term>
	  <listitem><simpara>if <literal>True</literal> the label's text
should be parsed for markup.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>set_use_markup</methodname>() method sets the
"use-markup" property to the value of <parameter>setting</parameter>. If
<literal>True</literal> the text of the label should be parsed as
markup.</para>

    </refsect2>

    <refsect2 id="method-gtklabel--get-use-markup">
      <title>gtk.Label.get_use_markup</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_use_markup</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara><literal>True</literal> if the label's text
will be parsed for markup.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>get_user_markup</methodname>() method returns
the value of the "use-markup" property. If <literal>True</literal> the
label's text is parsed as markup. See <link
linkend="method-gtklabel--set-use-markup"><methodname>set_use_markup</methodname>()</link>.</para>

    </refsect2>

    <refsect2 id="method-gtklabel--set-use-underline">
      <title>gtk.Label.set_use_underline</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_use_underline</methodname>
	  <methodparam><parameter
			 role="keyword">setting</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">setting</parameter>&nbsp;:</term>
	  <listitem><simpara>if <literal>True</literal> underscores in the
text indicate mnemonics</simpara></listitem>
	</varlistentry>
      </variablelist>

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

    </refsect2>

    <refsect2 id="method-gtklabel--get-use-underline">
      <title>gtk.Label.get_use_underline</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_use_underline</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara><literal>True</literal> if an embedded
underscore in the label indicates the mnemonic
accelerator.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>get_use_underline</methodname>() method returns
the value of the "use-underline" property. If <literal>True</literal> an
embedded underscore in the label indicates the next character is a mnemonic.
See <link
linkend="method-gtklabel--set-use-underline"><methodname>set_use_underline</methodname>()</link>.</para>

    </refsect2>

    <refsect2 id="method-gtklabel--set-markup-with-mnemonic">
      <title>gtk.Label.set_markup_with_mnemonic</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_markup_with_mnemonic</methodname>
	  <methodparam><parameter
			 role="keyword">str</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">str</parameter>&nbsp;:</term>
	  <listitem><simpara>a markup string including embedded
underscores</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>set_markup_with_mnemonic</methodname>() method
parses <parameter>str</parameter> as markup, setting the label's text and
attribute list based on the parse results. If characters in
<parameter>str</parameter> 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 <link
linkend="method-gtklabel--set-mnemonic-widget"><methodname>set_mnemonic_widget</methodname>()</link> 
method.</para>

    </refsect2>

    <refsect2 id="method-gtklabel--get-mnemonic-keyval">
      <title>gtk.Label.get_mnemonic_keyval</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_mnemonic_keyval</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a keyval, or the void symbol
keyval</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>get_mnemonic_keyval</methodname>() 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.</para>

    </refsect2>

    <refsect2 id="method-gtklabel--set-mnemonic-widget">
      <title>gtk.Label.set_mnemonic_widget</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_mnemonic_widget</methodname>
	  <methodparam><parameter
			 role="keyword">widget</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">widget</parameter>&nbsp;:</term>
	  <listitem><simpara>the widget to be activated when the mnemonic is
pressed</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>set_mnemonic_widget</methodname>() method sets
the "mnemonic-widget" property using the value of
<parameter>widget</parameter>. 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 <link
linkend="class-gtkbutton"><classname>gtk.Button</classname></link> or a
<link linkend="class-gtknotebook"><classname>gtk.Notebook</classname></link>
tab) it is automatically associated with the correct widget, but sometimes
(i.e. when the target is a <link
linkend="class-gtkentry"><classname>gtk.Entry</classname></link> 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.</para>

    </refsect2>

    <refsect2 id="method-gtklabel--get-mnemonic-widget">
      <title>gtk.Label.get_mnemonic_widget</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_mnemonic_widget</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>the target of the label's mnemonic, or
<literal>None</literal> if none has been set and the default algorithm will
be used.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>get_mnemonic_widget</methodname>() method
retrieves the value of the "mnemonic-widget" property which is the target of
the mnemonic accelerator of this label. See <link
linkend="method-gtklabel--set-mnemonic-widget"><methodname>set_mnemonic_widget</methodname>()</link>.</para>

    </refsect2>

    <refsect2 id="method-gtklabel--set-text-with-mnemonic">
      <title>gtk.Label.set_text_with_mnemonic</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_text_with_mnemonic</methodname>
	  <methodparam><parameter
			 role="keyword">str</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">str</parameter>&nbsp;:</term>
	  <listitem><simpara>the label text with embedded underscore
characters indicating the mnemonic characters</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>set_text_with_mnemonic</methodname>() method
sets the label's text from the string <parameter>str</parameter>. If
characters in <parameter>str</parameter> 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 <link
linkend="method-gtklabel--set-mnemonic-widget"><methodname>set_mnemonic_widget</methodname>()</link> 
method.</para>

    </refsect2>

    <refsect2 id="method-gtklabel--set-justify">
      <title>gtk.Label.set_justify</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_justify</methodname>
	  <methodparam><parameter
			 role="keyword">jtype</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">jtype</parameter>&nbsp;:</term>
	  <listitem><simpara>justification type</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>set_justify</methodname>() method sets the
alignment of the lines in the text of the label relative to each other using
the value of <parameter>jtype</parameter>. The possible values of
<parameter>jtype</parameter> are: <literal>gtk.JUSTIFY_LEFT</literal>,
<literal>gtk.JUSTIFY_RIGHT</literal>, <literal>gtk.JUSTIFY_CENTER</literal>
and <literal>gtk.JUSTIFY_FILL</literal>. <literal>gtk.JUSTIFY_LEFT</literal>
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 <link
linkend="method-gtkmisc--set-alignment"><methodname>gtk.Misc.set_alignment</methodname>()</link> 
method instead. The <link
linkend="method-gtklabel--set-justify"><methodname>set_justify</methodname>()</link> 
has no effect on labels containing only a single line.</para>

    </refsect2>

    <refsect2 id="method-gtklabel--get-justify">
      <title>gtk.Label.get_justify</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_justify</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>the label justification</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>get_justify</methodname>() method returns the
justification of the label; one of: <literal>gtk.JUSTIFY_LEFT</literal>,
<literal>gtk.JUSTIFY_RIGHT</literal>, <literal>gtk.JUSTIFY_CENTER</literal>
or <literal>gtk.JUSTIFY_FILL</literal>. See <link
linkend="method-gtklabel--set-justify"><methodname>set_justify</methodname>()</link>.</para>

    </refsect2>

    <refsect2 id="method-gtklabel--set-pattern">
      <title>gtk.Label.set_pattern</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_pattern</methodname>
	  <methodparam><parameter
			 role="keyword">pattern</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">pattern</parameter>&nbsp;:</term>
	  <listitem><simpara>the pattern of underlines</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>set_pattern</methodname>() method sets the
"pattern" property with the value of <parameter>pattern</parameter>. 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.</para>

    </refsect2>

    <refsect2 id="method-gtklabel--set-line-wrap">
      <title>gtk.Label.set_line_wrap</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_line_wrap</methodname>
	  <methodparam><parameter
			 role="keyword">wrap</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">wrap</parameter>&nbsp;:</term>
	  <listitem><simpara>if True the label lines will wrap if too big
for the widget size.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>set_wrap</methodname>() method sets the "wrap"
property tot he value of <parameter>wrap</parameter>. If
<parameter>wrap</parameter> is <literal>True</literal> 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.</para>

    </refsect2>

    <refsect2 id="method-gtklabel--get-line-wrap">
      <title>gtk.Label.get_line_wrap</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_line_wrap</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara><literal>True</literal> if the lines of the
label are automatically wrapped.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>get_line_wrap</methodname>() method returns the
value of the "wrap" property. If "wrap" is <literal>True</literal> the lines
in the label are automatically wrapped. See <link
linkend="method-gtklabel--set-line-wrap"><methodname>set_line_wrap</methodname>()</link>.</para>

    </refsect2>

    <refsect2 id="method-gtklabel--set-selectable">
      <title>gtk.Label.set_selectable</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_selectable</methodname>
	  <methodparam><parameter
			 role="keyword">setting</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">setting</parameter>&nbsp;:</term>
	  <listitem><simpara>if <literal>True</literal> allow the text in
the label to be selected</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>set_selectable</methodname>() method sets the
"selectable" property with the value of <parameter>setting</parameter>. If
<parameter>setting</parameter> is <literal>True</literal> the user is
allowed to select text from the label, for copy-and-paste.</para>

    </refsect2>

    <refsect2 id="method-gtklabel--get-selectable">
      <title>gtk.Label.get_selectable</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_selectable</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara><literal>True</literal> if the user can select
the label text</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>get_selectable</methodname>() method gets the
value of the "selectable" property set by the <link
linkend="method-gtklabel--set-selectable"><methodname>set_selectable</methodname>()</link> 
method.</para>

    </refsect2>

    <refsect2 id="method-gtklabel--select-region">
      <title>gtk.Label.select_region</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>select_region</methodname>
	  <methodparam><parameter
			 role="keyword">start_offset</parameter></methodparam>
	  <methodparam><parameter
			 role="keyword">end_offset</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter
role="keyword">start_offset</parameter>&nbsp;:</term>
	  <listitem><simpara>start offset in characters</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter
role="keyword">end_offset</parameter>&nbsp;:</term>
	  <listitem><simpara>end offset in characters</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>select_region</methodname>() method selects a
range of characters in the label, if the label is selectable. The selected
region is the range of characters between
<parameter>start_offset</parameter> and <parameter>end_offset</parameter>.
See <link
linkend="method-gtklabel--set-selectable"><methodname>set_selectable</methodname>()</link>. 
If the label is not selectable, this method has no effect. If
<parameter>start_offset</parameter> or <parameter>end_offset</parameter> are
-1, then the end of the label will be substituted.</para>

    </refsect2>

    <refsect2 id="method-gtklabel--get-selection-bounds">
      <title>gtk.Label.get_selection_bounds</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_selection_bounds</methodname>
	  <methodparam></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a tuple containing the start and end character
offsets of the selection</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>get_selection_bounds</methodname>() 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.</para>

    </refsect2>

    <refsect2 id="method-gtklabel--get-layout">
      <title>gtk.Label.get_layout</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_layout</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>the <link
linkend="class-pangolayout"><classname>pango.Layout</classname></link> for
this label</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>get_layout</methodname>() method returns the
<link linkend="class-pangolayout"><classname>pango.Layout</classname></link>
used to display the label. The layout is useful to e.g. convert text
positions to pixel positions, in combination with <link
linkend="method-gtklabel--get-layout-offsets"><methodname>get_layout_offsets</methodname>()</link>.</para>

    </refsect2>

    <refsect2 id="method-gtklabel--get-layout-offsets">
      <title>gtk.Label.get_layout_offsets</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_layout_offsets</methodname>
	  <methodparam></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a tuple containing the  X offset of the layout,
or <literal>None</literal> and the Y offset of layout, or
<literal>None</literal></simpara></listitem>
	</varlistentry>
      </variablelist>

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

    </refsect2>

    <refsect2 id="method-gtklabel--set-ellipsize">
      <title>gtk.Label.set_ellipsize</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_ellipsize</methodname>
	  <methodparam><parameter
			 role="keyword">mode</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">mode</parameter>&nbsp;:</term>
	  <listitem><simpara>one of the <xref
	  linkend="pango-ellipsize-mode-constants"
	  endterm="pango-ellipsize-mode-constants-title"></xref> to
	  use</simpara></listitem>
	</varlistentry>
      </variablelist>

      <note>
        <para>This method is available in PyGTK 2.6 and above.</para>
      </note>

      <para>The <methodname>set_ellipsize</methodname>() method sets the
"ellipsize" property to the value of
<parameter>mode</parameter>. <parameter>mode</parameter> should be one of
the <xref linkend="pango-ellipsize-mode-constants"
endterm="pango-ellipsize-mode-constants-title"></xref>. The "ellipsize"
property specifies if and where an ellipse should be used if there is not
enough room for the label text.</para>

    </refsect2>

    <refsect2 id="method-gtklabel--get-ellipsize">
      <title>gtk.Label.get_ellipsize</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_ellipsize</methodname>
	  <methodparam></methodparam>
        </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>the current ellipsize mode</simpara></listitem>
	</varlistentry>
      </variablelist>

      <note>
        <para>This method is available in PyGTK 2.6 and above.</para>
      </note>

      <para>The <methodname>get_ellipsize</methodname>() method returns the
value of the "ellipsize" property which contains one of the <xref
linkend="pango-ellipsize-mode-constants"
endterm="pango-ellipsize-mode-constants-title"></xref>. The "ellipsize"
property specifies if and where an ellipse should be used if there is not
enough room for the label text.</para>

    </refsect2>

    <refsect2 id="method-gtklabel--set-width-chars">
      <title>gtk.Label.set_width_chars</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_width_chars</methodname>
	  <methodparam><parameter
			 role="keyword">n_chars</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">n_chars</parameter>&nbsp;:</term>
	  <listitem><simpara> the new desired width, in
characters.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <note>
        <para>This method is available in PyGTK 2.6 and above.</para>
      </note>

      <para>The <methodname>set_width_chars</methodname>() method sets the
"width-chars" property to the value of <parameter>n_chars</parameter>. The
"width-chars" property specifies the desired width of the label in
characters.</para>

    </refsect2>

    <refsect2 id="method-gtklabel--get-width-chars">
      <title>gtk.Label.get_width_chars</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_width_chars</methodname>
	  <methodparam></methodparam>
        </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>the desired width of the label in
characters.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <note>
        <para>This method is available in PyGTK 2.6 and above.</para>
      </note>

      <para>The <methodname>get_width_chars</methodname>() method returns
the value of the "width-chars" property that specifies the desired width of
the label in characters.</para>

    </refsect2>

    <refsect2 id="method-gtklabel--set-single-line-mode">
      <title>gtk.Label.set_single_line_mode</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_single_line_mode</methodname>
	  <methodparam><parameter
			 role="keyword">single_line_mode</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">single_line_mode</parameter>&nbsp;:</term>
	  <listitem><simpara>if <literal>True</literal> the label is in
single line mode.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <note>
        <para>This method is available in PyGTK 2.6 and above.</para>
      </note>

      <para>The <methodname>set_single_line_mode</methodname>() method sets
the "single-line-mode" property to the value of
<parameter>single_line_mode</parameter>. If
<parameter>single_line_mode</parameter> is <literal>True</literal> 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.</para>

    </refsect2>

    <refsect2 id="method-gtklabel--get-single-line-mode">
      <title>gtk.Label.get_single_line_mode</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_single_line_mode</methodname>
	  <methodparam></methodparam>
        </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara></simpara></listitem>
	</varlistentry>
      </variablelist>

      <note>
        <para>This method is available in PyGTK 2.6 and above.</para>
      </note>

      <para>The <methodname>get_single_line_mode</methodname>() method
returns the value of the "single-line-mode" property. See the <link
linkend="method-gtklabel--set-single-line-mode"><methodname>set_single_line_mode</methodname>()</link>
method for more information.</para>

    </refsect2>

    <refsect2 id="method-gtklabel--set-max-width-chars">
      <title>gtk.Label.set_max_width_chars</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_max_width_chars</methodname>
	  <methodparam><parameter
			 role="keyword">n_chars</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">n_chars</parameter>&nbsp;:</term>
	  <listitem><simpara> the new desired maximum width, in
characters.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <note>
        <para>This method is available in PyGTK 2.6 and above.</para>
      </note>

      <para>The <methodname>set_max_width_chars</methodname>() method sets
the "max-width-chars" property to the value of
<parameter>n_chars</parameter>.</para>

    </refsect2>

    <refsect2 id="method-gtklabel--get-max-width-chars">
      <title>gtk.Label.get_max_width_chars</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_max_width_chars</methodname>
	  <methodparam></methodparam>
        </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara></simpara></listitem>
	</varlistentry>
      </variablelist>

      <note>
        <para>This method is available in PyGTK 2.6 and above.</para>
      </note>

      <para>The <methodname>get_max_width_chars</methodname>() method
returns the value of the "max-width-chars" property which is the desired
maximum width of the label in characters.</para>

    </refsect2>

    <refsect2 id="method-gtklabel--set-angle">
      <title>gtk.Label.set_angle</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_angle</methodname>
	  <methodparam><parameter
			 role="keyword">angle</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">angle</parameter>&nbsp;:</term>
	  <listitem><simpara> the angle that the baseline of the label makes
with the horizontal, in degrees, measured counterclockwise</simpara></listitem>
	</varlistentry>
      </variablelist>

      <note>
        <para>This method is available in PyGTK 2.6 and above.</para>
      </note>

      <para>The <methodname>set_angle</methodname>() method sets the "angle"
property to the value of
<parameter>angle</parameter>. <parameter>angle</parameter> 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.</para>

    </refsect2>

    <refsect2 id="method-gtklabel--get-angle">
      <title>gtk.Label.get_angle</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_angle</methodname>
	  <methodparam></methodparam>
        </methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara></simpara></listitem>
	</varlistentry>
      </variablelist>

      <note>
        <para>This method is available in PyGTK 2.6 and above.</para>
      </note>

      <para>The <methodname>get_angle</methodname>() method returns the
value of the "angle" property. See the <link
linkend="method-gtklabel--set-angle"><methodname>set_angle</methodname>()</link>
method for more information.</para>

    </refsect2>

  </refsect1>

  <refsect1>
    <title>Signals</title>

    <refsect2 id="signal-gtklabel--copy-clipboard">
      <title>The "copy-clipboard" gtk.Label Signal</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>callback</methodname>
	  <methodparam><parameter>label</parameter></methodparam>
	  <methodparam><parameter>user_param1</parameter></methodparam>
	  <methodparam><parameter>...</parameter></methodparam>
	</methodsynopsis></programlisting>

      <variablelist>
	<varlistentry>
	  <term><parameter>label</parameter>&nbsp;:</term>
	  <listitem><simpara>the label that received the
signal</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>user_param1</parameter>&nbsp;:</term>
          <listitem><simpara>the first user parameter (if any) specified
with the <link
linkend="method-gobject--connect"><methodname>connect</methodname>()</link>
method</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>...</parameter>&nbsp;:</term>
	  <listitem><simpara>additional user parameters (if
any)</simpara></listitem>
	</varlistentry>
      </variablelist>

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

    </refsect2>

    <refsect2 id="signal-gtklabel--move-cursor">
      <title>The "move-cursor" gtk.Label Signal</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>callback</methodname>
	  <methodparam><parameter>label</parameter></methodparam>
	  <methodparam><parameter>step</parameter></methodparam>
	  <methodparam><parameter>count</parameter></methodparam>
	  <methodparam><parameter>extend_selection</parameter></methodparam>
	  <methodparam><parameter>user_param1</parameter></methodparam>
	  <methodparam><parameter>...</parameter></methodparam>
	</methodsynopsis></programlisting>

      <variablelist>
	<varlistentry>
	  <term><parameter>label</parameter>&nbsp;:</term>
	  <listitem><simpara>the label that received the
signal</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>step</parameter>&nbsp;:</term>
	  <listitem><simpara>the step size of the move:
<literal>gtk.MOVEMENT_LOGICAL_POSITIONS</literal>,
<literal>gtk.MOVEMENT_VISUAL_POSITIONS</literal>,
<literal>gtk.MOVEMENT_WORDS</literal>,
<literal>gtk.MOVEMENT_DISPLAY_LINES</literal>,
<literal>gtk.MOVEMENT_DISPLAY_LINE_ENDS</literal>,
<literal>gtk.MOVEMENT_PARAGRAPHS</literal>,
<literal>gtk.MOVEMENT_PARAGRAPH_ENDS</literal>,
<literal>gtk.MOVEMENT_PAGES</literal> and
<literal>gtk.MOVEMENT_BUFFER_ENDS</literal></simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>count</parameter>&nbsp;:</term>
	  <listitem><simpara>the number of steps to
take</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>extend_selection</parameter>&nbsp;:</term>
	  <listitem><simpara>if <literal>True</literal> extend the range of
	  the selection</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>user_param1</parameter>&nbsp;:</term>
          <listitem><simpara>the first user parameter (if any) specified
with the <link
linkend="method-gobject--connect"><methodname>connect</methodname>()</link>
method</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>...</parameter>&nbsp;:</term>
	  <listitem><simpara>additional user parameters (if
any)</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The "move-cursor" signal is emitted when the cursor is being
moved <parameter>count</parameter> steps or size <literal>step</literal>.
The step size is one of:</para>

      <programlisting>
  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
</programlisting>

      <para>If <parameter>extend_selection</parameter> is
<literal>True</literal> the selection will be extended to include the text
moved over.</para>

    </refsect2>

    <refsect2 id="signal-gtklabel--populate-popup">
      <title>The "populate-popup" gtk.Label Signal</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>callback</methodname>
	  <methodparam><parameter>label</parameter></methodparam>
	  <methodparam><parameter>menu</parameter></methodparam>
	  <methodparam><parameter>user_param1</parameter></methodparam>
	  <methodparam><parameter>...</parameter></methodparam>
	</methodsynopsis></programlisting>

      <variablelist>
	<varlistentry>
	  <term><parameter>label</parameter>&nbsp;:</term>
	  <listitem><simpara>the label that received the
signal</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>menu</parameter>&nbsp;:</term>
	  <listitem><simpara>the menu to be populated</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>user_param1</parameter>&nbsp;:</term>
          <listitem><simpara>the first user parameter (if any) specified
with the <link
linkend="method-gobject--connect"><methodname>connect</methodname>()</link>
method</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>...</parameter>&nbsp;:</term>
	  <listitem><simpara>additional user parameters (if
any)</simpara></listitem>
	</varlistentry>
      </variablelist>

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

    </refsect2>

  </refsect1>

</refentry>