1 | /* GObject - GLib Type, Object, Parameter and Signal Library |
2 | * Copyright (C) 1998-1999, 2000-2001 Tim Janik and Red Hat, Inc. |
3 | * |
4 | * This library is free software; you can redistribute it and/or |
5 | * modify it under the terms of the GNU Lesser General Public |
6 | * License as published by the Free Software Foundation; either |
7 | * version 2 of the License, or (at your option) any later version. |
8 | * |
9 | * This library is distributed in the hope that it will be useful, |
10 | * but WITHOUT ANY WARRANTY; without even the implied warranty of |
11 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
12 | * Lesser General Public License for more details. |
13 | * |
14 | * You should have received a copy of the GNU Lesser General |
15 | * Public License along with this library; if not, see <http://www.gnu.org/licenses/>. |
16 | */ |
17 | #ifndef __G_TYPE_H__ |
18 | #define __G_TYPE_H__ |
19 | |
20 | #if !defined (__GLIB_GOBJECT_H_INSIDE__) && !defined (GOBJECT_COMPILATION) |
21 | #error "Only <glib-object.h> can be included directly." |
22 | #endif |
23 | |
24 | #include <glib.h> |
25 | |
26 | G_BEGIN_DECLS |
27 | |
28 | /* Basic Type Macros |
29 | */ |
30 | /** |
31 | * G_TYPE_FUNDAMENTAL: |
32 | * @type: A #GType value. |
33 | * |
34 | * The fundamental type which is the ancestor of @type. |
35 | * Fundamental types are types that serve as ultimate bases for the derived types, |
36 | * thus they are the roots of distinct inheritance hierarchies. |
37 | */ |
38 | #define G_TYPE_FUNDAMENTAL(type) (g_type_fundamental (type)) |
39 | /** |
40 | * G_TYPE_FUNDAMENTAL_MAX: |
41 | * |
42 | * An integer constant that represents the number of identifiers reserved |
43 | * for types that are assigned at compile-time. |
44 | */ |
45 | #define G_TYPE_FUNDAMENTAL_MAX (255 << G_TYPE_FUNDAMENTAL_SHIFT) |
46 | |
47 | /* Constant fundamental types, |
48 | */ |
49 | /** |
50 | * G_TYPE_INVALID: |
51 | * |
52 | * An invalid #GType used as error return value in some functions which return |
53 | * a #GType. |
54 | */ |
55 | #define G_TYPE_INVALID G_TYPE_MAKE_FUNDAMENTAL (0) |
56 | /** |
57 | * G_TYPE_NONE: |
58 | * |
59 | * A fundamental type which is used as a replacement for the C |
60 | * void return type. |
61 | */ |
62 | #define G_TYPE_NONE G_TYPE_MAKE_FUNDAMENTAL (1) |
63 | /** |
64 | * G_TYPE_INTERFACE: |
65 | * |
66 | * The fundamental type from which all interfaces are derived. |
67 | */ |
68 | #define G_TYPE_INTERFACE G_TYPE_MAKE_FUNDAMENTAL (2) |
69 | /** |
70 | * G_TYPE_CHAR: |
71 | * |
72 | * The fundamental type corresponding to #gchar. |
73 | * The type designated by G_TYPE_CHAR is unconditionally an 8-bit signed integer. |
74 | * This may or may not be the same type a the C type "gchar". |
75 | */ |
76 | #define G_TYPE_CHAR G_TYPE_MAKE_FUNDAMENTAL (3) |
77 | /** |
78 | * G_TYPE_UCHAR: |
79 | * |
80 | * The fundamental type corresponding to #guchar. |
81 | */ |
82 | #define G_TYPE_UCHAR G_TYPE_MAKE_FUNDAMENTAL (4) |
83 | /** |
84 | * G_TYPE_BOOLEAN: |
85 | * |
86 | * The fundamental type corresponding to #gboolean. |
87 | */ |
88 | #define G_TYPE_BOOLEAN G_TYPE_MAKE_FUNDAMENTAL (5) |
89 | /** |
90 | * G_TYPE_INT: |
91 | * |
92 | * The fundamental type corresponding to #gint. |
93 | */ |
94 | #define G_TYPE_INT G_TYPE_MAKE_FUNDAMENTAL (6) |
95 | /** |
96 | * G_TYPE_UINT: |
97 | * |
98 | * The fundamental type corresponding to #guint. |
99 | */ |
100 | #define G_TYPE_UINT G_TYPE_MAKE_FUNDAMENTAL (7) |
101 | /** |
102 | * G_TYPE_LONG: |
103 | * |
104 | * The fundamental type corresponding to #glong. |
105 | */ |
106 | #define G_TYPE_LONG G_TYPE_MAKE_FUNDAMENTAL (8) |
107 | /** |
108 | * G_TYPE_ULONG: |
109 | * |
110 | * The fundamental type corresponding to #gulong. |
111 | */ |
112 | #define G_TYPE_ULONG G_TYPE_MAKE_FUNDAMENTAL (9) |
113 | /** |
114 | * G_TYPE_INT64: |
115 | * |
116 | * The fundamental type corresponding to #gint64. |
117 | */ |
118 | #define G_TYPE_INT64 G_TYPE_MAKE_FUNDAMENTAL (10) |
119 | /** |
120 | * G_TYPE_UINT64: |
121 | * |
122 | * The fundamental type corresponding to #guint64. |
123 | */ |
124 | #define G_TYPE_UINT64 G_TYPE_MAKE_FUNDAMENTAL (11) |
125 | /** |
126 | * G_TYPE_ENUM: |
127 | * |
128 | * The fundamental type from which all enumeration types are derived. |
129 | */ |
130 | #define G_TYPE_ENUM G_TYPE_MAKE_FUNDAMENTAL (12) |
131 | /** |
132 | * G_TYPE_FLAGS: |
133 | * |
134 | * The fundamental type from which all flags types are derived. |
135 | */ |
136 | #define G_TYPE_FLAGS G_TYPE_MAKE_FUNDAMENTAL (13) |
137 | /** |
138 | * G_TYPE_FLOAT: |
139 | * |
140 | * The fundamental type corresponding to #gfloat. |
141 | */ |
142 | #define G_TYPE_FLOAT G_TYPE_MAKE_FUNDAMENTAL (14) |
143 | /** |
144 | * G_TYPE_DOUBLE: |
145 | * |
146 | * The fundamental type corresponding to #gdouble. |
147 | */ |
148 | #define G_TYPE_DOUBLE G_TYPE_MAKE_FUNDAMENTAL (15) |
149 | /** |
150 | * G_TYPE_STRING: |
151 | * |
152 | * The fundamental type corresponding to nul-terminated C strings. |
153 | */ |
154 | #define G_TYPE_STRING G_TYPE_MAKE_FUNDAMENTAL (16) |
155 | /** |
156 | * G_TYPE_POINTER: |
157 | * |
158 | * The fundamental type corresponding to #gpointer. |
159 | */ |
160 | #define G_TYPE_POINTER G_TYPE_MAKE_FUNDAMENTAL (17) |
161 | /** |
162 | * G_TYPE_BOXED: |
163 | * |
164 | * The fundamental type from which all boxed types are derived. |
165 | */ |
166 | #define G_TYPE_BOXED G_TYPE_MAKE_FUNDAMENTAL (18) |
167 | /** |
168 | * G_TYPE_PARAM: |
169 | * |
170 | * The fundamental type from which all #GParamSpec types are derived. |
171 | */ |
172 | #define G_TYPE_PARAM G_TYPE_MAKE_FUNDAMENTAL (19) |
173 | /** |
174 | * G_TYPE_OBJECT: |
175 | * |
176 | * The fundamental type for #GObject. |
177 | */ |
178 | #define G_TYPE_OBJECT G_TYPE_MAKE_FUNDAMENTAL (20) |
179 | /** |
180 | * G_TYPE_VARIANT: |
181 | * |
182 | * The fundamental type corresponding to #GVariant. |
183 | * |
184 | * All floating #GVariant instances passed through the #GType system are |
185 | * consumed. |
186 | * |
187 | * Note that callbacks in closures, and signal handlers |
188 | * for signals of return type %G_TYPE_VARIANT, must never return floating |
189 | * variants. |
190 | * |
191 | * Note: GLib 2.24 did include a boxed type with this name. It was replaced |
192 | * with this fundamental type in 2.26. |
193 | * |
194 | * Since: 2.26 |
195 | */ |
196 | #define G_TYPE_VARIANT G_TYPE_MAKE_FUNDAMENTAL (21) |
197 | |
198 | |
199 | /* Reserved fundamental type numbers to create new fundamental |
200 | * type IDs with G_TYPE_MAKE_FUNDAMENTAL(). |
201 | * Send email to gtk-devel-list@gnome.org for reservations. |
202 | */ |
203 | /** |
204 | * G_TYPE_FUNDAMENTAL_SHIFT: |
205 | * |
206 | * Shift value used in converting numbers to type IDs. |
207 | */ |
208 | #define G_TYPE_FUNDAMENTAL_SHIFT (2) |
209 | /** |
210 | * G_TYPE_MAKE_FUNDAMENTAL: |
211 | * @x: the fundamental type number. |
212 | * |
213 | * Get the type ID for the fundamental type number @x. |
214 | * Use g_type_fundamental_next() instead of this macro to create new fundamental |
215 | * types. |
216 | * |
217 | * Returns: the GType |
218 | */ |
219 | #define G_TYPE_MAKE_FUNDAMENTAL(x) ((GType) ((x) << G_TYPE_FUNDAMENTAL_SHIFT)) |
220 | /** |
221 | * G_TYPE_RESERVED_GLIB_FIRST: |
222 | * |
223 | * First fundamental type number to create a new fundamental type id with |
224 | * G_TYPE_MAKE_FUNDAMENTAL() reserved for GLib. |
225 | */ |
226 | #define G_TYPE_RESERVED_GLIB_FIRST (22) |
227 | /** |
228 | * G_TYPE_RESERVED_GLIB_LAST: |
229 | * |
230 | * Last fundamental type number reserved for GLib. |
231 | */ |
232 | #define G_TYPE_RESERVED_GLIB_LAST (31) |
233 | /** |
234 | * G_TYPE_RESERVED_BSE_FIRST: |
235 | * |
236 | * First fundamental type number to create a new fundamental type id with |
237 | * G_TYPE_MAKE_FUNDAMENTAL() reserved for BSE. |
238 | */ |
239 | #define G_TYPE_RESERVED_BSE_FIRST (32) |
240 | /** |
241 | * G_TYPE_RESERVED_BSE_LAST: |
242 | * |
243 | * Last fundamental type number reserved for BSE. |
244 | */ |
245 | #define G_TYPE_RESERVED_BSE_LAST (48) |
246 | /** |
247 | * G_TYPE_RESERVED_USER_FIRST: |
248 | * |
249 | * First available fundamental type number to create new fundamental |
250 | * type id with G_TYPE_MAKE_FUNDAMENTAL(). |
251 | */ |
252 | #define G_TYPE_RESERVED_USER_FIRST (49) |
253 | |
254 | |
255 | /* Type Checking Macros |
256 | */ |
257 | /** |
258 | * G_TYPE_IS_FUNDAMENTAL: |
259 | * @type: A #GType value. |
260 | * |
261 | * Checks if @type is a fundamental type. |
262 | * |
263 | * Returns: %TRUE on success. |
264 | */ |
265 | #define G_TYPE_IS_FUNDAMENTAL(type) ((type) <= G_TYPE_FUNDAMENTAL_MAX) |
266 | /** |
267 | * G_TYPE_IS_DERIVED: |
268 | * @type: A #GType value. |
269 | * |
270 | * Checks if @type is derived (or in object-oriented terminology: |
271 | * inherited) from another type (this holds true for all non-fundamental |
272 | * types). |
273 | * |
274 | * Returns: %TRUE on success. |
275 | */ |
276 | #define G_TYPE_IS_DERIVED(type) ((type) > G_TYPE_FUNDAMENTAL_MAX) |
277 | /** |
278 | * G_TYPE_IS_INTERFACE: |
279 | * @type: A #GType value. |
280 | * |
281 | * Checks if @type is an interface type. |
282 | * An interface type provides a pure API, the implementation |
283 | * of which is provided by another type (which is then said to conform |
284 | * to the interface). GLib interfaces are somewhat analogous to Java |
285 | * interfaces and C++ classes containing only pure virtual functions, |
286 | * with the difference that GType interfaces are not derivable (but see |
287 | * g_type_interface_add_prerequisite() for an alternative). |
288 | * |
289 | * Returns: %TRUE on success. |
290 | */ |
291 | #define G_TYPE_IS_INTERFACE(type) (G_TYPE_FUNDAMENTAL (type) == G_TYPE_INTERFACE) |
292 | /** |
293 | * G_TYPE_IS_CLASSED: |
294 | * @type: A #GType value. |
295 | * |
296 | * Checks if @type is a classed type. |
297 | * |
298 | * Returns: %TRUE on success. |
299 | */ |
300 | #define G_TYPE_IS_CLASSED(type) (g_type_test_flags ((type), G_TYPE_FLAG_CLASSED)) |
301 | /** |
302 | * G_TYPE_IS_INSTANTIATABLE: |
303 | * @type: A #GType value. |
304 | * |
305 | * Checks if @type can be instantiated. Instantiation is the |
306 | * process of creating an instance (object) of this type. |
307 | * |
308 | * Returns: %TRUE on success. |
309 | */ |
310 | #define G_TYPE_IS_INSTANTIATABLE(type) (g_type_test_flags ((type), G_TYPE_FLAG_INSTANTIATABLE)) |
311 | /** |
312 | * G_TYPE_IS_DERIVABLE: |
313 | * @type: A #GType value. |
314 | * |
315 | * Checks if @type is a derivable type. A derivable type can |
316 | * be used as the base class of a flat (single-level) class hierarchy. |
317 | * |
318 | * Returns: %TRUE on success. |
319 | */ |
320 | #define G_TYPE_IS_DERIVABLE(type) (g_type_test_flags ((type), G_TYPE_FLAG_DERIVABLE)) |
321 | /** |
322 | * G_TYPE_IS_DEEP_DERIVABLE: |
323 | * @type: A #GType value. |
324 | * |
325 | * Checks if @type is a deep derivable type. A deep derivable type |
326 | * can be used as the base class of a deep (multi-level) class hierarchy. |
327 | * |
328 | * Returns: %TRUE on success. |
329 | */ |
330 | #define G_TYPE_IS_DEEP_DERIVABLE(type) (g_type_test_flags ((type), G_TYPE_FLAG_DEEP_DERIVABLE)) |
331 | /** |
332 | * G_TYPE_IS_ABSTRACT: |
333 | * @type: A #GType value. |
334 | * |
335 | * Checks if @type is an abstract type. An abstract type cannot be |
336 | * instantiated and is normally used as an abstract base class for |
337 | * derived classes. |
338 | * |
339 | * Returns: %TRUE on success. |
340 | */ |
341 | #define G_TYPE_IS_ABSTRACT(type) (g_type_test_flags ((type), G_TYPE_FLAG_ABSTRACT)) |
342 | /** |
343 | * G_TYPE_IS_VALUE_ABSTRACT: |
344 | * @type: A #GType value. |
345 | * |
346 | * Checks if @type is an abstract value type. An abstract value type introduces |
347 | * a value table, but can't be used for g_value_init() and is normally used as |
348 | * an abstract base type for derived value types. |
349 | * |
350 | * Returns: %TRUE on success. |
351 | */ |
352 | #define G_TYPE_IS_VALUE_ABSTRACT(type) (g_type_test_flags ((type), G_TYPE_FLAG_VALUE_ABSTRACT)) |
353 | /** |
354 | * G_TYPE_IS_VALUE_TYPE: |
355 | * @type: A #GType value. |
356 | * |
357 | * Checks if @type is a value type and can be used with g_value_init(). |
358 | * |
359 | * Returns: %TRUE on success. |
360 | */ |
361 | #define G_TYPE_IS_VALUE_TYPE(type) (g_type_check_is_value_type (type)) |
362 | /** |
363 | * G_TYPE_HAS_VALUE_TABLE: |
364 | * @type: A #GType value. |
365 | * |
366 | * Checks if @type has a #GTypeValueTable. |
367 | * |
368 | * Returns: %TRUE on success. |
369 | */ |
370 | #define G_TYPE_HAS_VALUE_TABLE(type) (g_type_value_table_peek (type) != NULL) |
371 | |
372 | |
373 | /* Typedefs |
374 | */ |
375 | /** |
376 | * GType: |
377 | * |
378 | * A numerical value which represents the unique identifier of a registered |
379 | * type. |
380 | */ |
381 | #if GLIB_SIZEOF_SIZE_T != GLIB_SIZEOF_LONG || !defined __cplusplus |
382 | typedef gsize GType; |
383 | #else /* for historic reasons, C++ links against gulong GTypes */ |
384 | typedef gulong GType; |
385 | #endif |
386 | typedef struct _GValue GValue; |
387 | typedef union _GTypeCValue GTypeCValue; |
388 | typedef struct _GTypePlugin GTypePlugin; |
389 | typedef struct _GTypeClass GTypeClass; |
390 | typedef struct _GTypeInterface GTypeInterface; |
391 | typedef struct _GTypeInstance GTypeInstance; |
392 | typedef struct _GTypeInfo GTypeInfo; |
393 | typedef struct _GTypeFundamentalInfo GTypeFundamentalInfo; |
394 | typedef struct _GInterfaceInfo GInterfaceInfo; |
395 | typedef struct _GTypeValueTable GTypeValueTable; |
396 | typedef struct _GTypeQuery GTypeQuery; |
397 | |
398 | |
399 | /* Basic Type Structures |
400 | */ |
401 | /** |
402 | * GTypeClass: |
403 | * |
404 | * An opaque structure used as the base of all classes. |
405 | */ |
406 | struct _GTypeClass |
407 | { |
408 | /*< private >*/ |
409 | GType g_type; |
410 | }; |
411 | /** |
412 | * GTypeInstance: |
413 | * |
414 | * An opaque structure used as the base of all type instances. |
415 | */ |
416 | struct _GTypeInstance |
417 | { |
418 | /*< private >*/ |
419 | GTypeClass *g_class; |
420 | }; |
421 | /** |
422 | * GTypeInterface: |
423 | * |
424 | * An opaque structure used as the base of all interface types. |
425 | */ |
426 | struct _GTypeInterface |
427 | { |
428 | /*< private >*/ |
429 | GType g_type; /* iface type */ |
430 | GType g_instance_type; |
431 | }; |
432 | /** |
433 | * GTypeQuery: |
434 | * @type: the #GType value of the type. |
435 | * @type_name: the name of the type. |
436 | * @class_size: the size of the class structure. |
437 | * @instance_size: the size of the instance structure. |
438 | * |
439 | * A structure holding information for a specific type. It is |
440 | * filled in by the g_type_query() function. |
441 | */ |
442 | struct _GTypeQuery |
443 | { |
444 | GType type; |
445 | const gchar *type_name; |
446 | guint class_size; |
447 | guint instance_size; |
448 | }; |
449 | |
450 | |
451 | /* Casts, checks and accessors for structured types |
452 | * usage of these macros is reserved to type implementations only |
453 | */ |
454 | /*< protected >*/ |
455 | /** |
456 | * G_TYPE_CHECK_INSTANCE: |
457 | * @instance: Location of a #GTypeInstance structure. |
458 | * |
459 | * Checks if @instance is a valid #GTypeInstance structure, |
460 | * otherwise issues a warning and returns %FALSE. |
461 | * |
462 | * This macro should only be used in type implementations. |
463 | * |
464 | * Returns: %TRUE on success. |
465 | */ |
466 | #define G_TYPE_CHECK_INSTANCE(instance) (_G_TYPE_CHI ((GTypeInstance*) (instance))) |
467 | /** |
468 | * G_TYPE_CHECK_INSTANCE_CAST: |
469 | * @instance: Location of a #GTypeInstance structure. |
470 | * @g_type: The type to be returned. |
471 | * @c_type: The corresponding C type of @g_type. |
472 | * |
473 | * Checks that @instance is an instance of the type identified by @g_type |
474 | * and issues a warning if this is not the case. Returns @instance casted |
475 | * to a pointer to @c_type. |
476 | * |
477 | * This macro should only be used in type implementations. |
478 | */ |
479 | #define G_TYPE_CHECK_INSTANCE_CAST(instance, g_type, c_type) (_G_TYPE_CIC ((instance), (g_type), c_type)) |
480 | /** |
481 | * G_TYPE_CHECK_INSTANCE_TYPE: |
482 | * @instance: Location of a #GTypeInstance structure. |
483 | * @g_type: The type to be checked |
484 | * |
485 | * Checks if @instance is an instance of the type identified by @g_type. |
486 | * |
487 | * This macro should only be used in type implementations. |
488 | * |
489 | * Returns: %TRUE on success. |
490 | */ |
491 | #define G_TYPE_CHECK_INSTANCE_TYPE(instance, g_type) (_G_TYPE_CIT ((instance), (g_type))) |
492 | /** |
493 | * G_TYPE_INSTANCE_GET_CLASS: |
494 | * @instance: Location of the #GTypeInstance structure. |
495 | * @g_type: The #GType of the class to be returned. |
496 | * @c_type: The C type of the class structure. |
497 | * |
498 | * Get the class structure of a given @instance, casted |
499 | * to a specified ancestor type @g_type of the instance. |
500 | * |
501 | * Note that while calling a GInstanceInitFunc(), the class pointer gets |
502 | * modified, so it might not always return the expected pointer. |
503 | * |
504 | * This macro should only be used in type implementations. |
505 | * |
506 | * Returns: a pointer to the class structure |
507 | */ |
508 | #define G_TYPE_INSTANCE_GET_CLASS(instance, g_type, c_type) (_G_TYPE_IGC ((instance), (g_type), c_type)) |
509 | /** |
510 | * G_TYPE_INSTANCE_GET_INTERFACE: |
511 | * @instance: Location of the #GTypeInstance structure. |
512 | * @g_type: The #GType of the interface to be returned. |
513 | * @c_type: The C type of the interface structure. |
514 | * |
515 | * Get the interface structure for interface @g_type of a given @instance. |
516 | * |
517 | * This macro should only be used in type implementations. |
518 | * |
519 | * Returns: a pointer to the interface structure |
520 | */ |
521 | #define G_TYPE_INSTANCE_GET_INTERFACE(instance, g_type, c_type) (_G_TYPE_IGI ((instance), (g_type), c_type)) |
522 | /** |
523 | * G_TYPE_CHECK_CLASS_CAST: |
524 | * @g_class: Location of a #GTypeClass structure. |
525 | * @g_type: The type to be returned. |
526 | * @c_type: The corresponding C type of class structure of @g_type. |
527 | * |
528 | * Checks that @g_class is a class structure of the type identified by @g_type |
529 | * and issues a warning if this is not the case. Returns @g_class casted |
530 | * to a pointer to @c_type. |
531 | * |
532 | * This macro should only be used in type implementations. |
533 | */ |
534 | #define G_TYPE_CHECK_CLASS_CAST(g_class, g_type, c_type) (_G_TYPE_CCC ((g_class), (g_type), c_type)) |
535 | /** |
536 | * G_TYPE_CHECK_CLASS_TYPE: |
537 | * @g_class: Location of a #GTypeClass structure. |
538 | * @g_type: The type to be checked. |
539 | * |
540 | * Checks if @g_class is a class structure of the type identified by |
541 | * @g_type. |
542 | * |
543 | * This macro should only be used in type implementations. |
544 | * |
545 | * Returns: %TRUE on success. |
546 | */ |
547 | #define G_TYPE_CHECK_CLASS_TYPE(g_class, g_type) (_G_TYPE_CCT ((g_class), (g_type))) |
548 | /** |
549 | * G_TYPE_CHECK_VALUE: |
550 | * @value: a #GValue |
551 | * |
552 | * Checks if @value has been initialized to hold values |
553 | * of a value type. |
554 | * |
555 | * This macro should only be used in type implementations. |
556 | * |
557 | * Returns: %TRUE on success. |
558 | */ |
559 | #define G_TYPE_CHECK_VALUE(value) (_G_TYPE_CHV ((value))) |
560 | /** |
561 | * G_TYPE_CHECK_VALUE_TYPE: |
562 | * @value: a #GValue |
563 | * @g_type: The type to be checked. |
564 | * |
565 | * Checks if @value has been initialized to hold values |
566 | * of type @g_type. |
567 | * |
568 | * This macro should only be used in type implementations. |
569 | * |
570 | * Returns: %TRUE on success. |
571 | */ |
572 | #define G_TYPE_CHECK_VALUE_TYPE(value, g_type) (_G_TYPE_CVH ((value), (g_type))) |
573 | /** |
574 | * G_TYPE_FROM_INSTANCE: |
575 | * @instance: Location of a valid #GTypeInstance structure. |
576 | * |
577 | * Get the type identifier from a given @instance structure. |
578 | * |
579 | * This macro should only be used in type implementations. |
580 | * |
581 | * Returns: the #GType |
582 | */ |
583 | #define G_TYPE_FROM_INSTANCE(instance) (G_TYPE_FROM_CLASS (((GTypeInstance*) (instance))->g_class)) |
584 | /** |
585 | * G_TYPE_FROM_CLASS: |
586 | * @g_class: Location of a valid #GTypeClass structure. |
587 | * |
588 | * Get the type identifier from a given @class structure. |
589 | * |
590 | * This macro should only be used in type implementations. |
591 | * |
592 | * Returns: the #GType |
593 | */ |
594 | #define G_TYPE_FROM_CLASS(g_class) (((GTypeClass*) (g_class))->g_type) |
595 | /** |
596 | * G_TYPE_FROM_INTERFACE: |
597 | * @g_iface: Location of a valid #GTypeInterface structure. |
598 | * |
599 | * Get the type identifier from a given @interface structure. |
600 | * |
601 | * This macro should only be used in type implementations. |
602 | * |
603 | * Returns: the #GType |
604 | */ |
605 | #define G_TYPE_FROM_INTERFACE(g_iface) (((GTypeInterface*) (g_iface))->g_type) |
606 | |
607 | /** |
608 | * G_TYPE_INSTANCE_GET_PRIVATE: |
609 | * @instance: the instance of a type deriving from @private_type. |
610 | * @g_type: the type identifying which private data to retrieve. |
611 | * @c_type: The C type for the private structure. |
612 | * |
613 | * Gets the private structure for a particular type. |
614 | * The private structure must have been registered in the |
615 | * class_init function with g_type_class_add_private(). |
616 | * |
617 | * This macro should only be used in type implementations. |
618 | * |
619 | * Since: 2.4 |
620 | * Returns: a pointer to the private data structure. |
621 | */ |
622 | #define G_TYPE_INSTANCE_GET_PRIVATE(instance, g_type, c_type) ((c_type*) g_type_instance_get_private ((GTypeInstance*) (instance), (g_type))) |
623 | |
624 | /** |
625 | * G_TYPE_CLASS_GET_PRIVATE: |
626 | * @klass: the class of a type deriving from @private_type. |
627 | * @g_type: the type identifying which private data to retrieve. |
628 | * @c_type: The C type for the private structure. |
629 | * |
630 | * Gets the private class structure for a particular type. |
631 | * The private structure must have been registered in the |
632 | * get_type() function with g_type_add_class_private(). |
633 | * |
634 | * This macro should only be used in type implementations. |
635 | * |
636 | * Since: 2.24 |
637 | * Returns: a pointer to the private data structure. |
638 | */ |
639 | #define G_TYPE_CLASS_GET_PRIVATE(klass, g_type, c_type) ((c_type*) g_type_class_get_private ((GTypeClass*) (klass), (g_type))) |
640 | |
641 | /** |
642 | * GTypeDebugFlags: |
643 | * @G_TYPE_DEBUG_NONE: Print no messages. |
644 | * @G_TYPE_DEBUG_OBJECTS: Print messages about object bookkeeping. |
645 | * @G_TYPE_DEBUG_SIGNALS: Print messages about signal emissions. |
646 | * @G_TYPE_DEBUG_MASK: Mask covering all debug flags. |
647 | * |
648 | * These flags used to be passed to g_type_init_with_debug_flags() which |
649 | * is now deprecated. |
650 | * |
651 | * If you need to enable debugging features, use the GOBJECT_DEBUG |
652 | * environment variable. |
653 | * |
654 | * Deprecated: 2.36: g_type_init() is now done automatically |
655 | */ |
656 | typedef enum /*< skip >*/ |
657 | { |
658 | G_TYPE_DEBUG_NONE = 0, |
659 | G_TYPE_DEBUG_OBJECTS = 1 << 0, |
660 | G_TYPE_DEBUG_SIGNALS = 1 << 1, |
661 | G_TYPE_DEBUG_MASK = 0x03 |
662 | } GTypeDebugFlags; |
663 | |
664 | |
665 | /* --- prototypes --- */ |
666 | GLIB_DEPRECATED_IN_2_36 |
667 | void g_type_init (void); |
668 | GLIB_DEPRECATED_IN_2_36 |
669 | void g_type_init_with_debug_flags (GTypeDebugFlags debug_flags); |
670 | GLIB_AVAILABLE_IN_ALL |
671 | const gchar * g_type_name (GType type); |
672 | GLIB_AVAILABLE_IN_ALL |
673 | GQuark g_type_qname (GType type); |
674 | GLIB_AVAILABLE_IN_ALL |
675 | GType g_type_from_name (const gchar *name); |
676 | GLIB_AVAILABLE_IN_ALL |
677 | GType g_type_parent (GType type); |
678 | GLIB_AVAILABLE_IN_ALL |
679 | guint g_type_depth (GType type); |
680 | GLIB_AVAILABLE_IN_ALL |
681 | GType g_type_next_base (GType leaf_type, |
682 | GType root_type); |
683 | GLIB_AVAILABLE_IN_ALL |
684 | gboolean g_type_is_a (GType type, |
685 | GType is_a_type); |
686 | GLIB_AVAILABLE_IN_ALL |
687 | gpointer g_type_class_ref (GType type); |
688 | GLIB_AVAILABLE_IN_ALL |
689 | gpointer g_type_class_peek (GType type); |
690 | GLIB_AVAILABLE_IN_ALL |
691 | gpointer g_type_class_peek_static (GType type); |
692 | GLIB_AVAILABLE_IN_ALL |
693 | void g_type_class_unref (gpointer g_class); |
694 | GLIB_AVAILABLE_IN_ALL |
695 | gpointer g_type_class_peek_parent (gpointer g_class); |
696 | GLIB_AVAILABLE_IN_ALL |
697 | gpointer g_type_interface_peek (gpointer instance_class, |
698 | GType iface_type); |
699 | GLIB_AVAILABLE_IN_ALL |
700 | gpointer g_type_interface_peek_parent (gpointer g_iface); |
701 | |
702 | GLIB_AVAILABLE_IN_ALL |
703 | gpointer g_type_default_interface_ref (GType g_type); |
704 | GLIB_AVAILABLE_IN_ALL |
705 | gpointer g_type_default_interface_peek (GType g_type); |
706 | GLIB_AVAILABLE_IN_ALL |
707 | void g_type_default_interface_unref (gpointer g_iface); |
708 | |
709 | /* g_free() the returned arrays */ |
710 | GLIB_AVAILABLE_IN_ALL |
711 | GType* g_type_children (GType type, |
712 | guint *n_children); |
713 | GLIB_AVAILABLE_IN_ALL |
714 | GType* g_type_interfaces (GType type, |
715 | guint *n_interfaces); |
716 | |
717 | /* per-type _static_ data */ |
718 | GLIB_AVAILABLE_IN_ALL |
719 | void g_type_set_qdata (GType type, |
720 | GQuark quark, |
721 | gpointer data); |
722 | GLIB_AVAILABLE_IN_ALL |
723 | gpointer g_type_get_qdata (GType type, |
724 | GQuark quark); |
725 | GLIB_AVAILABLE_IN_ALL |
726 | void g_type_query (GType type, |
727 | GTypeQuery *query); |
728 | |
729 | |
730 | /* --- type registration --- */ |
731 | /** |
732 | * GBaseInitFunc: |
733 | * @g_class: The #GTypeClass structure to initialize. |
734 | * |
735 | * A callback function used by the type system to do base initialization |
736 | * of the class structures of derived types. It is called as part of the |
737 | * initialization process of all derived classes and should reallocate |
738 | * or reset all dynamic class members copied over from the parent class. |
739 | * For example, class members (such as strings) that are not sufficiently |
740 | * handled by a plain memory copy of the parent class into the derived class |
741 | * have to be altered. See GClassInitFunc() for a discussion of the class |
742 | * intialization process. |
743 | */ |
744 | typedef void (*GBaseInitFunc) (gpointer g_class); |
745 | /** |
746 | * GBaseFinalizeFunc: |
747 | * @g_class: The #GTypeClass structure to finalize. |
748 | * |
749 | * A callback function used by the type system to finalize those portions |
750 | * of a derived types class structure that were setup from the corresponding |
751 | * GBaseInitFunc() function. Class finalization basically works the inverse |
752 | * way in which class intialization is performed. |
753 | * See GClassInitFunc() for a discussion of the class intialization process. |
754 | */ |
755 | typedef void (*GBaseFinalizeFunc) (gpointer g_class); |
756 | /** |
757 | * GClassInitFunc: |
758 | * @g_class: The #GTypeClass structure to initialize. |
759 | * @class_data: The @class_data member supplied via the #GTypeInfo structure. |
760 | * |
761 | * A callback function used by the type system to initialize the class |
762 | * of a specific type. This function should initialize all static class |
763 | * members. |
764 | * The initialization process of a class involves: |
765 | * <itemizedlist> |
766 | * <listitem><para> |
767 | * 1 - Copying common members from the parent class over to the |
768 | * derived class structure. |
769 | * </para></listitem> |
770 | * <listitem><para> |
771 | * 2 - Zero initialization of the remaining members not copied |
772 | * over from the parent class. |
773 | * </para></listitem> |
774 | * <listitem><para> |
775 | * 3 - Invocation of the GBaseInitFunc() initializers of all parent |
776 | * types and the class' type. |
777 | * </para></listitem> |
778 | * <listitem><para> |
779 | * 4 - Invocation of the class' GClassInitFunc() initializer. |
780 | * </para></listitem> |
781 | * </itemizedlist> |
782 | * Since derived classes are partially initialized through a memory copy |
783 | * of the parent class, the general rule is that GBaseInitFunc() and |
784 | * GBaseFinalizeFunc() should take care of necessary reinitialization |
785 | * and release of those class members that were introduced by the type |
786 | * that specified these GBaseInitFunc()/GBaseFinalizeFunc(). |
787 | * GClassInitFunc() should only care about initializing static |
788 | * class members, while dynamic class members (such as allocated strings |
789 | * or reference counted resources) are better handled by a GBaseInitFunc() |
790 | * for this type, so proper initialization of the dynamic class members |
791 | * is performed for class initialization of derived types as well. |
792 | * An example may help to correspond the intend of the different class |
793 | * initializers: |
794 | * |
795 | * |[ |
796 | * typedef struct { |
797 | * GObjectClass parent_class; |
798 | * gint static_integer; |
799 | * gchar *dynamic_string; |
800 | * } TypeAClass; |
801 | * static void |
802 | * type_a_base_class_init (TypeAClass *class) |
803 | * { |
804 | * class->dynamic_string = g_strdup ("some string"); |
805 | * } |
806 | * static void |
807 | * type_a_base_class_finalize (TypeAClass *class) |
808 | * { |
809 | * g_free (class->dynamic_string); |
810 | * } |
811 | * static void |
812 | * type_a_class_init (TypeAClass *class) |
813 | * { |
814 | * class->static_integer = 42; |
815 | * } |
816 | * |
817 | * typedef struct { |
818 | * TypeAClass parent_class; |
819 | * gfloat static_float; |
820 | * GString *dynamic_gstring; |
821 | * } TypeBClass; |
822 | * static void |
823 | * type_b_base_class_init (TypeBClass *class) |
824 | * { |
825 | * class->dynamic_gstring = g_string_new ("some other string"); |
826 | * } |
827 | * static void |
828 | * type_b_base_class_finalize (TypeBClass *class) |
829 | * { |
830 | * g_string_free (class->dynamic_gstring); |
831 | * } |
832 | * static void |
833 | * type_b_class_init (TypeBClass *class) |
834 | * { |
835 | * class->static_float = 3.14159265358979323846; |
836 | * } |
837 | * ]| |
838 | * Initialization of TypeBClass will first cause initialization of |
839 | * TypeAClass (derived classes reference their parent classes, see |
840 | * g_type_class_ref() on this). |
841 | * Initialization of TypeAClass roughly involves zero-initializing its fields, |
842 | * then calling its GBaseInitFunc() type_a_base_class_init() to allocate |
843 | * its dynamic members (dynamic_string), and finally calling its GClassInitFunc() |
844 | * type_a_class_init() to initialize its static members (static_integer). |
845 | * The first step in the initialization process of TypeBClass is then |
846 | * a plain memory copy of the contents of TypeAClass into TypeBClass and |
847 | * zero-initialization of the remaining fields in TypeBClass. |
848 | * The dynamic members of TypeAClass within TypeBClass now need |
849 | * reinitialization which is performed by calling type_a_base_class_init() |
850 | * with an argument of TypeBClass. |
851 | * After that, the GBaseInitFunc() of TypeBClass, type_b_base_class_init() |
852 | * is called to allocate the dynamic members of TypeBClass (dynamic_gstring), |
853 | * and finally the GClassInitFunc() of TypeBClass, type_b_class_init(), |
854 | * is called to complete the initialization process with the static members |
855 | * (static_float). |
856 | * Corresponding finalization counter parts to the GBaseInitFunc() functions |
857 | * have to be provided to release allocated resources at class finalization |
858 | * time. |
859 | */ |
860 | typedef void (*GClassInitFunc) (gpointer g_class, |
861 | gpointer class_data); |
862 | /** |
863 | * GClassFinalizeFunc: |
864 | * @g_class: The #GTypeClass structure to finalize. |
865 | * @class_data: The @class_data member supplied via the #GTypeInfo structure. |
866 | * |
867 | * A callback function used by the type system to finalize a class. |
868 | * This function is rarely needed, as dynamically allocated class resources |
869 | * should be handled by GBaseInitFunc() and GBaseFinalizeFunc(). |
870 | * Also, specification of a GClassFinalizeFunc() in the #GTypeInfo |
871 | * structure of a static type is invalid, because classes of static types |
872 | * will never be finalized (they are artificially kept alive when their |
873 | * reference count drops to zero). |
874 | */ |
875 | typedef void (*GClassFinalizeFunc) (gpointer g_class, |
876 | gpointer class_data); |
877 | /** |
878 | * GInstanceInitFunc: |
879 | * @instance: The instance to initialize. |
880 | * @g_class: The class of the type the instance is created for. |
881 | * |
882 | * A callback function used by the type system to initialize a new |
883 | * instance of a type. This function initializes all instance members and |
884 | * allocates any resources required by it. |
885 | * Initialization of a derived instance involves calling all its parent |
886 | * types instance initializers, so the class member of the instance |
887 | * is altered during its initialization to always point to the class that |
888 | * belongs to the type the current initializer was introduced for. |
889 | */ |
890 | typedef void (*GInstanceInitFunc) (GTypeInstance *instance, |
891 | gpointer g_class); |
892 | /** |
893 | * GInterfaceInitFunc: |
894 | * @g_iface: The interface structure to initialize. |
895 | * @iface_data: The @interface_data supplied via the #GInterfaceInfo structure. |
896 | * |
897 | * A callback function used by the type system to initialize a new |
898 | * interface. This function should initialize all internal data and |
899 | * allocate any resources required by the interface. |
900 | */ |
901 | typedef void (*GInterfaceInitFunc) (gpointer g_iface, |
902 | gpointer iface_data); |
903 | /** |
904 | * GInterfaceFinalizeFunc: |
905 | * @g_iface: The interface structure to finalize. |
906 | * @iface_data: The @interface_data supplied via the #GInterfaceInfo structure. |
907 | * |
908 | * A callback function used by the type system to finalize an interface. |
909 | * This function should destroy any internal data and release any resources |
910 | * allocated by the corresponding GInterfaceInitFunc() function. |
911 | */ |
912 | typedef void (*GInterfaceFinalizeFunc) (gpointer g_iface, |
913 | gpointer iface_data); |
914 | /** |
915 | * GTypeClassCacheFunc: |
916 | * @cache_data: data that was given to the g_type_add_class_cache_func() call |
917 | * @g_class: The #GTypeClass structure which is unreferenced |
918 | * |
919 | * A callback function which is called when the reference count of a class |
920 | * drops to zero. It may use g_type_class_ref() to prevent the class from |
921 | * being freed. You should not call g_type_class_unref() from a |
922 | * #GTypeClassCacheFunc function to prevent infinite recursion, use |
923 | * g_type_class_unref_uncached() instead. |
924 | * |
925 | * The functions have to check the class id passed in to figure |
926 | * whether they actually want to cache the class of this type, since all |
927 | * classes are routed through the same #GTypeClassCacheFunc chain. |
928 | * |
929 | * Returns: %TRUE to stop further #GTypeClassCacheFunc<!-- -->s from being |
930 | * called, %FALSE to continue. |
931 | */ |
932 | typedef gboolean (*GTypeClassCacheFunc) (gpointer cache_data, |
933 | GTypeClass *g_class); |
934 | /** |
935 | * GTypeInterfaceCheckFunc: |
936 | * @check_data: data passed to g_type_add_interface_check(). |
937 | * @g_iface: the interface that has been initialized |
938 | * |
939 | * A callback called after an interface vtable is initialized. |
940 | * See g_type_add_interface_check(). |
941 | * |
942 | * Since: 2.4 |
943 | */ |
944 | typedef void (*GTypeInterfaceCheckFunc) (gpointer check_data, |
945 | gpointer g_iface); |
946 | /** |
947 | * GTypeFundamentalFlags: |
948 | * @G_TYPE_FLAG_CLASSED: Indicates a classed type. |
949 | * @G_TYPE_FLAG_INSTANTIATABLE: Indicates an instantiable type (implies classed). |
950 | * @G_TYPE_FLAG_DERIVABLE: Indicates a flat derivable type. |
951 | * @G_TYPE_FLAG_DEEP_DERIVABLE: Indicates a deep derivable type (implies derivable). |
952 | * |
953 | * Bit masks used to check or determine specific characteristics of a |
954 | * fundamental type. |
955 | */ |
956 | typedef enum /*< skip >*/ |
957 | { |
958 | G_TYPE_FLAG_CLASSED = (1 << 0), |
959 | G_TYPE_FLAG_INSTANTIATABLE = (1 << 1), |
960 | G_TYPE_FLAG_DERIVABLE = (1 << 2), |
961 | G_TYPE_FLAG_DEEP_DERIVABLE = (1 << 3) |
962 | } GTypeFundamentalFlags; |
963 | /** |
964 | * GTypeFlags: |
965 | * @G_TYPE_FLAG_ABSTRACT: Indicates an abstract type. No instances can be |
966 | * created for an abstract type. |
967 | * @G_TYPE_FLAG_VALUE_ABSTRACT: Indicates an abstract value type, i.e. a type |
968 | * that introduces a value table, but can't be used for |
969 | * g_value_init(). |
970 | * |
971 | * Bit masks used to check or determine characteristics of a type. |
972 | */ |
973 | typedef enum /*< skip >*/ |
974 | { |
975 | G_TYPE_FLAG_ABSTRACT = (1 << 4), |
976 | G_TYPE_FLAG_VALUE_ABSTRACT = (1 << 5) |
977 | } GTypeFlags; |
978 | /** |
979 | * GTypeInfo: |
980 | * @class_size: Size of the class structure (required for interface, classed and instantiatable types). |
981 | * @base_init: Location of the base initialization function (optional). |
982 | * @base_finalize: Location of the base finalization function (optional). |
983 | * @class_init: Location of the class initialization function for |
984 | * classed and instantiatable types. Location of the default vtable |
985 | * inititalization function for interface types. (optional) This function |
986 | * is used both to fill in virtual functions in the class or default vtable, |
987 | * and to do type-specific setup such as registering signals and object |
988 | * properties. |
989 | * @class_finalize: Location of the class finalization function for |
990 | * classed and instantiatable types. Location fo the default vtable |
991 | * finalization function for interface types. (optional) |
992 | * @class_data: User-supplied data passed to the class init/finalize functions. |
993 | * @instance_size: Size of the instance (object) structure (required for instantiatable types only). |
994 | * @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. |
995 | * @instance_init: Location of the instance initialization function (optional, for instantiatable types only). |
996 | * @value_table: A #GTypeValueTable function table for generic handling of GValues of this type (usually only |
997 | * useful for fundamental types). |
998 | * |
999 | * This structure is used to provide the type system with the information |
1000 | * required to initialize and destruct (finalize) a type's class and |
1001 | * its instances. |
1002 | * The initialized structure is passed to the g_type_register_static() function |
1003 | * (or is copied into the provided #GTypeInfo structure in the |
1004 | * g_type_plugin_complete_type_info()). The type system will perform a deep |
1005 | * copy of this structure, so its memory does not need to be persistent |
1006 | * across invocation of g_type_register_static(). |
1007 | */ |
1008 | struct _GTypeInfo |
1009 | { |
1010 | /* interface types, classed types, instantiated types */ |
1011 | guint16 class_size; |
1012 | |
1013 | GBaseInitFunc base_init; |
1014 | GBaseFinalizeFunc base_finalize; |
1015 | |
1016 | /* interface types, classed types, instantiated types */ |
1017 | GClassInitFunc class_init; |
1018 | GClassFinalizeFunc class_finalize; |
1019 | gconstpointer class_data; |
1020 | |
1021 | /* instantiated types */ |
1022 | guint16 instance_size; |
1023 | guint16 n_preallocs; |
1024 | GInstanceInitFunc instance_init; |
1025 | |
1026 | /* value handling */ |
1027 | const GTypeValueTable *value_table; |
1028 | }; |
1029 | /** |
1030 | * GTypeFundamentalInfo: |
1031 | * @type_flags: #GTypeFundamentalFlags describing the characteristics of the fundamental type |
1032 | * |
1033 | * A structure that provides information to the type system which is |
1034 | * used specifically for managing fundamental types. |
1035 | */ |
1036 | struct _GTypeFundamentalInfo |
1037 | { |
1038 | GTypeFundamentalFlags type_flags; |
1039 | }; |
1040 | /** |
1041 | * GInterfaceInfo: |
1042 | * @interface_init: location of the interface initialization function |
1043 | * @interface_finalize: location of the interface finalization function |
1044 | * @interface_data: user-supplied data passed to the interface init/finalize functions |
1045 | * |
1046 | * A structure that provides information to the type system which is |
1047 | * used specifically for managing interface types. |
1048 | */ |
1049 | struct _GInterfaceInfo |
1050 | { |
1051 | GInterfaceInitFunc interface_init; |
1052 | GInterfaceFinalizeFunc interface_finalize; |
1053 | gpointer interface_data; |
1054 | }; |
1055 | /** |
1056 | * GTypeValueTable: |
1057 | * @value_init: Default initialize @values contents by poking values |
1058 | * directly into the value->data array. The data array of |
1059 | * the #GValue passed into this function was zero-filled |
1060 | * with <function>memset()</function>, so no care has to |
1061 | * be taken to free any |
1062 | * old contents. E.g. for the implementation of a string |
1063 | * value that may never be %NULL, the implementation might |
1064 | * look like: |
1065 | * |[ |
1066 | * value->data[0].v_pointer = g_strdup (""); |
1067 | * ]| |
1068 | * @value_free: Free any old contents that might be left in the |
1069 | * data array of the passed in @value. No resources may |
1070 | * remain allocated through the #GValue contents after |
1071 | * this function returns. E.g. for our above string type: |
1072 | * |[ |
1073 | * // only free strings without a specific flag for static storage |
1074 | * if (!(value->data[1].v_uint & G_VALUE_NOCOPY_CONTENTS)) |
1075 | * g_free (value->data[0].v_pointer); |
1076 | * ]| |
1077 | * @value_copy: @dest_value is a #GValue with zero-filled data section |
1078 | * and @src_value is a properly setup #GValue of same or |
1079 | * derived type. |
1080 | * The purpose of this function is to copy the contents of |
1081 | * @src_value into @dest_value in a way, that even after |
1082 | * @src_value has been freed, the contents of @dest_value |
1083 | * remain valid. String type example: |
1084 | * |[ |
1085 | * dest_value->data[0].v_pointer = g_strdup (src_value->data[0].v_pointer); |
1086 | * ]| |
1087 | * @value_peek_pointer: If the value contents fit into a pointer, such as objects |
1088 | * or strings, return this pointer, so the caller can peek at |
1089 | * the current contents. To extend on our above string example: |
1090 | * |[ |
1091 | * return value->data[0].v_pointer; |
1092 | * ]| |
1093 | * @collect_format: A string format describing how to collect the contents of |
1094 | * this value bit-by-bit. Each character in the format represents |
1095 | * an argument to be collected, and the characters themselves indicate |
1096 | * the type of the argument. Currently supported arguments are: |
1097 | * <variablelist> |
1098 | * <varlistentry><term /><listitem><para> |
1099 | * 'i' - Integers. passed as collect_values[].v_int. |
1100 | * </para></listitem></varlistentry> |
1101 | * <varlistentry><term /><listitem><para> |
1102 | * 'l' - Longs. passed as collect_values[].v_long. |
1103 | * </para></listitem></varlistentry> |
1104 | * <varlistentry><term /><listitem><para> |
1105 | * 'd' - Doubles. passed as collect_values[].v_double. |
1106 | * </para></listitem></varlistentry> |
1107 | * <varlistentry><term /><listitem><para> |
1108 | * 'p' - Pointers. passed as collect_values[].v_pointer. |
1109 | * </para></listitem></varlistentry> |
1110 | * </variablelist> |
1111 | * It should be noted that for variable argument list construction, |
1112 | * ANSI C promotes every type smaller than an integer to an int, and |
1113 | * floats to doubles. So for collection of short int or char, 'i' |
1114 | * needs to be used, and for collection of floats 'd'. |
1115 | * @collect_value: The collect_value() function is responsible for converting the |
1116 | * values collected from a variable argument list into contents |
1117 | * suitable for storage in a GValue. This function should setup |
1118 | * @value similar to value_init(); e.g. for a string value that |
1119 | * does not allow %NULL pointers, it needs to either spew an error, |
1120 | * or do an implicit conversion by storing an empty string. |
1121 | * The @value passed in to this function has a zero-filled data |
1122 | * array, so just like for value_init() it is guaranteed to not |
1123 | * contain any old contents that might need freeing. |
1124 | * @n_collect_values is exactly the string length of @collect_format, |
1125 | * and @collect_values is an array of unions #GTypeCValue with |
1126 | * length @n_collect_values, containing the collected values |
1127 | * according to @collect_format. |
1128 | * @collect_flags is an argument provided as a hint by the caller. |
1129 | * It may contain the flag %G_VALUE_NOCOPY_CONTENTS indicating, |
1130 | * that the collected value contents may be considered "static" |
1131 | * for the duration of the @value lifetime. |
1132 | * Thus an extra copy of the contents stored in @collect_values is |
1133 | * not required for assignment to @value. |
1134 | * For our above string example, we continue with: |
1135 | * |[ |
1136 | * if (!collect_values[0].v_pointer) |
1137 | * value->data[0].v_pointer = g_strdup (""); |
1138 | * else if (collect_flags & G_VALUE_NOCOPY_CONTENTS) |
1139 | * { |
1140 | * value->data[0].v_pointer = collect_values[0].v_pointer; |
1141 | * // keep a flag for the value_free() implementation to not free this string |
1142 | * value->data[1].v_uint = G_VALUE_NOCOPY_CONTENTS; |
1143 | * } |
1144 | * else |
1145 | * value->data[0].v_pointer = g_strdup (collect_values[0].v_pointer); |
1146 | * return NULL; |
1147 | * ]| |
1148 | * It should be noted, that it is generally a bad idea to follow the |
1149 | * #G_VALUE_NOCOPY_CONTENTS hint for reference counted types. Due to |
1150 | * reentrancy requirements and reference count assertions performed |
1151 | * by the signal emission code, reference counts should always be |
1152 | * incremented for reference counted contents stored in the value->data |
1153 | * array. To deviate from our string example for a moment, and taking |
1154 | * a look at an exemplary implementation for collect_value() of |
1155 | * #GObject: |
1156 | * |[ |
1157 | * if (collect_values[0].v_pointer) |
1158 | * { |
1159 | * GObject *object = G_OBJECT (collect_values[0].v_pointer); |
1160 | * // never honour G_VALUE_NOCOPY_CONTENTS for ref-counted types |
1161 | * value->data[0].v_pointer = g_object_ref (object); |
1162 | * return NULL; |
1163 | * } |
1164 | * else |
1165 | * return g_strdup_printf ("Object passed as invalid NULL pointer"); |
1166 | * } |
1167 | * ]| |
1168 | * The reference count for valid objects is always incremented, |
1169 | * regardless of @collect_flags. For invalid objects, the example |
1170 | * returns a newly allocated string without altering @value. |
1171 | * Upon success, collect_value() needs to return %NULL. If, however, |
1172 | * an error condition occurred, collect_value() may spew an |
1173 | * error by returning a newly allocated non-%NULL string, giving |
1174 | * a suitable description of the error condition. |
1175 | * The calling code makes no assumptions about the @value |
1176 | * contents being valid upon error returns, @value |
1177 | * is simply thrown away without further freeing. As such, it is |
1178 | * a good idea to not allocate #GValue contents, prior to returning |
1179 | * an error, however, collect_values() is not obliged to return |
1180 | * a correctly setup @value for error returns, simply because |
1181 | * any non-%NULL return is considered a fatal condition so further |
1182 | * program behaviour is undefined. |
1183 | * @lcopy_format: Format description of the arguments to collect for @lcopy_value, |
1184 | * analogous to @collect_format. Usually, @lcopy_format string consists |
1185 | * only of 'p's to provide lcopy_value() with pointers to storage locations. |
1186 | * @lcopy_value: This function is responsible for storing the @value contents into |
1187 | * arguments passed through a variable argument list which got |
1188 | * collected into @collect_values according to @lcopy_format. |
1189 | * @n_collect_values equals the string length of @lcopy_format, |
1190 | * and @collect_flags may contain %G_VALUE_NOCOPY_CONTENTS. |
1191 | * In contrast to collect_value(), lcopy_value() is obliged to |
1192 | * always properly support %G_VALUE_NOCOPY_CONTENTS. |
1193 | * Similar to collect_value() the function may prematurely abort |
1194 | * by returning a newly allocated string describing an error condition. |
1195 | * To complete the string example: |
1196 | * |[ |
1197 | * gchar **string_p = collect_values[0].v_pointer; |
1198 | * if (!string_p) |
1199 | * return g_strdup_printf ("string location passed as NULL"); |
1200 | * if (collect_flags & G_VALUE_NOCOPY_CONTENTS) |
1201 | * *string_p = value->data[0].v_pointer; |
1202 | * else |
1203 | * *string_p = g_strdup (value->data[0].v_pointer); |
1204 | * ]| |
1205 | * And an illustrative version of lcopy_value() for |
1206 | * reference-counted types: |
1207 | * |[ |
1208 | * GObject **object_p = collect_values[0].v_pointer; |
1209 | * if (!object_p) |
1210 | * return g_strdup_printf ("object location passed as NULL"); |
1211 | * if (!value->data[0].v_pointer) |
1212 | * *object_p = NULL; |
1213 | * else if (collect_flags & G_VALUE_NOCOPY_CONTENTS) /* always honour */ |
1214 | * *object_p = value->data[0].v_pointer; |
1215 | * else |
1216 | * *object_p = g_object_ref (value->data[0].v_pointer); |
1217 | * return NULL; |
1218 | * ]| |
1219 | * |
1220 | * The #GTypeValueTable provides the functions required by the #GValue implementation, |
1221 | * to serve as a container for values of a type. |
1222 | */ |
1223 | |
1224 | struct _GTypeValueTable |
1225 | { |
1226 | void (*value_init) (GValue *value); |
1227 | void (*value_free) (GValue *value); |
1228 | void (*value_copy) (const GValue *src_value, |
1229 | GValue *dest_value); |
1230 | /* varargs functionality (optional) */ |
1231 | gpointer (*value_peek_pointer) (const GValue *value); |
1232 | const gchar *collect_format; |
1233 | gchar* (*collect_value) (GValue *value, |
1234 | guint n_collect_values, |
1235 | GTypeCValue *collect_values, |
1236 | guint collect_flags); |
1237 | const gchar *lcopy_format; |
1238 | gchar* (*lcopy_value) (const GValue *value, |
1239 | guint n_collect_values, |
1240 | GTypeCValue *collect_values, |
1241 | guint collect_flags); |
1242 | }; |
1243 | GLIB_AVAILABLE_IN_ALL |
1244 | GType g_type_register_static (GType parent_type, |
1245 | const gchar *type_name, |
1246 | const GTypeInfo *info, |
1247 | GTypeFlags flags); |
1248 | GLIB_AVAILABLE_IN_ALL |
1249 | GType g_type_register_static_simple (GType parent_type, |
1250 | const gchar *type_name, |
1251 | guint class_size, |
1252 | GClassInitFunc class_init, |
1253 | guint instance_size, |
1254 | GInstanceInitFunc instance_init, |
1255 | GTypeFlags flags); |
1256 | |
1257 | GLIB_AVAILABLE_IN_ALL |
1258 | GType g_type_register_dynamic (GType parent_type, |
1259 | const gchar *type_name, |
1260 | GTypePlugin *plugin, |
1261 | GTypeFlags flags); |
1262 | GLIB_AVAILABLE_IN_ALL |
1263 | GType g_type_register_fundamental (GType type_id, |
1264 | const gchar *type_name, |
1265 | const GTypeInfo *info, |
1266 | const GTypeFundamentalInfo *finfo, |
1267 | GTypeFlags flags); |
1268 | GLIB_AVAILABLE_IN_ALL |
1269 | void g_type_add_interface_static (GType instance_type, |
1270 | GType interface_type, |
1271 | const GInterfaceInfo *info); |
1272 | GLIB_AVAILABLE_IN_ALL |
1273 | void g_type_add_interface_dynamic (GType instance_type, |
1274 | GType interface_type, |
1275 | GTypePlugin *plugin); |
1276 | GLIB_AVAILABLE_IN_ALL |
1277 | void g_type_interface_add_prerequisite (GType interface_type, |
1278 | GType prerequisite_type); |
1279 | GLIB_AVAILABLE_IN_ALL |
1280 | GType*g_type_interface_prerequisites (GType interface_type, |
1281 | guint *n_prerequisites); |
1282 | GLIB_AVAILABLE_IN_ALL |
1283 | void g_type_class_add_private (gpointer g_class, |
1284 | gsize private_size); |
1285 | GLIB_AVAILABLE_IN_2_38 |
1286 | gint g_type_add_instance_private (GType class_type, |
1287 | gsize private_size); |
1288 | GLIB_AVAILABLE_IN_ALL |
1289 | gpointer g_type_instance_get_private (GTypeInstance *instance, |
1290 | GType private_type); |
1291 | GLIB_AVAILABLE_IN_2_38 |
1292 | void g_type_class_adjust_private_offset (gpointer g_class, |
1293 | gint *private_size_or_offset); |
1294 | |
1295 | GLIB_AVAILABLE_IN_ALL |
1296 | void g_type_add_class_private (GType class_type, |
1297 | gsize private_size); |
1298 | GLIB_AVAILABLE_IN_ALL |
1299 | gpointer g_type_class_get_private (GTypeClass *klass, |
1300 | GType private_type); |
1301 | GLIB_AVAILABLE_IN_2_38 |
1302 | gint g_type_class_get_instance_private_offset (gpointer g_class); |
1303 | |
1304 | GLIB_AVAILABLE_IN_2_34 |
1305 | void g_type_ensure (GType type); |
1306 | GLIB_AVAILABLE_IN_2_36 |
1307 | guint g_type_get_type_registration_serial (void); |
1308 | |
1309 | |
1310 | /* --- GType boilerplate --- */ |
1311 | /** |
1312 | * G_DEFINE_TYPE: |
1313 | * @TN: The name of the new type, in Camel case. |
1314 | * @t_n: The name of the new type, in lowercase, with words |
1315 | * separated by '_'. |
1316 | * @T_P: The #GType of the parent type. |
1317 | * |
1318 | * A convenience macro for type implementations, which declares a |
1319 | * class initialization function, an instance initialization function (see #GTypeInfo for information about |
1320 | * these) and a static variable named @t_n<!-- -->_parent_class pointing to the parent class. Furthermore, it defines |
1321 | * a *_get_type() function. See G_DEFINE_TYPE_EXTENDED() for an example. |
1322 | * |
1323 | * Since: 2.4 |
1324 | */ |
1325 | #define G_DEFINE_TYPE(TN, t_n, T_P) G_DEFINE_TYPE_EXTENDED (TN, t_n, T_P, 0, {}) |
1326 | /** |
1327 | * G_DEFINE_TYPE_WITH_CODE: |
1328 | * @TN: The name of the new type, in Camel case. |
1329 | * @t_n: The name of the new type in lowercase, with words separated by '_'. |
1330 | * @T_P: The #GType of the parent type. |
1331 | * @_C_: Custom code that gets inserted in the *_get_type() function. |
1332 | * |
1333 | * A convenience macro for type implementations. |
1334 | * Similar to G_DEFINE_TYPE(), but allows you to insert custom code into the |
1335 | * *_get_type() function, e.g. interface implementations via G_IMPLEMENT_INTERFACE(). |
1336 | * See G_DEFINE_TYPE_EXTENDED() for an example. |
1337 | * |
1338 | * Since: 2.4 |
1339 | */ |
1340 | #define G_DEFINE_TYPE_WITH_CODE(TN, t_n, T_P, _C_) _G_DEFINE_TYPE_EXTENDED_BEGIN (TN, t_n, T_P, 0) {_C_;} _G_DEFINE_TYPE_EXTENDED_END() |
1341 | /** |
1342 | * G_DEFINE_TYPE_WITH_PRIVATE: |
1343 | * @TN: The name of the new type, in Camel case. |
1344 | * @t_n: The name of the new type, in lowercase, with words |
1345 | * separated by '_'. |
1346 | * @T_P: The #GType of the parent type. |
1347 | * |
1348 | * A convenience macro for type implementations, which declares a |
1349 | * class initialization function, an instance initialization function (see #GTypeInfo for information about |
1350 | * these), a static variable named @t_n<!-- -->_parent_class pointing to the parent class, and adds private |
1351 | * instance data to the type. Furthermore, it defines a *_get_type() function. See G_DEFINE_TYPE_EXTENDED() |
1352 | * for an example. |
1353 | * |
1354 | * Note that private structs added with this macros must have a struct |
1355 | * name of the form <replaceable>@TN</replaceable>Private. |
1356 | * |
1357 | * Since: 2.38 |
1358 | */ |
1359 | #define G_DEFINE_TYPE_WITH_PRIVATE(TN, t_n, T_P) G_DEFINE_TYPE_EXTENDED (TN, t_n, T_P, 0, G_ADD_PRIVATE (TN)) |
1360 | /** |
1361 | * G_DEFINE_ABSTRACT_TYPE: |
1362 | * @TN: The name of the new type, in Camel case. |
1363 | * @t_n: The name of the new type, in lowercase, with words |
1364 | * separated by '_'. |
1365 | * @T_P: The #GType of the parent type. |
1366 | * |
1367 | * A convenience macro for type implementations. |
1368 | * Similar to G_DEFINE_TYPE(), but defines an abstract type. |
1369 | * See G_DEFINE_TYPE_EXTENDED() for an example. |
1370 | * |
1371 | * Since: 2.4 |
1372 | */ |
1373 | #define G_DEFINE_ABSTRACT_TYPE(TN, t_n, T_P) G_DEFINE_TYPE_EXTENDED (TN, t_n, T_P, G_TYPE_FLAG_ABSTRACT, {}) |
1374 | /** |
1375 | * G_DEFINE_ABSTRACT_TYPE_WITH_CODE: |
1376 | * @TN: The name of the new type, in Camel case. |
1377 | * @t_n: The name of the new type, in lowercase, with words |
1378 | * separated by '_'. |
1379 | * @T_P: The #GType of the parent type. |
1380 | * @_C_: Custom code that gets inserted in the @type_name_get_type() function. |
1381 | * |
1382 | * A convenience macro for type implementations. |
1383 | * Similar to G_DEFINE_TYPE_WITH_CODE(), but defines an abstract type and allows you to |
1384 | * insert custom code into the *_get_type() function, e.g. interface implementations |
1385 | * via G_IMPLEMENT_INTERFACE(). See G_DEFINE_TYPE_EXTENDED() for an example. |
1386 | * |
1387 | * Since: 2.4 |
1388 | */ |
1389 | #define G_DEFINE_ABSTRACT_TYPE_WITH_CODE(TN, t_n, T_P, _C_) _G_DEFINE_TYPE_EXTENDED_BEGIN (TN, t_n, T_P, G_TYPE_FLAG_ABSTRACT) {_C_;} _G_DEFINE_TYPE_EXTENDED_END() |
1390 | /** |
1391 | * G_DEFINE_ABSTRACT_TYPE_WITH_PRIVATE: |
1392 | * @TN: The name of the new type, in Camel case. |
1393 | * @t_n: The name of the new type, in lowercase, with words |
1394 | * separated by '_'. |
1395 | * @T_P: The #GType of the parent type. |
1396 | * |
1397 | * Similar to G_DEFINE_TYPE_WITH_PRIVATE(), but defines an abstract type. |
1398 | * See G_DEFINE_TYPE_EXTENDED() for an example. |
1399 | * |
1400 | * Since: 2.38 |
1401 | */ |
1402 | #define G_DEFINE_ABSTRACT_TYPE_WITH_PRIVATE(TN, t_n, T_P) G_DEFINE_TYPE_EXTENDED (TN, t_n, T_P, G_TYPE_FLAG_ABSTRACT, G_ADD_PRIVATE (TN)) |
1403 | /** |
1404 | * G_DEFINE_TYPE_EXTENDED: |
1405 | * @TN: The name of the new type, in Camel case. |
1406 | * @t_n: The name of the new type, in lowercase, with words |
1407 | * separated by '_'. |
1408 | * @T_P: The #GType of the parent type. |
1409 | * @_f_: #GTypeFlags to pass to g_type_register_static() |
1410 | * @_C_: Custom code that gets inserted in the *_get_type() function. |
1411 | * |
1412 | * The most general convenience macro for type implementations, on which |
1413 | * G_DEFINE_TYPE(), etc are based. |
1414 | * |
1415 | * |[ |
1416 | * G_DEFINE_TYPE_EXTENDED (GtkGadget, |
1417 | * gtk_gadget, |
1418 | * GTK_TYPE_WIDGET, |
1419 | * 0, |
1420 | * G_IMPLEMENT_INTERFACE (TYPE_GIZMO, |
1421 | * gtk_gadget_gizmo_init)); |
1422 | * ]| |
1423 | * expands to |
1424 | * |[ |
1425 | * static void gtk_gadget_init (GtkGadget *self); |
1426 | * static void gtk_gadget_class_init (GtkGadgetClass *klass); |
1427 | * static gpointer gtk_gadget_parent_class = NULL; |
1428 | * static void gtk_gadget_class_intern_init (gpointer klass) |
1429 | * { |
1430 | * gtk_gadget_parent_class = g_type_class_peek_parent (klass); |
1431 | * gtk_gadget_class_init ((GtkGadgetClass*) klass); |
1432 | * } |
1433 | * |
1434 | * GType |
1435 | * gtk_gadget_get_type (void) |
1436 | * { |
1437 | * static volatile gsize g_define_type_id__volatile = 0; |
1438 | * if (g_once_init_enter (&g_define_type_id__volatile)) |
1439 | * { |
1440 | * GType g_define_type_id = |
1441 | * g_type_register_static_simple (GTK_TYPE_WIDGET, |
1442 | * g_intern_static_string ("GtkGadget"), |
1443 | * sizeof (GtkGadgetClass), |
1444 | * (GClassInitFunc) gtk_gadget_class_intern_init, |
1445 | * sizeof (GtkGadget), |
1446 | * (GInstanceInitFunc) gtk_gadget_init, |
1447 | * 0); |
1448 | * { |
1449 | * const GInterfaceInfo g_implement_interface_info = { |
1450 | * (GInterfaceInitFunc) gtk_gadget_gizmo_init |
1451 | * }; |
1452 | * g_type_add_interface_static (g_define_type_id, TYPE_GIZMO, &g_implement_interface_info); |
1453 | * } |
1454 | * g_once_init_leave (&g_define_type_id__volatile, g_define_type_id); |
1455 | * } |
1456 | * return g_define_type_id__volatile; |
1457 | * } |
1458 | * ]| |
1459 | * The only pieces which have to be manually provided are the definitions of |
1460 | * the instance and class structure and the definitions of the instance and |
1461 | * class init functions. |
1462 | * |
1463 | * Since: 2.4 |
1464 | */ |
1465 | #define G_DEFINE_TYPE_EXTENDED(TN, t_n, T_P, _f_, _C_) _G_DEFINE_TYPE_EXTENDED_BEGIN (TN, t_n, T_P, _f_) {_C_;} _G_DEFINE_TYPE_EXTENDED_END() |
1466 | |
1467 | /** |
1468 | * G_DEFINE_INTERFACE: |
1469 | * @TN: The name of the new type, in Camel case. |
1470 | * @t_n: The name of the new type, in lowercase, with words separated by '_'. |
1471 | * @T_P: The #GType of the prerequisite type for the interface, or 0 |
1472 | * (%G_TYPE_INVALID) for no prerequisite type. |
1473 | * |
1474 | * A convenience macro for #GTypeInterface definitions, which declares |
1475 | * a default vtable initialization function and defines a *_get_type() |
1476 | * function. |
1477 | * |
1478 | * The macro expects the interface initialization function to have the |
1479 | * name `t_n ## _default_init`, and the interface structure to have the |
1480 | * name `TN ## Interface`. |
1481 | * |
1482 | * Since: 2.24 |
1483 | */ |
1484 | #define G_DEFINE_INTERFACE(TN, t_n, T_P) G_DEFINE_INTERFACE_WITH_CODE(TN, t_n, T_P, ;) |
1485 | |
1486 | /** |
1487 | * G_DEFINE_INTERFACE_WITH_CODE: |
1488 | * @TN: The name of the new type, in Camel case. |
1489 | * @t_n: The name of the new type, in lowercase, with words separated by '_'. |
1490 | * @T_P: The #GType of the prerequisite type for the interface, or 0 |
1491 | * (%G_TYPE_INVALID) for no prerequisite type. |
1492 | * @_C_: Custom code that gets inserted in the *_get_type() function. |
1493 | * |
1494 | * A convenience macro for #GTypeInterface definitions. Similar to |
1495 | * G_DEFINE_INTERFACE(), but allows you to insert custom code into the |
1496 | * *_get_type() function, e.g. additional interface implementations |
1497 | * via G_IMPLEMENT_INTERFACE(), or additional prerequisite types. See |
1498 | * G_DEFINE_TYPE_EXTENDED() for a similar example using |
1499 | * G_DEFINE_TYPE_WITH_CODE(). |
1500 | * |
1501 | * Since: 2.24 |
1502 | */ |
1503 | #define G_DEFINE_INTERFACE_WITH_CODE(TN, t_n, T_P, _C_) _G_DEFINE_INTERFACE_EXTENDED_BEGIN(TN, t_n, T_P) {_C_;} _G_DEFINE_INTERFACE_EXTENDED_END() |
1504 | |
1505 | /** |
1506 | * G_IMPLEMENT_INTERFACE: |
1507 | * @TYPE_IFACE: The #GType of the interface to add |
1508 | * @iface_init: The interface init function |
1509 | * |
1510 | * A convenience macro to ease interface addition in the @_C_ section |
1511 | * of G_DEFINE_TYPE_WITH_CODE() or G_DEFINE_ABSTRACT_TYPE_WITH_CODE(). |
1512 | * See G_DEFINE_TYPE_EXTENDED() for an example. |
1513 | * |
1514 | * Note that this macro can only be used together with the G_DEFINE_TYPE_* |
1515 | * macros, since it depends on variable names from those macros. |
1516 | * |
1517 | * Since: 2.4 |
1518 | */ |
1519 | #define G_IMPLEMENT_INTERFACE(TYPE_IFACE, iface_init) { \ |
1520 | const GInterfaceInfo g_implement_interface_info = { \ |
1521 | (GInterfaceInitFunc) iface_init, NULL, NULL \ |
1522 | }; \ |
1523 | g_type_add_interface_static (g_define_type_id, TYPE_IFACE, &g_implement_interface_info); \ |
1524 | } |
1525 | |
1526 | /** |
1527 | * G_ADD_PRIVATE: |
1528 | * @TypeName: the name of the type in CamelCase |
1529 | * |
1530 | * A convenience macro to ease adding private data to instances of a new type |
1531 | * in the @_C_ section of G_DEFINE_TYPE_WITH_CODE() or |
1532 | * G_DEFINE_ABSTRACT_TYPE_WITH_CODE(). |
1533 | * |
1534 | * For instance: |
1535 | * |
1536 | * |[ |
1537 | * typedef struct _MyObject MyObject; |
1538 | * typedef struct _MyObjectClass MyObjectClass; |
1539 | * |
1540 | * typedef struct { |
1541 | * gint foo; |
1542 | * gint bar; |
1543 | * } MyObjectPrivate; |
1544 | * |
1545 | * G_DEFINE_TYPE_WITH_CODE (MyObject, my_object, G_TYPE_OBJECT, |
1546 | * G_ADD_PRIVATE (MyObject)) |
1547 | * ]| |
1548 | * |
1549 | * Will add MyObjectPrivate as the private data to any instance of the MyObject |
1550 | * type. |
1551 | * |
1552 | * G_DEFINE_TYPE_* macros will automatically create a private function |
1553 | * based on the arguments to this macro, which can be used to safely |
1554 | * retrieve the private data from an instance of the type; for instance: |
1555 | * |
1556 | * |[ |
1557 | * gint |
1558 | * my_object_get_foo (MyObject *obj) |
1559 | * { |
1560 | * MyObjectPrivate *priv = my_object_get_instance_private (obj); |
1561 | * |
1562 | * return priv->foo; |
1563 | * } |
1564 | * |
1565 | * void |
1566 | * my_object_set_bar (MyObject *obj, |
1567 | * gint bar) |
1568 | * { |
1569 | * MyObjectPrivate *priv = my_object_get_instance_private (obj); |
1570 | * |
1571 | * if (priv->bar != bar) |
1572 | * priv->bar = bar; |
1573 | * } |
1574 | * ]| |
1575 | * |
1576 | * Note that this macro can only be used together with the G_DEFINE_TYPE_* |
1577 | * macros, since it depends on variable names from those macros. |
1578 | * |
1579 | * Also note that private structs added with these macros must have a struct |
1580 | * name of the form <replaceable>TypeName</replaceable>Private. |
1581 | * |
1582 | * Since: 2.38 |
1583 | */ |
1584 | #define G_ADD_PRIVATE(TypeName) { \ |
1585 | TypeName##_private_offset = \ |
1586 | g_type_add_instance_private (g_define_type_id, sizeof (TypeName##Private)); \ |
1587 | } |
1588 | |
1589 | /** |
1590 | * G_PRIVATE_OFFSET: |
1591 | * @TypeName: the name of the type in CamelCase |
1592 | * @field: the name of the field in the private data structure |
1593 | * |
1594 | * Evaluates to the offset of the @field inside the instance private data |
1595 | * structure for @TypeName. |
1596 | * |
1597 | * Note that this macro can only be used together with the G_DEFINE_TYPE_* |
1598 | * and G_ADD_PRIVATE() macros, since it depends on variable names from |
1599 | * those macros. |
1600 | * |
1601 | * Since: 2.38 |
1602 | */ |
1603 | #define G_PRIVATE_OFFSET(TypeName, field) \ |
1604 | (TypeName##_private_offset + (G_STRUCT_OFFSET (TypeName##Private, field))) |
1605 | |
1606 | /** |
1607 | * G_PRIVATE_FIELD_P: |
1608 | * @TypeName: the name of the type in CamelCase |
1609 | * @inst: the instance of @TypeName you wish to access |
1610 | * @field_name: the name of the field in the private data structure |
1611 | * |
1612 | * Evaluates to a pointer to the @field_name inside the @inst private data |
1613 | * structure for @TypeName. |
1614 | * |
1615 | * Note that this macro can only be used together with the G_DEFINE_TYPE_* |
1616 | * and G_ADD_PRIVATE() macros, since it depends on variable names from |
1617 | * those macros. |
1618 | * |
1619 | * Since: 2.38 |
1620 | */ |
1621 | #define G_PRIVATE_FIELD_P(TypeName, inst, field_name) \ |
1622 | G_STRUCT_MEMBER_P (inst, G_PRIVATE_OFFSET (TypeName, field_name)) |
1623 | |
1624 | /** |
1625 | * G_PRIVATE_FIELD: |
1626 | * @TypeName: the name of the type in CamelCase |
1627 | * @inst: the instance of @TypeName you wish to access |
1628 | * @field_type: the type of the field in the private data structure |
1629 | * @field_name: the name of the field in the private data structure |
1630 | * |
1631 | * Evaluates to the @field_name inside the @inst private data |
1632 | * structure for @TypeName. |
1633 | * |
1634 | * Note that this macro can only be used together with the G_DEFINE_TYPE_* |
1635 | * and G_ADD_PRIVATE() macros, since it depends on variable names from |
1636 | * those macros. |
1637 | * |
1638 | * Since: 2.38 |
1639 | */ |
1640 | #define G_PRIVATE_FIELD(TypeName, inst, field_type, field_name) \ |
1641 | G_STRUCT_MEMBER (field_type, inst, G_PRIVATE_OFFSET (TypeName, field_name)) |
1642 | |
1643 | /* we need to have this macro under conditional expansion, as it references |
1644 | * a function that has been added in 2.38. see bug: |
1645 | * https://bugzilla.gnome.org/show_bug.cgi?id=703191 |
1646 | */ |
1647 | #if GLIB_VERSION_MAX_ALLOWED >= GLIB_VERSION_2_38 |
1648 | #define _G_DEFINE_TYPE_EXTENDED_CLASS_INIT(TypeName, type_name) \ |
1649 | static void type_name##_class_intern_init (gpointer klass) \ |
1650 | { \ |
1651 | type_name##_parent_class = g_type_class_peek_parent (klass); \ |
1652 | if (TypeName##_private_offset != 0) \ |
1653 | g_type_class_adjust_private_offset (klass, &TypeName##_private_offset); \ |
1654 | type_name##_class_init ((TypeName##Class*) klass); \ |
1655 | } |
1656 | |
1657 | #else |
1658 | #define _G_DEFINE_TYPE_EXTENDED_CLASS_INIT(TypeName, type_name) \ |
1659 | static void type_name##_class_intern_init (gpointer klass) \ |
1660 | { \ |
1661 | type_name##_parent_class = g_type_class_peek_parent (klass); \ |
1662 | type_name##_class_init ((TypeName##Class*) klass); \ |
1663 | } |
1664 | #endif /* GLIB_VERSION_MAX_ALLOWED >= GLIB_VERSION_2_38 */ |
1665 | |
1666 | #define _G_DEFINE_TYPE_EXTENDED_BEGIN(TypeName, type_name, TYPE_PARENT, flags) \ |
1667 | \ |
1668 | static void type_name##_init (TypeName *self); \ |
1669 | static void type_name##_class_init (TypeName##Class *klass); \ |
1670 | static gpointer type_name##_parent_class = NULL; \ |
1671 | static gint TypeName##_private_offset; \ |
1672 | \ |
1673 | _G_DEFINE_TYPE_EXTENDED_CLASS_INIT(TypeName, type_name) \ |
1674 | \ |
1675 | G_GNUC_UNUSED \ |
1676 | static inline gpointer \ |
1677 | type_name##_get_instance_private (TypeName *self) \ |
1678 | { \ |
1679 | return (G_STRUCT_MEMBER_P (self, TypeName##_private_offset)); \ |
1680 | } \ |
1681 | \ |
1682 | GType \ |
1683 | type_name##_get_type (void) \ |
1684 | { \ |
1685 | static volatile gsize g_define_type_id__volatile = 0; \ |
1686 | if (g_once_init_enter (&g_define_type_id__volatile)) \ |
1687 | { \ |
1688 | GType g_define_type_id = \ |
1689 | g_type_register_static_simple (TYPE_PARENT, \ |
1690 | g_intern_static_string (#TypeName), \ |
1691 | sizeof (TypeName##Class), \ |
1692 | (GClassInitFunc) type_name##_class_intern_init, \ |
1693 | sizeof (TypeName), \ |
1694 | (GInstanceInitFunc) type_name##_init, \ |
1695 | (GTypeFlags) flags); \ |
1696 | { /* custom code follows */ |
1697 | #define _G_DEFINE_TYPE_EXTENDED_END() \ |
1698 | /* following custom code */ \ |
1699 | } \ |
1700 | g_once_init_leave (&g_define_type_id__volatile, g_define_type_id); \ |
1701 | } \ |
1702 | return g_define_type_id__volatile; \ |
1703 | } /* closes type_name##_get_type() */ |
1704 | |
1705 | #define _G_DEFINE_INTERFACE_EXTENDED_BEGIN(TypeName, type_name, TYPE_PREREQ) \ |
1706 | \ |
1707 | static void type_name##_default_init (TypeName##Interface *klass); \ |
1708 | \ |
1709 | GType \ |
1710 | type_name##_get_type (void) \ |
1711 | { \ |
1712 | static volatile gsize g_define_type_id__volatile = 0; \ |
1713 | if (g_once_init_enter (&g_define_type_id__volatile)) \ |
1714 | { \ |
1715 | GType g_define_type_id = \ |
1716 | g_type_register_static_simple (G_TYPE_INTERFACE, \ |
1717 | g_intern_static_string (#TypeName), \ |
1718 | sizeof (TypeName##Interface), \ |
1719 | (GClassInitFunc)type_name##_default_init, \ |
1720 | 0, \ |
1721 | (GInstanceInitFunc)NULL, \ |
1722 | (GTypeFlags) 0); \ |
1723 | if (TYPE_PREREQ) \ |
1724 | g_type_interface_add_prerequisite (g_define_type_id, TYPE_PREREQ); \ |
1725 | { /* custom code follows */ |
1726 | #define _G_DEFINE_INTERFACE_EXTENDED_END() \ |
1727 | /* following custom code */ \ |
1728 | } \ |
1729 | g_once_init_leave (&g_define_type_id__volatile, g_define_type_id); \ |
1730 | } \ |
1731 | return g_define_type_id__volatile; \ |
1732 | } /* closes type_name##_get_type() */ |
1733 | |
1734 | /** |
1735 | * G_DEFINE_BOXED_TYPE: |
1736 | * @TypeName: The name of the new type, in Camel case. |
1737 | * @type_name: The name of the new type, in lowercase, with words |
1738 | * separated by '_'. |
1739 | * @copy_func: the #GBoxedCopyFunc for the new type |
1740 | * @free_func: the #GBoxedFreeFunc for the new type |
1741 | * |
1742 | * A convenience macro for boxed type implementations, which defines a |
1743 | * type_name_get_type() function registering the boxed type. |
1744 | * |
1745 | * Since: 2.26 |
1746 | */ |
1747 | #define G_DEFINE_BOXED_TYPE(TypeName, type_name, copy_func, free_func) G_DEFINE_BOXED_TYPE_WITH_CODE (TypeName, type_name, copy_func, free_func, {}) |
1748 | /** |
1749 | * G_DEFINE_BOXED_TYPE_WITH_CODE: |
1750 | * @TypeName: The name of the new type, in Camel case. |
1751 | * @type_name: The name of the new type, in lowercase, with words |
1752 | * separated by '_'. |
1753 | * @copy_func: the #GBoxedCopyFunc for the new type |
1754 | * @free_func: the #GBoxedFreeFunc for the new type |
1755 | * @_C_: Custom code that gets inserted in the *_get_type() function. |
1756 | * |
1757 | * A convenience macro for boxed type implementations. |
1758 | * Similar to G_DEFINE_BOXED_TYPE(), but allows to insert custom code into the |
1759 | * type_name_get_type() function, e.g. to register value transformations with |
1760 | * g_value_register_transform_func(). |
1761 | * |
1762 | * Since: 2.26 |
1763 | */ |
1764 | #define G_DEFINE_BOXED_TYPE_WITH_CODE(TypeName, type_name, copy_func, free_func, _C_) _G_DEFINE_BOXED_TYPE_BEGIN (TypeName, type_name, copy_func, free_func) {_C_;} _G_DEFINE_TYPE_EXTENDED_END() |
1765 | |
1766 | /* Only use this in non-C++ on GCC >= 2.7, except for Darwin/ppc64. |
1767 | * See https://bugzilla.gnome.org/show_bug.cgi?id=647145 |
1768 | */ |
1769 | #if !defined (__cplusplus) && (__GNUC__ > 2 || (__GNUC__ == 2 && __GNUC_MINOR__ >= 7)) && !(defined (__APPLE__) && defined (__ppc64__)) |
1770 | #define _G_DEFINE_BOXED_TYPE_BEGIN(TypeName, type_name, copy_func, free_func) \ |
1771 | GType \ |
1772 | type_name##_get_type (void) \ |
1773 | { \ |
1774 | static volatile gsize g_define_type_id__volatile = 0; \ |
1775 | if (g_once_init_enter (&g_define_type_id__volatile)) \ |
1776 | { \ |
1777 | GType (* _g_register_boxed) \ |
1778 | (const gchar *, \ |
1779 | union \ |
1780 | { \ |
1781 | TypeName * (*do_copy_type) (TypeName *); \ |
1782 | TypeName * (*do_const_copy_type) (const TypeName *); \ |
1783 | GBoxedCopyFunc do_copy_boxed; \ |
1784 | } __attribute__((__transparent_union__)), \ |
1785 | union \ |
1786 | { \ |
1787 | void (* do_free_type) (TypeName *); \ |
1788 | GBoxedFreeFunc do_free_boxed; \ |
1789 | } __attribute__((__transparent_union__)) \ |
1790 | ) = g_boxed_type_register_static; \ |
1791 | GType g_define_type_id = \ |
1792 | _g_register_boxed (g_intern_static_string (#TypeName), copy_func, free_func); \ |
1793 | { /* custom code follows */ |
1794 | #else |
1795 | #define _G_DEFINE_BOXED_TYPE_BEGIN(TypeName, type_name, copy_func, free_func) \ |
1796 | GType \ |
1797 | type_name##_get_type (void) \ |
1798 | { \ |
1799 | static volatile gsize g_define_type_id__volatile = 0; \ |
1800 | if (g_once_init_enter (&g_define_type_id__volatile)) \ |
1801 | { \ |
1802 | GType g_define_type_id = \ |
1803 | g_boxed_type_register_static (g_intern_static_string (#TypeName), \ |
1804 | (GBoxedCopyFunc) copy_func, \ |
1805 | (GBoxedFreeFunc) free_func); \ |
1806 | { /* custom code follows */ |
1807 | #endif /* __GNUC__ */ |
1808 | |
1809 | /** |
1810 | * G_DEFINE_POINTER_TYPE: |
1811 | * @TypeName: The name of the new type, in Camel case. |
1812 | * @type_name: The name of the new type, in lowercase, with words |
1813 | * separated by '_'. |
1814 | * |
1815 | * A convenience macro for pointer type implementations, which defines a |
1816 | * type_name_get_type() function registering the pointer type. |
1817 | * |
1818 | * Since: 2.26 |
1819 | */ |
1820 | #define G_DEFINE_POINTER_TYPE(TypeName, type_name) G_DEFINE_POINTER_TYPE_WITH_CODE (TypeName, type_name, {}) |
1821 | /** |
1822 | * G_DEFINE_POINTER_TYPE_WITH_CODE: |
1823 | * @TypeName: The name of the new type, in Camel case. |
1824 | * @type_name: The name of the new type, in lowercase, with words |
1825 | * separated by '_'. |
1826 | * @_C_: Custom code that gets inserted in the *_get_type() function. |
1827 | * |
1828 | * A convenience macro for pointer type implementations. |
1829 | * Similar to G_DEFINE_POINTER_TYPE(), but allows to insert custom code into the |
1830 | * type_name_get_type() function. |
1831 | * |
1832 | * Since: 2.26 |
1833 | */ |
1834 | #define G_DEFINE_POINTER_TYPE_WITH_CODE(TypeName, type_name, _C_) _G_DEFINE_POINTER_TYPE_BEGIN (TypeName, type_name) {_C_;} _G_DEFINE_TYPE_EXTENDED_END() |
1835 | |
1836 | #define _G_DEFINE_POINTER_TYPE_BEGIN(TypeName, type_name) \ |
1837 | GType \ |
1838 | type_name##_get_type (void) \ |
1839 | { \ |
1840 | static volatile gsize g_define_type_id__volatile = 0; \ |
1841 | if (g_once_init_enter (&g_define_type_id__volatile)) \ |
1842 | { \ |
1843 | GType g_define_type_id = \ |
1844 | g_pointer_type_register_static (g_intern_static_string (#TypeName)); \ |
1845 | { /* custom code follows */ |
1846 | |
1847 | /* --- protected (for fundamental type implementations) --- */ |
1848 | GLIB_AVAILABLE_IN_ALL |
1849 | GTypePlugin* g_type_get_plugin (GType type); |
1850 | GLIB_AVAILABLE_IN_ALL |
1851 | GTypePlugin* g_type_interface_get_plugin (GType instance_type, |
1852 | GType interface_type); |
1853 | GLIB_AVAILABLE_IN_ALL |
1854 | GType g_type_fundamental_next (void); |
1855 | GLIB_AVAILABLE_IN_ALL |
1856 | GType g_type_fundamental (GType type_id); |
1857 | GLIB_AVAILABLE_IN_ALL |
1858 | GTypeInstance* g_type_create_instance (GType type); |
1859 | GLIB_AVAILABLE_IN_ALL |
1860 | void g_type_free_instance (GTypeInstance *instance); |
1861 | |
1862 | GLIB_AVAILABLE_IN_ALL |
1863 | void g_type_add_class_cache_func (gpointer cache_data, |
1864 | GTypeClassCacheFunc cache_func); |
1865 | GLIB_AVAILABLE_IN_ALL |
1866 | void g_type_remove_class_cache_func (gpointer cache_data, |
1867 | GTypeClassCacheFunc cache_func); |
1868 | GLIB_AVAILABLE_IN_ALL |
1869 | void g_type_class_unref_uncached (gpointer g_class); |
1870 | |
1871 | GLIB_AVAILABLE_IN_ALL |
1872 | void g_type_add_interface_check (gpointer check_data, |
1873 | GTypeInterfaceCheckFunc check_func); |
1874 | GLIB_AVAILABLE_IN_ALL |
1875 | void g_type_remove_interface_check (gpointer check_data, |
1876 | GTypeInterfaceCheckFunc check_func); |
1877 | |
1878 | GLIB_AVAILABLE_IN_ALL |
1879 | GTypeValueTable* g_type_value_table_peek (GType type); |
1880 | |
1881 | |
1882 | /*< private >*/ |
1883 | GLIB_AVAILABLE_IN_ALL |
1884 | gboolean g_type_check_instance (GTypeInstance *instance) G_GNUC_PURE; |
1885 | GLIB_AVAILABLE_IN_ALL |
1886 | GTypeInstance* g_type_check_instance_cast (GTypeInstance *instance, |
1887 | GType iface_type); |
1888 | GLIB_AVAILABLE_IN_ALL |
1889 | gboolean g_type_check_instance_is_a (GTypeInstance *instance, |
1890 | GType iface_type) G_GNUC_PURE; |
1891 | GLIB_AVAILABLE_IN_ALL |
1892 | GTypeClass* g_type_check_class_cast (GTypeClass *g_class, |
1893 | GType is_a_type); |
1894 | GLIB_AVAILABLE_IN_ALL |
1895 | gboolean g_type_check_class_is_a (GTypeClass *g_class, |
1896 | GType is_a_type) G_GNUC_PURE; |
1897 | GLIB_AVAILABLE_IN_ALL |
1898 | gboolean g_type_check_is_value_type (GType type) G_GNUC_CONST; |
1899 | GLIB_AVAILABLE_IN_ALL |
1900 | gboolean g_type_check_value (GValue *value) G_GNUC_PURE; |
1901 | GLIB_AVAILABLE_IN_ALL |
1902 | gboolean g_type_check_value_holds (GValue *value, |
1903 | GType type) G_GNUC_PURE; |
1904 | GLIB_AVAILABLE_IN_ALL |
1905 | gboolean g_type_test_flags (GType type, |
1906 | guint flags) G_GNUC_CONST; |
1907 | |
1908 | |
1909 | /* --- debugging functions --- */ |
1910 | GLIB_AVAILABLE_IN_ALL |
1911 | const gchar * g_type_name_from_instance (GTypeInstance *instance); |
1912 | GLIB_AVAILABLE_IN_ALL |
1913 | const gchar * g_type_name_from_class (GTypeClass *g_class); |
1914 | |
1915 | |
1916 | /* --- implementation bits --- */ |
1917 | #ifndef G_DISABLE_CAST_CHECKS |
1918 | # define _G_TYPE_CIC(ip, gt, ct) \ |
1919 | ((ct*) g_type_check_instance_cast ((GTypeInstance*) ip, gt)) |
1920 | # define _G_TYPE_CCC(cp, gt, ct) \ |
1921 | ((ct*) g_type_check_class_cast ((GTypeClass*) cp, gt)) |
1922 | #else /* G_DISABLE_CAST_CHECKS */ |
1923 | # define _G_TYPE_CIC(ip, gt, ct) ((ct*) ip) |
1924 | # define _G_TYPE_CCC(cp, gt, ct) ((ct*) cp) |
1925 | #endif /* G_DISABLE_CAST_CHECKS */ |
1926 | #define _G_TYPE_CHI(ip) (g_type_check_instance ((GTypeInstance*) ip)) |
1927 | #define _G_TYPE_CHV(vl) (g_type_check_value ((GValue*) vl)) |
1928 | #define _G_TYPE_IGC(ip, gt, ct) ((ct*) (((GTypeInstance*) ip)->g_class)) |
1929 | #define _G_TYPE_IGI(ip, gt, ct) ((ct*) g_type_interface_peek (((GTypeInstance*) ip)->g_class, gt)) |
1930 | #ifdef __GNUC__ |
1931 | # define _G_TYPE_CIT(ip, gt) (G_GNUC_EXTENSION ({ \ |
1932 | GTypeInstance *__inst = (GTypeInstance*) ip; GType __t = gt; gboolean __r; \ |
1933 | if (!__inst) \ |
1934 | __r = FALSE; \ |
1935 | else if (__inst->g_class && __inst->g_class->g_type == __t) \ |
1936 | __r = TRUE; \ |
1937 | else \ |
1938 | __r = g_type_check_instance_is_a (__inst, __t); \ |
1939 | __r; \ |
1940 | })) |
1941 | # define _G_TYPE_CCT(cp, gt) (G_GNUC_EXTENSION ({ \ |
1942 | GTypeClass *__class = (GTypeClass*) cp; GType __t = gt; gboolean __r; \ |
1943 | if (!__class) \ |
1944 | __r = FALSE; \ |
1945 | else if (__class->g_type == __t) \ |
1946 | __r = TRUE; \ |
1947 | else \ |
1948 | __r = g_type_check_class_is_a (__class, __t); \ |
1949 | __r; \ |
1950 | })) |
1951 | # define _G_TYPE_CVH(vl, gt) (G_GNUC_EXTENSION ({ \ |
1952 | GValue *__val = (GValue*) vl; GType __t = gt; gboolean __r; \ |
1953 | if (!__val) \ |
1954 | __r = FALSE; \ |
1955 | else if (__val->g_type == __t) \ |
1956 | __r = TRUE; \ |
1957 | else \ |
1958 | __r = g_type_check_value_holds (__val, __t); \ |
1959 | __r; \ |
1960 | })) |
1961 | #else /* !__GNUC__ */ |
1962 | # define _G_TYPE_CIT(ip, gt) (g_type_check_instance_is_a ((GTypeInstance*) ip, gt)) |
1963 | # define _G_TYPE_CCT(cp, gt) (g_type_check_class_is_a ((GTypeClass*) cp, gt)) |
1964 | # define _G_TYPE_CVH(vl, gt) (g_type_check_value_holds ((GValue*) vl, gt)) |
1965 | #endif /* !__GNUC__ */ |
1966 | /** |
1967 | * G_TYPE_FLAG_RESERVED_ID_BIT: |
1968 | * |
1969 | * A bit in the type number that's supposed to be left untouched. |
1970 | */ |
1971 | #define G_TYPE_FLAG_RESERVED_ID_BIT ((GType) (1 << 0)) |
1972 | extern GTypeDebugFlags _g_type_debug_flags; |
1973 | |
1974 | G_END_DECLS |
1975 | |
1976 | #endif /* __G_TYPE_H__ */ |
1977 | |