[gtk+] Move documentation to inline comments: GtkLabel

[Javier Jardón <jjardon src gnome org>]

commit c1e8577a66a2302956afc0ebe7925f89ef39b5ce
Author: Javier Jardón <jjardon gnome org>
Date:   Thu Apr 14 22:50:45 2011 +0100

    Move documentation to inline comments: GtkLabel

 docs/reference/gtk/tmpl/.gitignore    |    1 +
 docs/reference/gtk/tmpl/gtklabel.sgml |  751 ---------------------------------
 gtk/gtklabel.c                        |  188 ++++++++
 3 files changed, 189 insertions(+), 751 deletions(-)
---
diff --git a/docs/reference/gtk/tmpl/.gitignore b/docs/reference/gtk/tmpl/.gitignore
index 5417f73..0c37085 100644
--- a/docs/reference/gtk/tmpl/.gitignore
+++ b/docs/reference/gtk/tmpl/.gitignore
@@ -61,6 +61,7 @@ gtkimcontextsimple.sgml
 gtkimmulticontext.sgml
 gtkinvisible.sgml
 gtkitemfactory.sgml
+gtklabel.sgml
 gtklayout.sgml
 gtklinkbutton.sgml
 gtkliststore.sgml
diff --git a/gtk/gtklabel.c b/gtk/gtklabel.c
index 04bf4ff..23ae223 100644
--- a/gtk/gtklabel.c
+++ b/gtk/gtklabel.c
@@ -52,6 +52,184 @@
 #include "gtkprivate.h"
 #include "gtktypebuiltins.h"
 
+
+/**
+ * SECTION:gtklabel
+ * @Short_description: A widget that displays a small to medium amount of text
+ * @Title: GtkLabel
+ *
+ * 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.
+ *
+ * <refsect2 id="GtkLabel-BUILDER-UI">
+ * <title>GtkLabel as GtkBuildable</title>
+ * <para>
+ * The GtkLabel implementation of the GtkBuildable interface supports a
+ * custom &lt;attributes&gt; element, which supports any number of &lt;attribute&gt;
+ * elements. the &lt;attribute&gt; element has attributes named name, value,
+ * start and end and allows you to specify #PangoAttribute values for this label.
+ *
+ * <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>
+ * 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().
+ *
+ * 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.)
+ *
+ * The markup passed to gtk_label_set_markup() must be valid; for example,
+ * literal &lt;, &gt; and &amp; 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().
+ *
+ * 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>
+ * 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
+ * &mdash; such as error messages &mdash; should be made selectable.
+ * </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.
+ *
+ * Labels can automatically wrap text if you call
+ * gtk_label_set_line_wrap().
+ *
+ * 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().
+ *
+ * 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.
+ *
+ * <note><para>
+ * Note that the interpretation of #GtkLabel:width-chars and
+ * #GtkLabel:max-width-chars has changed a bit with the introduction of
+ * <link linkend="geometry-management">width-for-height geometry management.</link>
+ * </para></note>
+ * </para>
+ * </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&lt;/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>
+ */
+
+
 /*rint() is only available in GCC and/or C99*/
 #if (__STDC_VERSION__ < 199901L && !defined __GNUC__)
 double rint(double x)
@@ -2632,6 +2810,16 @@ gtk_label_set_pattern_internal (GtkLabel    *label,
   priv->effective_attrs = attrs;
 }
 
+/**
+ * gtk_label_set_pattern:
+ * @label: The #GtkLabel you want to set the pattern to.
+ * @pattern: The pattern as described above.
+ *
+ * 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".
+ */
 void
 gtk_label_set_pattern (GtkLabel	   *label,
 		       const gchar *pattern)