#GParamSpec is an object structure that encapsulates the metadata
required to specify parameters, such as e.g. #GObject properties.
</para>
-<para>
+<para id="canonical-parameter-name">
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.
</para>
<!-- ##### SECTION See_Also ##### -->
parameter is guaranteed to remain valid and
unmodified for the lifetime of the parameter.
Since 2.8
-@G_PARAM_STATIC_NICK: the string used as nick when constructing the
- parameter is guaranteed to remain valid and
- unmodified for the lifetime of the parameter.
+@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
+<!-- ##### MACRO G_PARAM_STATIC_STRINGS ##### -->
+<para>
+#GParamFlags value alias for %G_PARAM_STATIC_NAME | %G_PARAM_STATIC_NICK | %G_PARAM_STATIC_BLURB.
+
+Since 2.13.0
+</para>
+
+
+
<!-- ##### MACRO G_PARAM_MASK ##### -->
<para>
Mask containing the bits of #GParamSpec.flags which are reserved for GLib.
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
-<literal>g_param_spec_ref (@pspec); g_param_spec_sink (@pspec);</literal>
+<literal>g_param_spec_ref (pspec); g_param_spec_sink (pspec);</literal>
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
+<!-- ##### FUNCTION g_param_spec_ref_sink ##### -->
+<para>
+Convenience function to ref and sink a #GParamSpec.
+</para>
+
+@pspec: a valid #GParamSpec
+@Returns: the #GParamSpec that was passed into this function
+@Since: 2.10
+
+
<!-- ##### FUNCTION g_param_value_set_default ##### -->
<para>
Sets @value to its default value as specified in @pspec.
@pspec: a valid #GParamSpec
@value: a #GValue of correct type for @pspec
-@Returns: whether @value contains the canonical defualt for this @pspec
+@Returns: whether @value contains the canonical default for this @pspec
<!-- ##### FUNCTION g_param_value_validate ##### -->
@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 successfull,
+@Returns: %TRUE if transformation and validation were successful,
%FALSE otherwise and @dest_value is left untouched.
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
+the old pointer set, using %NULL as pointer essentially
removes the data stored.
</para>
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 perserving all the properties from the parent
+type while preserving all the properties from the parent
type. Redirection is established by creating a property
-of type #GParamSpecOverride. See g_object_override_property()
+of type #GParamSpecOverride. See g_object_class_override_property()
for an example of the use of this capability.
</para>
but they cannot be mixed. Using '-' is considerably more efficient and in
fact required when using property names as detail strings for signals.
</para>
+<para>
+Beyond the name, #GParamSpec<!-- -->s 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.
+</para>
@param_type: the #GType for the property; must be derived from #G_TYPE_PARAM
@name: the canonical name of the property
</para>
@instance_size: Size of the instance (object) structure.
-@n_preallocs: Number of pre-allocated (cached) instances to reserve memory for (0 indicates no caching).
+@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 <link linkend="glib-Memory-Slices">slice allocator</link> 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).
projects / platform / upstream / glib.git / blobdiff