[gtk+] docs: Note the side effects of GtkLabel setters
- From: Matthias Clasen <matthiasc src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [gtk+] docs: Note the side effects of GtkLabel setters
- Date: Mon, 6 Apr 2015 02:46:44 +0000 (UTC)
commit 3972520fbb871d66db4abe9f09b7dc84c323aa9d
Author: Emmanuele Bassi <ebassi gnome org>
Date: Sat Apr 4 13:54:34 2015 +0100
docs: Note the side effects of GtkLabel setters
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
gtk/gtklabel.c | 42 +++++++++++++++++++++++++++++++++++++-----
1 files changed, 37 insertions(+), 5 deletions(-)
---
diff --git a/gtk/gtklabel.c b/gtk/gtklabel.c
index 396ae97..4b980b2 100644
--- a/gtk/gtklabel.c
+++ b/gtk/gtklabel.c
@@ -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,
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]