From c1e8577a66a2302956afc0ebe7925f89ef39b5ce Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Javier=20Jard=C3=B3n?= Date: Thu, 14 Apr 2011 22:50:45 +0100 Subject: [PATCH] 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(-) delete mode 100644 docs/reference/gtk/tmpl/gtklabel.sgml 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 @@ - -GtkLabel - - -A widget that displays a small to medium amount of text - - - -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. - - - -GtkLabel as GtkBuildable - -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. - - -A UI definition fragment specifying Pango attributes - - - - " - - -]]> - - -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. - - - - - -Mnemonics - - -Labels may contain mnemonics. 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 "_File", 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: - - - - /* 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); - - -There's a convenience function to create buttons with a mnemonic label -already inside: - - - - /* Pressing Alt+H will activate this button */ - button = gtk_button_new_with_mnemonic ("_Hello"); - - - -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(): - - - /* 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); - - - - - - - - -Markup (styled text) - - -To make it easy to format text in a label (changing colors, fonts, -etc.), label text can be provided in a simple markup format. -Here's how to create a label with a small font: - - - label = gtk_label_new (NULL); - gtk_label_set_markup (GTK_LABEL (label), "<small>Small text</small>"); - - -(See complete documentation of available -tags in the Pango manual.) - - -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(). - - -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. - - - - -Selectable labels - - -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. - - - - -Text layout - - -A label can contain any number of paragraphs, but will have -performance problems if it contains more than a small number. -Paragraphs are separated by newlines or other paragraph separators -understood by Pango. - - -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 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. - - - -Links - - -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 -a 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: - -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..."); - -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. - - - - - - - - - - - - - - - - - -This should not be accessed directly. Use the accessor functions as -described below. - - - - - - - - -@label: the object which received the signal. - - - - - - -@label: the object which received the signal. -@arg1: -@Returns: - - - - - - -@label: the object which received the signal. - - - - - - -@label: the object which received the signal. -@arg1: -@arg2: -@arg3: - - - - - - -@label: the object which received the signal. -@arg1: - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -@str: -@Returns: - - - - - - - -@label: -@str: - - - - - - - -@label: -@attrs: - - - - - - - -@label: -@str: - - - - - - - -@label: -@str: - - - - -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". - - -@label: The #GtkLabel you want to set the pattern to. -@pattern: The pattern as described above. - - - - - - - -@label: -@jtype: - - - - - - - -@label: -@mode: - - - - - - - -@label: -@n_chars: - - - - - - - -@label: -@n_chars: - - - - - - - -@label: -@wrap: - - - - - - - -@label: -@wrap_mode: - - - - - - - -@label: -@x: -@y: - - - - - - - -@label: -@Returns: - - - - - - - -@label: -@Returns: - - - - - - - -@label: -@Returns: - - - - - - - -@str: -@Returns: - - - - - - - -@label: -@start_offset: -@end_offset: - - - - - - - -@label: -@widget: - - - - - - - -@label: -@setting: - - - - - - - -@label: -@str: - - - - - - - -@label: -@Returns: - - - - - - - -@label: -@Returns: - - - - - - - -@label: -@Returns: - - - - - - - -@label: -@Returns: - - - - - - - -@label: -@Returns: - - - - - - - -@label: -@Returns: - - - - - - - -@label: -@Returns: - - - - - - - -@label: -@Returns: - - - - - - - -@label: -@Returns: - - - - - - - -@label: -@Returns: - - - - - - - -@label: -@start: -@end: -@Returns: - - - - - - - -@label: -@Returns: - - - - - - - -@label: -@Returns: - - - - - - - -@label: -@Returns: - - - - - - - -@label: -@Returns: - - - - - - - -@label: -@str: - - - - - - - -@label: -@setting: - - - - - - - -@label: -@setting: - - - - - - - -@label: -@single_line_mode: - - - - - - - -@label: -@angle: - - - - - - - -@label: -@Returns: - - - - - - - -@label: -@track_links: - - - - - - - -@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. + * + * + * GtkLabel as GtkBuildable + * + * 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. + * + * + * A UI definition fragment specifying Pango attributes + * + * + * + * " + * + * + * ]]> + * + * 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. + * + * + * + * Mnemonics + * + * Labels may contain mnemonics. 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 "_File", 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: + * + * + * + * // 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); + * + * + * + * There's a convenience function to create buttons with a mnemonic label + * already inside: + * + * + * + * // Pressing Alt+H will activate this button + * button = gtk_button_new_with_mnemonic ("_Hello"); + * + * + * + * 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(): + * + * + * + * // 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); + * + * + * + * + * + * Markup (styled text) + * + * To make it easy to format text in a label (changing colors, fonts, + * etc.), label text can be provided in a simple markup format. + * Here's how to create a label with a small font: + * + * + * + * label = gtk_label_new (NULL); + * gtk_label_set_markup (GTK_LABEL (label), "Small text"); + * + * + * + * (See complete documentation 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. + * + * + * + * Selectable labels + * 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. + * + * + * Text layout + * + * A label can contain any number of paragraphs, but will have + * performance problems if it contains more than a small number. + * Paragraphs are separated by newlines or other paragraph separators + * understood by Pango. + * + * 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 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. + * + * + * + * + * Links + * + * 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 + * a 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: + * + * + * gtk_label_set_markup (label, "Go to the GTK+ website for more..."); + * + * + * 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. + * + * + */ + + /*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)