After an evaluation, GNOME has moved from Bugzilla to GitLab. Learn more about GitLab.
No new issues can be reported in GNOME Bugzilla anymore.
To report an issue in a GNOME project, go to GNOME GitLab.
Do not go to GNOME Gitlab for: Bluefish, Doxygen, GnuCash, GStreamer, java-gnome, LDTP, NetworkManager, Tomboy.
Bug 690737 - Add docs for GtkCellRendererText, plus some tiny fixes
Add docs for GtkCellRendererText, plus some tiny fixes
Status: RESOLVED OBSOLETE
Product: gtk+
Classification: Platform
Component: Widget: GtkTreeView
3.7.x
Other Linux
: Normal enhancement
: ---
Assigned To: gtktreeview-bugs
gtktreeview-bugs
Depends on:
Blocks:
 
 
Reported: 2012-12-26 14:34 UTC by Kevin Connor ARPE
Modified: 2018-04-15 00:39 UTC
See Also:
GNOME target: ---
GNOME version: ---


Attachments
Git patch (50.03 KB, patch)
2012-12-26 14:34 UTC, Kevin Connor ARPE
reviewed Details | Review

Description Kevin Connor ARPE 2012-12-26 14:34:04 UTC
Created attachment 232244 [details] [review]
Git patch

Part One: "docs"
----------------
Expanded documentation for many properties in GtkCellRendererText.
Specifically, I made references to other GDK & Pango functions.

Example: "foreground" references gdk_rgba_parse()
Example: "markup" references pango_parse_markup()
         and links to PangoMarkupFormat

When first learning this class, I struggled to make the connection
between many properties and their corresponding GDK & Pango functions.
This doc patch should help new users.

Part Two: "tiny fixes"
----------------------
(a) Refactored the code to set "background" and "foreground".
(b) When setting "size" or "size-points",
    both now emit notify signal for "size" and "size-points".
Comment 1 Emmanuele Bassi (:ebassi) 2013-01-14 09:58:43 UTC
Review of attachment 232244 [details] [review]:

hi, thanks for the patch.

could you please split the patch in two commits? a good set of rules for the commit policy in GTK (and GNOME) is available here:

https://live.gnome.org/Git/CommitMessages

in general, if your commit message has two parts so neatly separated it's an indicator that you can provide multiple patches.

thanks again for the patch!

now, on to the review...

::: gtk/gtkcellrenderertext.c
@@ +37,3 @@
+ * 
+ * A #GtkCellRendererText renders a given text in its cell, using the
+ * font, color and style information provided by its properties. The

I'm a bit of a sucker for the Oxford comma: http://en.wikipedia.org/wiki/Oxford_comma

@@ +41,3 @@
+ * #GtkCellRendererText:ellipsize property allows it.
+ * 
+ * Pango is used to render the text. You may control the rendering

the fact that Pango is used to render the text is implicit: GTK+ uses Pango to render text everywhere.

@@ +262,3 @@
+   * 
+   * UTF-8 text to render. %NULL and empty strings are valid. During get
+   * and set, strings are copied.

this paragraph should not be needed: GTK only accepts UTF-8 text (unless explicitly noted), and the memory management policy is the same across all GObject libraries. the only important part is that %NULL is an accepted value.

@@ +264,3 @@
+   * and set, strings are copied.
+   * 
+   * When setting a value (including %NULL or empty string), previous

you can remove the incidental between parenthesis.

@@ +284,3 @@
+   * See pango_parse_markup() to learn more about the parsing process.
+   * 
+   * When setting a value (including %NULL or empty string), both

same as above.

@@ +299,3 @@
+   * GtkCellRendererText:attributes:
+   * 
+   * #PangoAttrList (collection of #PangoAttribute) used to affect text

the PangoAttrList is referenced, so you can drop the incidental.

@@ +308,3 @@
+   * Pango text rendering.
+   * 
+   * Be careful when setting this property: If done after setting

you probably want to be a bit more formal, using something like:

 Setting this property along with the GtkCellRendererText:markup property yields undefined results.

side note: we should really fix this.

@@ +340,3 @@
+   * 
+   * Background color as a name. Internally converted to #GdkRGBA. See
+   * gdk_rgba_parse() for full format details. Value %NULL implies unset

"A value of %NULL"

@@ +341,3 @@
+   * Background color as a name. Internally converted to #GdkRGBA. See
+   * gdk_rgba_parse() for full format details. Value %NULL implies unset
+   * or transparent. See gdk_cairo_set_source_rgba() to learn more about

I'm not entirely sure the link to gdk_cairo_set_source_rgba() makes sense in this context.

@@ +347,3 @@
+   * #GtkCellRendererText:background-set to %TRUE. Setting this property
+   * to %NULL will also set property #GtkCellRendererText:background-set
+   * to %FALSE.

this could be reworded as:

  Settings this property will also set the #GtkCellRendererText:background-set property as a side effect.

@@ +366,3 @@
+   * Setting this property to a non-%NULL value will also set property
+   * #GtkCellRendererText:background-set to %TRUE. Setting this property
+   * to %NULL will also set property #GtkCellRendererText:background-set

same issues as above.

@@ +388,3 @@
+   * Setting this property to a non-%NULL value will also set property
+   * #GtkCellRendererText:background-set to %TRUE. Setting this property
+   * to %NULL will also set property #GtkCellRendererText:background-set

same issues as above.

@@ +413,3 @@
+   * 
+   * Setting this property to %NULL will also set property
+   * #GtkCellRendererText:foreground-set to %FALSE.

same issues as above.

@@ +434,3 @@
+   * 
+   * Setting this property to %NULL will also set property
+   * #GtkCellRendererText:foreground-set to %FALSE.

same issues as above.

@@ +457,3 @@
+   * 
+   * Setting this property to %NULL will also set property
+   * #GtkCellRendererText:foreground-set to %FALSE.

same issues as above.

@@ +499,3 @@
+   * 
+   * When setting a value (including %NULL or empty string), previous
+   * settings to property #GtkCellRendererText:font-desc are replaced.

this paragraph and the one below could be summarized as:

  Setting this property will also set the following properties as a side effect: #GtkCellRendererText:font-desc; #GtkCellRendererText:family-set;...

@@ +523,3 @@
+   * 
+   * When setting a value (including %NULL), previous settings to
+   * property #GtkCellRendererText:font are replaced.

same as above.

@@ +969,3 @@
    * #GtkCellRendererText:editable is %TRUE and the cell is empty.
+   * 
+   * %NULL and empty strings are valid. During get and set, strings are

see the comment for GtkCellRendererText:text

@@ +1812,3 @@
+        color = g_value_get_string (value);
+
+        if (!color)

please, use the pointer comparison, not the inherent truthy value of NULL, as per coding style.

@@ +1832,1 @@
+        if (!color)

same as above.

@@ +2136,3 @@
+ * Example: Bind the property #GtkCellRendererText:text on the cell
+ * renderer to a string value in the model, thus rendering a different
+ * string in each row of the #GtkTreeView.

instead of using an "Example", you can actually include a code example for this.
Comment 2 Matthias Clasen 2018-02-10 05:10:56 UTC
We're moving to gitlab! As part of this move, we are moving bugs to NEEDINFO if they haven't seen activity in more than a year. If this issue is still important to you and still relevant with GTK+ 3.22 or master, please reopen it and we will migrate it to gitlab.
Comment 3 Matthias Clasen 2018-04-15 00:39:07 UTC
As announced a while ago, we are migrating to gitlab, and bugs that haven't seen activity in the last year or so will be not be migrated, but closed out in bugzilla.

If this bug is still relevant to you, you can open a new issue describing the symptoms and how to reproduce it with gtk 3.22.x or master in gitlab:

https://gitlab.gnome.org/GNOME/gtk/issues/new