1 <!-- ##### SECTION Title ##### -->
4 <!-- ##### SECTION Short_Description ##### -->
5 Metadata for parameter specifications
7 <!-- ##### SECTION Long_Description ##### -->
9 #GParamSpec is an object structure that encapsulates the metadata
10 required to specify parameters, such as e.g. #GObject properties.
13 <!-- ##### SECTION See_Also ##### -->
15 g_object_class_install_property(), g_object_set(), g_object_get(),
16 g_object_set_property(), g_object_get_property(), g_value_register_transform_func()
19 <!-- ##### MACRO G_TYPE_IS_PARAM ##### -->
21 Returns whether @type "is a" %G_TYPE_PARAM.
27 <!-- ##### MACRO G_PARAM_SPEC ##### -->
29 Cast a derived #GParamSpec object (e.g. of type #GParamSpecInt) into
33 @pspec: a valid #GParamSpec
36 <!-- ##### MACRO G_IS_PARAM_SPEC ##### -->
38 Check whether @pspec "is a" valid #GParamSpec structure of type %G_TYPE_PARAM
45 <!-- ##### MACRO G_PARAM_SPEC_CLASS ##### -->
47 Cast a derived #GParamSpecClass structure into a #GParamSpecClass structure.
50 @pclass: a valid #GParamSpecClass
53 <!-- ##### MACRO G_IS_PARAM_SPEC_CLASS ##### -->
55 Check whether @pclass "is a" valid #GParamSpecClass structure of type %G_TYPE_PARAM
59 @pclass: a #GParamSpecClass
62 <!-- ##### MACRO G_PARAM_SPEC_GET_CLASS ##### -->
64 Retrieve the #GParamSpecClass of a #GParamSpec.
67 @pspec: a valid #GParamSpec
70 <!-- ##### MACRO G_PARAM_SPEC_TYPE ##### -->
72 Retrieve the #GType of this @pspec.
75 @pspec: a valid #GParamSpec
78 <!-- ##### MACRO G_PARAM_SPEC_TYPE_NAME ##### -->
80 Retrieve the #GType name of this @pspec.
83 @pspec: a valid #GParamSpec
86 <!-- ##### MACRO G_PARAM_SPEC_VALUE_TYPE ##### -->
88 Retrieve the #GType to intiialize a #GValue for this parameter.
91 @pspec: a valid #GParamSpec
94 <!-- ##### STRUCT GParamSpec ##### -->
99 @g_type_instance: private #GTypeInstance portion
100 @name: name of this parameter
101 @flags: #GParamFlags flags for this parameter
102 @value_type: the #GValue type for this parameter
103 @owner_type: #GType type that uses (introduces) this paremeter
105 <!-- ##### STRUCT GParamSpecClass ##### -->
111 <!-- ##### ENUM GParamFlags ##### -->
113 Through the #GParamFlags flag values, certain aspects of parameters
117 @G_PARAM_READABLE: the parameter is readable
118 @G_PARAM_WRITABLE: the parameter is writable
119 @G_PARAM_CONSTRUCT: the parameter will be set upon object construction
120 @G_PARAM_CONSTRUCT_ONLY: the parameter will only be set upon object construction
121 @G_PARAM_LAX_VALIDATION: upon parameter conversion (see g_param_value_convert())
122 strict validation is not required
125 <!-- ##### MACRO G_PARAM_READWRITE ##### -->
127 #GParamFlags value alias for %G_PARAM_READABLE | %G_PARAM_WRITABLE.
132 <!-- ##### MACRO G_PARAM_MASK ##### -->
134 Mask containing the bits of #GParamSpec.flags which are reserved for GLib.
139 <!-- ##### MACRO G_PARAM_USER_SHIFT ##### -->
141 Minimum shift count to be used for user defined flags, to be stored in
147 <!-- ##### FUNCTION g_param_spec_ref ##### -->
149 Increment the reference count of @pspec.
152 @pspec: a valid #GParamSpec
153 @Returns: the #GParamSpec that was passed into this function
156 <!-- ##### FUNCTION g_param_spec_unref ##### -->
158 Decrement the reference count of a @pspec.
161 @pspec: a valid #GParamSpec
164 <!-- ##### FUNCTION g_param_spec_sink ##### -->
166 The initial reference count of a newly created #GParamSpec is 1,
167 eventhough no one has explicitely called g_param_spec_ref() on it yet.
168 So the einital reference count is flagged as "floating", untill someone
169 calls: g_param_spec_ref (@pspec); g_param_spec_sink (@pspec);
170 in sequence on it, taking over the initial reference count (thus
171 ending up with a @pspec that has a reference count of 1 still, but is
172 not flagged "floating" anymore).
175 @pspec: a valid #GParamSpec
178 <!-- ##### FUNCTION g_param_value_set_default ##### -->
180 Set @value to its default value as specified in @pspec.
183 @pspec: a valid #GParamSpec
184 @value: a #GValue of correct type for @pspec
187 <!-- ##### FUNCTION g_param_value_defaults ##### -->
189 Check whether @value contains the default value as specified in @pspec.
192 @pspec: a valid #GParamSpec
193 @value: a #GValue of correct type for @pspec
194 @Returns: whether @value contains the canonical defualt for this @pspec
197 <!-- ##### FUNCTION g_param_value_validate ##### -->
199 Ensure that the contents of @value comply with the specifications
200 set out by @pspec. For example, a #GParamSpecInt might require
201 that integers stored in @value may not be smaller than -42 and not be
202 greater than +42. If @value contains an integer outside of this range,
203 it is modified accordingly, so the resulting value will fit into the
207 @pspec: a valid #GParamSpec
208 @value: a #GValue of correct type for @pspec
209 @Returns: whether modifying @value was necessary to ensure validity
212 <!-- ##### FUNCTION g_param_value_convert ##### -->
214 This function transforms @src_value into @dest_value if possible,
215 and then validates @dest_value, in order for it to conform to
217 If @strict_validation is %TRUE this function will only suceed if
218 the transformed @dest_value complied to @pspec without modifications.
220 See also g_value_type_transformable(), g_value_transform() and
221 g_param_value_validate().
224 @pspec: a valid #GParamSpec
225 @src_value: souce #GValue
226 @dest_value: destination #GValue of correct type for @pspec
227 @strict_validation: $TRUE requires @dest_value to conform to @pspec without modifications
228 @Returns: %TRUE if transformation and validation were successfull,
229 %FALSE otherwise and @dest_value is left untouched.
232 <!-- ##### FUNCTION g_param_values_cmp ##### -->
234 Compare @value1 with @value2 according to @pspec, and return -1, 0 or +1,
235 if @value1 is found to be less than, equal to or greater than @value2, respectively.
238 @pspec: a valid #GParamSpec
239 @value1: a #GValue of correct type for @pspec
240 @value2: a #GValue of correct type for @pspec
241 @Returns: -1, 0 or +1, for a less than, equal to or greater than result
244 <!-- ##### FUNCTION g_param_spec_get_name ##### -->
253 <!-- ##### FUNCTION g_param_spec_get_nick ##### -->
262 <!-- ##### FUNCTION g_param_spec_get_blurb ##### -->
271 <!-- ##### FUNCTION g_param_spec_get_qdata ##### -->
281 <!-- ##### FUNCTION g_param_spec_set_qdata ##### -->
291 <!-- ##### FUNCTION g_param_spec_set_qdata_full ##### -->
302 <!-- ##### FUNCTION g_param_spec_steal_qdata ##### -->
312 <!-- ##### FUNCTION g_param_spec_internal ##### -->
325 <!-- ##### STRUCT GParamSpecTypeInfo ##### -->
339 <!-- ##### FUNCTION g_param_type_register_static ##### -->
349 <!-- ##### STRUCT GParamSpecPool ##### -->
355 <!-- ##### FUNCTION g_param_spec_pool_new ##### -->
364 <!-- ##### FUNCTION g_param_spec_pool_insert ##### -->
374 <!-- ##### FUNCTION g_param_spec_pool_remove ##### -->
383 <!-- ##### FUNCTION g_param_spec_pool_lookup ##### -->
393 <!-- # Unused Parameters # -->
397 <!-- ##### FUNCTION g_param_spec_pool_list ##### -->
408 <!-- ##### FUNCTION g_param_spec_pool_list_owned ##### -->