GtkLabel
<!-- ##### SECTION Short_Description ##### -->
-A widget that displays a small to medium amount of text.
+A widget that displays a small to medium amount of text
<!-- ##### SECTION Long_Description ##### -->
-<para>\r
-The #GtkLabel widget is usually used directly by the programmer to display\r
-word(s) describing an adjacent widget or its use. It is also used internally\r
-by Gtk+ as #GtkButton labels, #GtkMenu items, and many other widgets which\r
-use text.\r
+<para>
+The #GtkLabel widget displays a small amount of text. As the name
+implies, most labels are used to label another widget such as a
+#GtkButton, a #GtkMenuItem, or a #GtkOptionMenu.
+</para>
+
+<refsect2 id="GtkLabel-BUILDER-UI">
+<title>GtkLabel as GtkBuildable</title>
+<para>
+The GtkLabel implementation of the GtkBuildable interface supports a
+custom <attributes> element, which supports any number of <attribute>
+elements. the <attribute> element has attributes named name, value,
+start and end and allows you to specify #PangoAttribute values for this label.
+</para>
+<example>
+<title>A UI definition fragment specifying Pango attributes</title>
+<programlisting><![CDATA[
+<object class="GtkLabel">
+ <attributes>
+ <attribute name="weight" value="PANGO_WEIGHT_BOLD"/>
+ <attribute name="background" value="red" start="5" end="10"/>"
+ </attributes>
+</object>
+]]></programlisting>
+</example>
+<para>
+The start and end attributes specify the range of characters to which the
+Pango attribute applies. If start and end are not specified, the attribute is
+applied to the whole text. Note that specifying ranges does not make much
+sense with translatable attributes. Use markup embedded in the translatable
+content instead.
+</para>
+</refsect2>
+
+
+<refsect2>
+<title>Mnemonics</title>
+
+<para>
+Labels may contain <firstterm>mnemonics</firstterm>. Mnemonics are
+underlined characters in the label, used for keyboard navigation.
+Mnemonics are created by providing a string with an underscore before
+the mnemonic character, such as <literal>"_File"</literal>, to the
+functions gtk_label_new_with_mnemonic() or
+gtk_label_set_text_with_mnemonic().
+</para>
+
+<para>
+Mnemonics automatically activate any activatable widget the label is
+inside, such as a #GtkButton; if the label is not inside the
+mnemonic's target widget, you have to tell the label about the target
+using gtk_label_set_mnemonic_widget(). Here's a simple example where
+the label is inside a button:
+
+<informalexample>
+<programlisting>
+ /* Pressing Alt+H will activate this button */
+ button = gtk_button_new (<!-- -->);
+ label = gtk_label_new_with_mnemonic ("_Hello");
+ gtk_container_add (GTK_CONTAINER (button), label);
+</programlisting>
+</informalexample>
+There's a convenience function to create buttons with a mnemonic label
+already inside:
+
+<informalexample>
+<programlisting>
+ /* Pressing Alt+H will activate this button */
+ button = gtk_button_new_with_mnemonic ("_Hello");
+</programlisting>
+</informalexample>
+
+To create a mnemonic for a widget alongside the label, such as a
+#GtkEntry, you have to point the label at the entry with
+gtk_label_set_mnemonic_widget():
+<informalexample>
+<programlisting>
+ /* Pressing Alt+H will focus the entry */
+ entry = gtk_entry_new (<!-- -->);
+ label = gtk_label_new_with_mnemonic ("_Hello");
+ gtk_label_set_mnemonic_widget (GTK_LABEL (label), entry);
+</programlisting>
+</informalexample>
+
</para>
+</refsect2>
+
+<refsect2>
+<title>Markup (styled text)</title>
+
+<para>
+To make it easy to format text in a label (changing colors, fonts,
+etc.), label text can be provided in a simple <link
+linkend="PangoMarkupFormat">markup format</link>.
+Here's how to create a label with a small font:
+<informalexample>
+<programlisting>
+ label = gtk_label_new (NULL);
+ gtk_label_set_markup (GTK_LABEL (label), "<small>Small text</small>");
+</programlisting>
+</informalexample>
+(See <link
+linkend="PangoMarkupFormat">complete documentation</link> of available
+tags in the Pango manual.)
+</para>
+<para>
+The markup passed to gtk_label_set_markup() must be valid; for example,
+literal </>/& characters must be escaped as &lt;,
+&gt;, and &amp;. If you pass text obtained from the user, file,
+or a network to gtk_label_set_markup(), you'll want to escape it with
+g_markup_escape_text() or g_markup_printf_escaped().
+</para>
+<para>
+Markup strings are just a convenient way to set the #PangoAttrList on
+a label; gtk_label_set_attributes() may be a simpler way to set
+attributes in some cases. Be careful though; #PangoAttrList tends to
+cause internationalization problems, unless you're applying attributes
+to the entire string (i.e. unless you set the range of each attribute
+to [0, G_MAXINT)). The reason is that specifying the start_index and
+end_index for a #PangoAttribute 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 gtk_label_set_selectable().
+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 id="label-text-layout">
+<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
+gtk_label_set_line_wrap().
+</para>
+<para>
+gtk_label_set_justify() 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 gtk_misc_set_alignment().
+</para>
+<para>
+The #GtkLabel:width-chars and #GtkLabel:max-width-chars properties
+can be used to control the size allocation of ellipsized or wrapped
+labels. For ellipsizing labels, if either is specified (and less
+than the actual text size), it is used as the minimum width, and the actual
+text size is used as the natural width of the label. For wrapping labels,
+width-chars is used as the minimum width, if specified, and max-width-chars
+is used as the natural width. Even if max-width-chars specified, wrapping
+labels will be rewrapped to use all of the available width.
+</para>
+<note><para>Note that the interpretation of #GtkLabel:width-chars and
+#GtkLabel:max-width-chars has changed a bit with the introduction of
+width-for-height geometry management and #GtkExtendedLayout.</para></note>
+</refsect2>
+
+<refsect2>
+<title>Links</title>
+
+<para>
+Since 2.18, GTK+ supports markup for clickable hyperlinks in addition
+to regular Pango markup. The markup for links is borrowed from HTML, using the
+<tag>a</tag> with href and title attributes. GTK+ renders links similar to the
+way they appear in web browsers, with colored, underlined text. The title
+attribute is displayed as a tooltip on the link. An example looks like this:
+<informalexample><programlisting>
+gtk_label_set_markup (label, "Go to the <a href=\"http://www.gtk.org\" title=\"&lt;i&gt;Our&/i&gt; website\">GTK+ website</a> for more...");
+</programlisting></informalexample>
+It is possible to implement custom handling for links and their tooltips with
+the #GtkLabel::activate-link signal and the gtk_label_get_current_uri() function.
+</para>
+
+</refsect2>
+
<!-- ##### SECTION See_Also ##### -->
-<para>\r
-\r
+<para>
+
</para>
+<!-- ##### SECTION Stability_Level ##### -->
+
+
+<!-- ##### SECTION Image ##### -->
+
+
<!-- ##### STRUCT GtkLabel ##### -->
-<para>\r
-This should not be accessed directly. Use the accessor functions as\r
-described below.\r
+<para>
+This should not be accessed directly. Use the accessor functions as
+described below.
+</para>
+
+
+<!-- ##### SIGNAL GtkLabel::activate-current-link ##### -->
+<para>
+
+</para>
+
+@label: the object which received the signal.
+
+<!-- ##### SIGNAL GtkLabel::activate-link ##### -->
+<para>
+
+</para>
+
+@label: the object which received the signal.
+@arg1:
+@Returns:
+
+<!-- ##### SIGNAL GtkLabel::copy-clipboard ##### -->
+<para>
+
+</para>
+
+@label: the object which received the signal.
+
+<!-- ##### SIGNAL GtkLabel::move-cursor ##### -->
+<para>
+
+</para>
+
+@label: the object which received the signal.
+@arg1:
+@arg2:
+@arg3:
+
+<!-- ##### SIGNAL GtkLabel::populate-popup ##### -->
+<para>
+
+</para>
+
+@label: the object which received the signal.
+@arg1:
+
+<!-- ##### ARG GtkLabel:angle ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GtkLabel:attributes ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GtkLabel:cursor-position ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GtkLabel:ellipsize ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GtkLabel:justify ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GtkLabel:label ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GtkLabel:max-width-chars ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GtkLabel:mnemonic-keyval ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GtkLabel:mnemonic-widget ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GtkLabel:pattern ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GtkLabel:selectable ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GtkLabel:selection-bound ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GtkLabel:single-line-mode ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GtkLabel:track-visited-links ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GtkLabel:use-markup ##### -->
+<para>
+
</para>
+<!-- ##### ARG GtkLabel:use-underline ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GtkLabel:width-chars ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GtkLabel:wrap ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GtkLabel:wrap-mode ##### -->
+<para>
+
+</para>
<!-- ##### FUNCTION gtk_label_new ##### -->
-<para>\r
-Creates a new label with the given string of text inside it. You can\r
-pass NULL to get an empty label widget.\r
+<para>
+
</para>
-@str: The string you want to display in the #GtkLabel
-@Returns: The newly allocated #GtkLabel widget
+@str:
+@Returns:
<!-- ##### FUNCTION gtk_label_set_text ##### -->
-<para>\r
-Sets the text within the #GtkLabel widget. It overwrites any text that\r
-was there before. Note that underlines that were there before do not\r
-get overwritten. If you want to erase underlines just send NULL to\r
-gtk_label_set_pattern().\r
+<para>
+
</para>
-@label: The #GtkLabel you want to set the text for.
-@str: The text you want to add.
+@label:
+@str:
<!-- ##### FUNCTION gtk_label_set_attributes ##### -->
<!-- ##### FUNCTION gtk_label_set_pattern ##### -->
-<para>\r
-The pattern of underlines you want under the existing text within the\r
-#GtkLabel widget. For example if the current text of the label says\r
-"FooBarBaz" passing a pattern of "___ ___" will underline\r
-"Foo" and "Baz" but not "Bar".\r
+<para>
+The pattern of underlines you want under the existing text within the
+#GtkLabel widget. For example if the current text of the label says
+"FooBarBaz" passing a pattern of "___ ___" will underline
+"Foo" and "Baz" but not "Bar".
</para>
@label: The #GtkLabel you want to set the pattern to.
<!-- ##### FUNCTION gtk_label_set_justify ##### -->
-<para>\r
-Set where the text within the #GtkLabel will align to. This can be one of\r
-four values: GTK_JUSTIFY_LEFT, GTK_JUSTIFY_RIGHT, GTK_JUSTIFY_CENTER,\r
-and GTK_JUSTIFY_FILL. GTK_JUSTIFY_CENTER is the default value when the\r
-widget is first created with gtk_label_new().\r
+<para>
+
</para>
-@label: The #GtkLabel widget you want to set justification for.
-@jtype: The #GtkJustification type as described above.
+@label:
+@jtype:
-<!-- ##### FUNCTION gtk_label_get ##### -->
-<para>\r
-Gets the current string of text within the #GtkLabel and writes it to\r
-the given str argument. It does not make a copy of this string so you\r
-must not write to it.\r
+<!-- ##### FUNCTION gtk_label_set_ellipsize ##### -->
+<para>
+
+</para>
+
+@label:
+@mode:
+
+
+<!-- ##### FUNCTION gtk_label_set_width_chars ##### -->
+<para>
+
</para>
-@label: The #GtkLabel widget you want to get the text from.
-@str: The reference to the pointer you want to point to the text.
+@label:
+@n_chars:
+
+<!-- ##### FUNCTION gtk_label_set_max_width_chars ##### -->
+<para>
-<!-- ##### FUNCTION gtk_label_parse_uline ##### -->
-<para>\r
-Parses the given string for underscores and converts the next\r
-character to an underlined character. The last character that\r
-was underlined will have its lower-cased accelerator keyval returned (i.e.\r
-"_File" would return the keyval for "f". This is\r
-probably only used within the Gtk+ library itself for menu items and such.\r
</para>
-@label: The #GtkLabel you want to affect.
-@string: The string you want to parse for underlines.
-@Returns: The lowercase keyval of the last character underlined.
+@label:
+@n_chars:
<!-- ##### FUNCTION gtk_label_set_line_wrap ##### -->
-<para>\r
-Toggles line wrapping within the #GtkLabel widget. TRUE makes it break\r
-lines if text exceeds the widget's size. FALSE lets the text get cut off\r
-by the edge of the widget if it exceeds the widget size.\r
+<para>
+
</para>
-@label: The #GtkLabel you want to set line wrapping for.
-@wrap: TRUE turns it on; FALSE turns it off.
+@label:
+@wrap:
+
+<!-- ##### FUNCTION gtk_label_set_line_wrap_mode ##### -->
+<para>
-<!-- ##### MACRO gtk_label_set ##### -->
-<para>\r
-Aliases gtk_label_set_text. Probably used for backward compatibility with\r
-Gtk+ 1.0.x.\r
</para>
+@label:
+@wrap_mode:
<!-- ##### FUNCTION gtk_label_get_layout_offsets ##### -->
@label:
@str:
-<!-- # Unused Parameters # -->
-@string:
<!-- ##### FUNCTION gtk_label_get_attributes ##### -->
@Returns:
-<!-- ##### FUNCTION gtk_label_get_label ##### -->
+<!-- ##### FUNCTION gtk_label_get_ellipsize ##### -->
<para>
</para>
@Returns:
-<!-- ##### FUNCTION gtk_label_get_layout ##### -->
+<!-- ##### FUNCTION gtk_label_get_width_chars ##### -->
<para>
</para>
@Returns:
-<!-- ##### FUNCTION gtk_label_get_line_wrap ##### -->
+<!-- ##### FUNCTION gtk_label_get_max_width_chars ##### -->
<para>
</para>
@Returns:
-<!-- ##### FUNCTION gtk_label_get_mnemonic_widget ##### -->
+<!-- ##### FUNCTION gtk_label_get_label ##### -->
<para>
</para>
@Returns:
-<!-- ##### FUNCTION gtk_label_get_selection_bounds ##### -->
+<!-- ##### FUNCTION gtk_label_get_layout ##### -->
<para>
</para>
@label:
-@start:
-@end:
@Returns:
-<!-- ##### FUNCTION gtk_label_get_use_markup ##### -->
+<!-- ##### FUNCTION gtk_label_get_line_wrap ##### -->
<para>
</para>
@Returns:
-<!-- ##### FUNCTION gtk_label_get_use_underline ##### -->
+<!-- ##### FUNCTION gtk_label_get_line_wrap_mode ##### -->
<para>
</para>
@Returns:
-<!-- ##### FUNCTION gtk_label_set_label ##### -->
+<!-- ##### FUNCTION gtk_label_get_mnemonic_widget ##### -->
<para>
</para>
@label:
-@str:
+@Returns:
-<!-- ##### FUNCTION gtk_label_set_use_markup ##### -->
+<!-- ##### FUNCTION gtk_label_get_selection_bounds ##### -->
<para>
</para>
@label:
-@setting:
+@start:
+@end:
+@Returns:
-<!-- ##### FUNCTION gtk_label_set_use_underline ##### -->
+<!-- ##### FUNCTION gtk_label_get_use_markup ##### -->
<para>
</para>
@label:
-@setting:
+@Returns:
-<!-- ##### SIGNAL GtkLabel::copy-clipboard ##### -->
+<!-- ##### FUNCTION gtk_label_get_use_underline ##### -->
<para>
</para>
-@label: the object which received the signal.
+@label:
+@Returns:
-<!-- ##### SIGNAL GtkLabel::move-cursor ##### -->
+
+<!-- ##### FUNCTION gtk_label_get_single_line_mode ##### -->
<para>
</para>
-@label: the object which received the signal.
-@arg1:
-@arg2:
-@arg3:
+@label:
+@Returns:
-<!-- ##### SIGNAL GtkLabel::populate-popup ##### -->
+
+<!-- ##### FUNCTION gtk_label_get_angle ##### -->
<para>
</para>
-@label: the object which received the signal.
-@arg1:
+@label:
+@Returns:
-<!-- ##### ARG GtkLabel:label ##### -->
-<para>\r
-The actual label text. Do not write to this pointer, it is not copied.\r
-</para>
-<!-- ##### ARG GtkLabel:attributes ##### -->
+<!-- ##### FUNCTION gtk_label_set_label ##### -->
<para>
</para>
-<!-- ##### ARG GtkLabel:use-markup ##### -->
-<para>
+@label:
+@str:
-</para>
-<!-- ##### ARG GtkLabel:use-underline ##### -->
+<!-- ##### FUNCTION gtk_label_set_use_markup ##### -->
<para>
</para>
-<!-- ##### ARG GtkLabel:justify ##### -->
-<para>\r
-The #GtkJustification setting. See gtk_label_set_justify() for more info.\r
-</para>
+@label:
+@setting:
-<!-- ##### ARG GtkLabel:pattern ##### -->
-<para>\r
-The pattern of underlines under the existing text. Do not change the\r
-pointer, it isn't copied.\r
-</para>
-<!-- ##### ARG GtkLabel:wrap ##### -->
+<!-- ##### FUNCTION gtk_label_set_use_underline ##### -->
<para>
</para>
-<!-- ##### ARG GtkLabel:selectable ##### -->
+@label:
+@setting:
+
+
+<!-- ##### FUNCTION gtk_label_set_single_line_mode ##### -->
<para>
</para>
-<!-- ##### ARG GtkLabel:mnemonic-keyval ##### -->
+@label:
+@single_line_mode:
+
+
+<!-- ##### FUNCTION gtk_label_set_angle ##### -->
<para>
</para>
-<!-- ##### ARG GtkLabel:mnemonic-widget ##### -->
+@label:
+@angle:
+
+
+<!-- ##### FUNCTION gtk_label_get_current_uri ##### -->
<para>
</para>
-<!-- ##### ARG GtkLabel:cursor-position ##### -->
+@label:
+@Returns:
+
+
+<!-- ##### FUNCTION gtk_label_set_track_visited_links ##### -->
<para>
</para>
-<!-- ##### ARG GtkLabel:selection-bound ##### -->
+@label:
+@track_links:
+
+
+<!-- ##### FUNCTION gtk_label_get_track_visited_links ##### -->
<para>
</para>
+@label:
+@Returns:
+
+
projects / ~andy / gtk / blobdiff