diff options
| -rw-r--r-- | docs/reference/gtk/tmpl/.gitignore | 1 | ||||
| -rw-r--r-- | docs/reference/gtk/tmpl/gtklabel.sgml | 751 | ||||
| -rw-r--r-- | 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 5417f735f0..0c37085575 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/docs/reference/gtk/tmpl/gtklabel.sgml b/docs/reference/gtk/tmpl/gtklabel.sgml deleted file mode 100644 index 0740e5f4af..0000000000 --- a/docs/reference/gtk/tmpl/gtklabel.sgml +++ /dev/null @@ -1,751 +0,0 @@ -<!-- ##### SECTION Title ##### --> -GtkLabel - -<!-- ##### SECTION Short_Description ##### --> -A widget that displays a small to medium amount of text - -<!-- ##### SECTION Long_Description ##### --> -<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> - -</para> - -<!-- ##### SECTION Stability_Level ##### --> - - -<!-- ##### SECTION Image ##### --> - - -<!-- ##### STRUCT GtkLabel ##### --> -<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> - -</para> - -@str: -@Returns: - - -<!-- ##### FUNCTION gtk_label_set_text ##### --> -<para> - -</para> - -@label: -@str: - - -<!-- ##### FUNCTION gtk_label_set_attributes ##### --> -<para> - -</para> - -@label: -@attrs: - - -<!-- ##### FUNCTION gtk_label_set_markup ##### --> -<para> - -</para> - -@label: -@str: - - -<!-- ##### FUNCTION gtk_label_set_markup_with_mnemonic ##### --> -<para> - -</para> - -@label: -@str: - - -<!-- ##### FUNCTION gtk_label_set_pattern ##### --> -<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. -@pattern: The pattern as described above. - - -<!-- ##### FUNCTION gtk_label_set_justify ##### --> -<para> - -</para> - -@label: -@jtype: - - -<!-- ##### FUNCTION gtk_label_set_ellipsize ##### --> -<para> - -</para> - -@label: -@mode: - - -<!-- ##### FUNCTION gtk_label_set_width_chars ##### --> -<para> - -</para> - -@label: -@n_chars: - - -<!-- ##### FUNCTION gtk_label_set_max_width_chars ##### --> -<para> - -</para> - -@label: -@n_chars: - - -<!-- ##### FUNCTION gtk_label_set_line_wrap ##### --> -<para> - -</para> - -@label: -@wrap: - - -<!-- ##### FUNCTION gtk_label_set_line_wrap_mode ##### --> -<para> - -</para> - -@label: -@wrap_mode: - - -<!-- ##### FUNCTION gtk_label_get_layout_offsets ##### --> -<para> - -</para> - -@label: -@x: -@y: - - -<!-- ##### FUNCTION gtk_label_get_mnemonic_keyval ##### --> -<para> - -</para> - -@label: -@Returns: - - -<!-- ##### FUNCTION gtk_label_get_selectable ##### --> -<para> - -</para> - -@label: -@Returns: - - -<!-- ##### FUNCTION gtk_label_get_text ##### --> -<para> - -</para> - -@label: -@Returns: - - -<!-- ##### FUNCTION gtk_label_new_with_mnemonic ##### --> -<para> - -</para> - -@str: -@Returns: - - -<!-- ##### FUNCTION gtk_label_select_region ##### --> -<para> - -</para> - -@label: -@start_offset: -@end_offset: - - -<!-- ##### FUNCTION gtk_label_set_mnemonic_widget ##### --> -<para> - -</para> - -@label: -@widget: - - -<!-- ##### FUNCTION gtk_label_set_selectable ##### --> -<para> - -</para> - -@label: -@setting: - - -<!-- ##### FUNCTION gtk_label_set_text_with_mnemonic ##### --> -<para> - -</para> - -@label: -@str: - - -<!-- ##### FUNCTION gtk_label_get_attributes ##### --> -<para> - -</para> - -@label: -@Returns: - - -<!-- ##### FUNCTION gtk_label_get_justify ##### --> -<para> - -</para> - -@label: -@Returns: - - -<!-- ##### FUNCTION gtk_label_get_ellipsize ##### --> -<para> - -</para> - -@label: -@Returns: - - -<!-- ##### FUNCTION gtk_label_get_width_chars ##### --> -<para> - -</para> - -@label: -@Returns: - - -<!-- ##### FUNCTION gtk_label_get_max_width_chars ##### --> -<para> - -</para> - -@label: -@Returns: - - -<!-- ##### FUNCTION gtk_label_get_label ##### --> -<para> - -</para> - -@label: -@Returns: - - -<!-- ##### FUNCTION gtk_label_get_layout ##### --> -<para> - -</para> - -@label: -@Returns: - - -<!-- ##### FUNCTION gtk_label_get_line_wrap ##### --> -<para> - -</para> - -@label: -@Returns: - - -<!-- ##### FUNCTION gtk_label_get_line_wrap_mode ##### --> -<para> - -</para> - -@label: -@Returns: - - -<!-- ##### FUNCTION gtk_label_get_mnemonic_widget ##### --> -<para> - -</para> - -@label: -@Returns: - - -<!-- ##### FUNCTION gtk_label_get_selection_bounds ##### --> -<para> - -</para> - -@label: -@start: -@end: -@Returns: - - -<!-- ##### FUNCTION gtk_label_get_use_markup ##### --> -<para> - -</para> - -@label: -@Returns: - - -<!-- ##### FUNCTION gtk_label_get_use_underline ##### --> -<para> - -</para> - -@label: -@Returns: - - -<!-- ##### FUNCTION gtk_label_get_single_line_mode ##### --> -<para> - -</para> - -@label: -@Returns: - - -<!-- ##### FUNCTION gtk_label_get_angle ##### --> -<para> - -</para> - -@label: -@Returns: - - -<!-- ##### FUNCTION gtk_label_set_label ##### --> -<para> - -</para> - -@label: -@str: - - -<!-- ##### FUNCTION gtk_label_set_use_markup ##### --> -<para> - -</para> - -@label: -@setting: - - -<!-- ##### FUNCTION gtk_label_set_use_underline ##### --> -<para> - -</para> - -@label: -@setting: - - -<!-- ##### FUNCTION gtk_label_set_single_line_mode ##### --> -<para> - -</para> - -@label: -@single_line_mode: - - -<!-- ##### FUNCTION gtk_label_set_angle ##### --> -<para> - -</para> - -@label: -@angle: - - -<!-- ##### FUNCTION gtk_label_get_current_uri ##### --> -<para> - -</para> - -@label: -@Returns: - - -<!-- ##### FUNCTION gtk_label_set_track_visited_links ##### --> -<para> - -</para> - -@label: -@track_links: - - -<!-- ##### FUNCTION gtk_label_get_track_visited_links ##### --> -<para> - -</para> - -@label: -@Returns: - - diff --git a/gtk/gtklabel.c b/gtk/gtklabel.c index 04bf4ffb39..23ae22366f 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 <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. + * + * <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 <, > and & characters must be escaped as \<, + * \gt;, and \&. 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 + * — such as error messages — 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="<i>Our</i> 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) |