mirror of
https://gitlab.gnome.org/GNOME/glib.git
synced 2024-11-11 03:46:17 +01:00
280a213b09
2003-02-07 Matthias Clasen <maclas@gmx.de> * gobject/tmpl/gtypemodule.sgml: * gobject/tmpl/gtype.sgml: * gobject/tmpl/gclosure.sgml: * gobject/tmpl/param_value_types.sgml: * gobject/tmpl/gparamspec.sgml: * gobject/tmpl/objects.sgml: * gobject/tmpl/signals.sgml: Move all docs out-of-line. Boy, what a waste of time.
429 lines
8.9 KiB
Plaintext
429 lines
8.9 KiB
Plaintext
<!-- ##### SECTION Title ##### -->
|
|
GParamSpec
|
|
|
|
<!-- ##### SECTION Short_Description ##### -->
|
|
Metadata for parameter specifications
|
|
|
|
<!-- ##### SECTION Long_Description ##### -->
|
|
<para>
|
|
#GParamSpec is an object structure that encapsulates the metadata
|
|
required to specify parameters, such as e.g. #GObject properties.
|
|
</para>
|
|
|
|
<!-- ##### SECTION See_Also ##### -->
|
|
<para>
|
|
g_object_class_install_property(), g_object_set(), g_object_get(),
|
|
g_object_set_property(), g_object_get_property(), g_value_register_transform_func()
|
|
</para>
|
|
|
|
<!-- ##### MACRO G_TYPE_IS_PARAM ##### -->
|
|
<para>
|
|
Returns whether @type "is a" %G_TYPE_PARAM.
|
|
</para>
|
|
|
|
@type: a #GType ID
|
|
|
|
|
|
<!-- ##### MACRO G_PARAM_SPEC ##### -->
|
|
<para>
|
|
Cast a derived #GParamSpec object (e.g. of type #GParamSpecInt) into
|
|
a #GParamSpec object.
|
|
</para>
|
|
|
|
@pspec: a valid #GParamSpec
|
|
|
|
|
|
<!-- ##### MACRO G_IS_PARAM_SPEC ##### -->
|
|
<para>
|
|
Check whether @pspec "is a" valid #GParamSpec structure of type %G_TYPE_PARAM
|
|
or derived.
|
|
</para>
|
|
|
|
@pspec: a #GParamSpec
|
|
|
|
|
|
<!-- ##### MACRO G_PARAM_SPEC_CLASS ##### -->
|
|
<para>
|
|
Cast a derived #GParamSpecClass structure into a #GParamSpecClass structure.
|
|
</para>
|
|
|
|
@pclass: a valid #GParamSpecClass
|
|
|
|
|
|
<!-- ##### MACRO G_IS_PARAM_SPEC_CLASS ##### -->
|
|
<para>
|
|
Check whether @pclass "is a" valid #GParamSpecClass structure of type %G_TYPE_PARAM
|
|
or derived.
|
|
</para>
|
|
|
|
@pclass: a #GParamSpecClass
|
|
|
|
|
|
<!-- ##### MACRO G_PARAM_SPEC_GET_CLASS ##### -->
|
|
<para>
|
|
Retrieve the #GParamSpecClass of a #GParamSpec.
|
|
</para>
|
|
|
|
@pspec: a valid #GParamSpec
|
|
|
|
|
|
<!-- ##### MACRO G_PARAM_SPEC_TYPE ##### -->
|
|
<para>
|
|
Retrieve the #GType of this @pspec.
|
|
</para>
|
|
|
|
@pspec: a valid #GParamSpec
|
|
|
|
|
|
<!-- ##### MACRO G_PARAM_SPEC_TYPE_NAME ##### -->
|
|
<para>
|
|
Retrieve the #GType name of this @pspec.
|
|
</para>
|
|
|
|
@pspec: a valid #GParamSpec
|
|
|
|
|
|
<!-- ##### MACRO G_PARAM_SPEC_VALUE_TYPE ##### -->
|
|
<para>
|
|
Retrieve the #GType to intiialize a #GValue for this parameter.
|
|
</para>
|
|
|
|
@pspec: a valid #GParamSpec
|
|
|
|
|
|
<!-- ##### STRUCT GParamSpec ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@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
|
|
|
|
<!-- ##### STRUCT GParamSpecClass ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
|
|
<!-- ##### ENUM GParamFlags ##### -->
|
|
<para>
|
|
Through the #GParamFlags flag values, certain aspects of parameters
|
|
can be configured.
|
|
</para>
|
|
|
|
@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_PRIVATE:
|
|
|
|
<!-- ##### MACRO G_PARAM_READWRITE ##### -->
|
|
<para>
|
|
#GParamFlags value alias for %G_PARAM_READABLE | %G_PARAM_WRITABLE.
|
|
</para>
|
|
|
|
|
|
|
|
<!-- ##### MACRO G_PARAM_MASK ##### -->
|
|
<para>
|
|
Mask containing the bits of #GParamSpec.flags which are reserved for GLib.
|
|
</para>
|
|
|
|
|
|
|
|
<!-- ##### MACRO G_PARAM_USER_SHIFT ##### -->
|
|
<para>
|
|
Minimum shift count to be used for user defined flags, to be stored in
|
|
#GParamSpec.flags.
|
|
</para>
|
|
|
|
|
|
|
|
<!-- ##### FUNCTION g_param_spec_ref ##### -->
|
|
<para>
|
|
Increment the reference count of @pspec.
|
|
</para>
|
|
|
|
@pspec: a valid #GParamSpec
|
|
@Returns: the #GParamSpec that was passed into this function
|
|
|
|
|
|
<!-- ##### FUNCTION g_param_spec_unref ##### -->
|
|
<para>
|
|
Decrement the reference count of a @pspec.
|
|
</para>
|
|
|
|
@pspec: a valid #GParamSpec
|
|
|
|
|
|
<!-- ##### FUNCTION g_param_spec_sink ##### -->
|
|
<para>
|
|
The initial reference count of a newly created #GParamSpec is 1,
|
|
eventhough no one has explicitely called g_param_spec_ref() on it yet.
|
|
So the einital reference count is flagged as "floating", untill 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).
|
|
</para>
|
|
|
|
@pspec: a valid #GParamSpec
|
|
|
|
|
|
<!-- ##### FUNCTION g_param_value_set_default ##### -->
|
|
<para>
|
|
Set @value to its default value as specified in @pspec.
|
|
</para>
|
|
|
|
@pspec: a valid #GParamSpec
|
|
@value: a #GValue of correct type for @pspec
|
|
|
|
|
|
<!-- ##### FUNCTION g_param_value_defaults ##### -->
|
|
<para>
|
|
Check whether @value contains the default value as specified in @pspec.
|
|
</para>
|
|
|
|
@pspec: a valid #GParamSpec
|
|
@value: a #GValue of correct type for @pspec
|
|
@Returns: whether @value contains the canonical defualt for this @pspec
|
|
|
|
|
|
<!-- ##### FUNCTION g_param_value_validate ##### -->
|
|
<para>
|
|
Ensure 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.
|
|
</para>
|
|
|
|
@pspec: a valid #GParamSpec
|
|
@value: a #GValue of correct type for @pspec
|
|
@Returns: whether modifying @value was necessary to ensure validity
|
|
|
|
|
|
<!-- ##### FUNCTION g_param_value_convert ##### -->
|
|
<para>
|
|
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
|
|
the transformed @dest_value complied to @pspec without modifications.
|
|
|
|
See also g_value_type_transformable(), g_value_transform() and
|
|
g_param_value_validate().
|
|
</para>
|
|
|
|
@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 successfull,
|
|
%FALSE otherwise and @dest_value is left untouched.
|
|
|
|
|
|
<!-- ##### FUNCTION g_param_values_cmp ##### -->
|
|
<para>
|
|
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.
|
|
</para>
|
|
|
|
@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
|
|
|
|
|
|
<!-- ##### FUNCTION g_param_spec_get_name ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@pspec:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION g_param_spec_get_nick ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@pspec:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION g_param_spec_get_blurb ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@pspec:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION g_param_spec_get_qdata ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@pspec:
|
|
@quark:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION g_param_spec_set_qdata ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@pspec:
|
|
@quark:
|
|
@data:
|
|
|
|
|
|
<!-- ##### FUNCTION g_param_spec_set_qdata_full ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@pspec:
|
|
@quark:
|
|
@data:
|
|
@destroy:
|
|
|
|
|
|
<!-- ##### FUNCTION g_param_spec_steal_qdata ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@pspec:
|
|
@quark:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION g_param_spec_internal ##### -->
|
|
<para>
|
|
Creates a new #GParamSpec instance.
|
|
</para>
|
|
<para>
|
|
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.
|
|
</para>
|
|
<para>
|
|
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.
|
|
</para>
|
|
|
|
@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
|
|
|
|
|
|
<!-- ##### STRUCT GParamSpecTypeInfo ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@instance_size:
|
|
@n_preallocs:
|
|
@instance_init:
|
|
@value_type:
|
|
@finalize:
|
|
@value_set_default:
|
|
@value_validate:
|
|
@values_cmp:
|
|
|
|
<!-- ##### FUNCTION g_param_type_register_static ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@name:
|
|
@pspec_info:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### STRUCT GParamSpecPool ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
|
|
<!-- ##### FUNCTION g_param_spec_pool_new ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@type_prefixing:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION g_param_spec_pool_insert ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@pool:
|
|
@pspec:
|
|
@owner_type:
|
|
|
|
|
|
<!-- ##### FUNCTION g_param_spec_pool_remove ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@pool:
|
|
@pspec:
|
|
|
|
|
|
<!-- ##### FUNCTION g_param_spec_pool_lookup ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@pool:
|
|
@param_name:
|
|
@owner_type:
|
|
@walk_ancestors:
|
|
@Returns:
|
|
<!-- # Unused Parameters # -->
|
|
@trailer_p:
|
|
|
|
|
|
<!-- ##### FUNCTION g_param_spec_pool_list ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@pool:
|
|
@owner_type:
|
|
@n_pspecs_p:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION g_param_spec_pool_list_owned ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@pool:
|
|
@owner_type:
|
|
@Returns:
|
|
|
|
|