diff --git a/ChangeLog b/ChangeLog index 7f71c8195..c430707c5 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,20 @@ +2008-06-22 Stefan Kost + + * 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. + 2008-06-21 Stefan Kost * docs/reference/gobject/tmpl/objects.sgml: diff --git a/docs/reference/gobject/tmpl/param_value_types.sgml b/docs/reference/gobject/tmpl/param_value_types.sgml deleted file mode 100644 index 3a21db70e..000000000 --- a/docs/reference/gobject/tmpl/param_value_types.sgml +++ /dev/null @@ -1,1806 +0,0 @@ - -Parameters and Values - - -Standard Parameter and Value Types - - - -#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. - - - - -#GParamSpec, #GValue, g_object_class_install_property(). - - - - - - - -Return whether the given #GParamSpec is of type %G_TYPE_PARAM_BOOLEAN. - - -@pspec: a valid #GParamSpec instance - - - - -Cast a #GParamSpec instance into a #GParamSpecBoolean. - - -@pspec: a valid #GParamSpec instance - - - - -Return whether the given #GValue can hold values of type %G_TYPE_BOOLEAN. - - -@value: a valid #GValue structure - - - - -The #GType of #GParamSpecBoolean. - - - - - - -A #GParamSpec derived structure that contains the meta data for boolean properties. - - -@parent_instance: private #GParamSpec portion -@default_value: default value 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. - - -@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 -@Returns: a newly created parameter specification - - - - -Set the contents of a %G_TYPE_BOOLEAN #GValue to @v_boolean. - - -@value: a valid #GValue of type %G_TYPE_BOOLEAN -@v_boolean: boolean value to be set - - - - -Get the contents of a %G_TYPE_BOOLEAN #GValue. - - -@value: a valid #GValue of type %G_TYPE_BOOLEAN -@Returns: boolean contents of @value - - - - -Return whether the given #GParamSpec is of type %G_TYPE_PARAM_CHAR. - - -@pspec: a valid #GParamSpec instance - - - - -Cast a #GParamSpec instance into a #GParamSpecChar. - - -@pspec: a valid #GParamSpec instance - - - - -Return whether the given #GValue can hold values of type %G_TYPE_CHAR. - - -@value: a valid #GValue structure - - - - -The #GType of #GParamSpecChar. - - - - - - -A #GParamSpec derived structure that contains the meta data for character properties. - - -@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 - - - -Creates a new #GParamSpecChar instance specifying a %G_TYPE_CHAR property. - - -@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 -@Returns: a newly created parameter specification - - - - -Set the contents of a %G_TYPE_CHAR #GValue to @v_char. - - -@value: a valid #GValue of type %G_TYPE_CHAR -@v_char: character value to be set - - - - -Get the contents of a %G_TYPE_CHAR #GValue. - - -@value: a valid #GValue of type %G_TYPE_CHAR -@Returns: character contents of @value - - - - -Return whether the given #GParamSpec is of type %G_TYPE_PARAM_UCHAR. - - -@pspec: a valid #GParamSpec instance - - - - -Cast a #GParamSpec instance into a #GParamSpecUChar. - - -@pspec: a valid #GParamSpec instance - - - - -Return whether the given #GValue can hold values of type %G_TYPE_UCHAR. - - -@value: a valid #GValue structure - - - - -The #GType of #GParamSpecUChar. - - - - - - -A #GParamSpec derived structure that contains the meta data for unsigned character properties. - - -@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 - - - -Creates a new #GParamSpecUChar instance specifying a %G_TYPE_UCHAR property. - - -@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 -@Returns: a newly created parameter specification - - - - -Set the contents of a %G_TYPE_UCHAR #GValue to @v_uchar. - - -@value: a valid #GValue of type %G_TYPE_UCHAR -@v_uchar: unsigned character value to be set - - - - -Get the contents of a %G_TYPE_UCHAR #GValue. - - -@value: a valid #GValue of type %G_TYPE_UCHAR -@Returns: unsigned character contents of @value - - - - -Return whether the given #GParamSpec is of type %G_TYPE_PARAM_INT. - - -@pspec: a valid #GParamSpec instance - - - - -Cast a #GParamSpec instance into a #GParamSpecInt. - - -@pspec: a valid #GParamSpec instance - - - - -Return whether the given #GValue can hold values of type %G_TYPE_INT. - - -@value: a valid #GValue structure - - - - -The #GType of #GParamSpecInt. - - - - - - -A #GParamSpec derived structure that contains the meta data for integer properties. - - -@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 - - - -Creates a new #GParamSpecInt instance specifying a %G_TYPE_INT property. - - -See g_param_spec_internal() for details on property names. - - -@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 -@Returns: a newly created parameter specification - - - - -Set the contents of a %G_TYPE_INT #GValue to @v_int. - - -@value: a valid #GValue of type %G_TYPE_INT -@v_int: integer value to be set - - - - -Get the contents of a %G_TYPE_INT #GValue. - - -@value: a valid #GValue of type %G_TYPE_INT -@Returns: integer contents of @value - - - - -Return whether the given #GParamSpec is of type %G_TYPE_PARAM_UINT. - - -@pspec: a valid #GParamSpec instance - - - - -Cast a #GParamSpec instance into a #GParamSpecUInt. - - -@pspec: a valid #GParamSpec instance - - - - -Return whether the given #GValue can hold values of type %G_TYPE_UINT. - - -@value: a valid #GValue structure - - - - -The #GType of #GParamSpecUInt. - - - - - - -A #GParamSpec derived structure that contains the meta data for unsigned integer properties. - - -@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 - - - -Creates a new #GParamSpecUInt instance specifying a %G_TYPE_UINT property. - - -See g_param_spec_internal() for details on property names. - - -@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 -@Returns: a newly created parameter specification - - - - -Set the contents of a %G_TYPE_UINT #GValue to @v_uint. - - -@value: a valid #GValue of type %G_TYPE_UINT -@v_uint: unsigned integer value to be set - - - - -Get the contents of a %G_TYPE_UINT #GValue. - - -@value: a valid #GValue of type %G_TYPE_UINT -@Returns: unsigned integer contents of @value - - - - -Return whether the given #GParamSpec is of type %G_TYPE_PARAM_LONG. - - -@pspec: a valid #GParamSpec instance - - - - -Cast a #GParamSpec instance into a #GParamSpecLong. - - -@pspec: a valid #GParamSpec instance - - - - -Return whether the given #GValue can hold values of type %G_TYPE_LONG. - - -@value: a valid #GValue structure - - - - -The #GType of #GParamSpecLong. - - - - - - -A #GParamSpec derived structure that contains the meta data for long integer properties. - - -@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 - - - -Creates a new #GParamSpecLong instance specifying a %G_TYPE_LONG property. - - -See g_param_spec_internal() for details on property names. - - -@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 -@Returns: a newly created parameter specification - - - - -Set the contents of a %G_TYPE_LONG #GValue to @v_long. - - -@value: a valid #GValue of type %G_TYPE_LONG -@v_long: long integer value to be set - - - - -Get the contents of a %G_TYPE_LONG #GValue. - - -@value: a valid #GValue of type %G_TYPE_LONG -@Returns: long integer contents of @value - - - - -Return whether the given #GParamSpec is of type %G_TYPE_PARAM_ULONG. - - -@pspec: a valid #GParamSpec instance - - - - -Cast a #GParamSpec instance into a #GParamSpecULong. - - -@pspec: a valid #GParamSpec instance - - - - -Return whether the given #GValue can hold values of type %G_TYPE_ULONG. - - -@value: a valid #GValue structure - - - - -The #GType of #GParamSpecULong. - - - - - - -A #GParamSpec derived structure that contains the meta data for unsigned long integer properties. - - -@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 - - - -Creates a new #GParamSpecULong instance specifying a %G_TYPE_ULONG property. - - -See g_param_spec_internal() for details on property names. - - -@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 -@Returns: a newly created parameter specification - - - - -Set the contents of a %G_TYPE_ULONG #GValue to @v_ulong. - - -@value: a valid #GValue of type %G_TYPE_ULONG -@v_ulong: unsigned long integer value to be set - - - - -Get the contents of a %G_TYPE_ULONG #GValue. - - -@value: a valid #GValue of type %G_TYPE_ULONG -@Returns: unsigned long integer contents of @value - - - - -Return whether the given #GParamSpec is of type %G_TYPE_PARAM_INT64. - - -@pspec: a valid #GParamSpec instance - - - - -Cast a #GParamSpec instance into a #GParamSpecInt64. - - -@pspec: a valid #GParamSpec instance - - - - -Return whether the given #GValue can hold values of type %G_TYPE_INT64. - - -@value: a valid #GValue structure - - - - -The #GType of #GParamSpecInt64. - - - - - - -A #GParamSpec derived structure that contains the meta data for 64bit integer properties. - - -@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 - - - -Creates a new #GParamSpecInt64 instance specifying a %G_TYPE_INT64 property. - - -See g_param_spec_internal() for details on property names. - - -@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 -@Returns: a newly created parameter specification - - - - -Set the contents of a %G_TYPE_INT64 #GValue to @v_int64. - - -@value: a valid #GValue of type %G_TYPE_INT64 -@v_int64: 64bit integer value to be set - - - - -Get the contents of a %G_TYPE_INT64 #GValue. - - -@value: a valid #GValue of type %G_TYPE_INT64 -@Returns: 64bit integer contents of @value - - - - -Return whether the given #GParamSpec is of type %G_TYPE_PARAM_UINT64. - - -@pspec: a valid #GParamSpec instance - - - - -Cast a #GParamSpec instance into a #GParamSpecUInt64. - - -@pspec: a valid #GParamSpec instance - - - - -Return whether the given #GValue can hold values of type %G_TYPE_UINT64. - - -@value: a valid #GValue structure - - - - -The #GType of #GParamSpecUInt64. - - - - - - -A #GParamSpec derived structure that contains the meta data for unsigned 64bit integer properties. - - -@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 - - - -Creates a new #GParamSpecUInt64 instance specifying a %G_TYPE_UINT64 -property. - - -See g_param_spec_internal() for details on property names. - - -@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 -@Returns: a newly created parameter specification - - - - -Set the contents of a %G_TYPE_UINT64 #GValue to @v_uint64. - - -@value: a valid #GValue of type %G_TYPE_UINT64 -@v_uint64: unsigned 64bit integer value to be set - - - - -Get the contents of a %G_TYPE_UINT64 #GValue. - - -@value: a valid #GValue of type %G_TYPE_UINT64 -@Returns: unsigned 64bit integer contents of @value - - - - -Return whether the given #GParamSpec is of type %G_TYPE_PARAM_FLOAT. - - -@pspec: a valid #GParamSpec instance - - - - -Cast a #GParamSpec instance into a #GParamSpecFloat. - - -@pspec: a valid #GParamSpec instance - - - - -Return whether the given #GValue can hold values of type %G_TYPE_FLOAT. - - -@value: a valid #GValue structure - - - - -The #GType of #GParamSpecFloat. - - - - - - -A #GParamSpec derived structure that contains the meta data for float properties. - - -@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. - - - -Creates a new #GParamSpecFloat instance specifying a %G_TYPE_FLOAT property. - - -See g_param_spec_internal() for details on property names. - - -@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 -@Returns: a newly created parameter specification - - - - -Set the contents of a %G_TYPE_FLOAT #GValue to @v_float. - - -@value: a valid #GValue of type %G_TYPE_FLOAT -@v_float: float value to be set - - - - -Get the contents of a %G_TYPE_FLOAT #GValue. - - -@value: a valid #GValue of type %G_TYPE_FLOAT -@Returns: float contents of @value - - - - -Return whether the given #GParamSpec is of type %G_TYPE_PARAM_DOUBLE. - - -@pspec: a valid #GParamSpec instance - - - - -Cast a #GParamSpec instance into a #GParamSpecDouble. - - -@pspec: a valid #GParamSpec instance - - - - -Return whether the given #GValue can hold values of type %G_TYPE_DOUBLE. - - -@value: a valid #GValue structure - - - - -The #GType of #GParamSpecDouble. - - - - - - -A #GParamSpec derived structure that contains the meta data for double properties. - - -@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. - - - -Creates a new #GParamSpecDouble instance specifying a %G_TYPE_DOUBLE -property. - - -See g_param_spec_internal() for details on property names. - - -@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 -@Returns: a newly created parameter specification - - - - -Set the contents of a %G_TYPE_DOUBLE #GValue to @v_double. - - -@value: a valid #GValue of type %G_TYPE_DOUBLE -@v_double: double value to be set - - - - -Get the contents of a %G_TYPE_DOUBLE #GValue. - - -@value: a valid #GValue of type %G_TYPE_DOUBLE -@Returns: double contents of @value - - - - -Returns whether the given #GParamSpec is of type %G_TYPE_PARAM_ENUM. - - -@pspec: a valid #GParamSpec instance - - - - -Cast a #GParamSpec instance into a #GParamSpecEnum. - - -@pspec: a valid #GParamSpec instance - - - - -Return whether the given #GValue can hold values derived from type %G_TYPE_ENUM. - - -@value: a valid #GValue structure - - - - -The #GType of #GParamSpecEnum. - - - - - - -A #GParamSpec derived structure that contains the meta data for enum -properties. - - -@parent_instance: private #GParamSpec portion -@enum_class: the #GEnumClass for the enum -@default_value: default value 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. - - -@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 -@Returns: a newly created parameter specification - - - - -Set the contents of a %G_TYPE_ENUM #GValue to @v_enum. - - -@value: a valid #GValue whose type is derived from %G_TYPE_ENUM -@v_enum: enum value to be set - - - - -Get the contents of a %G_TYPE_ENUM #GValue. - - -@value: a valid #GValue whose type is derived from %G_TYPE_ENUM -@Returns: enum contents of @value - - - - -Returns whether the given #GParamSpec is of type %G_TYPE_PARAM_FLAGS. - - -@pspec: a valid #GParamSpec instance - - - - -Cast a #GParamSpec instance into a #GParamSpecFlags. - - -@pspec: a valid #GParamSpec instance - - - - -Returns whether the given #GValue can hold values derived from type %G_TYPE_FLAGS. - - -@value: a valid #GValue structure - - - - -The #GType of #GParamSpecFlags. - - - - - - -A #GParamSpec derived structure that contains the meta data for flags -properties. - - -@parent_instance: private #GParamSpec portion -@flags_class: the #GFlagsClass for the flags -@default_value: default value 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. - - -@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 -@Returns: a newly created parameter specification - - - - -Set the contents of a %G_TYPE_FLAGS #GValue to @v_flags. - - -@value: a valid #GValue whose type is derived from %G_TYPE_FLAGS -@v_flags: flags value to be set - - - - -Get the contents of a %G_TYPE_FLAGS #GValue. - - -@value: a valid #GValue whose type is derived from %G_TYPE_FLAGS -@Returns: flags contents of @value - - - - -Returns whether the given #GParamSpec is of type %G_TYPE_PARAM_STRING. - - -@pspec: a valid #GParamSpec instance - - - - -Casts a #GParamSpec instance into a #GParamSpecString. - - -@pspec: a valid #GParamSpec instance - - - - -Return whether the given #GValue can hold values of type %G_TYPE_STRING. - - -@value: a valid #GValue structure - - - - -The #GType of #GParamSpecString. - - - - - - -A #GParamSpec derived structure that contains the meta data for string -properties. - - -@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 C representable type name for #G_TYPE_STRING. - - - - - -Creates a new #GParamSpecString instance. - - -See g_param_spec_internal() for details on property names. - - -@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 -@Returns: a newly created parameter specification - - - - -Set the contents of a %G_TYPE_STRING #GValue to @v_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. -The string is assumed to be static, and is thus not duplicated -when setting the #GValue. - - -@value: a valid #GValue of type %G_TYPE_STRING -@v_string: static string to be set - - - - -Sets the contents of a %G_TYPE_STRING #GValue to @v_string. - - -@value: a valid #GValue of type %G_TYPE_STRING -@v_string: duplicated unowned string to be set -@Since: 2.4 - - - - -This is an internal function introduced mainly for C marshallers. - - -@value: a valid #GValue of type %G_TYPE_STRING -@v_string: duplicated unowned string to be set -@Deprecated: 2.4: Use g_value_take_string() instead. - - - - -Get the contents of a %G_TYPE_STRING #GValue. - - -@value: a valid #GValue of type %G_TYPE_STRING -@Returns: string content of @value - - - - -Get a copy the contents of a %G_TYPE_STRING #GValue. - - -@value: a valid #GValue of type %G_TYPE_STRING -@Returns: a newly allocated copy of the string content of @value - - - - -Returns whether the given #GParamSpec is of type %G_TYPE_PARAM_PARAM. - - -@pspec: a valid #GParamSpec instance - - - - -Casts a #GParamSpec instance into a #GParamSpecParam. - - -@pspec: a valid #GParamSpec instance - - - - -Return whether the given #GValue can hold values derived from type %G_TYPE_PARAM. - - -@value: a valid #GValue structure - - - - -The #GType of #GParamSpecParam. - - - - - - -A #GParamSpec derived structure that contains the meta data for %G_TYPE_PARAM -properties. - - -@parent_instance: private #GParamSpec portion - - - -Creates a new #GParamSpecParam instance specifying a %G_TYPE_PARAM -property. - - -See g_param_spec_internal() for details on property names. - - -@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 -@Returns: a newly created parameter specification - -@default_value: default value for the property specified - - - - -Set the contents of a %G_TYPE_PARAM #GValue to @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. - - -@value: a valid #GValue of type %G_TYPE_PARAM -@param: the #GParamSpec to be set -@Since: 2.4 - - - - -This is an internal function introduced mainly for C marshallers. - - -@value: a valid #GValue of type %G_TYPE_PARAM -@param: the #GParamSpec to be set -@Deprecated: 2.4: Use g_value_take_param() instead. - - - - -Get the contents of a %G_TYPE_PARAM #GValue. - - -@value: a valid #GValue whose type is derived from %G_TYPE_PARAM -@Returns: #GParamSpec content of @value - - - - -Get the contents of a %G_TYPE_PARAM #GValue, increasing its reference count. - - -@value: a valid #GValue whose type is derived from %G_TYPE_PARAM -@Returns: #GParamSpec content of @value, should be unreferenced when no longer needed. - - - - -Return whether the given #GParamSpec is of type %G_TYPE_PARAM_BOXED. - - -@pspec: a valid #GParamSpec instance - - - - -Cast a #GParamSpec instance into a #GParamSpecBoxed. - - -@pspec: a valid #GParamSpec instance - - - - -Return whether the given #GValue can hold values derived from type %G_TYPE_BOXED. - - -@value: a valid #GValue structure - - - - -The #GType of #GParamSpecBoxed. - - - - - - -A #GParamSpec derived structure that contains the meta data for boxed properties. - - -@parent_instance: private #GParamSpec portion - - - -Creates a new #GParamSpecBoxed instance specifying a %G_TYPE_BOXED -derived property. - - -See g_param_spec_internal() for details on property names. - - -@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 -@Returns: a newly created parameter specification - - - - -Set the contents of a %G_TYPE_BOXED derived #GValue to @v_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. -The boxed value is assumed to be static, and is thus not duplicated -when setting the #GValue. - - -@value: a valid #GValue of %G_TYPE_BOXED derived type -@v_boxed: static 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. - - -@value: a valid #GValue of %G_TYPE_BOXED derived type -@v_boxed: duplicated unowned boxed value to be set -@Since: 2.4 - - - - -This is an internal function introduced mainly for C marshallers. - - -@value: a valid #GValue of %G_TYPE_BOXED derived type -@v_boxed: duplicated unowned boxed value to be set -@Deprecated: 2.4: Use g_value_take_boxed() instead. - - - - -Get the contents of a %G_TYPE_BOXED derived #GValue. - - -@value: a valid #GValue of %G_TYPE_BOXED derived type -@Returns: boxed contents of @value - - - - -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); - - -@value: a valid #GValue of %G_TYPE_BOXED derived type -@Returns: boxed contents of @value - - - - -Returns whether the given #GParamSpec is of type %G_TYPE_PARAM_POINTER. - - -@pspec: a valid #GParamSpec instance - - - - -Casts a #GParamSpec instance into a #GParamSpecPointer. - - -@pspec: a valid #GParamSpec instance - - - - -Return whether the given #GValue can hold values of type %G_TYPE_POINTER. - - -@value: a valid #GValue structure - - - - -The #GType of #GParamSpecPointer. - - - - - - -A #GParamSpec derived structure that contains the meta data for pointer properties. - - -@parent_instance: private #GParamSpec portion - - - -Creates a new #GParamSpecPoiner instance specifying a pointer property. - - -See g_param_spec_internal() for details on property names. - - -@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 -@Returns: a newly created parameter specification - - - - -Set the contents of a pointer #GValue to @v_pointer. - - -@value: a valid #GValue of %G_TYPE_POINTER -@v_pointer: pointer value to be set - - - - -Get the contents of a pointer #GValue. - - -@value: a valid #GValue of %G_TYPE_POINTER -@Returns: pointer contents of @value - - - - -Returns whether the given #GParamSpec is of type %G_TYPE_PARAM_OBJECT. - - -@pspec: a valid #GParamSpec instance - - - - -Casts a #GParamSpec instance into a #GParamSpecObject. - - -@pspec: a valid #GParamSpec instance - - - - -Return whether the given #GValue can hold values derived from type %G_TYPE_OBJECT. - - -@value: a valid #GValue structure - - - - -The #GType of #GParamSpecObject. - - - - - - -A #GParamSpec derived structure that contains the meta data for object properties. - - -@parent_instance: private #GParamSpec portion - - - -Creates a new #GParamSpecBoxed instance specifying a %G_TYPE_OBJECT -derived property. - - -See g_param_spec_internal() for details on property names. - - -@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 -@Returns: a newly created parameter specification - - - - -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 - - - - -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. - - -@value: a valid #GValue of %G_TYPE_OBJECT derived type -@v_object: object value to be set -@Since: 2.4 - - - - -This is an internal function introduced mainly for C marshallers. - - -@value: a valid #GValue of %G_TYPE_OBJECT derived type -@v_object: object value to be set -@Deprecated: 2.4: Use g_value_take_object() instead. - - - - -Get the contents of a %G_TYPE_OBJECT derived #GValue. - - -@value: a valid #GValue of %G_TYPE_OBJECT derived type -@Returns: object contents of @value - - - - -Get the contents of a %G_TYPE_OBJECT derived #GValue, increasing its reference count. - - -@value: a valid #GValue whose type is derived from %G_TYPE_OBJECT -@Returns: object content of @value, should be unreferenced when no longer needed. - - - - -Return whether the given #GParamSpec is of type %G_TYPE_PARAM_UNICHAR. - - -@pspec: a valid #GParamSpec instance - - - - -Cast a #GParamSpec instance into a #GParamSpecUnichar. - - -@pspec: a valid #GParamSpec instance - - - - -The #GType of #GParamSpecUnichar. - - - - - - -A #GParamSpec derived structure that contains the meta data for unichar (unsigned integer) properties. - - -@parent_instance: private #GParamSpec portion -@default_value: default value 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. - - -@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 -@Returns: a newly created parameter specification - - - - -Return whether the given #GParamSpec is of type %G_TYPE_PARAM_VALUE_ARRAY. - - -@pspec: a valid #GParamSpec instance - - - - -Cast a #GParamSpec instance into a #GParamSpecValueArray. - - -@pspec: a valid #GParamSpec instance - - - - -The #GType of #GParamSpecValueArray. - - - - - - -A #GParamSpec derived structure that contains the meta data for #GValueArray properties. - - -@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 - - - -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. - - -@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 -@Returns: a newly created parameter specification - - - - -Returns whether the given #GParamSpec is of type %G_TYPE_PARAM_OVERRIDE. - - -@pspec: a #GParamSpec -@Since: 2.4 - - - - -Casts a #GParamSpec into a #GParamSpecOverride. - - -@pspec: a #GParamSpec -@Since: 2.4 - - - - -The #GType of #GParamSpecOverride. - - -@Since: 2.4 - - - - -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 - - - -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. - - -@name: the name of the property. -@overridden: The property that is being overridden -@Returns: the newly created #GParamSpec -@Since: 2.4 - - - - -Returns whether the given #GParamSpec is of type %G_TYPE_PARAM_GTYPE. - - -@pspec: a #GParamSpec -@Since: 2.10 - - - - -Casts a #GParamSpec into a #GParamSpecGType. - - -@pspec: a #GParamSpec -@Since: 2.10 - - - - -Returns whether the given #GValue can hold values of type %G_TYPE_GTYPE. - - -@value: a valid #GValue structure -@Since: 2.12 - - - - -The #GType of #GParamSpecGType. - - -@Since: 2.10 - - - - -A #GParamSpec derived structure that contains the meta data for #GType properties. - - -@parent_instance: private #GParamSpec portion -@is_a_type: a #GType whose subtypes can occur as values -@Since: 2.10 - - - -Creates a new #GParamSpecGType instance specifying a -%G_TYPE_GTYPE property. - - -See g_param_spec_internal() for details on property names. - - -@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 -@Returns: a newly created parameter specification -@Since: 2.10 - - - - -Get the contents of a %G_TYPE_GTYPE #GValue. - - -@value: a valid #GValue of type %G_TYPE_GTYPE -@Returns: the #GType stored in @value -@Since: 2.12 - - - - -Set the contents of a %G_TYPE_GTYPE #GValue to @v_gtype. - - -@value: a valid #GValue of type %G_TYPE_GTYPE -@v_gtype: #GType to be set -@Since: 2.12 - - 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;