From: Stefan Kost Date: Sat, 21 Jun 2008 13:47:14 +0000 (+0000) Subject: Migrating docs. X-Git-Url: http://git.openbox.org/?a=commitdiff_plain;h=fb07c6502036cdb53fdfe69b90f472dcd3eee49e;p=dana%2Fcg-glib.git Migrating docs. * docs/reference/gobject/tmpl/gparamspec.sgml: * gobject/gparam.c: * gobject/gparam.h: Migrating docs. svn path=/trunk/; revision=7073 --- diff --git a/ChangeLog b/ChangeLog index cddaba6b..df573450 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,10 @@ +2008-06-21 Stefan Kost + + * docs/reference/gobject/tmpl/gparamspec.sgml: + * gobject/gparam.c: + * gobject/gparam.h: + Migrating docs. + 2008-06-21 Stefan Kost * gobject/gboxed.c: diff --git a/docs/reference/gobject/tmpl/gparamspec.sgml b/docs/reference/gobject/tmpl/gparamspec.sgml deleted file mode 100644 index cebf58ea..00000000 --- a/docs/reference/gobject/tmpl/gparamspec.sgml +++ /dev/null @@ -1,546 +0,0 @@ - -GParamSpec - - -Metadata for parameter specifications - - - -#GParamSpec is an object structure that encapsulates the metadata -required to specify parameters, such as e.g. #GObject properties. - - -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. -The result of this replacement is called the canonical name of the -parameter. - - - - -g_object_class_install_property(), g_object_set(), g_object_get(), -g_object_set_property(), g_object_get_property(), g_value_register_transform_func() - - - - - - - -Returns whether @type "is a" %G_TYPE_PARAM. - - -@type: a #GType ID - - - - -Casts a derived #GParamSpec object (e.g. of type #GParamSpecInt) into -a #GParamSpec object. - - -@pspec: a valid #GParamSpec - - - - -Checks whether @pspec "is a" valid #GParamSpec structure of type %G_TYPE_PARAM -or derived. - - -@pspec: a #GParamSpec - - - - -Casts a derived #GParamSpecClass structure into a #GParamSpecClass structure. - - -@pclass: a valid #GParamSpecClass - - - - -Checks whether @pclass "is a" valid #GParamSpecClass structure of type -%G_TYPE_PARAM or derived. - - -@pclass: a #GParamSpecClass - - - - -Retrieves the #GParamSpecClass of a #GParamSpec. - - -@pspec: a valid #GParamSpec - - - - -Retrieves the #GType of this @pspec. - - -@pspec: a valid #GParamSpec - - - - -Retrieves the #GType name of this @pspec. - - -@pspec: a valid #GParamSpec - - - - -Retrieves the #GType to initialize a #GValue for this parameter. - - -@pspec: a valid #GParamSpec - - - - -All fields of the GParamSpec struct are private and -should not be used directly, except for the following: - - -@g_type_instance: private #GTypeInstance portion -@name: name of this parameter -@flags: #GParamFlags flags for this parameter -@value_type: the #GValue type for this parameter -@owner_type: #GType type that uses (introduces) this paremeter - - - -The class structure for the GParamSpec type. -Normally, GParamSpec classes are filled by -g_param_type_register_static(). - - -@g_type_class: the parent class -@value_type: the #GValue type for this parameter -@finalize: The instance finalization function (optional), should chain - up to the finalize method of the parent class. -@value_set_default: Resets a @value to the default value for this type - (recommended, the default is g_value_reset()), see - g_param_value_set_default(). -@value_validate: Ensures that the contents of @value comply with the - specifications set out by this type (optional), see - g_param_value_set_validate(). -@values_cmp: Compares @value1 with @value2 according to this type - (recommended, the default is memcmp()), see g_param_values_cmp(). - - - -Through the #GParamFlags flag values, certain aspects of parameters -can be configured. - - -@G_PARAM_READABLE: the parameter is readable -@G_PARAM_WRITABLE: the parameter is writable -@G_PARAM_CONSTRUCT: the parameter will be set upon object construction -@G_PARAM_CONSTRUCT_ONLY: the parameter will only be set upon object construction -@G_PARAM_LAX_VALIDATION: upon parameter conversion (see g_param_value_convert()) - strict validation is not required -@G_PARAM_STATIC_NAME: the string used as name when constructing the - parameter is guaranteed to remain valid and - unmodified for the lifetime of the parameter. - Since 2.8 -@G_PARAM_PRIVATE: -@G_PARAM_STATIC_NICK: the string used as nick when constructing the - parameter is guaranteed to remain valid and - unmmodified for the lifetime of the parameter. - Since 2.8 -@G_PARAM_STATIC_BLURB: the string used as blurb when constructing the - parameter is guaranteed to remain valid and - unmodified for the lifetime of the parameter. - Since 2.8 - - - -#GParamFlags value alias for %G_PARAM_READABLE | %G_PARAM_WRITABLE. - - - - - - -#GParamFlags value alias for %G_PARAM_STATIC_NAME | %G_PARAM_STATIC_NICK | %G_PARAM_STATIC_BLURB. - -Since 2.13.0 - - - - - - -Mask containing the bits of #GParamSpec.flags which are reserved for GLib. - - - - - - -Minimum shift count to be used for user defined flags, to be stored in -#GParamSpec.flags. - - - - - - -Increments the reference count of @pspec. - - -@pspec: a valid #GParamSpec -@Returns: the #GParamSpec that was passed into this function - - - - -Decrements the reference count of a @pspec. - - -@pspec: a valid #GParamSpec - - - - -The initial reference count of a newly created #GParamSpec is 1, even -though no one has explicitly called g_param_spec_ref() on it yet. So the -initial reference count is flagged as "floating", until someone calls -g_param_spec_ref (pspec); g_param_spec_sink (pspec); -in sequence on it, taking over the initial reference count (thus -ending up with a @pspec that has a reference count of 1 still, but is -not flagged "floating" anymore). - - -@pspec: a valid #GParamSpec - - - - -Convenience function to ref and sink a #GParamSpec. - - -@pspec: a valid #GParamSpec -@Returns: the #GParamSpec that was passed into this function -@Since: 2.10 - - - - -Sets @value to its default value as specified in @pspec. - - -@pspec: a valid #GParamSpec -@value: a #GValue of correct type for @pspec - - - - -Checks whether @value contains the default value as specified in @pspec. - - -@pspec: a valid #GParamSpec -@value: a #GValue of correct type for @pspec -@Returns: whether @value contains the canonical default for this @pspec - - - - -Ensures that the contents of @value comply with the specifications -set out by @pspec. For example, a #GParamSpecInt might require -that integers stored in @value may not be smaller than -42 and not be -greater than +42. If @value contains an integer outside of this range, -it is modified accordingly, so the resulting value will fit into the -range -42 .. +42. - - -@pspec: a valid #GParamSpec -@value: a #GValue of correct type for @pspec -@Returns: whether modifying @value was necessary to ensure validity - - - - -Transforms @src_value into @dest_value if possible, and then validates -@dest_value, in order for it to conform to @pspec. -If @strict_validation is %TRUE this function will only succeed if -the transformed @dest_value complied to @pspec without modifications. - -See also g_value_type_transformable(), g_value_transform() and -g_param_value_validate(). - - -@pspec: a valid #GParamSpec -@src_value: souce #GValue -@dest_value: destination #GValue of correct type for @pspec -@strict_validation: %TRUE requires @dest_value to conform to @pspec without modifications -@Returns: %TRUE if transformation and validation were successful, - %FALSE otherwise and @dest_value is left untouched. - - - - -Compares @value1 with @value2 according to @pspec, and return -1, 0 or +1, -if @value1 is found to be less than, equal to or greater than @value2, -respectively. - - -@pspec: a valid #GParamSpec -@value1: a #GValue of correct type for @pspec -@value2: a #GValue of correct type for @pspec -@Returns: -1, 0 or +1, for a less than, equal to or greater than result - - - - -Returns the name of a #GParamSpec. - - -@pspec: a valid #GParamSpec -@Returns: the name of @pspec. - - - - -Returns the nickname of a #GParamSpec. - - -@pspec: a valid #GParamSpec -@Returns: the nickname of @pspec. - - - - -Returns the short description of a #GParamSpec. - - -@pspec: a valid #GParamSpec -@Returns: the short description of @pspec. - - - - -Gets back user data pointers stored via g_param_spec_set_qdata(). - - -@pspec: a valid #GParamSpec -@quark: a #GQuark, naming the user data pointer -@Returns: the user data pointer set, or %NULL - - - - -Sets an opaque, named pointer on a #GParamSpec. The name is specified -through a #GQuark (retrieved e.g. via g_quark_from_static_string()), and -the pointer can be gotten back from the @pspec with g_param_spec_get_qdata(). -Setting a previously set user data pointer, overrides (frees) -the old pointer set, using %NULL as pointer essentially -removes the data stored. - - -@pspec: the #GParamSpec to set store a user data pointer -@quark: a #GQuark, naming the user data pointer -@data: an opaque user data pointer - - - - -This function works like g_param_spec_set_qdata(), but in addition, -a void (*destroy) (gpointer) function may be -specified which is called with @data as argument when the @pspec is -finalized, or the data is being overwritten by a call to -g_param_spec_set_qdata() with the same @quark. - - -@pspec: the #GParamSpec to set store a user data pointer -@quark: a #GQuark, naming the user data pointer -@data: an opaque user data pointer -@destroy: function to invoke with @data as argument, when @data needs to - be freed - - - - -Gets back user data pointers stored via g_param_spec_set_qdata() and -removes the @data from @pspec without invoking it's destroy() function -(if any was set). -Usually, calling this function is only required to update -user data pointers with a destroy notifier. - - -@pspec: the #GParamSpec to get a stored user data pointer from -@quark: a #GQuark, naming the user data pointer -@Returns: the user data pointer set, or %NULL - - - - -If the paramspec redirects operations to another paramspec, -returns that paramspec. Redirect is used typically for -providing a new implementation of a property in a derived -type while preserving all the properties from the parent -type. Redirection is established by creating a property -of type #GParamSpecOverride. See g_object_class_override_property() -for an example of the use of this capability. - - -@pspec: a #GParamSpec -@Returns: paramspec to which requests on this paramspec should - be redirected, or %NULL if none. -@Since: 2.4 - - - - -Creates a new #GParamSpec instance. - - -A property name consists of segments consisting of ASCII letters and -digits, separated by either the '-' or '_' character. The first -character of a property name must be a letter. Names which violate these -rules lead to undefined behaviour. - - -When creating and looking up a #GParamSpec, either separator can be used, -but they cannot be mixed. Using '-' is considerably more efficient and in -fact required when using property names as detail strings for signals. - - -Beyond the name, #GParamSpecs have two more descriptive strings -associated with them, the @nick, which should be suitable for use as -a label for the property in a property editor, and the @blurb, which should -be a somewhat longer description, suitable for e.g. a tooltip. The @nick -and @blurb should ideally be localized. - - -@param_type: the #GType for the property; must be derived from #G_TYPE_PARAM -@name: the canonical name of the property -@nick: the nickname of the property -@blurb: a short description of the property -@flags: a combination of #GParamFlags -@Returns: a newly allocated #GParamSpec instance - - - - -This structure is used to provide the type system with the information -required to initialize and destruct (finalize) a parameter's class and -instances thereof. -The initialized structure is passed to the g_param_type_register_static() -The type system will perform a deep copy of this structure, so it's memory -does not need to be persistent across invocation of -g_param_type_register_static(). - - -@instance_size: Size of the instance (object) structure. -@n_preallocs: Prior to GLib 2.10, it specified the number of pre-allocated (cached) instances to reserve memory for (0 indicates no caching). Since GLib 2.10, it is ignored, since instances are allocated with the slice allocator now. -@instance_init: Location of the instance initialization function (optional). -@value_type: The #GType of values conforming to this #GParamSpec -@finalize: The instance finalization function (optional). -@value_set_default: Resets a @value to the default value for @pspec - (recommended, the default is g_value_reset()), see - g_param_value_set_default(). -@value_validate: Ensures that the contents of @value comply with the - specifications set out by @pspec (optional), see - g_param_value_set_validate(). -@values_cmp: Compares @value1 with @value2 according to @pspec - (recommended, the default is memcmp()), see g_param_values_cmp(). - - - -Registers @name as the name of a new static type derived from -#G_TYPE_PARAM. The type system uses the information contained in the -#GParamSpecTypeInfo structure pointed to by @info to manage the #GParamSpec -type and its instances. - - -@name: 0-terminated string used as the name of the new #GParamSpec type. -@pspec_info: The #GParamSpecTypeInfo for this #GParamSpec type. -@Returns: The new type identifier. - - - - -A #GParamSpecPool maintains a collection of #GParamSpecs which can be -quickly accessed by owner and name. The implementation of the #GObject property -system uses such a pool to store the #GParamSpecs of the properties all object -types. - - - - - -Creates a new #GParamSpecPool. - - -If @type_prefixing is %TRUE, lookups in the newly created pool will -allow to specify the owner as a colon-separated prefix of the property name, -like "GtkContainer:border-width". This feature is deprecated, so you should -always set @type_prefixing to %FALSE. - - -@type_prefixing: Whether the pool will support type-prefixed property names. -@Returns: a newly allocated #GParamSpecPool. - - - - -Inserts a #GParamSpec in the pool. - - -@pool: a #GParamSpecPool. -@pspec: the #GParamSpec to insert -@owner_type: a #GType identifying the owner of @pspec - - - - -Removes a #GParamSpec from the pool. - - -@pool: a #GParamSpecPool -@pspec: the #GParamSpec to remove - - - - -Looks up a #GParamSpec in the pool. - - -@pool: a #GParamSpecPool -@param_name: the name to look for -@owner_type: the owner to look for -@walk_ancestors: If %TRUE, also try to find a #GParamSpec with @param_name - owned by an ancestor of @owner_type. -@Returns: The found #GParamSpec, or %NULL if no matching #GParamSpec was found. - - - - -Gets an array of all #GParamSpecs owned by @owner_type in the pool. - - -@pool: a #GParamSpecPool -@owner_type: the owner to look for -@n_pspecs_p: return location for the length of the returned array -@Returns: a newly allocated array containing pointers to all - #GParamSpecs owned by @owner_type in the pool - - - - -Gets an #GList of all #GParamSpecs owned by @owner_type in the pool. - - -@pool: a #GParamSpecPool -@owner_type: the owner to look for -@Returns: a #GList of all #GParamSpecs owned by @owner_type in - the pool#GParamSpecs. - - diff --git a/gobject/gparam.c b/gobject/gparam.c index 8affe893..71de194b 100644 --- a/gobject/gparam.c +++ b/gobject/gparam.c @@ -16,7 +16,22 @@ * Free Software Foundation, Inc., 59 Temple Place, Suite 330, * Boston, MA 02111-1307, USA. */ - +/** + * SECTION:gparamspec + * @Short_description: Metadata for parameter specifications + * @See_also:g_object_class_install_property(), g_object_set(), g_object_get(), + * g_object_set_property(), g_object_get_property(), g_value_register_transform_func() + * + * #GParamSpec is an object structure that encapsulates the metadata + * required to specify parameters, such as e.g. #GObject properties. + * + * + * 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. + * The result of this replacement is called the canonical name of the + * parameter. + */ /* * MT safe */ @@ -160,6 +175,14 @@ g_param_spec_finalize (GParamSpec *pspec) g_type_free_instance ((GTypeInstance*) pspec); } +/** + * g_param_spec_ref: + * @pspec: a valid #GParamSpec + * + * Increments the reference count of @pspec. + * + * Returns: the #GParamSpec that was passed into this function + */ GParamSpec* g_param_spec_ref (GParamSpec *pspec) { @@ -171,6 +194,12 @@ g_param_spec_ref (GParamSpec *pspec) return pspec; } +/** + * g_param_spec_unref: + * @pspec: a valid #GParamSpec + * + * Decrements the reference count of a @pspec. + */ void g_param_spec_unref (GParamSpec *pspec) { @@ -187,6 +216,18 @@ g_param_spec_unref (GParamSpec *pspec) } } +/** + * g_param_spec_sink: + * @pspec: a valid #GParamSpec + * + * The initial reference count of a newly created #GParamSpec is 1, even + * though no one has explicitly called g_param_spec_ref() on it yet. So the + * initial reference count is flagged as "floating", until someone calls + * g_param_spec_ref (pspec); g_param_spec_sink (pspec); + * in sequence on it, taking over the initial reference count (thus + * ending up with a @pspec that has a reference count of 1 still, but is + * not flagged "floating" anymore). + */ void g_param_spec_sink (GParamSpec *pspec) { @@ -202,6 +243,15 @@ g_param_spec_sink (GParamSpec *pspec) g_param_spec_unref (pspec); } +/** + * g_param_spec_ref_sink: + * @pspec: a valid #GParamSpec + * + * Convenience function to ref and sink a #GParamSpec. + * + * Since: 2.10 + * Returns: the #GParamSpec that was passed into this function + */ GParamSpec* g_param_spec_ref_sink (GParamSpec *pspec) { @@ -213,6 +263,14 @@ g_param_spec_ref_sink (GParamSpec *pspec) return pspec; } +/** + * g_param_spec_get_name: + * @pspec: a valid #GParamSpec + * + * Get the name of a #GParamSpec. + * + * Returns: the name of @pspec. + */ G_CONST_RETURN gchar* g_param_spec_get_name (GParamSpec *pspec) { @@ -221,6 +279,14 @@ g_param_spec_get_name (GParamSpec *pspec) return pspec->name; } +/** + * g_param_spec_get_nick: + * @pspec: a valid #GParamSpec + * + * Get the nickname of a #GParamSpec. + * + * Returns: the nickname of @pspec. + */ G_CONST_RETURN gchar* g_param_spec_get_nick (GParamSpec *pspec) { @@ -240,6 +306,14 @@ g_param_spec_get_nick (GParamSpec *pspec) return pspec->name; } +/** + * g_param_spec_get_blurb: + * @pspec: a valid #GParamSpec + * + * Get the short description of a #GParamSpec. + * + * Returns: the short description of @pspec. + */ G_CONST_RETURN gchar* g_param_spec_get_blurb (GParamSpec *pspec) { @@ -295,6 +369,33 @@ is_canonical (const gchar *key) return TRUE; } +/** + * g_param_spec_internal: + * @param_type: the #GType for the property; must be derived from #G_TYPE_PARAM + * @name: the canonical name of the property + * @nick: the nickname of the property + * @blurb: a short description of the property + * @flags: a combination of #GParamFlags + * + * Creates a new #GParamSpec instance. + * + * A property name consists of segments consisting of ASCII letters and + * digits, separated by either the '-' or '_' character. The first + * character of a property name must be a letter. Names which violate these + * rules lead to undefined behaviour. + * + * When creating and looking up a #GParamSpec, either separator can be used, + * but they cannot be mixed. Using '-' is considerably more efficient and in + * fact required when using property names as detail strings for signals. + * + * Beyond the name, #GParamSpecs have two more descriptive strings + * associated with them, the @nick, which should be suitable for use as + * a label for the property in a property editor, and the @blurb, which should + * be a somewhat longer description, suitable for e.g. a tooltip. The @nick + * and @blurb should ideally be localized. + * + * Returns: a newly allocated #GParamSpec instance + */ gpointer g_param_spec_internal (GType param_type, const gchar *name, @@ -339,6 +440,15 @@ g_param_spec_internal (GType param_type, return pspec; } +/** + * g_param_spec_get_qdata: + * @pspec: a valid #GParamSpec + * @quark: a #GQuark, naming the user data pointer + * + * Gets back user data pointers stored via g_param_spec_set_qdata(). + * + * Returns: the user data pointer set, or %NULL + */ gpointer g_param_spec_get_qdata (GParamSpec *pspec, GQuark quark) @@ -348,6 +458,19 @@ g_param_spec_get_qdata (GParamSpec *pspec, return quark ? g_datalist_id_get_data (&pspec->qdata, quark) : NULL; } +/** + * g_param_spec_set_qdata: + * @pspec: the #GParamSpec to set store a user data pointer + * @quark: a #GQuark, naming the user data pointer + * @data: an opaque user data pointer + * + * Sets an opaque, named pointer on a #GParamSpec. The name is specified + * through a #GQuark (retrieved e.g. via g_quark_from_static_string()), and + * the pointer can be gotten back from the @pspec with g_param_spec_get_qdata(). + * Setting a previously set user data pointer, overrides (frees) + * the old pointer set, using %NULL as pointer essentially + * removes the data stored. + */ void g_param_spec_set_qdata (GParamSpec *pspec, GQuark quark, @@ -359,6 +482,20 @@ g_param_spec_set_qdata (GParamSpec *pspec, g_datalist_id_set_data (&pspec->qdata, quark, data); } +/** + * g_param_spec_set_qdata_full: + * @pspec: the #GParamSpec to set store a user data pointer + * @quark: a #GQuark, naming the user data pointer + * @data: an opaque user data pointer + * @destroy: function to invoke with @data as argument, when @data needs to + * be freed + * + * This function works like g_param_spec_set_qdata(), but in addition, + * a void (*destroy) (gpointer) function may be + * specified which is called with @data as argument when the @pspec is + * finalized, or the data is being overwritten by a call to + * g_param_spec_set_qdata() with the same @quark. + */ void g_param_spec_set_qdata_full (GParamSpec *pspec, GQuark quark, @@ -371,6 +508,19 @@ g_param_spec_set_qdata_full (GParamSpec *pspec, g_datalist_id_set_data_full (&pspec->qdata, quark, data, data ? destroy : (GDestroyNotify) NULL); } +/** + * g_param_spec_steal_qdata: + * @pspec: the #GParamSpec to get a stored user data pointer from + * @quark: a #GQuark, naming the user data pointer + * + * Gets back user data pointers stored via g_param_spec_set_qdata() and + * removes the @data from @pspec without invoking it's destroy() function + * (if any was set). + * Usually, calling this function is only required to update + * user data pointers with a destroy notifier. + * + * Returns: the user data pointer set, or %NULL + */ gpointer g_param_spec_steal_qdata (GParamSpec *pspec, GQuark quark) @@ -381,6 +531,22 @@ g_param_spec_steal_qdata (GParamSpec *pspec, return g_datalist_id_remove_no_notify (&pspec->qdata, quark); } +/** + * g_param_spec_get_redirect_target: + * @pspec: a #GParamSpec + * + * If the paramspec redirects operations to another paramspec, + * returns that paramspec. Redirect is used typically for + * providing a new implementation of a property in a derived + * type while preserving all the properties from the parent + * type. Redirection is established by creating a property + * of type #GParamSpecOverride. See g_object_class_override_property() + * for an example of the use of this capability. + * + * Since: 2.4 + * Returns: paramspec to which requests on this paramspec should + * be redirected, or %NULL if none. + */ GParamSpec* g_param_spec_get_redirect_target (GParamSpec *pspec) { @@ -396,6 +562,13 @@ g_param_spec_get_redirect_target (GParamSpec *pspec) return NULL; } +/** + * g_param_value_set_default: + * @pspec: a valid #GParamSpec + * @value: a #GValue of correct type for @pspec + * + * Sets @value to its default value as specified in @pspec. + */ void g_param_value_set_default (GParamSpec *pspec, GValue *value) @@ -408,6 +581,15 @@ g_param_value_set_default (GParamSpec *pspec, G_PARAM_SPEC_GET_CLASS (pspec)->value_set_default (pspec, value); } +/** + * g_param_value_defaults: + * @pspec: a valid #GParamSpec + * @value: a #GValue of correct type for @pspec + * + * Checks whether @value contains the default value as specified in @pspec. + * + * Returns: whether @value contains the canonical default for this @pspec + */ gboolean g_param_value_defaults (GParamSpec *pspec, GValue *value) @@ -427,6 +609,20 @@ g_param_value_defaults (GParamSpec *pspec, return defaults; } +/** + * g_param_value_validate: + * @pspec: a valid #GParamSpec + * @value: a #GValue of correct type for @pspec + * + * Ensures that the contents of @value comply with the specifications + * set out by @pspec. For example, a #GParamSpecInt might require + * that integers stored in @value may not be smaller than -42 and not be + * greater than +42. If @value contains an integer outside of this range, + * it is modified accordingly, so the resulting value will fit into the + * range -42 .. +42. + * + * Returns: whether modifying @value was necessary to ensure validity + */ gboolean g_param_value_validate (GParamSpec *pspec, GValue *value) @@ -447,6 +643,24 @@ g_param_value_validate (GParamSpec *pspec, return FALSE; } +/** + * g_param_value_convert: + * @pspec: a valid #GParamSpec + * @src_value: souce #GValue + * @dest_value: destination #GValue of correct type for @pspec + * @strict_validation: %TRUE requires @dest_value to conform to @pspec without modifications + * + * Transforms @src_value into @dest_value if possible, and then validates + * @dest_value, in order for it to conform to @pspec. + * If @strict_validation is %TRUE this function will only succeed if + * the transformed @dest_value complied to @pspec without modifications. + * + * See also g_value_type_transformable(), g_value_transform() and + * g_param_value_validate(). + * + * Returns: %TRUE if transformation and validation were successful, + * %FALSE otherwise and @dest_value is left untouched. + */ gboolean g_param_value_convert (GParamSpec *pspec, const GValue *src_value, @@ -481,6 +695,18 @@ g_param_value_convert (GParamSpec *pspec, } } +/** + * g_param_values_cmp: + * @pspec: a valid #GParamSpec + * @value1: a #GValue of correct type for @pspec + * @value2: a #GValue of correct type for @pspec + * + * Compares @value1 with @value2 according to @pspec, and return -1, 0 or +1, + * if @value1 is found to be less than, equal to or greater than @value2, + * respectively. + * + * Returns: -1, 0 or +1, for a less than, equal to or greater than result + */ gint g_param_values_cmp (GParamSpec *pspec, const GValue *value1, @@ -598,6 +824,14 @@ value_param_lcopy_value (const GValue *value, /* --- param spec pool --- */ +/** + * GParamSpecPool: + * + * A #GParamSpecPool maintains a collection of #GParamSpecs which can be + * quickly accessed by owner and name. The implementation of the #GObject property + * system uses such a pool to store the #GParamSpecs of the properties all object + * types. + */ struct _GParamSpecPool { GStaticMutex smutex; @@ -629,6 +863,19 @@ param_spec_pool_equals (gconstpointer key_spec_1, strcmp (key1->name, key2->name) == 0); } +/** + * g_param_spec_pool_new: + * @type_prefixing: Whether the pool will support type-prefixed property names. + * + * Creates a new #GParamSpecPool. + * + * If @type_prefixing is %TRUE, lookups in the newly created pool will + * allow to specify the owner as a colon-separated prefix of the property name, + * like "GtkContainer:border-width". This feature is deprecated, so you should + * always set @type_prefixing to %FALSE. + * + * Returns: a newly allocated #GParamSpecPool. + */ GParamSpecPool* g_param_spec_pool_new (gboolean type_prefixing) { @@ -642,7 +889,14 @@ g_param_spec_pool_new (gboolean type_prefixing) return pool; } -void +/** + * g_param_spec_pool_insert: + * @pool: a #GParamSpecPool. + * @pspec: the #GParamSpec to insert + * @owner_type: a #GType identifying the owner of @pspec + * + * Inserts a #GParamSpec in the pool. + */void g_param_spec_pool_insert (GParamSpecPool *pool, GParamSpec *pspec, GType owner_type) @@ -676,6 +930,13 @@ g_param_spec_pool_insert (GParamSpecPool *pool, } } +/** + * g_param_spec_pool_remove: + * @pool: a #GParamSpecPool + * @pspec: the #GParamSpec to remove + * + * Removes a #GParamSpec from the pool. + */ void g_param_spec_pool_remove (GParamSpecPool *pool, GParamSpec *pspec) @@ -745,6 +1006,18 @@ param_spec_ht_lookup (GHashTable *hash_table, return pspec; } +/** + * g_param_spec_pool_lookup: + * @pool: a #GParamSpecPool + * @param_name: the name to look for + * @owner_type: the owner to look for + * @walk_ancestors: If %TRUE, also try to find a #GParamSpec with @param_name + * owned by an ancestor of @owner_type. + * + * Looks up a #GParamSpec in the pool. + * + * Returns: The found #GParamSpec, or %NULL if no matching #GParamSpec was found. + */ GParamSpec* g_param_spec_pool_lookup (GParamSpecPool *pool, const gchar *param_name, @@ -822,6 +1095,16 @@ pool_list (gpointer key, data[0] = g_list_prepend (data[0], pspec); } +/** + * g_param_spec_pool_list_owned: + * @pool: a #GParamSpecPool + * @owner_type: the owner to look for + * + * Gets an #GList of all #GParamSpecs owned by @owner_type in the pool. + * + * Returns: a #GList of all #GParamSpecs owned by @owner_type in + * the pool#GParamSpecs. + */ GList* g_param_spec_pool_list_owned (GParamSpecPool *pool, GType owner_type) @@ -945,7 +1228,18 @@ pool_depth_list_for_interface (gpointer key, slists[0] = g_slist_prepend (slists[0], pspec); } -GParamSpec** /* free result */ +/** + * g_param_spec_pool_list: + * @pool: a #GParamSpecPool + * @owner_type: the owner to look for + * @n_pspecs_p: return location for the length of the returned array + * + * Gets an array of all #GParamSpecs owned by @owner_type in the pool. + * + * Returns: a newly allocated array containing pointers to all + * #GParamSpecs owned by @owner_type in the pool + */ +GParamSpec** g_param_spec_pool_list (GParamSpecPool *pool, GType owner_type, guint *n_pspecs_p) @@ -1038,6 +1332,18 @@ default_values_cmp (GParamSpec *pspec, return memcmp (&value1->data, &value2->data, sizeof (value1->data)); } +/** + * g_param_type_register_static: + * @name: 0-terminated string used as the name of the new #GParamSpec type. + * @pspec_info: The #GParamSpecTypeInfo for this #GParamSpec type. + * + * Registers @name as the name of a new static type derived from + * #G_TYPE_PARAM. The type system uses the information contained in the + * #GParamSpecTypeInfo structure pointed to by @info to manage the #GParamSpec + * type and its instances. + * + * Returns: The new type identifier. + */ GType g_param_type_register_static (const gchar *name, const GParamSpecTypeInfo *pspec_info) diff --git a/gobject/gparam.h b/gobject/gparam.h index 3790712e..92cc31be 100644 --- a/gobject/gparam.h +++ b/gobject/gparam.h @@ -30,22 +30,103 @@ G_BEGIN_DECLS /* --- standard type macros --- */ +/** + * G_TYPE_IS_PARAM: + * @type: a #GType ID + * + * Checks whether @type "is a" %G_TYPE_PARAM. + */ #define G_TYPE_IS_PARAM(type) (G_TYPE_FUNDAMENTAL (type) == G_TYPE_PARAM) +/** + * G_PARAM_SPEC: + * @pspec: a valid #GParamSpec + * + * Casts a derived #GParamSpec object (e.g. of type #GParamSpecInt) into + * a #GParamSpec object. + */ #define G_PARAM_SPEC(pspec) (G_TYPE_CHECK_INSTANCE_CAST ((pspec), G_TYPE_PARAM, GParamSpec)) +/** + * G_IS_PARAM_SPEC: + * @pspec: a #GParamSpec + * + * Checks whether @pspec "is a" valid #GParamSpec structure of type %G_TYPE_PARAM + * or derived. + */ #define G_IS_PARAM_SPEC(pspec) (G_TYPE_CHECK_INSTANCE_TYPE ((pspec), G_TYPE_PARAM)) +/** + * G_PARAM_SPEC_CLASS: + * @pclass: a valid #GParamSpecClass + * + * Casts a derived #GParamSpecClass structure into a #GParamSpecClass structure. + */ #define G_PARAM_SPEC_CLASS(pclass) (G_TYPE_CHECK_CLASS_CAST ((pclass), G_TYPE_PARAM, GParamSpecClass)) +/** + * G_IS_PARAM_SPEC_CLASS: + * @pclass: a #GParamSpecClass + * + * Checks whether @pclass "is a" valid #GParamSpecClass structure of type + * %G_TYPE_PARAM or derived. + */ #define G_IS_PARAM_SPEC_CLASS(pclass) (G_TYPE_CHECK_CLASS_TYPE ((pclass), G_TYPE_PARAM)) +/** + * G_PARAM_SPEC_GET_CLASS: + * @pspec: a valid #GParamSpec + * + * Retrieves the #GParamSpecClass of a #GParamSpec. + */ #define G_PARAM_SPEC_GET_CLASS(pspec) (G_TYPE_INSTANCE_GET_CLASS ((pspec), G_TYPE_PARAM, GParamSpecClass)) /* --- convenience macros --- */ +/** + * G_PARAM_SPEC_TYPE: + * @pspec: a valid #GParamSpec + * + * Retrieves the #GType of this @pspec. + */ #define G_PARAM_SPEC_TYPE(pspec) (G_TYPE_FROM_INSTANCE (pspec)) +/** + * G_PARAM_SPEC_TYPE_NAME: + * @pspec: a valid #GParamSpec + * + * Retrieves the #GType name of this @pspec. + */ #define G_PARAM_SPEC_TYPE_NAME(pspec) (g_type_name (G_PARAM_SPEC_TYPE (pspec))) +/** + * G_PARAM_SPEC_VALUE_TYPE: + * @pspec: a valid #GParamSpec + * + * Retrieves the #GType to initialize a #GValue for this parameter. + */ #define G_PARAM_SPEC_VALUE_TYPE(pspec) (G_PARAM_SPEC (pspec)->value_type) #define G_VALUE_HOLDS_PARAM(value) (G_TYPE_CHECK_VALUE_TYPE ((value), G_TYPE_PARAM)) /* --- flags --- */ +/** + * GParamFlags: + * @G_PARAM_READABLE: the parameter is readable + * @G_PARAM_WRITABLE: the parameter is writable + * @G_PARAM_CONSTRUCT: the parameter will be set upon object construction + * @G_PARAM_CONSTRUCT_ONLY: the parameter will only be set upon object construction + * @G_PARAM_LAX_VALIDATION: upon parameter conversion (see g_param_value_convert()) + * strict validation is not required + * @G_PARAM_STATIC_NAME: the string used as name when constructing the + * parameter is guaranteed to remain valid and + * unmodified for the lifetime of the parameter. + * Since 2.8 + * @G_PARAM_PRIVATE: * @G_PARAM_STATIC_NICK: the string used as nick when constructing the + * parameter is guaranteed to remain valid and + * unmmodified for the lifetime of the parameter. + * Since 2.8 + * @G_PARAM_STATIC_BLURB: the string used as blurb when constructing the + * parameter is guaranteed to remain valid and + * unmodified for the lifetime of the parameter. + * Since 2.8 + * + * Through the #GParamFlags flag values, certain aspects of parameters + * can be configured. + */ typedef enum { G_PARAM_READABLE = 1 << 0, @@ -60,10 +141,33 @@ typedef enum G_PARAM_STATIC_NICK = 1 << 6, G_PARAM_STATIC_BLURB = 1 << 7 } GParamFlags; +/** + * G_PARAM_READWRITE: + * + * #GParamFlags value alias for %G_PARAM_READABLE | %G_PARAM_WRITABLE. + */ #define G_PARAM_READWRITE (G_PARAM_READABLE | G_PARAM_WRITABLE) +/** + * G_PARAM_STATIC_STRINGS: + * + * #GParamFlags value alias for %G_PARAM_STATIC_NAME | %G_PARAM_STATIC_NICK | %G_PARAM_STATIC_BLURB. + * + * Since 2.13.0 + */ #define G_PARAM_STATIC_STRINGS (G_PARAM_STATIC_NAME | G_PARAM_STATIC_NICK | G_PARAM_STATIC_BLURB) -#define G_PARAM_MASK (0x000000ff) /* bits in the range 0xffffff00 are reserved for 3rd party usage */ +/** + * G_PARAM_MASK: + * + * Mask containing the bits of #GParamSpec.flags which are reserved for GLib. + */ +#define G_PARAM_MASK (0x000000ff) +/** + * G_PARAM_USER_SHIFT: + * + * Minimum shift count to be used for user defined flags, to be stored in + * #GParamSpec.flags. + */ #define G_PARAM_USER_SHIFT (8) @@ -72,6 +176,17 @@ typedef struct _GParamSpec GParamSpec; typedef struct _GParamSpecClass GParamSpecClass; typedef struct _GParameter GParameter; typedef struct _GParamSpecPool GParamSpecPool; +/** + * GParamSpec: + * @g_type_instance: private #GTypeInstance portion + * @name: name of this parameter + * @flags: #GParamFlags flags for this parameter + * @value_type: the #GValue type for this parameter + * @owner_type: #GType type that uses (introduces) this paremeter + * + * All fields of the GParamSpec struct are private and + * should not be used directly, except for the following: + */ struct _GParamSpec { GTypeInstance g_type_instance; @@ -88,6 +203,25 @@ struct _GParamSpec guint ref_count; guint param_id; /* sort-criteria */ }; +/** + * GParamSpecClass: + * @g_type_class: the parent class + * @value_type: the #GValue type for this parameter + * @finalize: The instance finalization function (optional), should chain + * up to the finalize method of the parent class. + * @value_set_default: Resets a @value to the default value for this type + * (recommended, the default is g_value_reset()), see + * g_param_value_set_default(). + * @value_validate: Ensures that the contents of @value comply with the + * specifications set out by this type (optional), see + * g_param_value_set_validate(). + * @values_cmp: Compares @value1 with @value2 according to this type + * (recommended, the default is memcmp()), see g_param_values_cmp(). + * + * The class structure for the GParamSpec type. + * Normally, GParamSpec classes are filled by + * g_param_type_register_static(). + */ struct _GParamSpecClass { GTypeClass g_type_class; @@ -163,6 +297,30 @@ void g_value_set_param_take_ownership (GValue *value, /* --- convenience functions --- */ typedef struct _GParamSpecTypeInfo GParamSpecTypeInfo; +/** + * GParamSpecTypeInfo: + * @instance_size: Size of the instance (object) structure. + * @n_preallocs: Prior to GLib 2.10, it specified the number of pre-allocated (cached) instances to reserve memory for (0 indicates no caching). Since GLib 2.10, it is ignored, since instances are allocated with the slice allocator now. + * @instance_init: Location of the instance initialization function (optional). + * @value_type: The #GType of values conforming to this #GParamSpec + * @finalize: The instance finalization function (optional). + * @value_set_default: Resets a @value to the default value for @pspec + * (recommended, the default is g_value_reset()), see + * g_param_value_set_default(). + * @value_validate: Ensures that the contents of @value comply with the + * specifications set out by @pspec (optional), see + * g_param_value_set_validate(). + * @values_cmp: Compares @value1 with @value2 according to @pspec + * (recommended, the default is memcmp()), see g_param_values_cmp(). + * + * This structure is used to provide the type system with the information + * required to initialize and destruct (finalize) a parameter's class and + * instances thereof. + * The initialized structure is passed to the g_param_type_register_static() + * The type system will perform a deep copy of this structure, so it's memory + * does not need to be persistent across invocation of + * g_param_type_register_static(). + */ struct _GParamSpecTypeInfo { /* type system portion */