← Back to branch summary

~ubuntu-branches/debian/jessie/glib2.0/jessie

« back to all changes in this revision

Viewing changes to gobject/gparam.h

  • Committer: Bazaar Package Importer
  • Author(s): Gustavo Noronha Silva
  • Date: 2009-02-15 13:00:43 UTC
  • mto: (1.4.3 upstream)
  • mto: This revision was merged to the branch mainline in revision 70.
  • Revision ID: james.westby@ubuntu.com-20090215130043-6snh45flhit8oalb
Tags: upstream-2.18.4
Import upstream version 2.18.4

Show diffs side-by-side

added added

removed removed

Lines of Context:
gobject/gparam.h
30
30
G_BEGIN_DECLS
31
31
 
32
32
/* --- standard type macros --- */
 
33
/**
 
34
 * G_TYPE_IS_PARAM:
 
35
 * @type: a #GType ID
 
36
 * 
 
37
 * Checks whether @type "is a" %G_TYPE_PARAM.
 
38
 */
33
39
#define G_TYPE_IS_PARAM(type)           (G_TYPE_FUNDAMENTAL (type) == G_TYPE_PARAM)
 
40
/**
 
41
 * G_PARAM_SPEC:
 
42
 * @pspec: a valid #GParamSpec
 
43
 * 
 
44
 * Casts a derived #GParamSpec object (e.g. of type #GParamSpecInt) into
 
45
 * a #GParamSpec object.
 
46
 */
34
47
#define G_PARAM_SPEC(pspec)             (G_TYPE_CHECK_INSTANCE_CAST ((pspec), G_TYPE_PARAM, GParamSpec))
 
48
/**
 
49
 * G_IS_PARAM_SPEC:
 
50
 * @pspec: a #GParamSpec
 
51
 * 
 
52
 * Checks whether @pspec "is a" valid #GParamSpec structure of type %G_TYPE_PARAM
 
53
 * or derived.
 
54
 */
35
55
#define G_IS_PARAM_SPEC(pspec)          (G_TYPE_CHECK_INSTANCE_TYPE ((pspec), G_TYPE_PARAM))
 
56
/**
 
57
 * G_PARAM_SPEC_CLASS:
 
58
 * @pclass: a valid #GParamSpecClass
 
59
 * 
 
60
 * Casts a derived #GParamSpecClass structure into a #GParamSpecClass structure.
 
61
 */
36
62
#define G_PARAM_SPEC_CLASS(pclass)      (G_TYPE_CHECK_CLASS_CAST ((pclass), G_TYPE_PARAM, GParamSpecClass))
 
63
/**
 
64
 * G_IS_PARAM_SPEC_CLASS:
 
65
 * @pclass: a #GParamSpecClass
 
66
 * 
 
67
 * Checks whether @pclass "is a" valid #GParamSpecClass structure of type 
 
68
 * %G_TYPE_PARAM or derived.
 
69
 */
37
70
#define G_IS_PARAM_SPEC_CLASS(pclass)   (G_TYPE_CHECK_CLASS_TYPE ((pclass), G_TYPE_PARAM))
 
71
/**
 
72
 * G_PARAM_SPEC_GET_CLASS:
 
73
 * @pspec: a valid #GParamSpec
 
74
 * 
 
75
 * Retrieves the #GParamSpecClass of a #GParamSpec.
 
76
 */
38
77
#define G_PARAM_SPEC_GET_CLASS(pspec)   (G_TYPE_INSTANCE_GET_CLASS ((pspec), G_TYPE_PARAM, GParamSpecClass))
39
78
 
40
79
 
41
80
/* --- convenience macros --- */
 
81
/**
 
82
 * G_PARAM_SPEC_TYPE:
 
83
 * @pspec: a valid #GParamSpec
 
84
 * 
 
85
 * Retrieves the #GType of this @pspec.
 
86
 */
42
87
#define G_PARAM_SPEC_TYPE(pspec)        (G_TYPE_FROM_INSTANCE (pspec))
 
88
/**
 
89
 * G_PARAM_SPEC_TYPE_NAME:
 
90
 * @pspec: a valid #GParamSpec
 
91
 * 
 
92
 * Retrieves the #GType name of this @pspec.
 
93
 */
43
94
#define G_PARAM_SPEC_TYPE_NAME(pspec)   (g_type_name (G_PARAM_SPEC_TYPE (pspec)))
 
95
/**
 
96
 * G_PARAM_SPEC_VALUE_TYPE:
 
97
 * @pspec: a valid #GParamSpec
 
98
 * 
 
99
 * Retrieves the #GType to initialize a #GValue for this parameter.
 
100
 */
44
101
#define G_PARAM_SPEC_VALUE_TYPE(pspec)  (G_PARAM_SPEC (pspec)->value_type)
 
102
/**
 
103
 * G_VALUE_HOLDS_PARAM:
 
104
 * @value: a valid #GValue structure
 
105
 * 
 
106
 * Checks whether the given #GValue can hold values derived from type %G_TYPE_PARAM.
 
107
 * 
 
108
 * Returns: %TRUE on success.
 
109
 */
45
110
#define G_VALUE_HOLDS_PARAM(value)      (G_TYPE_CHECK_VALUE_TYPE ((value), G_TYPE_PARAM))
46
111
       
47
112
 
48
113
/* --- flags --- */
 
114
/**
 
115
 * GParamFlags:
 
116
 * @G_PARAM_READABLE: the parameter is readable
 
117
 * @G_PARAM_WRITABLE: the parameter is writable
 
118
 * @G_PARAM_CONSTRUCT: the parameter will be set upon object construction
 
119
 * @G_PARAM_CONSTRUCT_ONLY: the parameter will only be set upon object construction
 
120
 * @G_PARAM_LAX_VALIDATION: upon parameter conversion (see g_param_value_convert())
 
121
 *  strict validation is not required
 
122
 * @G_PARAM_STATIC_NAME: the string used as name when constructing the 
 
123
 *  parameter is guaranteed to remain valid and
 
124
 *  unmodified for the lifetime of the parameter. 
 
125
 *  Since 2.8
 
126
 * @G_PARAM_STATIC_NICK: the string used as nick when constructing the
 
127
 *  parameter is guaranteed to remain valid and
 
128
 *  unmmodified for the lifetime of the parameter.
 
129
 *  Since 2.8
 
130
 * @G_PARAM_STATIC_BLURB: the string used as blurb when constructing the 
 
131
 *  parameter is guaranteed to remain valid and 
 
132
 *  unmodified for the lifetime of the parameter. 
 
133
 *  Since 2.8
 
134
 * @G_PARAM_PRIVATE: internal
 
135
 * 
 
136
 * Through the #GParamFlags flag values, certain aspects of parameters
 
137
 * can be configured.
 
138
 */
49
139
typedef enum
50
140
{
51
141
  G_PARAM_READABLE            = 1 << 0,
60
150
  G_PARAM_STATIC_NICK         = 1 << 6,
61
151
  G_PARAM_STATIC_BLURB        = 1 << 7
62
152
} GParamFlags;
 
153
/**
 
154
 * G_PARAM_READWRITE:
 
155
 * 
 
156
 * #GParamFlags value alias for %G_PARAM_READABLE | %G_PARAM_WRITABLE.
 
157
 */
63
158
#define G_PARAM_READWRITE       (G_PARAM_READABLE | G_PARAM_WRITABLE)
 
159
/**
 
160
 * G_PARAM_STATIC_STRINGS:
 
161
 * 
 
162
 * #GParamFlags value alias for %G_PARAM_STATIC_NAME | %G_PARAM_STATIC_NICK | %G_PARAM_STATIC_BLURB.
 
163
 * 
 
164
 * Since 2.13.0
 
165
 */
64
166
#define G_PARAM_STATIC_STRINGS (G_PARAM_STATIC_NAME | G_PARAM_STATIC_NICK | G_PARAM_STATIC_BLURB)
 
167
/* bits in the range 0xffffff00 are reserved for 3rd party usage */
 
168
/**
 
169
 * G_PARAM_MASK:
 
170
 * 
 
171
 * Mask containing the bits of #GParamSpec.flags which are reserved for GLib.
 
172
 */
65
173
#define G_PARAM_MASK            (0x000000ff)
66
 
/* bits in the range 0xffffff00 are reserved for 3rd party usage */
 
174
/**
 
175
 * G_PARAM_USER_SHIFT:
 
176
 * 
 
177
 * Minimum shift count to be used for user defined flags, to be stored in
 
178
 * #GParamSpec.flags.
 
179
 */
67
180
#define G_PARAM_USER_SHIFT      (8)
68
181
 
69
182
 
72
185
typedef struct _GParamSpecClass GParamSpecClass;
73
186
typedef struct _GParameter      GParameter;
74
187
typedef struct _GParamSpecPool  GParamSpecPool;
 
188
/**
 
189
 * GParamSpec:
 
190
 * @g_type_instance: private #GTypeInstance portion
 
191
 * @name: name of this parameter
 
192
 * @flags: #GParamFlags flags for this parameter
 
193
 * @value_type: the #GValue type for this parameter
 
194
 * @owner_type: #GType type that uses (introduces) this paremeter
 
195
 * 
 
196
 * All other fields of the <structname>GParamSpec</structname> struct are private and
 
197
 * should not be used directly.
 
198
 */
75
199
struct _GParamSpec
76
200
{
77
201
  GTypeInstance  g_type_instance;
88
212
  guint          ref_count;
89
213
  guint          param_id;      /* sort-criteria */
90
214
};
 
215
/**
 
216
 * GParamSpecClass:
 
217
 * @g_type_class: the parent class
 
218
 * @value_type: the #GValue type for this parameter
 
219
 * @finalize: The instance finalization function (optional), should chain 
 
220
 *  up to the finalize method of the parent class.
 
221
 * @value_set_default: Resets a @value to the default value for this type
 
222
 *  (recommended, the default is g_value_reset()), see 
 
223
 *  g_param_value_set_default().
 
224
 * @value_validate: Ensures that the contents of @value comply with the 
 
225
 *  specifications set out by this type (optional), see 
 
226
 *  g_param_value_set_validate().
 
227
 * @values_cmp: Compares @value1 with @value2 according to this type
 
228
 *  (recommended, the default is memcmp()), see g_param_values_cmp().
 
229
 * 
 
230
 * The class structure for the <structname>GParamSpec</structname> type.
 
231
 * Normally, <structname>GParamSpec</structname> classes are filled by
 
232
 * g_param_type_register_static().
 
233
 */
91
234
struct _GParamSpecClass
92
235
{
93
236
  GTypeClass      g_type_class;
107
250
  /*< private >*/
108
251
  gpointer        dummy[4];
109
252
};
 
253
/**
 
254
 * GParameter:
 
255
 * @name: the parameter name
 
256
 * @value: the parameter value
 
257
 * 
 
258
 * The <structname>GParameter</structname> struct is an auxiliary structure used
 
259
 * to hand parameter name/value pairs to g_object_newv().
 
260
 */
110
261
struct _GParameter /* auxillary structure for _setv() variants */
111
262
{
112
263
  const gchar *name;
163
314
 
164
315
/* --- convenience functions --- */
165
316
typedef struct _GParamSpecTypeInfo GParamSpecTypeInfo;
 
317
/**
 
318
 * GParamSpecTypeInfo:
 
319
 * @instance_size: Size of the instance (object) structure.
 
320
 * @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.
 
321
 * @instance_init: Location of the instance initialization function (optional).
 
322
 * @value_type: The #GType of values conforming to this #GParamSpec
 
323
 * @finalize: The instance finalization function (optional).
 
324
 * @value_set_default: Resets a @value to the default value for @pspec 
 
325
 *  (recommended, the default is g_value_reset()), see 
 
326
 *  g_param_value_set_default().
 
327
 * @value_validate: Ensures that the contents of @value comply with the 
 
328
 *  specifications set out by @pspec (optional), see 
 
329
 *  g_param_value_set_validate().
 
330
 * @values_cmp: Compares @value1 with @value2 according to @pspec 
 
331
 *  (recommended, the default is memcmp()), see g_param_values_cmp().
 
332
 * 
 
333
 * This structure is used to provide the type system with the information
 
334
 * required to initialize and destruct (finalize) a parameter's class and
 
335
 * instances thereof.
 
336
 * The initialized structure is passed to the g_param_type_register_static() 
 
337
 * The type system will perform a deep copy of this structure, so it's memory 
 
338
 * does not need to be persistent across invocation of 
 
339
 * g_param_type_register_static().
 
340
 */
166
341
struct _GParamSpecTypeInfo
167
342
{
168
343
  /* type system portion */