From fca3fb58185ebec71040a4fc88689010e8cd8557 Mon Sep 17 00:00:00 2001 From: Stefan Kost Date: Sat, 21 Jun 2008 22:16:14 +0000 Subject: Migrating docs. * docs/reference/gobject/tmpl/param_value_types.sgml: * gobject/gboxed.c: * gobject/gboxed.h: * gobject/genums.c: * gobject/genums.h: * gobject/gobject.c: * gobject/gobject.h: * gobject/gparam.c: * gobject/gparam.h: * gobject/gparamspecs.c: * gobject/gparamspecs.h: * gobject/gvaluetypes.c: * gobject/gvaluetypes.h: Migrating docs. svn path=/trunk/; revision=7081 --- gobject/gboxed.c | 54 +++++ gobject/gboxed.h | 8 + gobject/genums.c | 30 +++ gobject/genums.h | 16 ++ gobject/gobject.c | 58 +++++ gobject/gobject.h | 8 + gobject/gparam.c | 43 ++++ gobject/gparam.h | 8 + gobject/gparamspecs.c | 358 +++++++++++++++++++++++++++- gobject/gparamspecs.h | 648 +++++++++++++++++++++++++++++++++++++++++++++++++- gobject/gvaluetypes.c | 248 +++++++++++++++++++ gobject/gvaluetypes.h | 118 +++++++++ 12 files changed, 1594 insertions(+), 3 deletions(-) (limited to 'gobject') diff --git a/gobject/gboxed.c b/gobject/gboxed.c index 907cf8e55..a3fb202a7 100644 --- a/gobject/gboxed.c +++ b/gobject/gboxed.c @@ -532,6 +532,14 @@ g_boxed_free (GType boxed_type, } } +/** + * g_value_get_boxed: + * @value: a valid #GValue of %G_TYPE_BOXED derived type + * + * Get the contents of a %G_TYPE_BOXED derived #GValue. + * + * Returns: boxed contents of @value + */ gpointer g_value_get_boxed (const GValue *value) { @@ -541,6 +549,16 @@ g_value_get_boxed (const GValue *value) return value->data[0].v_pointer; } +/** + * g_value_dup_boxed: + * @value: a valid #GValue of %G_TYPE_BOXED derived type + * + * Get the contents of a %G_TYPE_BOXED derived #GValue. + * Upon getting, the boxed value is duplicated and needs to be + * later freed with g_boxed_free(), e.g. like: g_boxed_free (G_VALUE_TYPE (@value), return_value); + * + * Returns: boxed contents of @value + */ gpointer g_value_dup_boxed (const GValue *value) { @@ -593,6 +611,13 @@ value_set_boxed_internal (GValue *value, } } +/** + * g_value_set_boxed: + * @value: a valid #GValue of %G_TYPE_BOXED derived type + * @v_boxed: boxed value to be set + * + * Set the contents of a %G_TYPE_BOXED derived #GValue to @v_boxed. + */ void g_value_set_boxed (GValue *value, gconstpointer boxed) @@ -603,6 +628,15 @@ g_value_set_boxed (GValue *value, value_set_boxed_internal (value, boxed, TRUE, TRUE); } +/** + * g_value_set_static_boxed: + * @value: a valid #GValue of %G_TYPE_BOXED derived type + * @v_boxed: static boxed value to be set + * + * Set the contents of a %G_TYPE_BOXED derived #GValue to @v_boxed. + * The boxed value is assumed to be static, and is thus not duplicated + * when setting the #GValue. + */ void g_value_set_static_boxed (GValue *value, gconstpointer boxed) @@ -613,6 +647,15 @@ g_value_set_static_boxed (GValue *value, value_set_boxed_internal (value, boxed, FALSE, FALSE); } +/** + * g_value_set_boxed_take_ownership: + * @value: a valid #GValue of %G_TYPE_BOXED derived type + * @v_boxed: duplicated unowned boxed value to be set + * + * This is an internal function introduced mainly for C marshallers. + * + * Deprecated: 2.4: Use g_value_take_boxed() instead. + */ void g_value_set_boxed_take_ownership (GValue *value, gconstpointer boxed) @@ -620,6 +663,17 @@ g_value_set_boxed_take_ownership (GValue *value, g_value_take_boxed (value, boxed); } +/** + * g_value_take_boxed: + * @value: a valid #GValue of %G_TYPE_BOXED derived type + * @v_boxed: duplicated unowned boxed value to be set + * + * Sets the contents of a %G_TYPE_BOXED derived #GValue to @v_boxed and + * takes over the ownership of the callers reference to @v_boxed; + * the caller doesn't have to unref it any more. + * + * Since: 2.4 + */ void g_value_take_boxed (GValue *value, gconstpointer boxed) diff --git a/gobject/gboxed.h b/gobject/gboxed.h index 7d778c085..75a5193af 100644 --- a/gobject/gboxed.h +++ b/gobject/gboxed.h @@ -29,6 +29,14 @@ G_BEGIN_DECLS /* --- type macros --- */ #define G_TYPE_IS_BOXED(type) (G_TYPE_FUNDAMENTAL (type) == G_TYPE_BOXED) +/** + * G_VALUE_HOLDS_BOXED: + * @value: a valid #GValue structure + * + * Checks whether the given #GValue can hold values derived from type %G_TYPE_BOXED. + * + * Returns: %TRUE on success. + */ #define G_VALUE_HOLDS_BOXED(value) (G_TYPE_CHECK_VALUE_TYPE ((value), G_TYPE_BOXED)) diff --git a/gobject/genums.c b/gobject/genums.c index 5dff11b90..a2bce4c91 100644 --- a/gobject/genums.c +++ b/gobject/genums.c @@ -546,6 +546,13 @@ g_flags_get_first_value (GFlagsClass *flags_class, return NULL; } +/** + * g_value_set_enum: + * @value: a valid #GValue whose type is derived from %G_TYPE_ENUM + * @v_enum: enum value to be set + * + * Set the contents of a %G_TYPE_ENUM #GValue to @v_enum. + */ void g_value_set_enum (GValue *value, gint v_enum) @@ -555,6 +562,14 @@ g_value_set_enum (GValue *value, value->data[0].v_long = v_enum; } +/** + * g_value_get_enum: + * @value: a valid #GValue whose type is derived from %G_TYPE_ENUM + * + * Get the contents of a %G_TYPE_ENUM #GValue. + * + * Returns: enum contents of @value + */ gint g_value_get_enum (const GValue *value) { @@ -563,6 +578,13 @@ g_value_get_enum (const GValue *value) return value->data[0].v_long; } +/** + * g_value_set_flags: + * @value: a valid #GValue whose type is derived from %G_TYPE_FLAGS + * @v_flags: flags value to be set + * + * Set the contents of a %G_TYPE_FLAGS #GValue to @v_flags. + */ void g_value_set_flags (GValue *value, guint v_flags) @@ -572,6 +594,14 @@ g_value_set_flags (GValue *value, value->data[0].v_ulong = v_flags; } +/** + * g_value_get_flags: + * @value: a valid #GValue whose type is derived from %G_TYPE_FLAGS + * + * Get the contents of a %G_TYPE_FLAGS #GValue. + * + * Returns: flags contents of @value + */ guint g_value_get_flags (const GValue *value) { diff --git a/gobject/genums.h b/gobject/genums.h index 1e872bace..32e885cba 100644 --- a/gobject/genums.h +++ b/gobject/genums.h @@ -116,7 +116,23 @@ G_BEGIN_DECLS #define G_FLAGS_CLASS_TYPE_NAME(class) (g_type_name (G_FLAGS_CLASS_TYPE (class))) +/** + * G_VALUE_HOLDS_ENUM: + * @value: a valid #GValue structure + * + * Checks whether the given #GValue can hold values derived from type %G_TYPE_ENUM. + * + * Returns: %TRUE on success. + */ #define G_VALUE_HOLDS_ENUM(value) (G_TYPE_CHECK_VALUE_TYPE ((value), G_TYPE_ENUM)) +/** + * G_VALUE_HOLDS_FLAGS: + * @value: a valid #GValue structure + * + * Checks whether the given #GValue can hold values derived from type %G_TYPE_FLAGS. + * + * Returns: %TRUE on success. + */ #define G_VALUE_HOLDS_FLAGS(value) (G_TYPE_CHECK_VALUE_TYPE ((value), G_TYPE_FLAGS)) diff --git a/gobject/gobject.c b/gobject/gobject.c index ac6cb77b6..aba014161 100644 --- a/gobject/gobject.c +++ b/gobject/gobject.c @@ -2718,6 +2718,24 @@ g_value_object_lcopy_value (const GValue *value, return NULL; } +/** + * g_value_set_object: + * @value: a valid #GValue of %G_TYPE_OBJECT derived type + * @v_object: object value to be set + * + * 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). + */ void g_value_set_object (GValue *value, gpointer v_object) @@ -2743,6 +2761,15 @@ g_value_set_object (GValue *value, g_object_unref (old); } +/** + * g_value_set_object_take_ownership: + * @value: a valid #GValue of %G_TYPE_OBJECT derived type + * @v_object: object value to be set + * + * This is an internal function introduced mainly for C marshallers. + * + * Deprecated: 2.4: Use g_value_take_object() instead. + */ void g_value_set_object_take_ownership (GValue *value, gpointer v_object) @@ -2750,6 +2777,21 @@ g_value_set_object_take_ownership (GValue *value, g_value_take_object (value, v_object); } +/** + * g_value_take_object: + * @value: a valid #GValue of %G_TYPE_OBJECT derived type + * @v_object: object value to be set + * + * 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 (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. + * + * Since: 2.4 + */ void g_value_take_object (GValue *value, gpointer v_object) @@ -2771,6 +2813,14 @@ g_value_take_object (GValue *value, } } +/** + * g_value_get_object: + * @value: a valid #GValue of %G_TYPE_OBJECT derived type + * + * Get the contents of a %G_TYPE_OBJECT derived #GValue. + * + * Returns: object contents of @value + */ gpointer g_value_get_object (const GValue *value) { @@ -2779,6 +2829,14 @@ g_value_get_object (const GValue *value) return value->data[0].v_pointer; } +/** + * g_value_dup_object: + * @value: a valid #GValue whose type is derived from %G_TYPE_OBJECT + * + * Get the contents of a %G_TYPE_OBJECT derived #GValue, increasing its reference count. + * + * Returns: object content of @value, should be unreferenced when no longer needed. + */ gpointer g_value_dup_object (const GValue *value) { diff --git a/gobject/gobject.h b/gobject/gobject.h index b352c958e..5ef57af05 100644 --- a/gobject/gobject.h +++ b/gobject/gobject.h @@ -119,6 +119,14 @@ G_BEGIN_DECLS * should not be freed. */ #define G_OBJECT_CLASS_NAME(class) (g_type_name (G_OBJECT_CLASS_TYPE (class))) +/** + * G_VALUE_HOLDS_OBJECT: + * @value: a valid #GValue structure + * + * Checks whether the given #GValue can hold values derived from type %G_TYPE_OBJECT. + * + * Returns: %TRUE on success. + */ #define G_VALUE_HOLDS_OBJECT(value) (G_TYPE_CHECK_VALUE_TYPE ((value), G_TYPE_OBJECT)) /* --- type macros --- */ diff --git a/gobject/gparam.c b/gobject/gparam.c index e1f7f7834..1a898292a 100644 --- a/gobject/gparam.c +++ b/gobject/gparam.c @@ -1386,6 +1386,13 @@ g_param_type_register_static (const gchar *name, return g_type_register_static (G_TYPE_PARAM, name, &info, 0); } +/** + * g_value_set_param: + * @value: a valid #GValue of type %G_TYPE_PARAM + * @param: the #GParamSpec to be set + * + * Set the contents of a %G_TYPE_PARAM #GValue to @param. + */ void g_value_set_param (GValue *value, GParamSpec *param) @@ -1401,6 +1408,15 @@ g_value_set_param (GValue *value, g_param_spec_ref (value->data[0].v_pointer); } +/** + * g_value_set_param_take_ownership: + * @value: a valid #GValue of type %G_TYPE_PARAM + * @param: the #GParamSpec to be set + * + * This is an internal function introduced mainly for C marshallers. + * + * Deprecated: 2.4: Use g_value_take_param() instead. + */ void g_value_set_param_take_ownership (GValue *value, GParamSpec *param) @@ -1408,6 +1424,17 @@ g_value_set_param_take_ownership (GValue *value, g_value_take_param (value, param); } +/** + * g_value_take_param: + * @value: a valid #GValue of type %G_TYPE_PARAM + * @param: the #GParamSpec to be set + * + * Sets the contents of a %G_TYPE_PARAM #GValue to @param and + * takes over the ownership of the callers reference to @param; + * the caller doesn't have to unref it any more. + * + * Since: 2.4 + */ void g_value_take_param (GValue *value, GParamSpec *param) @@ -1421,6 +1448,14 @@ g_value_take_param (GValue *value, value->data[0].v_pointer = param; /* we take over the reference count */ } +/** + * g_value_get_param: + * @value: a valid #GValue whose type is derived from %G_TYPE_PARAM + * + * Get the contents of a %G_TYPE_PARAM #GValue. + * + * Returns: #GParamSpec content of @value + */ GParamSpec* g_value_get_param (const GValue *value) { @@ -1429,6 +1464,14 @@ g_value_get_param (const GValue *value) return value->data[0].v_pointer; } +/** + * g_value_dup_param: + * @value: a valid #GValue whose type is derived from %G_TYPE_PARAM + * + * Get the contents of a %G_TYPE_PARAM #GValue, increasing its reference count. + * + * Returns: #GParamSpec content of @value, should be unreferenced when no longer needed. + */ GParamSpec* g_value_dup_param (const GValue *value) { diff --git a/gobject/gparam.h b/gobject/gparam.h index ede8cb300..441a75228 100644 --- a/gobject/gparam.h +++ b/gobject/gparam.h @@ -99,6 +99,14 @@ G_BEGIN_DECLS * Retrieves the #GType to initialize a #GValue for this parameter. */ #define G_PARAM_SPEC_VALUE_TYPE(pspec) (G_PARAM_SPEC (pspec)->value_type) +/** + * G_VALUE_HOLDS_PARAM: + * @value: a valid #GValue structure + * + * Checks whether the given #GValue can hold values derived from type %G_TYPE_PARAM. + * + * Returns: %TRUE on success. + */ #define G_VALUE_HOLDS_PARAM(value) (G_TYPE_CHECK_VALUE_TYPE ((value), G_TYPE_PARAM)) diff --git a/gobject/gparamspecs.c b/gobject/gparamspecs.c index 5cbe6054a..c956a5c55 100644 --- a/gobject/gparamspecs.c +++ b/gobject/gparamspecs.c @@ -16,7 +16,23 @@ * Free Software Foundation, Inc., 59 Temple Place, Suite 330, * Boston, MA 02111-1307, USA. */ - +/** + * SECTION:param_value_types + * @Short_description: Standard Parameter and Value Types + * @See_also:#GParamSpec, #GValue, g_object_class_install_property(). + * @Title: Parameters and Values + * + * #GValue provides an abstract container structure which can be copied, + * transformed and compared while holding a value of any (derived) type, which + * is registered as a #GType with a #GTypeValueTable in its #GTypeInfo structure. + * Parameter specifications for most value types can be created as + * #GParamSpec derived instances, to implement e.g. #GObject properties which + * operate on #GValue containers. + * + * Parameter names need to start with a letter (a-z or A-Z). Subsequent + * characters can be letters, numbers or a '-'. + * All other characters are replaced by a '-' during construction. + */ /* * MT safe */ @@ -1493,6 +1509,20 @@ g_param_spec_types_init (void) /* --- GParamSpec initialization --- */ +/** + * g_param_spec_char: + * @name: canonical name of the property specified + * @nick: nick name for the property specified + * @blurb: description of the property specified + * @minimum: minimum value for the property specified + * @maximum: maximum value for the property specified + * @default_value: default value for the property specified + * @flags: flags for the property specified + * + * Creates a new #GParamSpecChar instance specifying a %G_TYPE_CHAR property. + * + * Returns: a newly created parameter specification + */ GParamSpec* g_param_spec_char (const gchar *name, const gchar *nick, @@ -1519,6 +1549,20 @@ g_param_spec_char (const gchar *name, return G_PARAM_SPEC (cspec); } +/** + * g_param_spec_uchar: + * @name: canonical name of the property specified + * @nick: nick name for the property specified + * @blurb: description of the property specified + * @minimum: minimum value for the property specified + * @maximum: maximum value for the property specified + * @default_value: default value for the property specified + * @flags: flags for the property specified + * + * Creates a new #GParamSpecUChar instance specifying a %G_TYPE_UCHAR property. + * + * Returns: a newly created parameter specification + */ GParamSpec* g_param_spec_uchar (const gchar *name, const gchar *nick, @@ -1545,6 +1589,21 @@ g_param_spec_uchar (const gchar *name, return G_PARAM_SPEC (uspec); } +/** + * g_param_spec_boolean: + * @name: canonical name of the property specified + * @nick: nick name for the property specified + * @blurb: description of the property specified + * @default_value: default value for the property specified + * @flags: flags for the property specified + * + * Creates a new #GParamSpecBoolean instance specifying a %G_TYPE_BOOLEAN + * property. + * + * See g_param_spec_internal() for details on property names. + * + * Returns: a newly created parameter specification + */ GParamSpec* g_param_spec_boolean (const gchar *name, const gchar *nick, @@ -1567,6 +1626,22 @@ g_param_spec_boolean (const gchar *name, return G_PARAM_SPEC (bspec); } +/** + * g_param_spec_int: + * @name: canonical name of the property specified + * @nick: nick name for the property specified + * @blurb: description of the property specified + * @minimum: minimum value for the property specified + * @maximum: maximum value for the property specified + * @default_value: default value for the property specified + * @flags: flags for the property specified + * + * Creates a new #GParamSpecInt instance specifying a %G_TYPE_INT property. + * + * See g_param_spec_internal() for details on property names. + * + * Returns: a newly created parameter specification + */ GParamSpec* g_param_spec_int (const gchar *name, const gchar *nick, @@ -1593,6 +1668,22 @@ g_param_spec_int (const gchar *name, return G_PARAM_SPEC (ispec); } +/** + * g_param_spec_uint: + * @name: canonical name of the property specified + * @nick: nick name for the property specified + * @blurb: description of the property specified + * @minimum: minimum value for the property specified + * @maximum: maximum value for the property specified + * @default_value: default value for the property specified + * @flags: flags for the property specified + * + * Creates a new #GParamSpecUInt instance specifying a %G_TYPE_UINT property. + * + * See g_param_spec_internal() for details on property names. + * + * Returns: a newly created parameter specification + */ GParamSpec* g_param_spec_uint (const gchar *name, const gchar *nick, @@ -1619,6 +1710,22 @@ g_param_spec_uint (const gchar *name, return G_PARAM_SPEC (uspec); } +/** + * g_param_spec_long: + * @name: canonical name of the property specified + * @nick: nick name for the property specified + * @blurb: description of the property specified + * @minimum: minimum value for the property specified + * @maximum: maximum value for the property specified + * @default_value: default value for the property specified + * @flags: flags for the property specified + * + * Creates a new #GParamSpecLong instance specifying a %G_TYPE_LONG property. + * + * See g_param_spec_internal() for details on property names. + * + * Returns: a newly created parameter specification + */ GParamSpec* g_param_spec_long (const gchar *name, const gchar *nick, @@ -1645,6 +1752,22 @@ g_param_spec_long (const gchar *name, return G_PARAM_SPEC (lspec); } +/** + * g_param_spec_ulong: + * @name: canonical name of the property specified + * @nick: nick name for the property specified + * @blurb: description of the property specified + * @minimum: minimum value for the property specified + * @maximum: maximum value for the property specified + * @default_value: default value for the property specified + * @flags: flags for the property specified + * + * Creates a new #GParamSpecULong instance specifying a %G_TYPE_ULONG property. + * + * See g_param_spec_internal() for details on property names. + * + * Returns: a newly created parameter specification + */ GParamSpec* g_param_spec_ulong (const gchar *name, const gchar *nick, @@ -1671,6 +1794,22 @@ g_param_spec_ulong (const gchar *name, return G_PARAM_SPEC (uspec); } +/** + * g_param_spec_int64: + * @name: canonical name of the property specified + * @nick: nick name for the property specified + * @blurb: description of the property specified + * @minimum: minimum value for the property specified + * @maximum: maximum value for the property specified + * @default_value: default value for the property specified + * @flags: flags for the property specified + * + * Creates a new #GParamSpecInt64 instance specifying a %G_TYPE_INT64 property. + * + * See g_param_spec_internal() for details on property names. + * + * Returns: a newly created parameter specification + */ GParamSpec* g_param_spec_int64 (const gchar *name, const gchar *nick, @@ -1697,6 +1836,23 @@ g_param_spec_int64 (const gchar *name, return G_PARAM_SPEC (lspec); } +/** + * g_param_spec_uint64: + * @name: canonical name of the property specified + * @nick: nick name for the property specified + * @blurb: description of the property specified + * @minimum: minimum value for the property specified + * @maximum: maximum value for the property specified + * @default_value: default value for the property specified + * @flags: flags for the property specified + * + * Creates a new #GParamSpecUInt64 instance specifying a %G_TYPE_UINT64 + * property. + * + * See g_param_spec_internal() for details on property names. + * + * Returns: a newly created parameter specification + */ GParamSpec* g_param_spec_uint64 (const gchar *name, const gchar *nick, @@ -1723,6 +1879,22 @@ g_param_spec_uint64 (const gchar *name, return G_PARAM_SPEC (uspec); } +/** + * g_param_spec_unichar: + * @name: canonical name of the property specified + * @nick: nick name for the property specified + * @blurb: description of the property specified + * @default_value: default value for the property specified + * @flags: flags for the property specified + * + * Creates a new #GParamSpecUnichar instance specifying a %G_TYPE_UINT + * property. #GValue structures for this property can be accessed with + * g_value_set_uint() and g_value_get_uint(). + * + * See g_param_spec_internal() for details on property names. + * + * Returns: a newly created parameter specification + */ GParamSpec* g_param_spec_unichar (const gchar *name, const gchar *nick, @@ -1743,6 +1915,22 @@ g_param_spec_unichar (const gchar *name, return G_PARAM_SPEC (uspec); } +/** + * g_param_spec_enum: + * @name: canonical name of the property specified + * @nick: nick name for the property specified + * @blurb: description of the property specified + * @enum_type: a #GType derived from %G_TYPE_ENUM + * @default_value: default value for the property specified + * @flags: flags for the property specified + * + * Creates a new #GParamSpecEnum instance specifying a %G_TYPE_ENUM + * property. + * + * See g_param_spec_internal() for details on property names. + * + * Returns: a newly created parameter specification + */ GParamSpec* g_param_spec_enum (const gchar *name, const gchar *nick, @@ -1773,6 +1961,22 @@ g_param_spec_enum (const gchar *name, return G_PARAM_SPEC (espec); } +/** + * g_param_spec_flags: + * @name: canonical name of the property specified + * @nick: nick name for the property specified + * @blurb: description of the property specified + * @flags_type: a #GType derived from %G_TYPE_FLAGS + * @default_value: default value for the property specified + * @flags: flags for the property specified + * + * Creates a new #GParamSpecFlags instance specifying a %G_TYPE_FLAGS + * property. + * + * See g_param_spec_internal() for details on property names. + * + * Returns: a newly created parameter specification + */ GParamSpec* g_param_spec_flags (const gchar *name, const gchar *nick, @@ -1803,6 +2007,22 @@ g_param_spec_flags (const gchar *name, return G_PARAM_SPEC (fspec); } +/** + * g_param_spec_float: + * @name: canonical name of the property specified + * @nick: nick name for the property specified + * @blurb: description of the property specified + * @minimum: minimum value for the property specified + * @maximum: maximum value for the property specified + * @default_value: default value for the property specified + * @flags: flags for the property specified + * + * Creates a new #GParamSpecFloat instance specifying a %G_TYPE_FLOAT property. + * + * See g_param_spec_internal() for details on property names. + * + * Returns: a newly created parameter specification + */ GParamSpec* g_param_spec_float (const gchar *name, const gchar *nick, @@ -1829,6 +2049,23 @@ g_param_spec_float (const gchar *name, return G_PARAM_SPEC (fspec); } +/** + * g_param_spec_double: + * @name: canonical name of the property specified + * @nick: nick name for the property specified + * @blurb: description of the property specified + * @minimum: minimum value for the property specified + * @maximum: maximum value for the property specified + * @default_value: default value for the property specified + * @flags: flags for the property specified + * + * Creates a new #GParamSpecDouble instance specifying a %G_TYPE_DOUBLE + * property. + * + * See g_param_spec_internal() for details on property names. + * + * Returns: a newly created parameter specification + */ GParamSpec* g_param_spec_double (const gchar *name, const gchar *nick, @@ -1855,6 +2092,20 @@ g_param_spec_double (const gchar *name, return G_PARAM_SPEC (dspec); } +/** + * g_param_spec_string: + * @name: canonical name of the property specified + * @nick: nick name for the property specified + * @blurb: description of the property specified + * @default_value: default value for the property specified + * @flags: flags for the property specified + * + * Creates a new #GParamSpecString instance. + * + * See g_param_spec_internal() for details on property names. + * + * Returns: a newly created parameter specification + */ GParamSpec* g_param_spec_string (const gchar *name, const gchar *nick, @@ -1873,6 +2124,21 @@ g_param_spec_string (const gchar *name, return G_PARAM_SPEC (sspec); } +/** + * g_param_spec_param: + * @name: canonical name of the property specified + * @nick: nick name for the property specified + * @blurb: description of the property specified + * @param_type: a #GType derived from %G_TYPE_PARAM + * @flags: flags for the property specified + * + * Creates a new #GParamSpecParam instance specifying a %G_TYPE_PARAM + * property. + * + * See g_param_spec_internal() for details on property names. + * + * Returns: a newly created parameter specification + */ GParamSpec* g_param_spec_param (const gchar *name, const gchar *nick, @@ -1894,6 +2160,21 @@ g_param_spec_param (const gchar *name, return G_PARAM_SPEC (pspec); } +/** + * g_param_spec_boxed: + * @name: canonical name of the property specified + * @nick: nick name for the property specified + * @blurb: description of the property specified + * @boxed_type: %G_TYPE_BOXED derived type of this property + * @flags: flags for the property specified + * + * Creates a new #GParamSpecBoxed instance specifying a %G_TYPE_BOXED + * derived property. + * + * See g_param_spec_internal() for details on property names. + * + * Returns: a newly created parameter specification + */ GParamSpec* g_param_spec_boxed (const gchar *name, const gchar *nick, @@ -1916,6 +2197,19 @@ g_param_spec_boxed (const gchar *name, return G_PARAM_SPEC (bspec); } +/** + * g_param_spec_pointer: + * @name: canonical name of the property specified + * @nick: nick name for the property specified + * @blurb: description of the property specified + * @flags: flags for the property specified + * + * Creates a new #GParamSpecPoiner instance specifying a pointer property. + * + * See g_param_spec_internal() for details on property names. + * + * Returns: a newly created parameter specification + */ GParamSpec* g_param_spec_pointer (const gchar *name, const gchar *nick, @@ -1932,6 +2226,23 @@ g_param_spec_pointer (const gchar *name, return G_PARAM_SPEC (pspec); } +/** + * g_param_spec_gtype: + * @name: canonical name of the property specified + * @nick: nick name for the property specified + * @blurb: description of the property specified + * @is_a_type: a #GType whose subtypes are allowed as values + * of the property (use %G_TYPE_NONE for any type) + * @flags: flags for the property specified + * + * Creates a new #GParamSpecGType instance specifying a + * %G_TYPE_GTYPE property. + * + * See g_param_spec_internal() for details on property names. + * + * Since: 2.10 + * Returns: a newly created parameter specification + */ GParamSpec* g_param_spec_gtype (const gchar *name, const gchar *nick, @@ -1952,6 +2263,24 @@ g_param_spec_gtype (const gchar *name, return G_PARAM_SPEC (tspec); } +/** + * g_param_spec_value_array: + * @name: canonical name of the property specified + * @nick: nick name for the property specified + * @blurb: description of the property specified + * @element_spec: a #GParamSpec describing the elements contained in + * arrays of this property, may be %NULL + * @flags: flags for the property specified + * + * Creates a new #GParamSpecValueArray instance specifying a + * %G_TYPE_VALUE_ARRAY property. %G_TYPE_VALUE_ARRAY is a %G_TYPE_BOXED + * type, as such, #GValue structures for this property can be accessed + * with g_value_set_boxed() and g_value_get_boxed(). + * + * See g_param_spec_internal() for details on property names. + * + * Returns: a newly created parameter specification + */ GParamSpec* g_param_spec_value_array (const gchar *name, const gchar *nick, @@ -1978,6 +2307,21 @@ g_param_spec_value_array (const gchar *name, return G_PARAM_SPEC (aspec); } +/** + * g_param_spec_object: + * @name: canonical name of the property specified + * @nick: nick name for the property specified + * @blurb: description of the property specified + * @object_type: %G_TYPE_OBJECT derived type of this property + * @flags: flags for the property specified + * + * Creates a new #GParamSpecBoxed instance specifying a %G_TYPE_OBJECT + * derived property. + * + * See g_param_spec_internal() for details on property names. + * + * Returns: a newly created parameter specification + */ GParamSpec* g_param_spec_object (const gchar *name, const gchar *nick, @@ -1999,6 +2343,18 @@ g_param_spec_object (const gchar *name, return G_PARAM_SPEC (ospec); } +/** + * g_param_spec_override: + * @name: the name of the property. + * @overridden: The property that is being overridden + * + * Creates a new property of type #GParamSpecOverride. This is used + * to direct operations to another paramspec, and will not be directly + * useful unless you are implementing a new base type similar to GObject. + * + * Since: 2.4 + * Returns: the newly created #GParamSpec + */ GParamSpec* g_param_spec_override (const gchar *name, GParamSpec *overridden) diff --git a/gobject/gparamspecs.h b/gobject/gparamspecs.h index b6add1cbf..345db03fd 100644 --- a/gobject/gparamspecs.h +++ b/gobject/gparamspecs.h @@ -33,71 +33,520 @@ G_BEGIN_DECLS /* --- type macros --- */ +/** + * G_TYPE_PARAM_CHAR: + * + * The #GType of #GParamSpecChar. + */ #define G_TYPE_PARAM_CHAR (g_param_spec_types[0]) +/** + * G_IS_PARAM_SPEC_CHAR: + * @pspec: a valid #GParamSpec instance + * + * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_CHAR. + * + * Returns: %TRUE on success. + */ #define G_IS_PARAM_SPEC_CHAR(pspec) (G_TYPE_CHECK_INSTANCE_TYPE ((pspec), G_TYPE_PARAM_CHAR)) +/** + * G_PARAM_SPEC_CHAR: + * @pspec: a valid #GParamSpec instance + * + * Cast a #GParamSpec instance into a #GParamSpecChar. + */ #define G_PARAM_SPEC_CHAR(pspec) (G_TYPE_CHECK_INSTANCE_CAST ((pspec), G_TYPE_PARAM_CHAR, GParamSpecChar)) + +/** + * G_TYPE_PARAM_UCHAR: + * + * The #GType of #GParamSpecUChar. + */ #define G_TYPE_PARAM_UCHAR (g_param_spec_types[1]) +/** + * G_IS_PARAM_SPEC_UCHAR: + * @pspec: a valid #GParamSpec instance + * + * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_UCHAR. + * + * Returns: %TRUE on success. + */ #define G_IS_PARAM_SPEC_UCHAR(pspec) (G_TYPE_CHECK_INSTANCE_TYPE ((pspec), G_TYPE_PARAM_UCHAR)) +/** + * G_PARAM_SPEC_UCHAR: + * @pspec: a valid #GParamSpec instance + * + * Cast a #GParamSpec instance into a #GParamSpecUChar. + */ #define G_PARAM_SPEC_UCHAR(pspec) (G_TYPE_CHECK_INSTANCE_CAST ((pspec), G_TYPE_PARAM_UCHAR, GParamSpecUChar)) + +/** + * G_TYPE_PARAM_BOOLEAN: + * + * The #GType of #GParamSpecBoolean. + */ #define G_TYPE_PARAM_BOOLEAN (g_param_spec_types[2]) +/** + * G_IS_PARAM_SPEC_BOOLEAN: + * @pspec: a valid #GParamSpec instance + * + * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_BOOLEAN. + * + * Returns: %TRUE on success. + */ #define G_IS_PARAM_SPEC_BOOLEAN(pspec) (G_TYPE_CHECK_INSTANCE_TYPE ((pspec), G_TYPE_PARAM_BOOLEAN)) +/** + * G_PARAM_SPEC_BOOLEAN: + * @pspec: a valid #GParamSpec instance + * + * Cast a #GParamSpec instance into a #GParamSpecBoolean. + */ #define G_PARAM_SPEC_BOOLEAN(pspec) (G_TYPE_CHECK_INSTANCE_CAST ((pspec), G_TYPE_PARAM_BOOLEAN, GParamSpecBoolean)) + +/** + * G_TYPE_PARAM_INT: + * + * The #GType of #GParamSpecInt. + */ #define G_TYPE_PARAM_INT (g_param_spec_types[3]) +/** + * G_IS_PARAM_SPEC_INT: + * @pspec: a valid #GParamSpec instance + * + * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_INT. + * + * Returns: %TRUE on success. + */ #define G_IS_PARAM_SPEC_INT(pspec) (G_TYPE_CHECK_INSTANCE_TYPE ((pspec), G_TYPE_PARAM_INT)) +/** + * G_PARAM_SPEC_INT: + * @pspec: a valid #GParamSpec instance + * + * Cast a #GParamSpec instance into a #GParamSpecInt. + */ #define G_PARAM_SPEC_INT(pspec) (G_TYPE_CHECK_INSTANCE_CAST ((pspec), G_TYPE_PARAM_INT, GParamSpecInt)) + +/** + * G_TYPE_PARAM_UINT: + * + * The #GType of #GParamSpecUInt. + */ #define G_TYPE_PARAM_UINT (g_param_spec_types[4]) +/** + * G_IS_PARAM_SPEC_UINT: + * @pspec: a valid #GParamSpec instance + * + * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_UINT. + * + * Returns: %TRUE on success. + */ #define G_IS_PARAM_SPEC_UINT(pspec) (G_TYPE_CHECK_INSTANCE_TYPE ((pspec), G_TYPE_PARAM_UINT)) +/** + * G_PARAM_SPEC_UINT: + * @pspec: a valid #GParamSpec instance + * + * Cast a #GParamSpec instance into a #GParamSpecUInt. + */ #define G_PARAM_SPEC_UINT(pspec) (G_TYPE_CHECK_INSTANCE_CAST ((pspec), G_TYPE_PARAM_UINT, GParamSpecUInt)) + +/** + * G_TYPE_PARAM_LONG: + * + * The #GType of #GParamSpecLong. + */ #define G_TYPE_PARAM_LONG (g_param_spec_types[5]) +/** + * G_IS_PARAM_SPEC_LONG: + * @pspec: a valid #GParamSpec instance + * + * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_LONG. + * + * Returns: %TRUE on success. + */ #define G_IS_PARAM_SPEC_LONG(pspec) (G_TYPE_CHECK_INSTANCE_TYPE ((pspec), G_TYPE_PARAM_LONG)) +/** + * G_PARAM_SPEC_LONG: + * @pspec: a valid #GParamSpec instance + * + * Cast a #GParamSpec instance into a #GParamSpecLong. + */ #define G_PARAM_SPEC_LONG(pspec) (G_TYPE_CHECK_INSTANCE_CAST ((pspec), G_TYPE_PARAM_LONG, GParamSpecLong)) + +/** + * G_TYPE_PARAM_ULONG: + * + * The #GType of #GParamSpecULong. + */ #define G_TYPE_PARAM_ULONG (g_param_spec_types[6]) +/** + * G_IS_PARAM_SPEC_ULONG: + * @pspec: a valid #GParamSpec instance + * + * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_ULONG. + * + * Returns: %TRUE on success. + */ #define G_IS_PARAM_SPEC_ULONG(pspec) (G_TYPE_CHECK_INSTANCE_TYPE ((pspec), G_TYPE_PARAM_ULONG)) +/** + * G_PARAM_SPEC_ULONG: + * @pspec: a valid #GParamSpec instance + * + * Cast a #GParamSpec instance into a #GParamSpecULong. + */ #define G_PARAM_SPEC_ULONG(pspec) (G_TYPE_CHECK_INSTANCE_CAST ((pspec), G_TYPE_PARAM_ULONG, GParamSpecULong)) + +/** + * G_TYPE_PARAM_INT64: + * + * The #GType of #GParamSpecInt64. + */ #define G_TYPE_PARAM_INT64 (g_param_spec_types[7]) +/** + * G_IS_PARAM_SPEC_INT64: + * @pspec: a valid #GParamSpec instance + * + * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_INT64. + * + * Returns: %TRUE on success. + */ #define G_IS_PARAM_SPEC_INT64(pspec) (G_TYPE_CHECK_INSTANCE_TYPE ((pspec), G_TYPE_PARAM_INT64)) +/** + * G_PARAM_SPEC_INT64: + * @pspec: a valid #GParamSpec instance + * + * Cast a #GParamSpec instance into a #GParamSpecInt64. + */ #define G_PARAM_SPEC_INT64(pspec) (G_TYPE_CHECK_INSTANCE_CAST ((pspec), G_TYPE_PARAM_INT64, GParamSpecInt64)) + +/** + * G_TYPE_PARAM_UINT64: + * + * The #GType of #GParamSpecUInt64. + */ #define G_TYPE_PARAM_UINT64 (g_param_spec_types[8]) +/** + * G_IS_PARAM_SPEC_UINT64: + * @pspec: a valid #GParamSpec instance + * + * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_UINT64. + * + * Returns: %TRUE on success. + */ #define G_IS_PARAM_SPEC_UINT64(pspec) (G_TYPE_CHECK_INSTANCE_TYPE ((pspec), G_TYPE_PARAM_UINT64)) +/** + * G_PARAM_SPEC_UINT64: + * @pspec: a valid #GParamSpec instance + * + * Cast a #GParamSpec instance into a #GParamSpecUInt64. + */ #define G_PARAM_SPEC_UINT64(pspec) (G_TYPE_CHECK_INSTANCE_CAST ((pspec), G_TYPE_PARAM_UINT64, GParamSpecUInt64)) + +/** + * G_TYPE_PARAM_UNICHAR: + * + * The #GType of #GParamSpecUnichar. + */ #define G_TYPE_PARAM_UNICHAR (g_param_spec_types[9]) +/** + * G_PARAM_SPEC_UNICHAR: + * @pspec: a valid #GParamSpec instance + * + * Cast a #GParamSpec instance into a #GParamSpecUnichar. + */ #define G_PARAM_SPEC_UNICHAR(pspec) (G_TYPE_CHECK_INSTANCE_CAST ((pspec), G_TYPE_PARAM_UNICHAR, GParamSpecUnichar)) +/** + * G_IS_PARAM_SPEC_UNICHAR: + * @pspec: a valid #GParamSpec instance + * + * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_UNICHAR. + * + * Returns: %TRUE on success. + */ #define G_IS_PARAM_SPEC_UNICHAR(pspec) (G_TYPE_CHECK_INSTANCE_TYPE ((pspec), G_TYPE_PARAM_UNICHAR)) + +/** + * G_TYPE_PARAM_ENUM: + * + * The #GType of #GParamSpecEnum. + */ #define G_TYPE_PARAM_ENUM (g_param_spec_types[10]) +/** + * G_IS_PARAM_SPEC_ENUM: + * @pspec: a valid #GParamSpec instance + * + * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_ENUM. + * + * Returns: %TRUE on success. + */ #define G_IS_PARAM_SPEC_ENUM(pspec) (G_TYPE_CHECK_INSTANCE_TYPE ((pspec), G_TYPE_PARAM_ENUM)) +/** + * G_PARAM_SPEC_ENUM: + * @pspec: a valid #GParamSpec instance + * + * Cast a #GParamSpec instance into a #GParamSpecEnum. + */ #define G_PARAM_SPEC_ENUM(pspec) (G_TYPE_CHECK_INSTANCE_CAST ((pspec), G_TYPE_PARAM_ENUM, GParamSpecEnum)) + +/** + * G_TYPE_PARAM_FLAGS: + * + * The #GType of #GParamSpecFlags. + */ #define G_TYPE_PARAM_FLAGS (g_param_spec_types[11]) +/** + * G_IS_PARAM_SPEC_FLAGS: + * @pspec: a valid #GParamSpec instance + * + * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_FLAGS. + * + * Returns: %TRUE on success. + */ #define G_IS_PARAM_SPEC_FLAGS(pspec) (G_TYPE_CHECK_INSTANCE_TYPE ((pspec), G_TYPE_PARAM_FLAGS)) +/** + * G_PARAM_SPEC_FLAGS: + * @pspec: a valid #GParamSpec instance + * + * Cast a #GParamSpec instance into a #GParamSpecFlags. + */ #define G_PARAM_SPEC_FLAGS(pspec) (G_TYPE_CHECK_INSTANCE_CAST ((pspec), G_TYPE_PARAM_FLAGS, GParamSpecFlags)) + +/** + * G_TYPE_PARAM_FLOAT: + * + * The #GType of #GParamSpecFloat. + */ #define G_TYPE_PARAM_FLOAT (g_param_spec_types[12]) +/** + * G_IS_PARAM_SPEC_FLOAT: + * @pspec: a valid #GParamSpec instance + * + * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_FLOAT. + * + * Returns: %TRUE on success. + */ #define G_IS_PARAM_SPEC_FLOAT(pspec) (G_TYPE_CHECK_INSTANCE_TYPE ((pspec), G_TYPE_PARAM_FLOAT)) +/** + * G_PARAM_SPEC_FLOAT: + * @pspec: a valid #GParamSpec instance + * + * Cast a #GParamSpec instance into a #GParamSpecFloat. + */ #define G_PARAM_SPEC_FLOAT(pspec) (G_TYPE_CHECK_INSTANCE_CAST ((pspec), G_TYPE_PARAM_FLOAT, GParamSpecFloat)) + +/** + * G_TYPE_PARAM_DOUBLE: + * + * The #GType of #GParamSpecDouble. + */ #define G_TYPE_PARAM_DOUBLE (g_param_spec_types[13]) +/** + * G_IS_PARAM_SPEC_DOUBLE: + * @pspec: a valid #GParamSpec instance + * + * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_DOUBLE. + * + * Returns: %TRUE on success. + */ #define G_IS_PARAM_SPEC_DOUBLE(pspec) (G_TYPE_CHECK_INSTANCE_TYPE ((pspec), G_TYPE_PARAM_DOUBLE)) +/** + * G_PARAM_SPEC_DOUBLE: + * @pspec: a valid #GParamSpec instance + * + * Cast a #GParamSpec instance into a #GParamSpecDouble. + */ #define G_PARAM_SPEC_DOUBLE(pspec) (G_TYPE_CHECK_INSTANCE_CAST ((pspec), G_TYPE_PARAM_DOUBLE, GParamSpecDouble)) + +/** + * G_TYPE_PARAM_STRING: + * + * The #GType of #GParamSpecString. + */ #define G_TYPE_PARAM_STRING (g_param_spec_types[14]) +/** + * G_IS_PARAM_SPEC_STRING: + * @pspec: a valid #GParamSpec instance + * + * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_STRING. + * + * Returns: %TRUE on success. + */ #define G_IS_PARAM_SPEC_STRING(pspec) (G_TYPE_CHECK_INSTANCE_TYPE ((pspec), G_TYPE_PARAM_STRING)) +/** + * G_PARAM_SPEC_STRING: + * @pspec: a valid #GParamSpec instance + * + * Casts a #GParamSpec instance into a #GParamSpecString. + */ #define G_PARAM_SPEC_STRING(pspec) (G_TYPE_CHECK_INSTANCE_CAST ((pspec), G_TYPE_PARAM_STRING, GParamSpecString)) + +/** + * G_TYPE_PARAM_PARAM: + * + * The #GType of #GParamSpecParam. + */ #define G_TYPE_PARAM_PARAM (g_param_spec_types[15]) +/** + * G_IS_PARAM_SPEC_PARAM: + * @pspec: a valid #GParamSpec instance + * + * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_PARAM. + * + * Returns: %TRUE on success. + */ #define G_IS_PARAM_SPEC_PARAM(pspec) (G_TYPE_CHECK_INSTANCE_TYPE ((pspec), G_TYPE_PARAM_PARAM)) +/** + * G_PARAM_SPEC_PARAM: + * @pspec: a valid #GParamSpec instance + * + * Casts a #GParamSpec instance into a #GParamSpecParam. + */ #define G_PARAM_SPEC_PARAM(pspec) (G_TYPE_CHECK_INSTANCE_CAST ((pspec), G_TYPE_PARAM_PARAM, GParamSpecParam)) + +/** + * G_TYPE_PARAM_BOXED: + * + * The #GType of #GParamSpecBoxed. + */ #define G_TYPE_PARAM_BOXED (g_param_spec_types[16]) +/** + * G_IS_PARAM_SPEC_BOXED: + * @pspec: a valid #GParamSpec instance + * + * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_BOXED. + * + * Returns: %TRUE on success. + */ #define G_IS_PARAM_SPEC_BOXED(pspec) (G_TYPE_CHECK_INSTANCE_TYPE ((pspec), G_TYPE_PARAM_BOXED)) +/** + * G_PARAM_SPEC_BOXED: + * @pspec: a valid #GParamSpec instance + * + * Cast a #GParamSpec instance into a #GParamSpecBoxed. + */ #define G_PARAM_SPEC_BOXED(pspec) (G_TYPE_CHECK_INSTANCE_CAST ((pspec), G_TYPE_PARAM_BOXED, GParamSpecBoxed)) + +/** + * G_TYPE_PARAM_POINTER: + * + * The #GType of #GParamSpecPointer. + */ #define G_TYPE_PARAM_POINTER (g_param_spec_types[17]) +/** + * G_IS_PARAM_SPEC_POINTER: + * @pspec: a valid #GParamSpec instance + * + * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_POINTER. + * + * Returns: %TRUE on success. + */ #define G_IS_PARAM_SPEC_POINTER(pspec) (G_TYPE_CHECK_INSTANCE_TYPE ((pspec), G_TYPE_PARAM_POINTER)) +/** + * G_PARAM_SPEC_POINTER: + * @pspec: a valid #GParamSpec instance + * + * Casts a #GParamSpec instance into a #GParamSpecPointer. + */ #define G_PARAM_SPEC_POINTER(pspec) (G_TYPE_CHECK_INSTANCE_CAST ((pspec), G_TYPE_PARAM_POINTER, GParamSpecPointer)) + +/** + * G_TYPE_PARAM_VALUE_ARRAY: + * + * The #GType of #GParamSpecValueArray. + */ #define G_TYPE_PARAM_VALUE_ARRAY (g_param_spec_types[18]) +/** + * G_IS_PARAM_SPEC_VALUE_ARRAY: + * @pspec: a valid #GParamSpec instance + * + * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_VALUE_ARRAY. + * + * Returns: %TRUE on success. + */ #define G_IS_PARAM_SPEC_VALUE_ARRAY(pspec) (G_TYPE_CHECK_INSTANCE_TYPE ((pspec), G_TYPE_PARAM_VALUE_ARRAY)) +/** + * G_PARAM_SPEC_VALUE_ARRAY: + * @pspec: a valid #GParamSpec instance + * + * Cast a #GParamSpec instance into a #GParamSpecValueArray. + */ #define G_PARAM_SPEC_VALUE_ARRAY(pspec) (G_TYPE_CHECK_INSTANCE_CAST ((pspec), G_TYPE_PARAM_VALUE_ARRAY, GParamSpecValueArray)) + +/** + * G_TYPE_PARAM_OBJECT: + * + * The #GType of #GParamSpecObject. + */ #define G_TYPE_PARAM_OBJECT (g_param_spec_types[19]) +/** + * G_IS_PARAM_SPEC_OBJECT: + * @pspec: a valid #GParamSpec instance + * + * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_OBJECT. + * + * Returns: %TRUE on success. + */ #define G_IS_PARAM_SPEC_OBJECT(pspec) (G_TYPE_CHECK_INSTANCE_TYPE ((pspec), G_TYPE_PARAM_OBJECT)) +/** + * G_PARAM_SPEC_OBJECT: + * @pspec: a valid #GParamSpec instance + * + * Casts a #GParamSpec instance into a #GParamSpecObject. + */ #define G_PARAM_SPEC_OBJECT(pspec) (G_TYPE_CHECK_INSTANCE_CAST ((pspec), G_TYPE_PARAM_OBJECT, GParamSpecObject)) + +/** + * G_TYPE_PARAM_OVERRIDE: + * + * The #GType of #GParamSpecOverride. + * + * Since: 2.4 + */ #define G_TYPE_PARAM_OVERRIDE (g_param_spec_types[20]) +/** + * G_IS_PARAM_SPEC_OVERRIDE: + * @pspec: a #GParamSpec + * + * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_OVERRIDE. + * + * Since: 2.4 + * Returns: %TRUE on success. + */ #define G_IS_PARAM_SPEC_OVERRIDE(pspec) (G_TYPE_CHECK_INSTANCE_TYPE ((pspec), G_TYPE_PARAM_OVERRIDE)) +/** + * G_PARAM_SPEC_OVERRIDE: + * @pspec: a #GParamSpec + * + * Casts a #GParamSpec into a #GParamSpecOverride. + * + * Since: 2.4 + */ #define G_PARAM_SPEC_OVERRIDE(pspec) (G_TYPE_CHECK_INSTANCE_CAST ((pspec), G_TYPE_PARAM_OVERRIDE, GParamSpecOverride)) + +/** + * G_TYPE_PARAM_GTYPE: + * + * The #GType of #GParamSpecGType. + * + * Since: 2.10 + */ #define G_TYPE_PARAM_GTYPE (g_param_spec_types[21]) +/** + * G_IS_PARAM_SPEC_GTYPE: + * @pspec: a #GParamSpec + * + * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_GTYPE. + * + * Since: 2.10 + * Returns: %TRUE on success. + */ #define G_IS_PARAM_SPEC_GTYPE(pspec) (G_TYPE_CHECK_INSTANCE_TYPE ((pspec), G_TYPE_PARAM_GTYPE)) +/** + * G_PARAM_SPEC_GTYPE: + * @pspec: a #GParamSpec + * + * Casts a #GParamSpec into a #GParamSpecGType. + * + * Since: 2.10 + */ #define G_PARAM_SPEC_GTYPE(pspec) (G_TYPE_CHECK_INSTANCE_CAST ((pspec), G_TYPE_PARAM_GTYPE, GParamSpecGType)) @@ -125,6 +574,15 @@ typedef struct _GParamSpecObject GParamSpecObject; typedef struct _GParamSpecOverride GParamSpecOverride; typedef struct _GParamSpecGType GParamSpecGType; +/** + * GParamSpecChar: + * @parent_instance: private #GParamSpec portion + * @minimum: minimum value for the property specified + * @maximum: maximum value for the property specified + * @default_value: default value for the property specified + * + * A #GParamSpec derived structure that contains the meta data for character properties. + */ struct _GParamSpecChar { GParamSpec parent_instance; @@ -133,6 +591,15 @@ struct _GParamSpecChar gint8 maximum; gint8 default_value; }; +/** + * GParamSpecUChar: + * @parent_instance: private #GParamSpec portion + * @minimum: minimum value for the property specified + * @maximum: maximum value for the property specified + * @default_value: default value for the property specified + * + * A #GParamSpec derived structure that contains the meta data for unsigned character properties. + */ struct _GParamSpecUChar { GParamSpec parent_instance; @@ -141,12 +608,28 @@ struct _GParamSpecUChar guint8 maximum; guint8 default_value; }; +/** + * GParamSpecBoolean: + * @parent_instance: private #GParamSpec portion + * @default_value: default value for the property specified + * + * A #GParamSpec derived structure that contains the meta data for boolean properties. + */ struct _GParamSpecBoolean { GParamSpec parent_instance; gboolean default_value; }; +/** + * GParamSpecInt: + * @parent_instance: private #GParamSpec portion + * @minimum: minimum value for the property specified + * @maximum: maximum value for the property specified + * @default_value: default value for the property specified + * + * A #GParamSpec derived structure that contains the meta data for integer properties. + */ struct _GParamSpecInt { GParamSpec parent_instance; @@ -155,6 +638,15 @@ struct _GParamSpecInt gint maximum; gint default_value; }; +/** + * GParamSpecUInt: + * @parent_instance: private #GParamSpec portion + * @minimum: minimum value for the property specified + * @maximum: maximum value for the property specified + * @default_value: default value for the property specified + * + * A #GParamSpec derived structure that contains the meta data for unsigned integer properties. + */ struct _GParamSpecUInt { GParamSpec parent_instance; @@ -163,6 +655,15 @@ struct _GParamSpecUInt guint maximum; guint default_value; }; +/** + * GParamSpecLong: + * @parent_instance: private #GParamSpec portion + * @minimum: minimum value for the property specified + * @maximum: maximum value for the property specified + * @default_value: default value for the property specified + * + * A #GParamSpec derived structure that contains the meta data for long integer properties. + */ struct _GParamSpecLong { GParamSpec parent_instance; @@ -171,6 +672,15 @@ struct _GParamSpecLong glong maximum; glong default_value; }; +/** + * GParamSpecULong: + * @parent_instance: private #GParamSpec portion + * @minimum: minimum value for the property specified + * @maximum: maximum value for the property specified + * @default_value: default value for the property specified + * + * A #GParamSpec derived structure that contains the meta data for unsigned long integer properties. + */ struct _GParamSpecULong { GParamSpec parent_instance; @@ -179,6 +689,15 @@ struct _GParamSpecULong gulong maximum; gulong default_value; }; +/** + * GParamSpecInt64: + * @parent_instance: private #GParamSpec portion + * @minimum: minimum value for the property specified + * @maximum: maximum value for the property specified + * @default_value: default value for the property specified + * + * A #GParamSpec derived structure that contains the meta data for 64bit integer properties. + */ struct _GParamSpecInt64 { GParamSpec parent_instance; @@ -187,6 +706,15 @@ struct _GParamSpecInt64 gint64 maximum; gint64 default_value; }; +/** + * GParamSpecUInt64: + * @parent_instance: private #GParamSpec portion + * @minimum: minimum value for the property specified + * @maximum: maximum value for the property specified + * @default_value: default value for the property specified + * + * A #GParamSpec derived structure that contains the meta data for unsigned 64bit integer properties. + */ struct _GParamSpecUInt64 { GParamSpec parent_instance; @@ -195,12 +723,28 @@ struct _GParamSpecUInt64 guint64 maximum; guint64 default_value; }; +/** + * GParamSpecUnichar: + * @parent_instance: private #GParamSpec portion + * @default_value: default value for the property specified + * + * A #GParamSpec derived structure that contains the meta data for unichar (unsigned integer) properties. + */ struct _GParamSpecUnichar { GParamSpec parent_instance; gunichar default_value; }; +/** + * GParamSpecEnum: + * @parent_instance: private #GParamSpec portion + * @enum_class: the #GEnumClass for the enum + * @default_value: default value for the property specified + * + * A #GParamSpec derived structure that contains the meta data for enum + * properties. + */ struct _GParamSpecEnum { GParamSpec parent_instance; @@ -208,6 +752,15 @@ struct _GParamSpecEnum GEnumClass *enum_class; gint default_value; }; +/** + * GParamSpecFlags: + * @parent_instance: private #GParamSpec portion + * @flags_class: the #GFlagsClass for the flags + * @default_value: default value for the property specified + * + * A #GParamSpec derived structure that contains the meta data for flags + * properties. + */ struct _GParamSpecFlags { GParamSpec parent_instance; @@ -215,6 +768,17 @@ struct _GParamSpecFlags GFlagsClass *flags_class; guint default_value; }; +/** + * GParamSpecFloat: + * @parent_instance: private #GParamSpec portion + * @minimum: minimum value for the property specified + * @maximum: maximum value for the property specified + * @default_value: default value for the property specified + * @epsilon: values closer than @epsilon will be considered identical + * by g_param_values_cmp(); the default value is 1e-30. + * + * A #GParamSpec derived structure that contains the meta data for float properties. + */ struct _GParamSpecFloat { GParamSpec parent_instance; @@ -224,6 +788,17 @@ struct _GParamSpecFloat gfloat default_value; gfloat epsilon; }; +/** + * GParamSpecDouble: + * @parent_instance: private #GParamSpec portion + * @minimum: minimum value for the property specified + * @maximum: maximum value for the property specified + * @default_value: default value for the property specified + * @epsilon: values closer than @epsilon will be considered identical + * by g_param_values_cmp(); the default value is 1e-90. + * + * A #GParamSpec derived structure that contains the meta data for double properties. + */ struct _GParamSpecDouble { GParamSpec parent_instance; @@ -233,6 +808,19 @@ struct _GParamSpecDouble gdouble default_value; gdouble epsilon; }; +/** + * GParamSpecString: + * @parent_instance: private #GParamSpec portion + * @default_value: default value for the property specified + * @cset_first: a string containing the allowed values for the first byte + * @cset_nth: a string containing the allowed values for the subsequent bytes + * @substitutor: the replacement byte for bytes which don't match @cset_first or @cset_nth. + * @null_fold_if_empty: replace empty string by %NULL + * @ensure_non_null: replace %NULL strings by an empty string + * + * A #GParamSpec derived structure that contains the meta data for string + * properties. + */ struct _GParamSpecString { GParamSpec parent_instance; @@ -244,34 +832,90 @@ struct _GParamSpecString guint null_fold_if_empty : 1; guint ensure_non_null : 1; }; +/** + * GParamSpecParam: + * @parent_instance: private #GParamSpec portion + * + * A #GParamSpec derived structure that contains the meta data for %G_TYPE_PARAM + * properties. + */ struct _GParamSpecParam { GParamSpec parent_instance; }; +/** + * GParamSpecBoxed: + * @parent_instance: private #GParamSpec portion + * + * A #GParamSpec derived structure that contains the meta data for boxed properties. + */ struct _GParamSpecBoxed { GParamSpec parent_instance; }; +/** + * GParamSpecPointer: + * @parent_instance: private #GParamSpec portion + * + * A #GParamSpec derived structure that contains the meta data for pointer properties. + */ struct _GParamSpecPointer { GParamSpec parent_instance; }; +/** + * GParamSpecValueArray: + * @parent_instance: private #GParamSpec portion + * @element_spec: a #GParamSpec describing the elements contained in arrays of this property, may be %NULL + * @fixed_n_elements: if greater than 0, arrays of this property will always have this many elements + * + * A #GParamSpec derived structure that contains the meta data for #GValueArray properties. + */ struct _GParamSpecValueArray { GParamSpec parent_instance; GParamSpec *element_spec; guint fixed_n_elements; }; +/** + * GParamSpecObject: + * @parent_instance: private #GParamSpec portion + * + * A #GParamSpec derived structure that contains the meta data for object properties. + */ struct _GParamSpecObject { GParamSpec parent_instance; }; +/** + * GParamSpecOverride: + * + * This is a type of #GParamSpec type that simply redirects operations to + * another paramspec. All operations other than getting or + * setting the value are redirected, including accessing the nick and + * blurb, validating a value, and so forth. See + * g_param_spec_get_redirect_target() for retrieving the overidden + * property. #GParamSpecOverride is used in implementing + * g_object_class_override_property(), and will not be directly useful + * unless you are implementing a new base type similar to GObject. + * + * Since: 2.4 + */ struct _GParamSpecOverride { /*< private >*/ GParamSpec parent_instance; GParamSpec *overridden; }; +/** + * GParamSpecGType: + * @parent_instance: private #GParamSpec portion + * @is_a_type: a #GType whose subtypes can occur as values + * + * A #GParamSpec derived structure that contains the meta data for #GType properties. + * + * Since: 2.10 + */ struct _GParamSpecGType { GParamSpec parent_instance; @@ -340,7 +984,7 @@ GParamSpec* g_param_spec_uint64 (const gchar *name, guint64 maximum, guint64 default_value, GParamFlags flags); -GParamSpec* g_param_spec_unichar (const gchar *name, +GParamSpec* g_param_spec_unichar (const gchar *name, const gchar *nick, const gchar *blurb, gunichar default_value, @@ -400,7 +1044,7 @@ GParamSpec* g_param_spec_object (const gchar *name, const gchar *blurb, GType object_type, GParamFlags flags); -GParamSpec* g_param_spec_override (const gchar *name, +GParamSpec* g_param_spec_override (const gchar *name, GParamSpec *overridden); GParamSpec* g_param_spec_gtype (const gchar *name, const gchar *nick, diff --git a/gobject/gvaluetypes.c b/gobject/gvaluetypes.c index 5da1eba9e..7c519f5a9 100644 --- a/gobject/gvaluetypes.c +++ b/gobject/gvaluetypes.c @@ -554,6 +554,13 @@ g_value_types_init (void) /* --- GValue functions --- */ +/** + * g_value_set_char: + * @value: a valid #GValue of type %G_TYPE_CHAR + * @v_char: character value to be set + * + * Set the contents of a %G_TYPE_CHAR #GValue to @v_char. + */ void g_value_set_char (GValue *value, gchar v_char) @@ -563,6 +570,14 @@ g_value_set_char (GValue *value, value->data[0].v_int = v_char; } +/** + * g_value_get_char: + * @value: a valid #GValue of type %G_TYPE_CHAR + * + * Get the contents of a %G_TYPE_CHAR #GValue. + * + * Returns: character contents of @value + */ gchar g_value_get_char (const GValue *value) { @@ -571,6 +586,13 @@ g_value_get_char (const GValue *value) return value->data[0].v_int; } +/** + * g_value_set_uchar: + * @value: a valid #GValue of type %G_TYPE_UCHAR + * @v_uchar: unsigned character value to be set + * + * Set the contents of a %G_TYPE_UCHAR #GValue to @v_uchar. + */ void g_value_set_uchar (GValue *value, guchar v_uchar) @@ -580,6 +602,14 @@ g_value_set_uchar (GValue *value, value->data[0].v_uint = v_uchar; } +/** + * g_value_get_uchar: + * @value: a valid #GValue of type %G_TYPE_UCHAR + * + * Get the contents of a %G_TYPE_UCHAR #GValue. + * + * Returns: unsigned character contents of @value + */ guchar g_value_get_uchar (const GValue *value) { @@ -588,6 +618,13 @@ g_value_get_uchar (const GValue *value) return value->data[0].v_uint; } +/** + * g_value_set_boolean: + * @value: a valid #GValue of type %G_TYPE_BOOLEAN + * @v_boolean: boolean value to be set + * + * Set the contents of a %G_TYPE_BOOLEAN #GValue to @v_boolean. + */ void g_value_set_boolean (GValue *value, gboolean v_boolean) @@ -597,6 +634,14 @@ g_value_set_boolean (GValue *value, value->data[0].v_int = v_boolean != FALSE; } +/** + * g_value_get_boolean: + * @value: a valid #GValue of type %G_TYPE_BOOLEAN + * + * Get the contents of a %G_TYPE_BOOLEAN #GValue. + * + * Returns: boolean contents of @value + */ gboolean g_value_get_boolean (const GValue *value) { @@ -605,6 +650,13 @@ g_value_get_boolean (const GValue *value) return value->data[0].v_int; } +/** + * g_value_set_int: + * @value: a valid #GValue of type %G_TYPE_INT + * @v_int: integer value to be set + * + * Set the contents of a %G_TYPE_INT #GValue to @v_int. + */ void g_value_set_int (GValue *value, gint v_int) @@ -614,6 +666,14 @@ g_value_set_int (GValue *value, value->data[0].v_int = v_int; } +/** + * g_value_get_int: + * @value: a valid #GValue of type %G_TYPE_INT + * + * Get the contents of a %G_TYPE_INT #GValue. + * + * Returns: integer contents of @value + */ gint g_value_get_int (const GValue *value) { @@ -622,6 +682,13 @@ g_value_get_int (const GValue *value) return value->data[0].v_int; } +/** + * g_value_set_uint: + * @value: a valid #GValue of type %G_TYPE_UINT + * @v_uint: unsigned integer value to be set + * + * Set the contents of a %G_TYPE_UINT #GValue to @v_uint. + */ void g_value_set_uint (GValue *value, guint v_uint) @@ -631,6 +698,14 @@ g_value_set_uint (GValue *value, value->data[0].v_uint = v_uint; } +/** + * g_value_get_uint: + * @value: a valid #GValue of type %G_TYPE_UINT + * + * Get the contents of a %G_TYPE_UINT #GValue. + * + * Returns: unsigned integer contents of @value + */ guint g_value_get_uint (const GValue *value) { @@ -639,6 +714,13 @@ g_value_get_uint (const GValue *value) return value->data[0].v_uint; } +/** + * g_value_set_long: + * @value: a valid #GValue of type %G_TYPE_LONG + * @v_long: long integer value to be set + * + * Set the contents of a %G_TYPE_LONG #GValue to @v_long. + */ void g_value_set_long (GValue *value, glong v_long) @@ -648,6 +730,14 @@ g_value_set_long (GValue *value, value->data[0].v_long = v_long; } +/** + * g_value_get_long: + * @value: a valid #GValue of type %G_TYPE_LONG + * + * Get the contents of a %G_TYPE_LONG #GValue. + * + * Returns: long integer contents of @value + */ glong g_value_get_long (const GValue *value) { @@ -656,6 +746,13 @@ g_value_get_long (const GValue *value) return value->data[0].v_long; } +/** + * g_value_set_ulong: + * @value: a valid #GValue of type %G_TYPE_ULONG + * @v_ulong: unsigned long integer value to be set + * + * Set the contents of a %G_TYPE_ULONG #GValue to @v_ulong. + */ void g_value_set_ulong (GValue *value, gulong v_ulong) @@ -665,6 +762,14 @@ g_value_set_ulong (GValue *value, value->data[0].v_ulong = v_ulong; } +/** + * g_value_get_ulong: + * @value: a valid #GValue of type %G_TYPE_ULONG + * + * Get the contents of a %G_TYPE_ULONG #GValue. + * + * Returns: unsigned long integer contents of @value + */ gulong g_value_get_ulong (const GValue *value) { @@ -673,6 +778,14 @@ g_value_get_ulong (const GValue *value) return value->data[0].v_ulong; } +/** + * g_value_get_int64: + * @value: a valid #GValue of type %G_TYPE_INT64 + * + * Get the contents of a %G_TYPE_INT64 #GValue. + * + * Returns: 64bit integer contents of @value + */ void g_value_set_int64 (GValue *value, gint64 v_int64) @@ -682,6 +795,13 @@ g_value_set_int64 (GValue *value, value->data[0].v_int64 = v_int64; } +/** + * g_value_set_int64: + * @value: a valid #GValue of type %G_TYPE_INT64 + * @v_int64: 64bit integer value to be set + * + * Set the contents of a %G_TYPE_INT64 #GValue to @v_int64. + */ gint64 g_value_get_int64 (const GValue *value) { @@ -690,6 +810,13 @@ g_value_get_int64 (const GValue *value) return value->data[0].v_int64; } +/** + * g_value_set_uint64: + * @value: a valid #GValue of type %G_TYPE_UINT64 + * @v_uint64: unsigned 64bit integer value to be set + * + * Set the contents of a %G_TYPE_UINT64 #GValue to @v_uint64. + */ void g_value_set_uint64 (GValue *value, guint64 v_uint64) @@ -699,6 +826,14 @@ g_value_set_uint64 (GValue *value, value->data[0].v_uint64 = v_uint64; } +/** + * g_value_get_uint64: + * @value: a valid #GValue of type %G_TYPE_UINT64 + * + * Get the contents of a %G_TYPE_UINT64 #GValue. + * + * Returns: unsigned 64bit integer contents of @value + */ guint64 g_value_get_uint64 (const GValue *value) { @@ -707,6 +842,13 @@ g_value_get_uint64 (const GValue *value) return value->data[0].v_uint64; } +/** + * g_value_set_float: + * @value: a valid #GValue of type %G_TYPE_FLOAT + * @v_float: float value to be set + * + * Set the contents of a %G_TYPE_FLOAT #GValue to @v_float. + */ void g_value_set_float (GValue *value, gfloat v_float) @@ -716,6 +858,14 @@ g_value_set_float (GValue *value, value->data[0].v_float = v_float; } +/** + * g_value_get_float: + * @value: a valid #GValue of type %G_TYPE_FLOAT + * + * Get the contents of a %G_TYPE_FLOAT #GValue. + * + * Returns: float contents of @value + */ gfloat g_value_get_float (const GValue *value) { @@ -724,6 +874,13 @@ g_value_get_float (const GValue *value) return value->data[0].v_float; } +/** + * g_value_set_double: + * @value: a valid #GValue of type %G_TYPE_DOUBLE + * @v_double: double value to be set + * + * Set the contents of a %G_TYPE_DOUBLE #GValue to @v_double. + */ void g_value_set_double (GValue *value, gdouble v_double) @@ -733,6 +890,14 @@ g_value_set_double (GValue *value, value->data[0].v_double = v_double; } +/** + * g_value_get_double: + * @value: a valid #GValue of type %G_TYPE_DOUBLE + * + * Get the contents of a %G_TYPE_DOUBLE #GValue. + * + * Returns: double contents of @value + */ gdouble g_value_get_double (const GValue *value) { @@ -741,6 +906,13 @@ g_value_get_double (const GValue *value) return value->data[0].v_double; } +/** + * g_value_set_string: + * @value: a valid #GValue of type %G_TYPE_STRING + * @v_string: string to be set + * + * Set the contents of a %G_TYPE_STRING #GValue to @v_string. + */ void g_value_set_string (GValue *value, const gchar *v_string) @@ -759,6 +931,15 @@ g_value_set_string (GValue *value, value->data[0].v_pointer = new_val; } +/** + * g_value_set_static_string: + * @value: a valid #GValue of type %G_TYPE_STRING + * @v_string: static string to be set + * + * Set the contents of a %G_TYPE_STRING #GValue to @v_string. + * The string is assumed to be static, and is thus not duplicated + * when setting the #GValue. + */ void g_value_set_static_string (GValue *value, const gchar *v_string) @@ -771,6 +952,15 @@ g_value_set_static_string (GValue *value, value->data[0].v_pointer = (gchar*) v_string; } +/** + * g_value_set_string_take_ownership: + * @value: a valid #GValue of type %G_TYPE_STRING + * @v_string: duplicated unowned string to be set + * + * This is an internal function introduced mainly for C marshallers. + * + * Deprecated: 2.4: Use g_value_take_string() instead. + */ void g_value_set_string_take_ownership (GValue *value, gchar *v_string) @@ -778,6 +968,15 @@ g_value_set_string_take_ownership (GValue *value, g_value_take_string (value, v_string); } +/** + * g_value_take_string: + * @value: a valid #GValue of type %G_TYPE_STRING + * @v_string: duplicated unowned string to be set + * + * Sets the contents of a %G_TYPE_STRING #GValue to @v_string. + * + * Since: 2.4 + */ void g_value_take_string (GValue *value, gchar *v_string) @@ -791,6 +990,14 @@ g_value_take_string (GValue *value, value->data[0].v_pointer = v_string; } +/** + * g_value_get_string: + * @value: a valid #GValue of type %G_TYPE_STRING + * + * Get the contents of a %G_TYPE_STRING #GValue. + * + * Returns: string content of @value + */ G_CONST_RETURN gchar* g_value_get_string (const GValue *value) { @@ -799,6 +1006,14 @@ g_value_get_string (const GValue *value) return value->data[0].v_pointer; } +/** + * g_value_dup_string: + * @value: a valid #GValue of type %G_TYPE_STRING + * + * Get a copy the contents of a %G_TYPE_STRING #GValue. + * + * Returns: a newly allocated copy of the string content of @value + */ gchar* g_value_dup_string (const GValue *value) { @@ -807,6 +1022,13 @@ g_value_dup_string (const GValue *value) return g_strdup (value->data[0].v_pointer); } +/** + * g_value_set_pointer: + * @value: a valid #GValue of %G_TYPE_POINTER + * @v_pointer: pointer value to be set + * + * Set the contents of a pointer #GValue to @v_pointer. + */ void g_value_set_pointer (GValue *value, gpointer v_pointer) @@ -816,6 +1038,14 @@ g_value_set_pointer (GValue *value, value->data[0].v_pointer = v_pointer; } +/** + * g_value_get_pointer: + * @value: a valid #GValue of %G_TYPE_POINTER + * + * Get the contents of a pointer #GValue. + * + * Returns: pointer contents of @value + */ gpointer g_value_get_pointer (const GValue *value) { @@ -834,6 +1064,15 @@ g_gtype_get_type (void) return type; } +/** + * g_value_set_gtype: + * @value: a valid #GValue of type %G_TYPE_GTYPE + * @v_gtype: #GType to be set + * + * Set the contents of a %G_TYPE_GTYPE #GValue to @v_gtype. + * + * Since: 2.12 + */ void g_value_set_gtype (GValue *value, GType v_gtype) @@ -844,6 +1083,15 @@ g_value_set_gtype (GValue *value, } +/** + * g_value_get_gtype: + * @value: a valid #GValue of type %G_TYPE_GTYPE + * + * Get the contents of a %G_TYPE_GTYPE #GValue. + * + * Since: 2.12 + * Returns: the #GType stored in @value + */ GType g_value_get_gtype (const GValue *value) { diff --git a/gobject/gvaluetypes.h b/gobject/gvaluetypes.h index 258360873..638578337 100644 --- a/gobject/gvaluetypes.h +++ b/gobject/gvaluetypes.h @@ -30,18 +30,122 @@ G_BEGIN_DECLS /* --- type macros --- */ +/** + * G_VALUE_HOLDS_CHAR: + * @value: a valid #GValue structure + * + * Checks whether the given #GValue can hold values of type %G_TYPE_CHAR. + * + * Returns: %TRUE on success. + */ #define G_VALUE_HOLDS_CHAR(value) (G_TYPE_CHECK_VALUE_TYPE ((value), G_TYPE_CHAR)) +/** + * G_VALUE_HOLDS_UCHAR: + * @value: a valid #GValue structure + * + * Checks whether the given #GValue can hold values of type %G_TYPE_UCHAR. + * + * Returns: %TRUE on success. + */ #define G_VALUE_HOLDS_UCHAR(value) (G_TYPE_CHECK_VALUE_TYPE ((value), G_TYPE_UCHAR)) +/** + * G_VALUE_HOLDS_BOOLEAN: + * @value: a valid #GValue structure + * + * Checks whether the given #GValue can hold values of type %G_TYPE_BOOLEAN. + * + * Returns: %TRUE on success. + */ #define G_VALUE_HOLDS_BOOLEAN(value) (G_TYPE_CHECK_VALUE_TYPE ((value), G_TYPE_BOOLEAN)) +/** + * G_VALUE_HOLDS_INT: + * @value: a valid #GValue structure + * + * Checks whether the given #GValue can hold values of type %G_TYPE_INT. + * + * Returns: %TRUE on success. + */ #define G_VALUE_HOLDS_INT(value) (G_TYPE_CHECK_VALUE_TYPE ((value), G_TYPE_INT)) +/** + * G_VALUE_HOLDS_UINT: + * @value: a valid #GValue structure + * + * Checks whether the given #GValue can hold values of type %G_TYPE_UINT. + * + * Returns: %TRUE on success. + */ #define G_VALUE_HOLDS_UINT(value) (G_TYPE_CHECK_VALUE_TYPE ((value), G_TYPE_UINT)) +/** + * G_VALUE_HOLDS_LONG: + * @value: a valid #GValue structure + * + * Checks whether the given #GValue can hold values of type %G_TYPE_LONG. + * + * Returns: %TRUE on success. + */ #define G_VALUE_HOLDS_LONG(value) (G_TYPE_CHECK_VALUE_TYPE ((value), G_TYPE_LONG)) +/** + * G_VALUE_HOLDS_ULONG: + * @value: a valid #GValue structure + * + * Checks whether the given #GValue can hold values of type %G_TYPE_ULONG. + * + * Returns: %TRUE on success. + */ #define G_VALUE_HOLDS_ULONG(value) (G_TYPE_CHECK_VALUE_TYPE ((value), G_TYPE_ULONG)) +/** + * G_VALUE_HOLDS_INT64: + * @value: a valid #GValue structure + * + * Checks whether the given #GValue can hold values of type %G_TYPE_INT64. + * + * Returns: %TRUE on success. + */ #define G_VALUE_HOLDS_INT64(value) (G_TYPE_CHECK_VALUE_TYPE ((value), G_TYPE_INT64)) +/** + * G_VALUE_HOLDS_UINT64: + * @value: a valid #GValue structure + * + * Checks whether the given #GValue can hold values of type %G_TYPE_UINT64. + * + * Returns: %TRUE on success. + */ #define G_VALUE_HOLDS_UINT64(value) (G_TYPE_CHECK_VALUE_TYPE ((value), G_TYPE_UINT64)) +/** + * G_VALUE_HOLDS_FLOAT: + * @value: a valid #GValue structure + * + * Checks whether the given #GValue can hold values of type %G_TYPE_FLOAT. + * + * Returns: %TRUE on success. + */ #define G_VALUE_HOLDS_FLOAT(value) (G_TYPE_CHECK_VALUE_TYPE ((value), G_TYPE_FLOAT)) +/** + * G_VALUE_HOLDS_DOUBLE: + * @value: a valid #GValue structure + * + * Checks whether the given #GValue can hold values of type %G_TYPE_DOUBLE. + * + * Returns: %TRUE on success. + */ #define G_VALUE_HOLDS_DOUBLE(value) (G_TYPE_CHECK_VALUE_TYPE ((value), G_TYPE_DOUBLE)) +/** + * G_VALUE_HOLDS_STRING: + * @value: a valid #GValue structure + * + * Checks whether the given #GValue can hold values of type %G_TYPE_STRING. + * + * Returns: %TRUE on success. + */ #define G_VALUE_HOLDS_STRING(value) (G_TYPE_CHECK_VALUE_TYPE ((value), G_TYPE_STRING)) +/** + * G_VALUE_HOLDS_POINTER: + * @value: a valid #GValue structure + * + * Checks whether the given #GValue can hold values of type %G_TYPE_POINTER. + * + * Returns: %TRUE on success. + */ #define G_VALUE_HOLDS_POINTER(value) (G_TYPE_CHECK_VALUE_TYPE ((value), G_TYPE_POINTER)) /** * G_TYPE_GTYPE: @@ -49,6 +153,15 @@ G_BEGIN_DECLS * The type for #GType. */ #define G_TYPE_GTYPE (g_gtype_get_type()) +/** + * G_VALUE_HOLDS_GTYPE: + * @value: a valid #GValue structure + * + * Checks whether the given #GValue can hold values of type %G_TYPE_GTYPE. + * + * Since: 2.12 + * Returns: %TRUE on success. + */ #define G_VALUE_HOLDS_GTYPE(value) (G_TYPE_CHECK_VALUE_TYPE ((value), G_TYPE_GTYPE)) @@ -117,6 +230,11 @@ void g_value_set_string_take_ownership (GValue *value, /* humpf, need a C representable type name for G_TYPE_STRING */ +/** + * gchararray: + * + * A C representable type name for #G_TYPE_STRING. + */ typedef gchar* gchararray; -- cgit v1.2.3-70-g09d2