AuroraMiddleware/gtk
1
0
Fork 1
mirror of https://gitlab.gnome.org/GNOME/gtk.git synced 2024-12-29 06:51:10 +00:00
Code Issues Projects Releases Wiki Activity

docs: Note the side effects of GtkLabel setters

Browse Source 
The gtk_label_set_text() and gtk_label_set_markup() functions have
various side effects that ought to be documented, especially for
non-C developers using properties directly.

https://bugzilla.gnome.org/show_bug.cgi?id=747121
This commit is contained in:
Emmanuele Bassi 2015-04-04 13:54:34 +01:00 committed by Matthias Clasen
parent e6061caa7b
commit 3972520fbb
1 changed files with 37 additions and 5 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

42
gtk/gtklabel.c
View File

@ -725,6 +725,21 @@ gtk_label_class_init (GtkLabelClass *class)
_gtk_marshal_BOOLEAN__STRING,
G_TYPE_BOOLEAN, 1, G_TYPE_STRING);
/**
* GtkLabel:label:
*
* The contents of the label.
*
* If the string contains [Pango XML markup][PangoMarkupFormat], you will
* have to set the #GtkLabel:use-markup property to %TRUE in order for the
* label to display the markup attributes. See also gtk_label_set_markup()
* for a convenience function that sets both this property and the
* #GtkLabel:use-markup property at the same time.
*
* If the string contains underlines acting as mnemonics, you will have to
* set the #GtkLabel:use-underline property to %TRUE in order for the label
* to display them.
*/
g_object_class_install_property (gobject_class,
PROP_LABEL,
g_param_spec_string ("label",
@ -2210,7 +2225,13 @@ gtk_label_recalculate (GtkLabel *label)
* Sets the text within the #GtkLabel widget. It overwrites any text that
* was there before.
*
* This will also clear any previously set mnemonic accelerators.
* This function will clear any previously set mnemonic accelerators, and
* set the #GtkLabel:use-underline property to %FALSE as a side effect.
*
* This function will set the #GtkLabel:use-markup property to %FALSE
* as a side effect.
*
* See also: gtk_label_set_markup()
**/
void
gtk_label_set_text (GtkLabel *label,
@ -2294,7 +2315,7 @@ gtk_label_get_attributes (GtkLabel *label)
*
* Sets the text of the label. The label is interpreted as
* including embedded underlines and/or Pango markup depending
* on the values of the #GtkLabel:use-underline" and
* on the values of the #GtkLabel:use-underline and
* #GtkLabel:use-markup properties.
**/
void
@ -2706,9 +2727,11 @@ gtk_label_set_markup_internal (GtkLabel *label,
*
* Parses @str which is marked up with the
* [Pango text markup language][PangoMarkupFormat], setting the
* label’s text and attribute list based on the parse results. If the @str is
* external data, you may need to escape it with g_markup_escape_text() or
* g_markup_printf_escaped():
* label’s text and attribute list based on the parse results.
*
* If the @str is external data, you may need to escape it with
* g_markup_escape_text() or g_markup_printf_escaped():
*
* |[<!-- language="C" -->
* const char *format = "<span style=\"italic\">\%s</span>";
* char *markup;
@ -2717,6 +2740,15 @@ gtk_label_set_markup_internal (GtkLabel *label,
* gtk_label_set_markup (GTK_LABEL (label), markup);
* g_free (markup);
* ]|
*
* This function will set the #GtkLabel:use-markup property to %TRUE as
* a side effect.
*
* If you set the label contents using the #GtkLabel:label property you
* should also ensure that you set the #GtkLabel:use-markup property
* accordingly.
*
* See also: gtk_label_set_text()
**/
void
gtk_label_set_markup (GtkLabel *label,