From 6e5ded7781b6b66e564d8736e961b256df5d4a10 Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Wed, 15 Oct 2003 23:03:20 +0000 Subject: [PATCH] Additions, document GParamSpecPool. Thu Oct 16 01:02:04 2003 Matthias Clasen * gobject/tmpl/gparamspec.sgml: Additions, document GParamSpecPool. --- docs/reference/ChangeLog | 5 + docs/reference/gobject/tmpl/gparamspec.sgml | 183 ++++++++++++++++------------ 2 files changed, 107 insertions(+), 81 deletions(-) diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog index 0f6ac7f..63fc499 100644 --- a/docs/reference/ChangeLog +++ b/docs/reference/ChangeLog @@ -1,3 +1,8 @@ +Thu Oct 16 01:02:04 2003 Matthias Clasen + + * gobject/tmpl/gparamspec.sgml: Additions, document + GParamSpecPool. + Wed Oct 15 00:56:30 2003 Matthias Clasen * gobject/tmpl/gclosure.sgml: Improvements from Owen's feedback. diff --git a/docs/reference/gobject/tmpl/gparamspec.sgml b/docs/reference/gobject/tmpl/gparamspec.sgml index 32793ed..a728696 100644 --- a/docs/reference/gobject/tmpl/gparamspec.sgml +++ b/docs/reference/gobject/tmpl/gparamspec.sgml @@ -26,7 +26,7 @@ Returns whether @type "is a" %G_TYPE_PARAM. -Cast a derived #GParamSpec object (e.g. of type #GParamSpecInt) into +Casts a derived #GParamSpec object (e.g. of type #GParamSpecInt) into a #GParamSpec object. @@ -35,7 +35,7 @@ a #GParamSpec object. -Check whether @pspec "is a" valid #GParamSpec structure of type %G_TYPE_PARAM +Checks whether @pspec "is a" valid #GParamSpec structure of type %G_TYPE_PARAM or derived. @@ -44,7 +44,7 @@ or derived. -Cast a derived #GParamSpecClass structure into a #GParamSpecClass structure. +Casts a derived #GParamSpecClass structure into a #GParamSpecClass structure. @pclass: a valid #GParamSpecClass @@ -52,8 +52,8 @@ Cast a derived #GParamSpecClass structure into a #GParamSpecClass structure. -Check whether @pclass "is a" valid #GParamSpecClass structure of type %G_TYPE_PARAM -or derived. +Checks whether @pclass "is a" valid #GParamSpecClass structure of type +%G_TYPE_PARAM or derived. @pclass: a #GParamSpecClass @@ -61,7 +61,7 @@ or derived. -Retrieve the #GParamSpecClass of a #GParamSpec. +Retrieves the #GParamSpecClass of a #GParamSpec. @pspec: a valid #GParamSpec @@ -69,7 +69,7 @@ Retrieve the #GParamSpecClass of a #GParamSpec. -Retrieve the #GType of this @pspec. +Retrieves the #GType of this @pspec. @pspec: a valid #GParamSpec @@ -77,7 +77,7 @@ Retrieve the #GType of this @pspec. -Retrieve the #GType name of this @pspec. +Retrieves the #GType name of this @pspec. @pspec: a valid #GParamSpec @@ -85,7 +85,7 @@ Retrieve the #GType name of this @pspec. -Retrieve the #GType to intiialize a #GValue for this parameter. +Retrieves the #GType to initialize a #GValue for this parameter. @pspec: a valid #GParamSpec @@ -153,7 +153,7 @@ Minimum shift count to be used for user defined flags, to be stored in -Increment the reference count of @pspec. +Increments the reference count of @pspec. @pspec: a valid #GParamSpec @@ -162,7 +162,7 @@ Increment the reference count of @pspec. -Decrement the reference count of a @pspec. +Decrements the reference count of a @pspec. @pspec: a valid #GParamSpec @@ -170,10 +170,10 @@ Decrement the reference count of a @pspec. -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 inital reference count is flagged as "floating", until someone -calls g_param_spec_ref (@pspec); g_param_spec_sink (@pspec); +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). @@ -184,7 +184,7 @@ not flagged "floating" anymore). -Set @value to its default value as specified in @pspec. +Sets @value to its default value as specified in @pspec. @pspec: a valid #GParamSpec @@ -193,7 +193,7 @@ Set @value to its default value as specified in @pspec. -Check whether @value contains the default value as specified in @pspec. +Checks whether @value contains the default value as specified in @pspec. @pspec: a valid #GParamSpec @@ -203,7 +203,7 @@ Check whether @value contains the default value as specified in @pspec. -Ensure that the contents of @value comply with the specifications +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, @@ -218,10 +218,9 @@ range -42 .. +42. -This function 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 suceed if +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 @@ -238,8 +237,9 @@ g_param_value_validate(). -Compare @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. +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 @@ -277,8 +277,7 @@ Returns the short description of a #GParamSpec. -This function gets back user data pointers stored via -g_param_spec_set_qdata(). +Gets back user data pointers stored via g_param_spec_set_qdata(). @pspec: a valid #GParamSpec @@ -288,10 +287,9 @@ g_param_spec_set_qdata(). -This sets an opaque, named pointer on a #GParamSpec. -The name is specified through a #GQuark (retrived e.g. via -g_quark_from_static_string()), and the pointer -can be gotten back from the @pspec with g_param_spec_get_qdata(). +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. @@ -304,12 +302,11 @@ removes the data stored. -This function works like g_param_spec_set_qdata(), but in addition, +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. +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 @@ -321,10 +318,9 @@ with the same @quark. -This function 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). +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. @@ -360,94 +356,119 @@ fact required when using property names as detail strings for signals. - - - -@instance_size: -@n_preallocs: -@instance_init: -@value_type: -@finalize: -@value_set_default: -@value_validate: -@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(). + + +@instance_size: Size of the instance (object) structure. +@n_preallocs: Number of pre-allocated (cached) instances to reserve memory for (0 indicates no caching). +@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: -@pspec_info: -@Returns: +@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: -@Returns: +@type_prefixing: Whether the pool will support type-prefixed property names. +@Returns: a newly allocated #GParamSpecPool. - +Inserts a #GParamSpec in the pool. -@pool: -@pspec: -@owner_type: +@pool: a #GParamSpecPool. +@pspec: the #GParamSpec to insert +@owner_type: a #GType identifying the owner of @pspec - +Removes a #GParamSpec from the pool. -@pool: -@pspec: +@pool: a #GParamSpecPool +@pspec: the #GParamSpec to remove - +Looks up a #GParamSpec in the pool. -@pool: -@param_name: -@owner_type: -@walk_ancestors: -@Returns: - -@trailer_p: +@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: -@owner_type: -@n_pspecs_p: -@Returns: +@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: -@owner_type: -@Returns: +@pool: a #GParamSpecPool +@owner_type: the owner to look for +@Returns: a #GList of all #GParamSpecs owned by @owner_type in + the pool#GParamSpecs. -- 2.7.4