30
30
/* Basic Type Macros
34
* @type: A #GType value.
36
* The fundamental type which is the ancestor of @type.
37
* Fundamental types are types that serve as ultimate bases for the derived types,
38
* thus they are the roots of distinct inheritance hierarchies.
32
40
#define G_TYPE_FUNDAMENTAL(type) (g_type_fundamental (type))
42
* G_TYPE_FUNDAMENTAL_MAX:
44
* An integer constant that represents the number of identifiers reserved
45
* for types that are assigned at compile-time.
33
47
#define G_TYPE_FUNDAMENTAL_MAX (255 << G_TYPE_FUNDAMENTAL_SHIFT)
35
49
/* Constant fundamental types,
36
50
* introduced by g_type_init().
55
* An invalid #GType used as error return value in some functions which return
38
58
#define G_TYPE_INVALID G_TYPE_MAKE_FUNDAMENTAL (0)
62
* A fundamental type which is used as a replacement for the C
63
* <literal>void</literal> return type.
39
65
#define G_TYPE_NONE G_TYPE_MAKE_FUNDAMENTAL (1)
69
* The fundamental type from which all interfaces are derived.
40
71
#define G_TYPE_INTERFACE G_TYPE_MAKE_FUNDAMENTAL (2)
75
* The fundamental type corresponding to #gchar.
76
* The type designated by G_TYPE_CHAR is unconditionally an 8-bit signed integer.
77
* This may or may not be the same type a the C type "gchar".
41
79
#define G_TYPE_CHAR G_TYPE_MAKE_FUNDAMENTAL (3)
83
* The fundamental type corresponding to #guchar.
42
85
#define G_TYPE_UCHAR G_TYPE_MAKE_FUNDAMENTAL (4)
89
* The fundamental type corresponding to #gboolean.
43
91
#define G_TYPE_BOOLEAN G_TYPE_MAKE_FUNDAMENTAL (5)
95
* The fundamental type corresponding to #gint.
44
97
#define G_TYPE_INT G_TYPE_MAKE_FUNDAMENTAL (6)
101
* The fundamental type corresponding to #guint.
45
103
#define G_TYPE_UINT G_TYPE_MAKE_FUNDAMENTAL (7)
107
* The fundamental type corresponding to #glong.
46
109
#define G_TYPE_LONG G_TYPE_MAKE_FUNDAMENTAL (8)
113
* The fundamental type corresponding to #gulong.
47
115
#define G_TYPE_ULONG G_TYPE_MAKE_FUNDAMENTAL (9)
119
* The fundamental type corresponding to #gint64.
48
121
#define G_TYPE_INT64 G_TYPE_MAKE_FUNDAMENTAL (10)
125
* The fundamental type corresponding to #guint64.
49
127
#define G_TYPE_UINT64 G_TYPE_MAKE_FUNDAMENTAL (11)
131
* The fundamental type from which all enumeration types are derived.
50
133
#define G_TYPE_ENUM G_TYPE_MAKE_FUNDAMENTAL (12)
137
* The fundamental type from which all flags types are derived.
51
139
#define G_TYPE_FLAGS G_TYPE_MAKE_FUNDAMENTAL (13)
143
* The fundamental type corresponding to #gfloat.
52
145
#define G_TYPE_FLOAT G_TYPE_MAKE_FUNDAMENTAL (14)
149
* The fundamental type corresponding to #gdouble.
53
151
#define G_TYPE_DOUBLE G_TYPE_MAKE_FUNDAMENTAL (15)
155
* The fundamental type corresponding to nul-terminated C strings.
54
157
#define G_TYPE_STRING G_TYPE_MAKE_FUNDAMENTAL (16)
161
* The fundamental type corresponding to #gpointer.
55
163
#define G_TYPE_POINTER G_TYPE_MAKE_FUNDAMENTAL (17)
167
* The fundamental type from which all boxed types are derived.
56
169
#define G_TYPE_BOXED G_TYPE_MAKE_FUNDAMENTAL (18)
173
* The fundamental type from which all #GParamSpec types are derived.
57
175
#define G_TYPE_PARAM G_TYPE_MAKE_FUNDAMENTAL (19)
179
* The fundamental type for #GObject.
58
181
#define G_TYPE_OBJECT G_TYPE_MAKE_FUNDAMENTAL (20)
61
184
/* Reserved fundamental type numbers to create new fundamental
62
185
* type IDs with G_TYPE_MAKE_FUNDAMENTAL().
63
* Send email to gtk-devel-list@redhat.com for reservations.
186
* Send email to gtk-devel-list@gnome.org for reservations.
189
* G_TYPE_FUNDAMENTAL_SHIFT:
191
* Shift value used in converting numbers to type IDs.
65
193
#define G_TYPE_FUNDAMENTAL_SHIFT (2)
195
* G_TYPE_MAKE_FUNDAMENTAL:
196
* @x: the fundamental type number.
198
* Get the type ID for the fundamental type number @x.
199
* Use g_type_fundamental_next() instead of this macro to create new fundamental
66
204
#define G_TYPE_MAKE_FUNDAMENTAL(x) ((GType) ((x) << G_TYPE_FUNDAMENTAL_SHIFT))
206
* G_TYPE_RESERVED_GLIB_FIRST:
208
* First fundamental type number to create a new fundamental type id with
209
* G_TYPE_MAKE_FUNDAMENTAL() reserved for GLib.
67
211
#define G_TYPE_RESERVED_GLIB_FIRST (21)
213
* G_TYPE_RESERVED_GLIB_LAST:
215
* Last fundamental type number reserved for GLib.
68
217
#define G_TYPE_RESERVED_GLIB_LAST (31)
219
* G_TYPE_RESERVED_BSE_FIRST:
221
* First fundamental type number to create a new fundamental type id with
222
* G_TYPE_MAKE_FUNDAMENTAL() reserved for BSE.
69
224
#define G_TYPE_RESERVED_BSE_FIRST (32)
226
* G_TYPE_RESERVED_BSE_LAST:
228
* Last fundamental type number reserved for BSE.
70
230
#define G_TYPE_RESERVED_BSE_LAST (48)
232
* G_TYPE_RESERVED_USER_FIRST:
234
* First available fundamental type number to create new fundamental
235
* type id with G_TYPE_MAKE_FUNDAMENTAL().
71
237
#define G_TYPE_RESERVED_USER_FIRST (49)
74
240
/* Type Checking Macros
243
* G_TYPE_IS_FUNDAMENTAL:
244
* @type: A #GType value.
246
* Checks if @type is a fundamental type.
248
* Returns: %TRUE on success.
76
250
#define G_TYPE_IS_FUNDAMENTAL(type) ((type) <= G_TYPE_FUNDAMENTAL_MAX)
253
* @type: A #GType value.
255
* Checks if @type is derived (or in object-oriented terminology:
256
* inherited) from another type (this holds true for all non-fundamental
259
* Returns: %TRUE on success.
77
261
#define G_TYPE_IS_DERIVED(type) ((type) > G_TYPE_FUNDAMENTAL_MAX)
263
* G_TYPE_IS_INTERFACE:
264
* @type: A #GType value.
266
* Checks if @type is an interface type.
267
* An interface type provides a pure API, the implementation
268
* of which is provided by another type (which is then said to conform
269
* to the interface). GLib interfaces are somewhat analogous to Java
270
* interfaces and C++ classes containing only pure virtual functions,
271
* with the difference that GType interfaces are not derivable (but see
272
* g_type_interface_add_prerequisite() for an alternative).
274
* Returns: %TRUE on success.
78
276
#define G_TYPE_IS_INTERFACE(type) (G_TYPE_FUNDAMENTAL (type) == G_TYPE_INTERFACE)
279
* @type: A #GType value.
281
* Checks if @type is a classed type.
283
* Returns: %TRUE on success.
79
285
#define G_TYPE_IS_CLASSED(type) (g_type_test_flags ((type), G_TYPE_FLAG_CLASSED))
287
* G_TYPE_IS_INSTANTIATABLE:
288
* @type: A #GType value.
290
* Checks if @type can be instantiated. Instantiation is the
291
* process of creating an instance (object) of this type.
293
* Returns: %TRUE on success.
80
295
#define G_TYPE_IS_INSTANTIATABLE(type) (g_type_test_flags ((type), G_TYPE_FLAG_INSTANTIATABLE))
297
* G_TYPE_IS_DERIVABLE:
298
* @type: A #GType value.
300
* Checks if @type is a derivable type. A derivable type can
301
* be used as the base class of a flat (single-level) class hierarchy.
303
* Returns: %TRUE on success.
81
305
#define G_TYPE_IS_DERIVABLE(type) (g_type_test_flags ((type), G_TYPE_FLAG_DERIVABLE))
307
* G_TYPE_IS_DEEP_DERIVABLE:
308
* @type: A #GType value.
310
* Checks if @type is a deep derivable type. A deep derivable type
311
* can be used as the base class of a deep (multi-level) class hierarchy.
313
* Returns: %TRUE on success.
82
315
#define G_TYPE_IS_DEEP_DERIVABLE(type) (g_type_test_flags ((type), G_TYPE_FLAG_DEEP_DERIVABLE))
317
* G_TYPE_IS_ABSTRACT:
318
* @type: A #GType value.
320
* Checks if @type is an abstract type. An abstract type can not be
321
* instantiated and is normally used as an abstract base class for
324
* Returns: %TRUE on success.
83
326
#define G_TYPE_IS_ABSTRACT(type) (g_type_test_flags ((type), G_TYPE_FLAG_ABSTRACT))
328
* G_TYPE_IS_VALUE_ABSTRACT:
329
* @type: A #GType value.
331
* Checks if @type is an abstract value type. An abstract value type introduces
332
* a value table, but can't be used for g_value_init() and is normally used as
333
* an abstract base type for derived value types.
335
* Returns: %TRUE on success.
84
337
#define G_TYPE_IS_VALUE_ABSTRACT(type) (g_type_test_flags ((type), G_TYPE_FLAG_VALUE_ABSTRACT))
339
* G_TYPE_IS_VALUE_TYPE:
340
* @type: A #GType value.
342
* Checks if @type is a value type and can be used with g_value_init().
344
* Returns: %TRUE on success.
85
346
#define G_TYPE_IS_VALUE_TYPE(type) (g_type_check_is_value_type (type))
348
* G_TYPE_HAS_VALUE_TABLE:
349
* @type: A #GType value.
351
* Checks if @type has a #GTypeValueTable.
353
* Returns: %TRUE on success.
86
355
#define G_TYPE_HAS_VALUE_TABLE(type) (g_type_value_table_peek (type) != NULL)
363
* A numerical value which represents the unique identifier of a registered
91
366
#if GLIB_SIZEOF_SIZE_T != GLIB_SIZEOF_LONG || !defined __cplusplus
92
367
typedef gsize GType;
93
368
#else /* for historic reasons, C++ links against gulong GTypes */
137
437
* usage of these macros is reserved to type implementations only
139
439
/*< protected >*/
441
* G_TYPE_CHECK_INSTANCE:
442
* @instance: Location of a #GTypeInstance structure.
444
* Checks if @instance is a valid #GTypeInstance structure,
445
* otherwise issues a warning and returns %FALSE.
447
* This macro should only be used in type implementations.
449
* Returns: %TRUE on success.
140
451
#define G_TYPE_CHECK_INSTANCE(instance) (_G_TYPE_CHI ((GTypeInstance*) (instance)))
453
* G_TYPE_CHECK_INSTANCE_CAST:
454
* @instance: Location of a #GTypeInstance structure.
455
* @g_type: The type to be returned.
456
* @c_type: The corresponding C type of @g_type.
458
* Checks that @instance is an instance of the type identified by @g_type
459
* and issues a warning if this is not the case. Returns @instance casted
460
* to a pointer to @c_type.
462
* This macro should only be used in type implementations.
141
464
#define G_TYPE_CHECK_INSTANCE_CAST(instance, g_type, c_type) (_G_TYPE_CIC ((instance), (g_type), c_type))
466
* G_TYPE_CHECK_INSTANCE_TYPE:
467
* @instance: Location of a #GTypeInstance structure.
468
* @g_type: The type to be checked
470
* Checks if @instance is an instance of the type identified by @g_type.
472
* This macro should only be used in type implementations.
474
* Returns: %TRUE on success.
142
476
#define G_TYPE_CHECK_INSTANCE_TYPE(instance, g_type) (_G_TYPE_CIT ((instance), (g_type)))
478
* G_TYPE_INSTANCE_GET_CLASS:
479
* @instance: Location of the #GTypeInstance structure.
480
* @g_type: The #GType of the class to be returned.
481
* @c_type: The C type of the class structure.
483
* Get the class structure of a given @instance, casted
484
* to a specified ancestor type @g_type of the instance.
486
* Note that while calling a GInstanceInitFunc(), the class pointer gets
487
* modified, so it might not always return the expected pointer.
489
* This macro should only be used in type implementations.
491
* Returns: a pointer to the class structure
143
493
#define G_TYPE_INSTANCE_GET_CLASS(instance, g_type, c_type) (_G_TYPE_IGC ((instance), (g_type), c_type))
495
* G_TYPE_INSTANCE_GET_INTERFACE:
496
* @instance: Location of the #GTypeInstance structure.
497
* @g_type: The #GType of the interface to be returned.
498
* @c_type: The C type of the interface structure.
500
* Get the interface structure for interface @g_type of a given @instance.
502
* This macro should only be used in type implementations.
504
* Returns: a pointer to the interface structure
144
506
#define G_TYPE_INSTANCE_GET_INTERFACE(instance, g_type, c_type) (_G_TYPE_IGI ((instance), (g_type), c_type))
508
* G_TYPE_CHECK_CLASS_CAST:
509
* @g_class: Location of a #GTypeClass structure.
510
* @g_type: The type to be returned.
511
* @c_type: The corresponding C type of class structure of @g_type.
513
* Checks that @g_class is a class structure of the type identified by @g_type
514
* and issues a warning if this is not the case. Returns @g_class casted
515
* to a pointer to @c_type.
517
* This macro should only be used in type implementations.
145
519
#define G_TYPE_CHECK_CLASS_CAST(g_class, g_type, c_type) (_G_TYPE_CCC ((g_class), (g_type), c_type))
521
* G_TYPE_CHECK_CLASS_TYPE:
522
* @g_class: Location of a #GTypeClass structure.
523
* @g_type: The type to be checked.
525
* Checks if @g_class is a class structure of the type identified by
528
* This macro should only be used in type implementations.
530
* Returns: %TRUE on success.
146
532
#define G_TYPE_CHECK_CLASS_TYPE(g_class, g_type) (_G_TYPE_CCT ((g_class), (g_type)))
534
* G_TYPE_CHECK_VALUE:
537
* Checks if @value has been initialized to hold values
540
* This macro should only be used in type implementations.
542
* Returns: %TRUE on success.
147
544
#define G_TYPE_CHECK_VALUE(value) (_G_TYPE_CHV ((value)))
546
* G_TYPE_CHECK_VALUE_TYPE:
548
* @g_type: The type to be checked.
550
* Checks if @value has been initialized to hold values
553
* This macro should only be used in type implementations.
555
* Returns: %TRUE on success.
148
557
#define G_TYPE_CHECK_VALUE_TYPE(value, g_type) (_G_TYPE_CVH ((value), (g_type)))
559
* G_TYPE_FROM_INSTANCE:
560
* @instance: Location of a valid #GTypeInstance structure.
562
* Get the type identifier from a given @instance structure.
564
* This macro should only be used in type implementations.
566
* Returns: the #GType
149
568
#define G_TYPE_FROM_INSTANCE(instance) (G_TYPE_FROM_CLASS (((GTypeInstance*) (instance))->g_class))
571
* @g_class: Location of a valid #GTypeClass structure.
573
* Get the type identifier from a given @class structure.
575
* This macro should only be used in type implementations.
577
* Returns: the #GType
150
579
#define G_TYPE_FROM_CLASS(g_class) (((GTypeClass*) (g_class))->g_type)
581
* G_TYPE_FROM_INTERFACE:
582
* @g_iface: Location of a valid #GTypeInterface structure.
584
* Get the type identifier from a given @interface structure.
586
* This macro should only be used in type implementations.
588
* Returns: the #GType
151
590
#define G_TYPE_FROM_INTERFACE(g_iface) (((GTypeInterface*) (g_iface))->g_type)
593
* G_TYPE_INSTANCE_GET_PRIVATE:
594
* @instance: the instance of a type deriving from @private_type.
595
* @g_type: the type identifying which private data to retrieve.
596
* @c_type: The C type for the private structure.
598
* Gets the private structure for a particular type.
599
* The private structure must have been registered in the
600
* class_init function with g_type_class_add_private().
602
* This macro should only be used in type implementations.
605
* Returns: a pointer to the private data structure.
153
607
#define G_TYPE_INSTANCE_GET_PRIVATE(instance, g_type, c_type) ((c_type*) g_type_instance_get_private ((GTypeInstance*) (instance), (g_type)))
156
/* debug flags for g_type_init_with_debug_flags() */
612
* @G_TYPE_DEBUG_NONE: Print no messages.
613
* @G_TYPE_DEBUG_OBJECTS: Print messages about object bookkeeping.
614
* @G_TYPE_DEBUG_SIGNALS: Print messages about signal emissions.
615
* @G_TYPE_DEBUG_MASK: Mask covering all debug flags.
617
* The <type>GTypeDebugFlags</type> enumeration values can be passed to
618
* g_type_init_with_debug_flags() to trigger debugging messages during runtime.
619
* Note that the messages can also be triggered by setting the
620
* <envar>GOBJECT_DEBUG</envar> environment variable to a ':'-separated list of
621
* "objects" and "signals".
157
623
typedef enum /*< skip >*/
159
625
G_TYPE_DEBUG_NONE = 0,
207
673
/* --- type registration --- */
676
* @g_class: The #GTypeClass structure to initialize.
678
* A callback function used by the type system to do base initialization
679
* of the class structures of derived types. It is called as part of the
680
* initialization process of all derived classes and should reallocate
681
* or reset all dynamic class members copied over from the parent class.
682
* For example, class members (such as strings) that are not sufficiently
683
* handled by a plain memory copy of the parent class into the derived class
684
* have to be altered. See GClassInitFunc() for a discussion of the class
685
* intialization process.
208
687
typedef void (*GBaseInitFunc) (gpointer g_class);
690
* @g_class: The #GTypeClass structure to finalize.
692
* A callback function used by the type system to finalize those portions
693
* of a derived types class structure that were setup from the corresponding
694
* GBaseInitFunc() function. Class finalization basically works the inverse
695
* way in which class intialization is performed.
696
* See GClassInitFunc() for a discussion of the class intialization process.
209
698
typedef void (*GBaseFinalizeFunc) (gpointer g_class);
701
* @g_class: The #GTypeClass structure to initialize.
702
* @class_data: The @class_data member supplied via the #GTypeInfo structure.
704
* A callback function used by the type system to initialize the class
705
* of a specific type. This function should initialize all static class
707
* The initialization process of a class involves:
710
* 1 - Copying common members from the parent class over to the
711
* derived class structure.
714
* 2 - Zero initialization of the remaining members not copied
715
* over from the parent class.
718
* 3 - Invocation of the GBaseInitFunc() initializers of all parent
719
* types and the class' type.
722
* 4 - Invocation of the class' GClassInitFunc() initializer.
725
* Since derived classes are partially initialized through a memory copy
726
* of the parent class, the general rule is that GBaseInitFunc() and
727
* GBaseFinalizeFunc() should take care of necessary reinitialization
728
* and release of those class members that were introduced by the type
729
* that specified these GBaseInitFunc()/GBaseFinalizeFunc().
730
* GClassInitFunc() should only care about initializing static
731
* class members, while dynamic class members (such as allocated strings
732
* or reference counted resources) are better handled by a GBaseInitFunc()
733
* for this type, so proper initialization of the dynamic class members
734
* is performed for class initialization of derived types as well.
735
* An example may help to correspond the intend of the different class
740
* GObjectClass parent_class;
741
* gint static_integer;
742
* gchar *dynamic_string;
745
* type_a_base_class_init (TypeAClass *class)
747
* class->dynamic_string = g_strdup ("some string");
750
* type_a_base_class_finalize (TypeAClass *class)
752
* g_free (class->dynamic_string);
755
* type_a_class_init (TypeAClass *class)
757
* class->static_integer = 42;
761
* TypeAClass parent_class;
762
* gfloat static_float;
763
* GString *dynamic_gstring;
766
* type_b_base_class_init (TypeBClass *class)
768
* class->dynamic_gstring = g_string_new ("some other string");
771
* type_b_base_class_finalize (TypeBClass *class)
773
* g_string_free (class->dynamic_gstring);
776
* type_b_class_init (TypeBClass *class)
778
* class->static_float = 3.14159265358979323846;
781
* Initialization of TypeBClass will first cause initialization of
782
* TypeAClass (derived classes reference their parent classes, see
783
* g_type_class_ref() on this).
784
* Initialization of TypeAClass roughly involves zero-initializing its fields,
785
* then calling its GBaseInitFunc() type_a_base_class_init() to allocate
786
* its dynamic members (dynamic_string), and finally calling its GClassInitFunc()
787
* type_a_class_init() to initialize its static members (static_integer).
788
* The first step in the initialization process of TypeBClass is then
789
* a plain memory copy of the contents of TypeAClass into TypeBClass and
790
* zero-initialization of the remaining fields in TypeBClass.
791
* The dynamic members of TypeAClass within TypeBClass now need
792
* reinitialization which is performed by calling type_a_base_class_init()
793
* with an argument of TypeBClass.
794
* After that, the GBaseInitFunc() of TypeBClass, type_b_base_class_init()
795
* is called to allocate the dynamic members of TypeBClass (dynamic_gstring),
796
* and finally the GClassInitFunc() of TypeBClass, type_b_class_init(),
797
* is called to complete the initialization process with the static members
799
* Corresponding finalization counter parts to the GBaseInitFunc() functions
800
* have to be provided to release allocated resources at class finalization
210
803
typedef void (*GClassInitFunc) (gpointer g_class,
211
804
gpointer class_data);
806
* GClassFinalizeFunc:
807
* @g_class: The #GTypeClass structure to finalize.
808
* @class_data: The @class_data member supplied via the #GTypeInfo structure.
810
* A callback function used by the type system to finalize a class.
811
* This function is rarely needed, as dynamically allocated class resources
812
* should be handled by GBaseInitFunc() and GBaseFinalizeFunc().
813
* Also, specification of a GClassFinalizeFunc() in the #GTypeInfo
814
* structure of a static type is invalid, because classes of static types
815
* will never be finalized (they are artificially kept alive when their
816
* reference count drops to zero).
212
818
typedef void (*GClassFinalizeFunc) (gpointer g_class,
213
819
gpointer class_data);
822
* @instance: The instance to initialize.
823
* @g_class: The class of the type the instance is created for.
825
* A callback function used by the type system to initialize a new
826
* instance of a type. This function initializes all instance members and
827
* allocates any resources required by it.
828
* Initialization of a derived instance involves calling all its parent
829
* types instance initializers, so the class member of the instance
830
* is altered during its initialization to always point to the class that
831
* belongs to the type the current initializer was introduced for.
214
833
typedef void (*GInstanceInitFunc) (GTypeInstance *instance,
215
834
gpointer g_class);
836
* GInterfaceInitFunc:
837
* @g_iface: The interface structure to initialize.
838
* @iface_data: The @interface_data supplied via the #GInterfaceInfo structure.
840
* A callback function used by the type system to initialize a new
841
* interface. This function should initialize all internal data and
842
* allocate any resources required by the interface.
216
844
typedef void (*GInterfaceInitFunc) (gpointer g_iface,
217
845
gpointer iface_data);
847
* GInterfaceFinalizeFunc:
848
* @g_iface: The interface structure to finalize.
849
* @iface_data: The @interface_data supplied via the #GInterfaceInfo structure.
851
* A callback function used by the type system to finalize an interface.
852
* This function should destroy any internal data and release any resources
853
* allocated by the corresponding GInterfaceInitFunc() function.
218
855
typedef void (*GInterfaceFinalizeFunc) (gpointer g_iface,
219
856
gpointer iface_data);
858
* GTypeClassCacheFunc:
859
* @cache_data: data that was given to the g_type_add_class_cache_func() call
860
* @g_class: The #GTypeClass structure which is unreferenced
862
* A callback function which is called when the reference count of a class
863
* drops to zero. It may use g_type_class_ref() to prevent the class from
864
* being freed. You should not call g_type_class_unref() from a
865
* #GTypeClassCacheFunc function to prevent infinite recursion, use
866
* g_type_class_unref_uncached() instead.
868
* The functions have to check the class id passed in to figure
869
* whether they actually want to cache the class of this type, since all
870
* classes are routed through the same #GTypeClassCacheFunc chain.
872
* Returns: %TRUE to stop further #GTypeClassCacheFunc<!-- -->s from being
873
* called, %FALSE to continue.
220
875
typedef gboolean (*GTypeClassCacheFunc) (gpointer cache_data,
221
876
GTypeClass *g_class);
878
* GTypeInterfaceCheckFunc:
879
* @check_data: data passed to g_type_add_interface_check().
880
* @g_iface: the interface that has been initialized
882
* A callback called after an interface vtable is initialized.
883
* See g_type_add_interface_check().
222
887
typedef void (*GTypeInterfaceCheckFunc) (gpointer check_data,
223
888
gpointer g_iface);
890
* GTypeFundamentalFlags:
891
* @G_TYPE_FLAG_CLASSED: Indicates a classed type.
892
* @G_TYPE_FLAG_INSTANTIATABLE: Indicates an instantiable type (implies classed).
893
* @G_TYPE_FLAG_DERIVABLE: Indicates a flat derivable type.
894
* @G_TYPE_FLAG_DEEP_DERIVABLE: Indicates a deep derivable type (implies derivable).
896
* Bit masks used to check or determine specific characteristics of a
224
899
typedef enum /*< skip >*/
226
901
G_TYPE_FLAG_CLASSED = (1 << 0),
228
903
G_TYPE_FLAG_DERIVABLE = (1 << 2),
229
904
G_TYPE_FLAG_DEEP_DERIVABLE = (1 << 3)
230
905
} GTypeFundamentalFlags;
908
* @G_TYPE_FLAG_ABSTRACT: Indicates an abstract type. No instances can be
909
* created for an abstract type.
910
* @G_TYPE_FLAG_VALUE_ABSTRACT: Indicates an abstract value type, i.e. a type
911
* that introduces a value table, but can't be used for
914
* Bit masks used to check or determine characteristics of a type.
231
916
typedef enum /*< skip >*/
233
918
G_TYPE_FLAG_ABSTRACT = (1 << 4),
234
919
G_TYPE_FLAG_VALUE_ABSTRACT = (1 << 5)
923
* @class_size: Size of the class structure (required for interface, classed and instantiatable types).
924
* @base_init: Location of the base initialization function (optional).
925
* @base_finalize: Location of the base finalization function (optional).
926
* @class_init: Location of the class initialization function for
927
* classed and instantiatable types. Location of the default vtable
928
* inititalization function for interface types. (optional) This function
929
* is used both to fill in virtual functions in the class or default vtable,
930
* and to do type-specific setup such as registering signals and object
932
* @class_finalize: Location of the class finalization function for
933
* classed and instantiatable types. Location fo the default vtable
934
* finalization function for interface types. (optional)
935
* @class_data: User-supplied data passed to the class init/finalize functions.
936
* @instance_size: Size of the instance (object) structure (required for instantiatable types only).
937
* @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.
938
* @instance_init: Location of the instance initialization function (optional, for instantiatable types only).
939
* @value_table: A #GTypeValueTable function table for generic handling of GValues of this type (usually only
940
* useful for fundamental types).
942
* This structure is used to provide the type system with the information
943
* required to initialize and destruct (finalize) a type's class and
945
* The initialized structure is passed to the g_type_register_static() function
946
* (or is copied into the provided #GTypeInfo structure in the
947
* g_type_plugin_complete_type_info()). The type system will perform a deep
948
* copy of this structure, so its memory does not need to be persistent
949
* across invocation of g_type_register_static().
236
951
struct _GTypeInfo
238
953
/* interface types, classed types, instantiated types */
254
969
/* value handling */
255
970
const GTypeValueTable *value_table;
973
* GTypeFundamentalInfo:
974
* @type_flags: #GTypeFundamentalFlags describing the characteristics of the fundamental type
976
* A structure that provides information to the type system which is
977
* used specifically for managing fundamental types.
257
979
struct _GTypeFundamentalInfo
259
981
GTypeFundamentalFlags type_flags;
985
* @interface_init: location of the interface initialization function
986
* @interface_finalize: location of the interface finalization function
987
* @interface_data: user-supplied data passed to the interface init/finalize functions
989
* A structure that provides information to the type system which is
990
* used specifically for managing interface types.
261
992
struct _GInterfaceInfo
263
994
GInterfaceInitFunc interface_init;
264
995
GInterfaceFinalizeFunc interface_finalize;
265
996
gpointer interface_data;
1000
* @value_init: Default initialize @values contents by poking values
1001
* directly into the value->data array. The data array of
1002
* the #GValue passed into this function was zero-filled
1003
* with <function>memset()</function>, so no care has to
1004
* be taken to free any
1005
* old contents. E.g. for the implementation of a string
1006
* value that may never be %NULL, the implementation might
1009
* value->data[0].v_pointer = g_strdup ("");
1011
* @value_free: Free any old contents that might be left in the
1012
* data array of the passed in @value. No resources may
1013
* remain allocated through the #GValue contents after
1014
* this function returns. E.g. for our above string type:
1016
* // only free strings without a specific flag for static storage
1017
* if (!(value->data[1].v_uint & G_VALUE_NOCOPY_CONTENTS))
1018
* g_free (value->data[0].v_pointer);
1020
* @value_copy: @dest_value is a #GValue with zero-filled data section
1021
* and @src_value is a properly setup #GValue of same or
1023
* The purpose of this function is to copy the contents of
1024
* @src_value into @dest_value in a way, that even after
1025
* @src_value has been freed, the contents of @dest_value
1026
* remain valid. String type example:
1028
* dest_value->data[0].v_pointer = g_strdup (src_value->data[0].v_pointer);
1030
* @value_peek_pointer: If the value contents fit into a pointer, such as objects
1031
* or strings, return this pointer, so the caller can peek at
1032
* the current contents. To extend on our above string example:
1034
* return value->data[0].v_pointer;
1036
* @collect_format: A string format describing how to collect the contents of
1037
* this value bit-by-bit. Each character in the format represents
1038
* an argument to be collected, and the characters themselves indicate
1039
* the type of the argument. Currently supported arguments are:
1041
* <varlistentry><term /><listitem><para>
1042
* 'i' - Integers. passed as collect_values[].v_int.
1043
* </para></listitem></varlistentry>
1044
* <varlistentry><term /><listitem><para>
1045
* 'l' - Longs. passed as collect_values[].v_long.
1046
* </para></listitem></varlistentry>
1047
* <varlistentry><term /><listitem><para>
1048
* 'd' - Doubles. passed as collect_values[].v_double.
1049
* </para></listitem></varlistentry>
1050
* <varlistentry><term /><listitem><para>
1051
* 'p' - Pointers. passed as collect_values[].v_pointer.
1052
* </para></listitem></varlistentry>
1054
* It should be noted that for variable argument list construction,
1055
* ANSI C promotes every type smaller than an integer to an int, and
1056
* floats to doubles. So for collection of short int or char, 'i'
1057
* needs to be used, and for collection of floats 'd'.
1058
* @collect_value: The collect_value() function is responsible for converting the
1059
* values collected from a variable argument list into contents
1060
* suitable for storage in a GValue. This function should setup
1061
* @value similar to value_init(); e.g. for a string value that
1062
* does not allow %NULL pointers, it needs to either spew an error,
1063
* or do an implicit conversion by storing an empty string.
1064
* The @value passed in to this function has a zero-filled data
1065
* array, so just like for value_init() it is guaranteed to not
1066
* contain any old contents that might need freeing.
1067
* @n_collect_values is exactly the string length of @collect_format,
1068
* and @collect_values is an array of unions #GTypeCValue with
1069
* length @n_collect_values, containing the collected values
1070
* according to @collect_format.
1071
* @collect_flags is an argument provided as a hint by the caller.
1072
* It may contain the flag %G_VALUE_NOCOPY_CONTENTS indicating,
1073
* that the collected value contents may be considered "static"
1074
* for the duration of the @value lifetime.
1075
* Thus an extra copy of the contents stored in @collect_values is
1076
* not required for assignment to @value.
1077
* For our above string example, we continue with:
1079
* if (!collect_values[0].v_pointer)
1080
* value->data[0].v_pointer = g_strdup ("");
1081
* else if (collect_flags & G_VALUE_NOCOPY_CONTENTS)
1083
* value->data[0].v_pointer = collect_values[0].v_pointer;
1084
* // keep a flag for the value_free() implementation to not free this string
1085
* value->data[1].v_uint = G_VALUE_NOCOPY_CONTENTS;
1088
* value->data[0].v_pointer = g_strdup (collect_values[0].v_pointer);
1091
* It should be noted, that it is generally a bad idea to follow the
1092
* #G_VALUE_NOCOPY_CONTENTS hint for reference counted types. Due to
1093
* reentrancy requirements and reference count assertions performed
1094
* by the #GSignal code, reference counts should always be incremented
1095
* for reference counted contents stored in the value->data array.
1096
* To deviate from our string example for a moment, and taking a look
1097
* at an exemplary implementation for collect_value() of #GObject:
1099
* if (collect_values[0].v_pointer)
1101
* GObject *object = G_OBJECT (collect_values[0].v_pointer);
1102
* // never honour G_VALUE_NOCOPY_CONTENTS for ref-counted types
1103
* value->data[0].v_pointer = g_object_ref (object);
1107
* return g_strdup_printf ("Object passed as invalid NULL pointer");
1110
* The reference count for valid objects is always incremented,
1111
* regardless of @collect_flags. For invalid objects, the example
1112
* returns a newly allocated string without altering @value.
1113
* Upon success, collect_value() needs to return %NULL. If, however,
1114
* an error condition occurred, collect_value() may spew an
1115
* error by returning a newly allocated non-%NULL string, giving
1116
* a suitable description of the error condition.
1117
* The calling code makes no assumptions about the @value
1118
* contents being valid upon error returns, @value
1119
* is simply thrown away without further freeing. As such, it is
1120
* a good idea to not allocate #GValue contents, prior to returning
1121
* an error, however, collect_values() is not obliged to return
1122
* a correctly setup @value for error returns, simply because
1123
* any non-%NULL return is considered a fatal condition so further
1124
* program behaviour is undefined.
1125
* @lcopy_format: Format description of the arguments to collect for @lcopy_value,
1126
* analogous to @collect_format. Usually, @lcopy_format string consists
1127
* only of 'p's to provide lcopy_value() with pointers to storage locations.
1128
* @lcopy_value: This function is responsible for storing the @value contents into
1129
* arguments passed through a variable argument list which got
1130
* collected into @collect_values according to @lcopy_format.
1131
* @n_collect_values equals the string length of @lcopy_format,
1132
* and @collect_flags may contain %G_VALUE_NOCOPY_CONTENTS.
1133
* In contrast to collect_value(), lcopy_value() is obliged to
1134
* always properly support %G_VALUE_NOCOPY_CONTENTS.
1135
* Similar to collect_value() the function may prematurely abort
1136
* by returning a newly allocated string describing an error condition.
1137
* To complete the string example:
1139
* gchar **string_p = collect_values[0].v_pointer;
1141
* return g_strdup_printf ("string location passed as NULL");
1142
* if (collect_flags & G_VALUE_NOCOPY_CONTENTS)
1143
* *string_p = value->data[0].v_pointer;
1145
* *string_p = g_strdup (value->data[0].v_pointer);
1147
* And an illustrative version of lcopy_value() for
1148
* reference-counted types:
1150
* GObject **object_p = collect_values[0].v_pointer;
1152
* return g_strdup_printf ("object location passed as NULL");
1153
* if (!value->data[0].v_pointer)
1155
* else if (collect_flags & G_VALUE_NOCOPY_CONTENTS) // always honour
1156
* *object_p = value->data[0].v_pointer;
1158
* *object_p = g_object_ref (value->data[0].v_pointer);
1162
* The #GTypeValueTable provides the functions required by the #GValue implementation,
1163
* to serve as a container for values of a type.
267
1166
struct _GTypeValueTable
269
1168
void (*value_init) (GValue *value);
323
1222
/* --- GType boilerplate --- */
324
/* convenience macros for type implementations, which for a type GtkGadget will:
325
* - prototype: static void gtk_gadget_class_init (GtkGadgetClass *klass);
326
* - prototype: static void gtk_gadget_init (GtkGadget *self);
327
* - define: static gpointer gtk_gadget_parent_class = NULL;
328
* gtk_gadget_parent_class is initialized prior to calling gtk_gadget_class_init()
329
* - implement: GType gtk_gadget_get_type (void) { ... }
330
* - support custom code in gtk_gadget_get_type() after the type is registered.
332
* macro arguments: TypeName, type_name, TYPE_PARENT, CODE
333
* example: G_DEFINE_TYPE_WITH_CODE (GtkGadget, gtk_gadget, GTK_TYPE_WIDGET,
334
* g_print ("GtkGadget-id: %lu\n", g_define_type_id));
1225
* @TN: The name of the new type, in Camel case.
1226
* @t_n: The name of the new type, in lowercase, with words
1228
* @T_P: The #GType of the parent type.
1230
* A convenience macro for type implementations, which declares a
1231
* class initialization function, an instance initialization function (see #GTypeInfo for information about
1232
* these) and a static variable named @t_n<!-- -->_parent_class pointing to the parent class. Furthermore, it defines
1233
* a *_get_type() function. See G_DEFINE_TYPE_EXTENDED() for an example.
336
1237
#define G_DEFINE_TYPE(TN, t_n, T_P) G_DEFINE_TYPE_EXTENDED (TN, t_n, T_P, 0, {})
1239
* G_DEFINE_TYPE_WITH_CODE:
1240
* @TN: The name of the new type, in Camel case.
1241
* @t_n: The name of the new type in lowercase, with words separated by '_'.
1242
* @T_P: The #GType of the parent type.
1243
* @_C_: Custom code that gets inserted in the *_get_type() function.
1245
* A convenience macro for type implementations.
1246
* Similar to G_DEFINE_TYPE(), but allows to insert custom code into the
1247
* *_get_type() function, e.g. interface implementations via G_IMPLEMENT_INTERFACE().
1248
* See G_DEFINE_TYPE_EXTENDED() for an example.
337
1252
#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()
1254
* G_DEFINE_ABSTRACT_TYPE:
1255
* @TN: The name of the new type, in Camel case.
1256
* @t_n: The name of the new type, in lowercase, with words
1258
* @T_P: The #GType of the parent type.
1260
* A convenience macro for type implementations.
1261
* Similar to G_DEFINE_TYPE(), but defines an abstract type.
1262
* See G_DEFINE_TYPE_EXTENDED() for an example.
338
1266
#define G_DEFINE_ABSTRACT_TYPE(TN, t_n, T_P) G_DEFINE_TYPE_EXTENDED (TN, t_n, T_P, G_TYPE_FLAG_ABSTRACT, {})
1268
* G_DEFINE_ABSTRACT_TYPE_WITH_CODE:
1269
* @TN: The name of the new type, in Camel case.
1270
* @t_n: The name of the new type, in lowercase, with words
1272
* @T_P: The #GType of the parent type.
1273
* @_C_: Custom code that gets inserted in the @type_name_get_type() function.
1275
* A convenience macro for type implementations.
1276
* Similar to G_DEFINE_TYPE_WITH_CODE(), but defines an abstract type and allows to
1277
* insert custom code into the *_get_type() function, e.g. interface implementations
1278
* via G_IMPLEMENT_INTERFACE(). See G_DEFINE_TYPE_EXTENDED() for an example.
339
1282
#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()
1284
* G_DEFINE_TYPE_EXTENDED:
1285
* @TN: The name of the new type, in Camel case.
1286
* @t_n: The name of the new type, in lowercase, with words
1288
* @T_P: The #GType of the parent type.
1289
* @_f_: #GTypeFlags to pass to g_type_register_static()
1290
* @_C_: Custom code that gets inserted in the *_get_type() function.
1292
* The most general convenience macro for type implementations, on which
1293
* G_DEFINE_TYPE(), etc are based.
1296
* G_DEFINE_TYPE_EXTENDED (GtkGadget,
1300
* G_IMPLEMENT_INTERFACE (TYPE_GIZMO,
1301
* gtk_gadget_gizmo_init));
1305
* static void gtk_gadget_init (GtkGadget *self);
1306
* static void gtk_gadget_class_init (GtkGadgetClass *klass);
1307
* static gpointer gtk_gadget_parent_class = NULL;
1308
* static void gtk_gadget_class_intern_init (gpointer klass)
1310
* gtk_gadget_parent_class = g_type_class_peek_parent (klass);
1311
* gtk_gadget_class_init ((GtkGadgetClass*) klass);
1315
* gtk_gadget_get_type (void)
1317
* static GType g_define_type_id = 0;
1318
* if (G_UNLIKELY (g_define_type_id == 0))
1320
* static const GTypeInfo g_define_type_info = {
1321
* sizeof (GtkGadgetClass),
1322
* (GBaseInitFunc) NULL,
1323
* (GBaseFinalizeFunc) NULL,
1324
* (GClassInitFunc) gtk_gadget_class_intern_init,
1325
* (GClassFinalizeFunc) NULL,
1326
* NULL, // class_data
1327
* sizeof (GtkGadget),
1329
* (GInstanceInitFunc) gtk_gadget_init,
1331
* g_define_type_id = g_type_register_static (GTK_TYPE_WIDGET, "GtkGadget", &g_define_type_info, 0);
1333
* static const GInterfaceInfo g_implement_interface_info = {
1334
* (GInterfaceInitFunc) gtk_gadget_gizmo_init
1336
* g_type_add_interface_static (g_define_type_id, TYPE_GIZMO, &g_implement_interface_info);
1339
* return g_define_type_id;
1342
* The only pieces which have to be manually provided are the definitions of the
1343
* instance and class structure and the definitions of the instance and class
340
1348
#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()
342
/* convenience macro to ease interface addition in the CODE
343
* section of G_DEFINE_TYPE_WITH_CODE() (this macro relies on
344
* the g_define_type_id present within G_DEFINE_TYPE_WITH_CODE()).
346
* G_DEFINE_TYPE_WITH_CODE (GtkTreeStore, gtk_tree_store, G_TYPE_OBJECT,
347
* G_IMPLEMENT_INTERFACE (GTK_TYPE_TREE_MODEL,
348
* gtk_tree_store_tree_model_init));
1351
* G_IMPLEMENT_INTERFACE:
1352
* @TYPE_IFACE: The #GType of the interface to add
1353
* @iface_init: The interface init function
1355
* A convenience macro to ease interface addition in the @_C_ section
1356
* of G_DEFINE_TYPE_WITH_CODE() or G_DEFINE_ABSTRACT_TYPE_WITH_CODE().
1357
* See G_DEFINE_TYPE_EXTENDED() for an example.
1359
* Note that this macro can only be used together with the G_DEFINE_TYPE_*
1360
* macros, since it depends on variable names from those macros.
350
1364
#define G_IMPLEMENT_INTERFACE(TYPE_IFACE, iface_init) { \
351
1365
const GInterfaceInfo g_implement_interface_info = { \
added
removed
gobject/gtype.h
