From c1a97800434eefc689a1ae9208177eb6cf8c00dc Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Tue, 16 Oct 2007 05:35:23 +0000 Subject: [PATCH] Improve g_value_set_object docs svn path=/trunk/; revision=5784 --- docs/reference/ChangeLog | 6 ++++++ .../gobject/tmpl/param_value_types.sgml | 20 ++++++++++++++++++- 2 files changed, 25 insertions(+), 1 deletion(-) diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog index a372215c..8d36d23f 100644 --- a/docs/reference/ChangeLog +++ b/docs/reference/ChangeLog @@ -1,3 +1,9 @@ +2007-10-16 Matthias Clasen + + * gobject/tmpl/param_value_types.sgml: Add some discussion on + g_value_set_object() vs g_value_take_object(). (#477957, Davyd + Madeley) + 2007-09-19 Behdad Esfahbod * glib/building.sgml: Fix gettext URL. (#478349, kraai ftbfs.org) diff --git a/docs/reference/gobject/tmpl/param_value_types.sgml b/docs/reference/gobject/tmpl/param_value_types.sgml index 06850aae..242b79f3 100644 --- a/docs/reference/gobject/tmpl/param_value_types.sgml +++ b/docs/reference/gobject/tmpl/param_value_types.sgml @@ -1504,6 +1504,19 @@ See g_param_spec_internal() for details on property names. Set the contents of a %G_TYPE_OBJECT derived #GValue to @v_object. + +g_value_set_object() increases the reference count of @v_object +(the #GValue holds a reference to @v_object). +If you do not wish to increase the reference count of the object +(i.e. you wish to pass your current reference to the #GValue because you no +longer need it), +use g_value_take_object() instead. + + +It is important that your #GValue holds a reference to @v_object (either its +own, or one it has taken) to ensure that the object won't be destroyed while +the #GValue still exists). + @value: a valid #GValue of %G_TYPE_OBJECT derived type @v_object: object value to be set @@ -1513,7 +1526,12 @@ Set the contents of a %G_TYPE_OBJECT derived #GValue to @v_object. Sets the contents of a %G_TYPE_OBJECT derived #GValue to @v_object and takes over the ownership of the callers reference to @v_object; -the caller doesn't have to unref it any more. +the caller doesn't have to unref it any more (i.e. the reference +count of the object is not increased). + + +If you want the #GValue to hold its own reference to @v_object, use +g_value_set_object() instead. @value: a valid #GValue of %G_TYPE_OBJECT derived type -- 2.34.1