1/* GObject - GLib Type, Object, Parameter and Signal Library
2 * Copyright (C) 1998-1999, 2000-2001 Tim Janik and Red Hat, Inc.
3 *
4 * SPDX-License-Identifier: LGPL-2.1-or-later
5 *
6 * This library is free software; you can redistribute it and/or
7 * modify it under the terms of the GNU Lesser General Public
8 * License as published by the Free Software Foundation; either
9 * version 2.1 of the License, or (at your option) any later version.
10 *
11 * This library is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 * Lesser General Public License for more details.
15 *
16 * You should have received a copy of the GNU Lesser General
17 * Public License along with this library; if not, see <http://www.gnu.org/licenses/>.
18 */
19#ifndef __G_TYPE_H__
20#define __G_TYPE_H__
21
22#if !defined (__GLIB_GOBJECT_H_INSIDE__) && !defined (GOBJECT_COMPILATION)
23#error "Only <glib-object.h> can be included directly."
24#endif
25
26#include <glib.h>
27#include <gobject/gobject-visibility.h>
28
29G_BEGIN_DECLS
30
31/* Basic Type Macros
32 */
33/**
34 * G_TYPE_FUNDAMENTAL:
35 * @type: A #GType value.
36 *
37 * The fundamental type which is the ancestor of @type.
38 *
39 * Fundamental types are types that serve as ultimate bases for the derived types,
40 * thus they are the roots of distinct inheritance hierarchies.
41 */
42#define G_TYPE_FUNDAMENTAL(type) (g_type_fundamental (type))
43/**
44 * G_TYPE_FUNDAMENTAL_SHIFT:
45 *
46 * Shift value used in converting numbers to type IDs.
47 */
48#define G_TYPE_FUNDAMENTAL_SHIFT (2)
49/**
50 * G_TYPE_FUNDAMENTAL_MAX: (value 1020)
51 *
52 * An integer constant that represents the number of identifiers reserved
53 * for types that are assigned at compile-time.
54 */
55#define G_TYPE_FUNDAMENTAL_MAX (255 << G_TYPE_FUNDAMENTAL_SHIFT)
56
57/* Constant fundamental types,
58 */
59/**
60 * G_TYPE_INVALID:
61 *
62 * An invalid #GType used as error return value in some functions which return
63 * a #GType.
64 */
65#define G_TYPE_INVALID G_TYPE_MAKE_FUNDAMENTAL (0)
66/**
67 * G_TYPE_NONE:
68 *
69 * A fundamental type which is used as a replacement for the C
70 * void return type.
71 */
72#define G_TYPE_NONE G_TYPE_MAKE_FUNDAMENTAL (1)
73/**
74 * G_TYPE_INTERFACE:
75 *
76 * The fundamental type from which all interfaces are derived.
77 */
78#define G_TYPE_INTERFACE G_TYPE_MAKE_FUNDAMENTAL (2)
79/**
80 * G_TYPE_CHAR:
81 *
82 * The fundamental type corresponding to #gchar.
83 *
84 * The type designated by %G_TYPE_CHAR is unconditionally an 8-bit signed integer.
85 * This may or may not be the same type a the C type "gchar".
86 */
87#define G_TYPE_CHAR G_TYPE_MAKE_FUNDAMENTAL (3)
88/**
89 * G_TYPE_UCHAR:
90 *
91 * The fundamental type corresponding to #guchar.
92 */
93#define G_TYPE_UCHAR G_TYPE_MAKE_FUNDAMENTAL (4)
94/**
95 * G_TYPE_BOOLEAN:
96 *
97 * The fundamental type corresponding to #gboolean.
98 */
99#define G_TYPE_BOOLEAN G_TYPE_MAKE_FUNDAMENTAL (5)
100/**
101 * G_TYPE_INT:
102 *
103 * The fundamental type corresponding to #gint.
104 */
105#define G_TYPE_INT G_TYPE_MAKE_FUNDAMENTAL (6)
106/**
107 * G_TYPE_UINT:
108 *
109 * The fundamental type corresponding to #guint.
110 */
111#define G_TYPE_UINT G_TYPE_MAKE_FUNDAMENTAL (7)
112/**
113 * G_TYPE_LONG:
114 *
115 * The fundamental type corresponding to #glong.
116 */
117#define G_TYPE_LONG G_TYPE_MAKE_FUNDAMENTAL (8)
118/**
119 * G_TYPE_ULONG:
120 *
121 * The fundamental type corresponding to #gulong.
122 */
123#define G_TYPE_ULONG G_TYPE_MAKE_FUNDAMENTAL (9)
124/**
125 * G_TYPE_INT64:
126 *
127 * The fundamental type corresponding to #gint64.
128 */
129#define G_TYPE_INT64 G_TYPE_MAKE_FUNDAMENTAL (10)
130/**
131 * G_TYPE_UINT64:
132 *
133 * The fundamental type corresponding to #guint64.
134 */
135#define G_TYPE_UINT64 G_TYPE_MAKE_FUNDAMENTAL (11)
136/**
137 * G_TYPE_ENUM:
138 *
139 * The fundamental type from which all enumeration types are derived.
140 */
141#define G_TYPE_ENUM G_TYPE_MAKE_FUNDAMENTAL (12)
142/**
143 * G_TYPE_FLAGS:
144 *
145 * The fundamental type from which all flags types are derived.
146 */
147#define G_TYPE_FLAGS G_TYPE_MAKE_FUNDAMENTAL (13)
148/**
149 * G_TYPE_FLOAT:
150 *
151 * The fundamental type corresponding to #gfloat.
152 */
153#define G_TYPE_FLOAT G_TYPE_MAKE_FUNDAMENTAL (14)
154/**
155 * G_TYPE_DOUBLE:
156 *
157 * The fundamental type corresponding to #gdouble.
158 */
159#define G_TYPE_DOUBLE G_TYPE_MAKE_FUNDAMENTAL (15)
160/**
161 * G_TYPE_STRING:
162 *
163 * The fundamental type corresponding to nul-terminated C strings.
164 */
165#define G_TYPE_STRING G_TYPE_MAKE_FUNDAMENTAL (16)
166/**
167 * G_TYPE_POINTER:
168 *
169 * The fundamental type corresponding to #gpointer.
170 */
171#define G_TYPE_POINTER G_TYPE_MAKE_FUNDAMENTAL (17)
172/**
173 * G_TYPE_BOXED:
174 *
175 * The fundamental type from which all boxed types are derived.
176 */
177#define G_TYPE_BOXED G_TYPE_MAKE_FUNDAMENTAL (18)
178/**
179 * G_TYPE_PARAM:
180 *
181 * The fundamental type from which all #GParamSpec types are derived.
182 */
183#define G_TYPE_PARAM G_TYPE_MAKE_FUNDAMENTAL (19)
184/**
185 * G_TYPE_OBJECT:
186 *
187 * The fundamental type for #GObject.
188 */
189#define G_TYPE_OBJECT G_TYPE_MAKE_FUNDAMENTAL (20)
190/**
191 * G_TYPE_VARIANT:
192 *
193 * The fundamental type corresponding to #GVariant.
194 *
195 * All floating #GVariant instances passed through the #GType system are
196 * consumed.
197 *
198 * Note that callbacks in closures, and signal handlers
199 * for signals of return type %G_TYPE_VARIANT, must never return floating
200 * variants.
201 *
202 * Note: GLib 2.24 did include a boxed type with this name. It was replaced
203 * with this fundamental type in 2.26.
204 *
205 * Since: 2.26
206 */
207#define G_TYPE_VARIANT G_TYPE_MAKE_FUNDAMENTAL (21)
208
209
210/* Reserved fundamental type numbers to create new fundamental
211 * type IDs with G_TYPE_MAKE_FUNDAMENTAL().
212 *
213 * Open an issue on https://gitlab.gnome.org/GNOME/glib/issues/new for
214 * reservations.
215 */
216/**
217 * G_TYPE_MAKE_FUNDAMENTAL:
218 * @x: the fundamental type number.
219 *
220 * Get the type ID for the fundamental type number @x.
221 *
222 * Use g_type_fundamental_next() instead of this macro to create new fundamental
223 * types.
224 *
225 * Returns: the GType
226 */
227#define G_TYPE_MAKE_FUNDAMENTAL(x) ((GType) ((x) << G_TYPE_FUNDAMENTAL_SHIFT))
228/**
229 * G_TYPE_RESERVED_GLIB_FIRST:
230 *
231 * First fundamental type number to create a new fundamental type id with
232 * G_TYPE_MAKE_FUNDAMENTAL() reserved for GLib.
233 */
234#define G_TYPE_RESERVED_GLIB_FIRST (22)
235/**
236 * G_TYPE_RESERVED_GLIB_LAST:
237 *
238 * Last fundamental type number reserved for GLib.
239 */
240#define G_TYPE_RESERVED_GLIB_LAST (31)
241/**
242 * G_TYPE_RESERVED_BSE_FIRST:
243 *
244 * First fundamental type number to create a new fundamental type id with
245 * G_TYPE_MAKE_FUNDAMENTAL() reserved for BSE.
246 */
247#define G_TYPE_RESERVED_BSE_FIRST (32)
248/**
249 * G_TYPE_RESERVED_BSE_LAST:
250 *
251 * Last fundamental type number reserved for BSE.
252 */
253#define G_TYPE_RESERVED_BSE_LAST (48)
254/**
255 * G_TYPE_RESERVED_USER_FIRST:
256 *
257 * First available fundamental type number to create new fundamental
258 * type id with G_TYPE_MAKE_FUNDAMENTAL().
259 */
260#define G_TYPE_RESERVED_USER_FIRST (49)
261
262
263/* Type Checking Macros
264 */
265/**
266 * G_TYPE_IS_FUNDAMENTAL:
267 * @type: A #GType value
268 *
269 * Checks if @type is a fundamental type.
270 *
271 * Returns: %TRUE is @type is fundamental
272 */
273#define G_TYPE_IS_FUNDAMENTAL(type) ((type) <= G_TYPE_FUNDAMENTAL_MAX)
274/**
275 * G_TYPE_IS_DERIVED:
276 * @type: A #GType value
277 *
278 * Checks if @type is derived (or in object-oriented terminology:
279 * inherited) from another type (this holds true for all non-fundamental
280 * types).
281 *
282 * Returns: %TRUE if @type is derived
283 */
284#define G_TYPE_IS_DERIVED(type) ((type) > G_TYPE_FUNDAMENTAL_MAX)
285/**
286 * G_TYPE_IS_INTERFACE:
287 * @type: A #GType value
288 *
289 * Checks if @type is an interface type.
290 *
291 * An interface type provides a pure API, the implementation
292 * of which is provided by another type (which is then said to conform
293 * to the interface). GLib interfaces are somewhat analogous to Java
294 * interfaces and C++ classes containing only pure virtual functions,
295 * with the difference that GType interfaces are not derivable (but see
296 * g_type_interface_add_prerequisite() for an alternative).
297 *
298 * Returns: %TRUE if @type is an interface
299 */
300#define G_TYPE_IS_INTERFACE(type) (G_TYPE_FUNDAMENTAL (type) == G_TYPE_INTERFACE)
301/**
302 * G_TYPE_IS_CLASSED:
303 * @type: A #GType value
304 *
305 * Checks if @type is a classed type.
306 *
307 * A classed type has an associated #GTypeClass which can be derived to store
308 * class-wide virtual function pointers and data for all instances of the type.
309 * This allows for subclassing. All #GObjects are classed; none of the scalar
310 * fundamental types built into GLib are classed.
311 *
312 * Interfaces are not classed: while their #GTypeInterface struct could be
313 * considered similar to #GTypeClass, and classes can derive interfaces,
314 * #GTypeInterface doesn’t allow for subclassing.
315 *
316 * Returns: %TRUE if @type is classed
317 */
318#define G_TYPE_IS_CLASSED(type) (g_type_test_flags ((type), G_TYPE_FLAG_CLASSED))
319/**
320 * G_TYPE_IS_INSTANTIATABLE:
321 * @type: A #GType value
322 *
323 * Checks if @type can be instantiated. Instantiation is the
324 * process of creating an instance (object) of this type.
325 *
326 * Returns: %TRUE if @type is instantiatable
327 */
328#define G_TYPE_IS_INSTANTIATABLE(type) (g_type_test_flags ((type), G_TYPE_FLAG_INSTANTIATABLE))
329/**
330 * G_TYPE_IS_DERIVABLE:
331 * @type: A #GType value
332 *
333 * Checks if @type is a derivable type. A derivable type can
334 * be used as the base class of a flat (single-level) class hierarchy.
335 *
336 * Returns: %TRUE if @type is derivable
337 */
338#define G_TYPE_IS_DERIVABLE(type) (g_type_test_flags ((type), G_TYPE_FLAG_DERIVABLE))
339/**
340 * G_TYPE_IS_DEEP_DERIVABLE:
341 * @type: A #GType value
342 *
343 * Checks if @type is a deep derivable type. A deep derivable type
344 * can be used as the base class of a deep (multi-level) class hierarchy.
345 *
346 * Returns: %TRUE if @type is deep derivable
347 */
348#define G_TYPE_IS_DEEP_DERIVABLE(type) (g_type_test_flags ((type), G_TYPE_FLAG_DEEP_DERIVABLE))
349/**
350 * G_TYPE_IS_ABSTRACT:
351 * @type: A #GType value
352 *
353 * Checks if @type is an abstract type. An abstract type cannot be
354 * instantiated and is normally used as an abstract base class for
355 * derived classes.
356 *
357 * Returns: %TRUE if @type is abstract
358 */
359#define G_TYPE_IS_ABSTRACT(type) (g_type_test_flags ((type), G_TYPE_FLAG_ABSTRACT))
360/**
361 * G_TYPE_IS_VALUE_ABSTRACT:
362 * @type: A #GType value
363 *
364 * Checks if @type is an abstract value type. An abstract value type introduces
365 * a value table, but can't be used for g_value_init() and is normally used as
366 * an abstract base type for derived value types.
367 *
368 * Returns: %TRUE if @type is an abstract value type
369 */
370#define G_TYPE_IS_VALUE_ABSTRACT(type) (g_type_test_flags ((type), G_TYPE_FLAG_VALUE_ABSTRACT))
371/**
372 * G_TYPE_IS_VALUE_TYPE:
373 * @type: A #GType value
374 *
375 * Checks if @type is a value type and can be used with g_value_init().
376 *
377 * Returns: %TRUE if @type is a value type
378 */
379#define G_TYPE_IS_VALUE_TYPE(type) (g_type_check_is_value_type (type))
380/**
381 * G_TYPE_HAS_VALUE_TABLE:
382 * @type: A #GType value
383 *
384 * Checks if @type has a #GTypeValueTable.
385 *
386 * Returns: %TRUE if @type has a value table
387 */
388#define G_TYPE_HAS_VALUE_TABLE(type) (g_type_value_table_peek (type) != NULL)
389/**
390 * G_TYPE_IS_FINAL:
391 * @type: a #GType value
392 *
393 * Checks if @type is a final type. A final type cannot be derived any
394 * further.
395 *
396 * Returns: %TRUE if @type is final
397 *
398 * Since: 2.70
399 */
400#define G_TYPE_IS_FINAL(type) (g_type_test_flags ((type), G_TYPE_FLAG_FINAL)) GOBJECT_AVAILABLE_MACRO_IN_2_70
401
402/**
403 * G_TYPE_IS_DEPRECATED:
404 * @type: a #GType value
405 *
406 * Checks if @type is deprecated. Instantiating a deprecated type will
407 * trigger a warning if running with `G_ENABLE_DIAGNOSTIC=1`.
408 *
409 * Returns: %TRUE if the type is deprecated
410 *
411 * Since: 2.76
412 */
413#define G_TYPE_IS_DEPRECATED(type) (g_type_test_flags ((type), G_TYPE_FLAG_DEPRECATED)) GOBJECT_AVAILABLE_MACRO_IN_2_76
414
415
416/* Typedefs
417 */
418/**
419 * GType:
420 *
421 * A numerical value which represents the unique identifier of a registered
422 * type.
423 */
424#if GLIB_SIZEOF_VOID_P > GLIB_SIZEOF_SIZE_T
425typedef guintptr GType;
426#elif GLIB_SIZEOF_SIZE_T != GLIB_SIZEOF_LONG || !defined (G_CXX_STD_VERSION)
427typedef gsize GType;
428#else /* for historic reasons, C++ on non-Morello/CHERI systems links against gulong GTypes */
429typedef gulong GType;
430#endif
431typedef struct _GValue GValue;
432typedef union _GTypeCValue GTypeCValue;
433typedef struct _GTypePlugin GTypePlugin;
434typedef struct _GTypeClass GTypeClass;
435typedef struct _GTypeInterface GTypeInterface;
436typedef struct _GTypeInstance GTypeInstance;
437typedef struct _GTypeInfo GTypeInfo;
438typedef struct _GTypeFundamentalInfo GTypeFundamentalInfo;
439typedef struct _GInterfaceInfo GInterfaceInfo;
440typedef struct _GTypeValueTable GTypeValueTable;
441typedef struct _GTypeQuery GTypeQuery;
442
443
444/* Basic Type Structures
445 */
446/**
447 * GTypeClass:
448 *
449 * An opaque structure used as the base of all classes.
450 */
451struct _GTypeClass
452{
453 /*< private >*/
454 GType g_type;
455};
456/**
457 * GTypeInstance:
458 *
459 * An opaque structure used as the base of all type instances.
460 */
461struct _GTypeInstance
462{
463 /*< private >*/
464 GTypeClass *g_class;
465};
466/**
467 * GTypeInterface:
468 *
469 * An opaque structure used as the base of all interface types.
470 */
471struct _GTypeInterface
472{
473 /*< private >*/
474 GType g_type; /* iface type */
475 GType g_instance_type;
476};
477/**
478 * GTypeQuery:
479 * @type: the #GType value of the type
480 * @type_name: the name of the type
481 * @class_size: the size of the class structure
482 * @instance_size: the size of the instance structure
483 *
484 * A structure holding information for a specific type.
485 *
486 * See also: g_type_query()
487 */
488struct _GTypeQuery
489{
490 GType type;
491 const gchar *type_name;
492 guint class_size;
493 guint instance_size;
494};
495
496
497/* Casts, checks and accessors for structured types
498 * usage of these macros is reserved to type implementations only
499 */
500/*< protected >*/
501/**
502 * G_TYPE_CHECK_INSTANCE:
503 * @instance: Location of a #GTypeInstance structure
504 *
505 * Checks if @instance is a valid #GTypeInstance structure,
506 * otherwise issues a warning and returns %FALSE. %NULL is not a valid
507 * #GTypeInstance.
508 *
509 * This macro should only be used in type implementations.
510 *
511 * Returns: %TRUE if @instance is valid
512 */
513#define G_TYPE_CHECK_INSTANCE(instance) (_G_TYPE_CHI ((GTypeInstance*) (instance)))
514/**
515 * G_TYPE_CHECK_INSTANCE_CAST:
516 * @instance: (nullable): Location of a #GTypeInstance structure
517 * @g_type: The type to be returned
518 * @c_type: The corresponding C type of @g_type
519 *
520 * Checks that @instance is an instance of the type identified by @g_type
521 * and issues a warning if this is not the case. Returns @instance casted
522 * to a pointer to @c_type.
523 *
524 * No warning will be issued if @instance is %NULL, and %NULL will be returned.
525 *
526 * This macro should only be used in type implementations.
527 */
528#define G_TYPE_CHECK_INSTANCE_CAST(instance, g_type, c_type) (_G_TYPE_CIC ((instance), (g_type), c_type))
529/**
530 * G_TYPE_CHECK_INSTANCE_TYPE:
531 * @instance: (nullable): Location of a #GTypeInstance structure.
532 * @g_type: The type to be checked
533 *
534 * Checks if @instance is an instance of the type identified by @g_type. If
535 * @instance is %NULL, %FALSE will be returned.
536 *
537 * This macro should only be used in type implementations.
538 *
539 * Returns: %TRUE if @instance is an instance of @g_type
540 */
541#define G_TYPE_CHECK_INSTANCE_TYPE(instance, g_type) (_G_TYPE_CIT ((instance), (g_type)))
542/**
543 * G_TYPE_CHECK_INSTANCE_FUNDAMENTAL_TYPE:
544 * @instance: (nullable): Location of a #GTypeInstance structure.
545 * @g_type: The fundamental type to be checked
546 *
547 * Checks if @instance is an instance of the fundamental type identified by @g_type.
548 * If @instance is %NULL, %FALSE will be returned.
549 *
550 * This macro should only be used in type implementations.
551 *
552 * Returns: %TRUE if @instance is an instance of @g_type
553 */
554#define G_TYPE_CHECK_INSTANCE_FUNDAMENTAL_TYPE(instance, g_type) (_G_TYPE_CIFT ((instance), (g_type)))
555/**
556 * G_TYPE_INSTANCE_GET_CLASS:
557 * @instance: Location of the #GTypeInstance structure
558 * @g_type: The #GType of the class to be returned
559 * @c_type: The C type of the class structure
560 *
561 * Get the class structure of a given @instance, casted
562 * to a specified ancestor type @g_type of the instance.
563 *
564 * Note that while calling a GInstanceInitFunc(), the class pointer
565 * gets modified, so it might not always return the expected pointer.
566 *
567 * This macro should only be used in type implementations.
568 *
569 * Returns: a pointer to the class structure
570 */
571#define G_TYPE_INSTANCE_GET_CLASS(instance, g_type, c_type) (_G_TYPE_IGC ((instance), (g_type), c_type))
572/**
573 * G_TYPE_INSTANCE_GET_INTERFACE:
574 * @instance: Location of the #GTypeInstance structure
575 * @g_type: The #GType of the interface to be returned
576 * @c_type: The C type of the interface structure
577 *
578 * Get the interface structure for interface @g_type of a given @instance.
579 *
580 * This macro should only be used in type implementations.
581 *
582 * Returns: a pointer to the interface structure
583 */
584#define G_TYPE_INSTANCE_GET_INTERFACE(instance, g_type, c_type) (_G_TYPE_IGI ((instance), (g_type), c_type))
585/**
586 * G_TYPE_CHECK_CLASS_CAST:
587 * @g_class: Location of a #GTypeClass structure
588 * @g_type: The type to be returned
589 * @c_type: The corresponding C type of class structure of @g_type
590 *
591 * Checks that @g_class is a class structure of the type identified by @g_type
592 * and issues a warning if this is not the case. Returns @g_class casted
593 * to a pointer to @c_type. %NULL is not a valid class structure.
594 *
595 * This macro should only be used in type implementations.
596 */
597#define G_TYPE_CHECK_CLASS_CAST(g_class, g_type, c_type) (_G_TYPE_CCC ((g_class), (g_type), c_type))
598/**
599 * G_TYPE_CHECK_CLASS_TYPE:
600 * @g_class: (nullable): Location of a #GTypeClass structure
601 * @g_type: The type to be checked
602 *
603 * Checks if @g_class is a class structure of the type identified by
604 * @g_type. If @g_class is %NULL, %FALSE will be returned.
605 *
606 * This macro should only be used in type implementations.
607 *
608 * Returns: %TRUE if @g_class is a class structure of @g_type
609 */
610#define G_TYPE_CHECK_CLASS_TYPE(g_class, g_type) (_G_TYPE_CCT ((g_class), (g_type)))
611/**
612 * G_TYPE_CHECK_VALUE:
613 * @value: a #GValue
614 *
615 * Checks if @value has been initialized to hold values
616 * of a value type.
617 *
618 * This macro should only be used in type implementations.
619 *
620 * Returns: %TRUE if @value is initialized
621 */
622#define G_TYPE_CHECK_VALUE(value) (_G_TYPE_CHV ((value)))
623/**
624 * G_TYPE_CHECK_VALUE_TYPE:
625 * @value: a #GValue
626 * @g_type: The type to be checked
627 *
628 * Checks if @value has been initialized to hold values
629 * of type @g_type.
630 *
631 * This macro should only be used in type implementations.
632 *
633 * Returns: %TRUE if @value has been initialized to hold values of type @g_type
634 */
635#define G_TYPE_CHECK_VALUE_TYPE(value, g_type) (_G_TYPE_CVH ((value), (g_type)))
636/**
637 * G_TYPE_FROM_INSTANCE:
638 * @instance: Location of a valid #GTypeInstance structure
639 *
640 * Get the type identifier from a given @instance structure.
641 *
642 * This macro should only be used in type implementations.
643 *
644 * Returns: the #GType
645 */
646#define G_TYPE_FROM_INSTANCE(instance) (G_TYPE_FROM_CLASS (((GTypeInstance*) (instance))->g_class))
647/**
648 * G_TYPE_FROM_CLASS:
649 * @g_class: Location of a valid #GTypeClass structure
650 *
651 * Get the type identifier from a given @class structure.
652 *
653 * This macro should only be used in type implementations.
654 *
655 * Returns: the #GType
656 */
657#define G_TYPE_FROM_CLASS(g_class) (((GTypeClass*) (g_class))->g_type)
658/**
659 * G_TYPE_FROM_INTERFACE:
660 * @g_iface: Location of a valid #GTypeInterface structure
661 *
662 * Get the type identifier from a given @interface structure.
663 *
664 * This macro should only be used in type implementations.
665 *
666 * Returns: the #GType
667 */
668#define G_TYPE_FROM_INTERFACE(g_iface) (((GTypeInterface*) (g_iface))->g_type)
669
670/**
671 * G_TYPE_INSTANCE_GET_PRIVATE:
672 * @instance: the instance of a type deriving from @private_type
673 * @g_type: the type identifying which private data to retrieve
674 * @c_type: The C type for the private structure
675 *
676 * Gets the private structure for a particular type.
677 *
678 * The private structure must have been registered in the
679 * class_init function with g_type_class_add_private().
680 *
681 * This macro should only be used in type implementations.
682 *
683 * Since: 2.4
684 * Deprecated: 2.58: Use G_ADD_PRIVATE() and the generated
685 * `your_type_get_instance_private()` function instead
686 * Returns: (not nullable): a pointer to the private data structure
687 */
688#define G_TYPE_INSTANCE_GET_PRIVATE(instance, g_type, c_type) ((c_type*) g_type_instance_get_private ((GTypeInstance*) (instance), (g_type))) GOBJECT_DEPRECATED_MACRO_IN_2_58_FOR(G_ADD_PRIVATE)
689
690/**
691 * G_TYPE_CLASS_GET_PRIVATE:
692 * @klass: the class of a type deriving from @private_type
693 * @g_type: the type identifying which private data to retrieve
694 * @c_type: The C type for the private structure
695 *
696 * Gets the private class structure for a particular type.
697 *
698 * The private structure must have been registered in the
699 * get_type() function with g_type_add_class_private().
700 *
701 * This macro should only be used in type implementations.
702 *
703 * Since: 2.24
704 * Returns: (not nullable): a pointer to the private data structure
705 */
706#define G_TYPE_CLASS_GET_PRIVATE(klass, g_type, c_type) ((c_type*) g_type_class_get_private ((GTypeClass*) (klass), (g_type)))
707
708/**
709 * GTypeDebugFlags:
710 * @G_TYPE_DEBUG_NONE: Print no messages
711 * @G_TYPE_DEBUG_OBJECTS: Print messages about object bookkeeping
712 * @G_TYPE_DEBUG_SIGNALS: Print messages about signal emissions
713 * @G_TYPE_DEBUG_MASK: Mask covering all debug flags
714 * @G_TYPE_DEBUG_INSTANCE_COUNT: Keep a count of instances of each type
715 *
716 * These flags used to be passed to g_type_init_with_debug_flags() which
717 * is now deprecated.
718 *
719 * If you need to enable debugging features, use the `GOBJECT_DEBUG`
720 * environment variable.
721 *
722 * Deprecated: 2.36: g_type_init() is now done automatically
723 */
724typedef enum /*< skip >*/
725{
726 G_TYPE_DEBUG_NONE = 0,
727 G_TYPE_DEBUG_OBJECTS = 1 << 0,
728 G_TYPE_DEBUG_SIGNALS = 1 << 1,
729 G_TYPE_DEBUG_INSTANCE_COUNT = 1 << 2,
730 G_TYPE_DEBUG_MASK = 0x07
731} GTypeDebugFlags GOBJECT_DEPRECATED_TYPE_IN_2_36;
732
733
734/* --- prototypes --- */
735G_GNUC_BEGIN_IGNORE_DEPRECATIONS
736GOBJECT_DEPRECATED_IN_2_36
737void g_type_init (void);
738GOBJECT_DEPRECATED_IN_2_36
739void g_type_init_with_debug_flags (GTypeDebugFlags debug_flags);
740G_GNUC_END_IGNORE_DEPRECATIONS
741
742GOBJECT_AVAILABLE_IN_ALL
743const gchar * g_type_name (GType type);
744GOBJECT_AVAILABLE_IN_ALL
745GQuark g_type_qname (GType type);
746GOBJECT_AVAILABLE_IN_ALL
747GType g_type_from_name (const gchar *name);
748GOBJECT_AVAILABLE_IN_ALL
749GType g_type_parent (GType type);
750GOBJECT_AVAILABLE_IN_ALL
751guint g_type_depth (GType type);
752GOBJECT_AVAILABLE_IN_ALL
753GType g_type_next_base (GType leaf_type,
754 GType root_type);
755GOBJECT_AVAILABLE_IN_ALL
756gboolean g_type_is_a (GType type,
757 GType is_a_type);
758
759/* Hoist exact GType comparisons into the caller */
760#define g_type_is_a(a,b) ((a) == (b) || (g_type_is_a) ((a), (b)))
761
762GOBJECT_AVAILABLE_IN_ALL
763gpointer g_type_class_ref (GType type);
764GOBJECT_AVAILABLE_IN_ALL
765gpointer g_type_class_peek (GType type);
766GOBJECT_AVAILABLE_IN_ALL
767gpointer g_type_class_peek_static (GType type);
768GOBJECT_AVAILABLE_IN_ALL
769void g_type_class_unref (gpointer g_class);
770GOBJECT_AVAILABLE_IN_ALL
771gpointer g_type_class_peek_parent (gpointer g_class);
772GOBJECT_AVAILABLE_IN_ALL
773gpointer g_type_interface_peek (gpointer instance_class,
774 GType iface_type);
775GOBJECT_AVAILABLE_IN_ALL
776gpointer g_type_interface_peek_parent (gpointer g_iface);
777
778GOBJECT_AVAILABLE_IN_ALL
779gpointer g_type_default_interface_ref (GType g_type);
780GOBJECT_AVAILABLE_IN_ALL
781gpointer g_type_default_interface_peek (GType g_type);
782GOBJECT_AVAILABLE_IN_ALL
783void g_type_default_interface_unref (gpointer g_iface);
784
785/* g_free() the returned arrays */
786GOBJECT_AVAILABLE_IN_ALL
787GType* g_type_children (GType type,
788 guint *n_children);
789GOBJECT_AVAILABLE_IN_ALL
790GType* g_type_interfaces (GType type,
791 guint *n_interfaces);
792
793/* per-type _static_ data */
794GOBJECT_AVAILABLE_IN_ALL
795void g_type_set_qdata (GType type,
796 GQuark quark,
797 gpointer data);
798GOBJECT_AVAILABLE_IN_ALL
799gpointer g_type_get_qdata (GType type,
800 GQuark quark);
801GOBJECT_AVAILABLE_IN_ALL
802void g_type_query (GType type,
803 GTypeQuery *query);
804
805GOBJECT_AVAILABLE_IN_2_44
806int g_type_get_instance_count (GType type);
807
808/* --- type registration --- */
809/**
810 * GBaseInitFunc:
811 * @g_class: (type GObject.TypeClass): The #GTypeClass structure to initialize
812 *
813 * A callback function used by the type system to do base initialization
814 * of the class structures of derived types.
815 *
816 * This function is called as part of the initialization process of all derived
817 * classes and should reallocate or reset all dynamic class members copied over
818 * from the parent class.
819 *
820 * For example, class members (such as strings) that are not sufficiently
821 * handled by a plain memory copy of the parent class into the derived class
822 * have to be altered. See GClassInitFunc() for a discussion of the class
823 * initialization process.
824 */
825typedef void (*GBaseInitFunc) (gpointer g_class);
826/**
827 * GBaseFinalizeFunc:
828 * @g_class: (type GObject.TypeClass): The #GTypeClass structure to finalize
829 *
830 * A callback function used by the type system to finalize those portions
831 * of a derived types class structure that were setup from the corresponding
832 * GBaseInitFunc() function.
833 *
834 * Class finalization basically works the inverse way in which class
835 * initialization is performed.
836 *
837 * See GClassInitFunc() for a discussion of the class initialization process.
838 */
839typedef void (*GBaseFinalizeFunc) (gpointer g_class);
840/**
841 * GClassInitFunc:
842 * @g_class: (type GObject.TypeClass): The #GTypeClass structure to initialize.
843 * @class_data: The @class_data member supplied via the #GTypeInfo structure.
844 *
845 * A callback function used by the type system to initialize the class
846 * of a specific type.
847 *
848 * This function should initialize all static class members.
849 *
850 * The initialization process of a class involves:
851 *
852 * - Copying common members from the parent class over to the
853 * derived class structure.
854 * - Zero initialization of the remaining members not copied
855 * over from the parent class.
856 * - Invocation of the GBaseInitFunc() initializers of all parent
857 * types and the class' type.
858 * - Invocation of the class' GClassInitFunc() initializer.
859 *
860 * Since derived classes are partially initialized through a memory copy
861 * of the parent class, the general rule is that GBaseInitFunc() and
862 * GBaseFinalizeFunc() should take care of necessary reinitialization
863 * and release of those class members that were introduced by the type
864 * that specified these GBaseInitFunc()/GBaseFinalizeFunc().
865 * GClassInitFunc() should only care about initializing static
866 * class members, while dynamic class members (such as allocated strings
867 * or reference counted resources) are better handled by a GBaseInitFunc()
868 * for this type, so proper initialization of the dynamic class members
869 * is performed for class initialization of derived types as well.
870 *
871 * An example may help to correspond the intend of the different class
872 * initializers:
873 *
874 * |[<!-- language="C" -->
875 * typedef struct {
876 * GObjectClass parent_class;
877 * gint static_integer;
878 * gchar *dynamic_string;
879 * } TypeAClass;
880 * static void
881 * type_a_base_class_init (TypeAClass *class)
882 * {
883 * class->dynamic_string = g_strdup ("some string");
884 * }
885 * static void
886 * type_a_base_class_finalize (TypeAClass *class)
887 * {
888 * g_free (class->dynamic_string);
889 * }
890 * static void
891 * type_a_class_init (TypeAClass *class)
892 * {
893 * class->static_integer = 42;
894 * }
895 *
896 * typedef struct {
897 * TypeAClass parent_class;
898 * gfloat static_float;
899 * GString *dynamic_gstring;
900 * } TypeBClass;
901 * static void
902 * type_b_base_class_init (TypeBClass *class)
903 * {
904 * class->dynamic_gstring = g_string_new ("some other string");
905 * }
906 * static void
907 * type_b_base_class_finalize (TypeBClass *class)
908 * {
909 * g_string_free (class->dynamic_gstring);
910 * }
911 * static void
912 * type_b_class_init (TypeBClass *class)
913 * {
914 * class->static_float = 3.14159265358979323846;
915 * }
916 * ]|
917 *
918 * Initialization of TypeBClass will first cause initialization of
919 * TypeAClass (derived classes reference their parent classes, see
920 * g_type_class_ref() on this).
921 *
922 * Initialization of TypeAClass roughly involves zero-initializing its fields,
923 * then calling its GBaseInitFunc() type_a_base_class_init() to allocate
924 * its dynamic members (dynamic_string), and finally calling its GClassInitFunc()
925 * type_a_class_init() to initialize its static members (static_integer).
926 * The first step in the initialization process of TypeBClass is then
927 * a plain memory copy of the contents of TypeAClass into TypeBClass and
928 * zero-initialization of the remaining fields in TypeBClass.
929 * The dynamic members of TypeAClass within TypeBClass now need
930 * reinitialization which is performed by calling type_a_base_class_init()
931 * with an argument of TypeBClass.
932 *
933 * After that, the GBaseInitFunc() of TypeBClass, type_b_base_class_init()
934 * is called to allocate the dynamic members of TypeBClass (dynamic_gstring),
935 * and finally the GClassInitFunc() of TypeBClass, type_b_class_init(),
936 * is called to complete the initialization process with the static members
937 * (static_float).
938 *
939 * Corresponding finalization counter parts to the GBaseInitFunc() functions
940 * have to be provided to release allocated resources at class finalization
941 * time.
942 */
943typedef void (*GClassInitFunc) (gpointer g_class,
944 gpointer class_data);
945/**
946 * GClassFinalizeFunc:
947 * @g_class: (type GObject.TypeClass): The #GTypeClass structure to finalize
948 * @class_data: The @class_data member supplied via the #GTypeInfo structure
949 *
950 * A callback function used by the type system to finalize a class.
951 *
952 * This function is rarely needed, as dynamically allocated class resources
953 * should be handled by GBaseInitFunc() and GBaseFinalizeFunc().
954 *
955 * Also, specification of a GClassFinalizeFunc() in the #GTypeInfo
956 * structure of a static type is invalid, because classes of static types
957 * will never be finalized (they are artificially kept alive when their
958 * reference count drops to zero).
959 */
960typedef void (*GClassFinalizeFunc) (gpointer g_class,
961 gpointer class_data);
962/**
963 * GInstanceInitFunc:
964 * @instance: The instance to initialize
965 * @g_class: (type GObject.TypeClass): The class of the type the instance is
966 * created for
967 *
968 * A callback function used by the type system to initialize a new
969 * instance of a type.
970 *
971 * This function initializes all instance members and allocates any resources
972 * required by it.
973 *
974 * Initialization of a derived instance involves calling all its parent
975 * types instance initializers, so the class member of the instance
976 * is altered during its initialization to always point to the class that
977 * belongs to the type the current initializer was introduced for.
978 *
979 * The extended members of @instance are guaranteed to have been filled with
980 * zeros before this function is called.
981 */
982typedef void (*GInstanceInitFunc) (GTypeInstance *instance,
983 gpointer g_class);
984/**
985 * GInterfaceInitFunc:
986 * @g_iface: (type GObject.TypeInterface): The interface structure to initialize
987 * @iface_data: The @interface_data supplied via the #GInterfaceInfo structure
988 *
989 * A callback function used by the type system to initialize a new
990 * interface.
991 *
992 * This function should initialize all internal data and* allocate any
993 * resources required by the interface.
994 *
995 * The members of @iface_data are guaranteed to have been filled with
996 * zeros before this function is called.
997 */
998typedef void (*GInterfaceInitFunc) (gpointer g_iface,
999 gpointer iface_data);
1000/**
1001 * GInterfaceFinalizeFunc:
1002 * @g_iface: (type GObject.TypeInterface): The interface structure to finalize
1003 * @iface_data: The @interface_data supplied via the #GInterfaceInfo structure
1004 *
1005 * A callback function used by the type system to finalize an interface.
1006 *
1007 * This function should destroy any internal data and release any resources
1008 * allocated by the corresponding GInterfaceInitFunc() function.
1009 */
1010typedef void (*GInterfaceFinalizeFunc) (gpointer g_iface,
1011 gpointer iface_data);
1012/**
1013 * GTypeClassCacheFunc:
1014 * @cache_data: data that was given to the g_type_add_class_cache_func() call
1015 * @g_class: (type GObject.TypeClass): The #GTypeClass structure which is
1016 * unreferenced
1017 *
1018 * A callback function which is called when the reference count of a class
1019 * drops to zero.
1020 *
1021 * It may use g_type_class_ref() to prevent the class from being freed. You
1022 * should not call g_type_class_unref() from a #GTypeClassCacheFunc function
1023 * to prevent infinite recursion, use g_type_class_unref_uncached() instead.
1024 *
1025 * The functions have to check the class id passed in to figure
1026 * whether they actually want to cache the class of this type, since all
1027 * classes are routed through the same #GTypeClassCacheFunc chain.
1028 *
1029 * Returns: %TRUE to stop further #GTypeClassCacheFuncs from being
1030 * called, %FALSE to continue
1031 */
1032typedef gboolean (*GTypeClassCacheFunc) (gpointer cache_data,
1033 GTypeClass *g_class);
1034/**
1035 * GTypeInterfaceCheckFunc:
1036 * @check_data: data passed to g_type_add_interface_check()
1037 * @g_iface: (type GObject.TypeInterface): the interface that has been
1038 * initialized
1039 *
1040 * A callback called after an interface vtable is initialized.
1041 *
1042 * See g_type_add_interface_check().
1043 *
1044 * Since: 2.4
1045 */
1046typedef void (*GTypeInterfaceCheckFunc) (gpointer check_data,
1047 gpointer g_iface);
1048/**
1049 * GTypeFundamentalFlags:
1050 * @G_TYPE_FLAG_CLASSED: Indicates a classed type
1051 * @G_TYPE_FLAG_INSTANTIATABLE: Indicates an instantiatable type (implies classed)
1052 * @G_TYPE_FLAG_DERIVABLE: Indicates a flat derivable type
1053 * @G_TYPE_FLAG_DEEP_DERIVABLE: Indicates a deep derivable type (implies derivable)
1054 *
1055 * Bit masks used to check or determine specific characteristics of a
1056 * fundamental type.
1057 */
1058typedef enum /*< skip >*/
1059{
1060 /* There is no G_TYPE_FUNDAMENTAL_FLAGS_NONE: this is implemented to use
1061 * the same bits as GTypeFlags */
1062 G_TYPE_FLAG_CLASSED = (1 << 0),
1063 G_TYPE_FLAG_INSTANTIATABLE = (1 << 1),
1064 G_TYPE_FLAG_DERIVABLE = (1 << 2),
1065 G_TYPE_FLAG_DEEP_DERIVABLE = (1 << 3)
1066} GTypeFundamentalFlags;
1067/**
1068 * GTypeFlags:
1069 * @G_TYPE_FLAG_NONE: No special flags. Since: 2.74
1070 * @G_TYPE_FLAG_ABSTRACT: Indicates an abstract type. No instances can be
1071 * created for an abstract type
1072 * @G_TYPE_FLAG_VALUE_ABSTRACT: Indicates an abstract value type, i.e. a type
1073 * that introduces a value table, but can't be used for
1074 * g_value_init()
1075 * @G_TYPE_FLAG_FINAL: Indicates a final type. A final type is a non-derivable
1076 * leaf node in a deep derivable type hierarchy tree. Since: 2.70
1077 * @G_TYPE_FLAG_DEPRECATED: The type is deprecated and may be removed in a
1078 * future version. A warning will be emitted if it is instantiated while
1079 * running with `G_ENABLE_DIAGNOSTIC=1`. Since 2.76
1080 *
1081 * Bit masks used to check or determine characteristics of a type.
1082 */
1083typedef enum /*< skip >*/
1084{
1085 G_TYPE_FLAG_NONE GOBJECT_AVAILABLE_ENUMERATOR_IN_2_74 = 0,
1086 G_TYPE_FLAG_ABSTRACT = (1 << 4),
1087 G_TYPE_FLAG_VALUE_ABSTRACT = (1 << 5),
1088 G_TYPE_FLAG_FINAL GOBJECT_AVAILABLE_ENUMERATOR_IN_2_70 = (1 << 6),
1089 G_TYPE_FLAG_DEPRECATED GOBJECT_AVAILABLE_ENUMERATOR_IN_2_76 = (1 << 7)
1090} GTypeFlags;
1091/**
1092 * GTypeInfo:
1093 * @class_size: Size of the class structure (required for interface, classed and instantiatable types)
1094 * @base_init: Location of the base initialization function (optional)
1095 * @base_finalize: Location of the base finalization function (optional)
1096 * @class_init: Location of the class initialization function for
1097 * classed and instantiatable types. Location of the default vtable
1098 * inititalization function for interface types. (optional) This function
1099 * is used both to fill in virtual functions in the class or default vtable,
1100 * and to do type-specific setup such as registering signals and object
1101 * properties.
1102 * @class_finalize: Location of the class finalization function for
1103 * classed and instantiatable types. Location of the default vtable
1104 * finalization function for interface types. (optional)
1105 * @class_data: User-supplied data passed to the class init/finalize functions
1106 * @instance_size: Size of the instance (object) structure (required for instantiatable types only)
1107 * @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 this field is ignored.
1108 * @instance_init: Location of the instance initialization function (optional, for instantiatable types only)
1109 * @value_table: A #GTypeValueTable function table for generic handling of GValues
1110 * of this type (usually only useful for fundamental types)
1111 *
1112 * This structure is used to provide the type system with the information
1113 * required to initialize and destruct (finalize) a type's class and
1114 * its instances.
1115 *
1116 * The initialized structure is passed to the g_type_register_static() function
1117 * (or is copied into the provided #GTypeInfo structure in the
1118 * g_type_plugin_complete_type_info()). The type system will perform a deep
1119 * copy of this structure, so its memory does not need to be persistent
1120 * across invocation of g_type_register_static().
1121 */
1122struct _GTypeInfo
1123{
1124 /* interface types, classed types, instantiated types */
1125 guint16 class_size;
1126
1127 GBaseInitFunc base_init;
1128 GBaseFinalizeFunc base_finalize;
1129
1130 /* interface types, classed types, instantiated types */
1131 GClassInitFunc class_init;
1132 GClassFinalizeFunc class_finalize;
1133 gconstpointer class_data;
1134
1135 /* instantiated types */
1136 guint16 instance_size;
1137 guint16 n_preallocs;
1138 GInstanceInitFunc instance_init;
1139
1140 /* value handling */
1141 const GTypeValueTable *value_table;
1142};
1143/**
1144 * GTypeFundamentalInfo:
1145 * @type_flags: #GTypeFundamentalFlags describing the characteristics of the fundamental type
1146 *
1147 * A structure that provides information to the type system which is
1148 * used specifically for managing fundamental types.
1149 */
1150struct _GTypeFundamentalInfo
1151{
1152 GTypeFundamentalFlags type_flags;
1153};
1154/**
1155 * GInterfaceInfo:
1156 * @interface_init: location of the interface initialization function
1157 * @interface_finalize: location of the interface finalization function
1158 * @interface_data: user-supplied data passed to the interface init/finalize functions
1159 *
1160 * A structure that provides information to the type system which is
1161 * used specifically for managing interface types.
1162 */
1163struct _GInterfaceInfo
1164{
1165 GInterfaceInitFunc interface_init;
1166 GInterfaceFinalizeFunc interface_finalize;
1167 gpointer interface_data;
1168};
1169
1170/**
1171 * GTypeValueInitFunc:
1172 * @value: the value to initialize
1173 *
1174 * Initializes the value contents by setting the fields of the `value->data`
1175 * array.
1176 *
1177 * The data array of the #GValue passed into this function was zero-filled
1178 * with `memset()`, so no care has to be taken to free any old contents.
1179 * For example, in the case of a string value that may never be %NULL, the
1180 * implementation might look like:
1181 *
1182 * |[<!-- language="C" -->
1183 * value->data[0].v_pointer = g_strdup ("");
1184 * ]|
1185 *
1186 * Since: 2.78
1187 */
1188GOBJECT_AVAILABLE_TYPE_IN_2_78
1189typedef void (* GTypeValueInitFunc) (GValue *value);
1190
1191/**
1192 * GTypeValueFreeFunc:
1193 * @value: the value to free
1194 *
1195 * Frees any old contents that might be left in the `value->data` array of
1196 * the given value.
1197 *
1198 * No resources may remain allocated through the #GValue contents after this
1199 * function returns. E.g. for our above string type:
1200 *
1201 * |[<!-- language="C" -->
1202 * // only free strings without a specific flag for static storage
1203 * if (!(value->data[1].v_uint & G_VALUE_NOCOPY_CONTENTS))
1204 * g_free (value->data[0].v_pointer);
1205 * ]|
1206 *
1207 * Since: 2.78
1208 */
1209GOBJECT_AVAILABLE_TYPE_IN_2_78
1210typedef void (* GTypeValueFreeFunc) (GValue *value);
1211
1212/**
1213 * GTypeValueCopyFunc:
1214 * @src_value: the value to copy
1215 * @dest_value: (out): the location of the copy
1216 *
1217 * Copies the content of a #GValue into another.
1218 *
1219 * The @dest_value is a #GValue with zero-filled data section and @src_value
1220 * is a properly initialized #GValue of same type, or derived type.
1221 *
1222 * The purpose of this function is to copy the contents of @src_value
1223 * into @dest_value in a way, that even after @src_value has been freed, the
1224 * contents of @dest_value remain valid. String type example:
1225 *
1226 * |[<!-- language="C" -->
1227 * dest_value->data[0].v_pointer = g_strdup (src_value->data[0].v_pointer);
1228 * ]|
1229 *
1230 * Since: 2.78
1231 */
1232GOBJECT_AVAILABLE_TYPE_IN_2_78
1233typedef void (* GTypeValueCopyFunc) (const GValue *src_value,
1234 GValue *dest_value);
1235
1236/**
1237 * GTypeValuePeekPointerFunc:
1238 * @value: the value to peek
1239 *
1240 * If the value contents fit into a pointer, such as objects or strings,
1241 * return this pointer, so the caller can peek at the current contents.
1242 *
1243 * To extend on our above string example:
1244 *
1245 * |[<!-- language="C" -->
1246 * return value->data[0].v_pointer;
1247 * ]|
1248 *
1249 * Returns: (transfer none): a pointer to the value contents
1250 *
1251 * Since: 2.78
1252 */
1253GOBJECT_AVAILABLE_TYPE_IN_2_78
1254typedef gpointer (* GTypeValuePeekPointerFunc) (const GValue *value);
1255
1256/**
1257 * GTypeValueCollectFunc:
1258 * @value: the value to initialize
1259 * @n_collect_values: the number of collected values
1260 * @collect_values: (array length=n_collect_values): the collected values
1261 * @collect_flags: optional flags
1262 *
1263 * This function is responsible for converting the values collected from
1264 * a variadic argument list into contents suitable for storage in a #GValue.
1265 *
1266 * This function should setup @value similar to #GTypeValueInitFunc; e.g.
1267 * for a string value that does not allow `NULL` pointers, it needs to either
1268 * emit an error, or do an implicit conversion by storing an empty string.
1269 *
1270 * The @value passed in to this function has a zero-filled data array, so
1271 * just like for #GTypeValueInitFunc it is guaranteed to not contain any old
1272 * contents that might need freeing.
1273 *
1274 * The @n_collect_values argument is the string length of the `collect_format`
1275 * field of #GTypeValueTable, and `collect_values` is an array of #GTypeCValue
1276 * with length of @n_collect_values, containing the collected values according
1277 * to `collect_format`.
1278 *
1279 * The @collect_flags argument provided as a hint by the caller. It may
1280 * contain the flag %G_VALUE_NOCOPY_CONTENTS indicating that the collected
1281 * value contents may be considered ‘static’ for the duration of the @value
1282 * lifetime. Thus an extra copy of the contents stored in @collect_values is
1283 * not required for assignment to @value.
1284 *
1285 * For our above string example, we continue with:
1286 *
1287 * |[<!-- language="C" -->
1288 * if (!collect_values[0].v_pointer)
1289 * value->data[0].v_pointer = g_strdup ("");
1290 * else if (collect_flags & G_VALUE_NOCOPY_CONTENTS)
1291 * {
1292 * value->data[0].v_pointer = collect_values[0].v_pointer;
1293 * // keep a flag for the value_free() implementation to not free this string
1294 * value->data[1].v_uint = G_VALUE_NOCOPY_CONTENTS;
1295 * }
1296 * else
1297 * value->data[0].v_pointer = g_strdup (collect_values[0].v_pointer);
1298 * return NULL;
1299 * ]|
1300 *
1301 * It should be noted, that it is generally a bad idea to follow the
1302 * %G_VALUE_NOCOPY_CONTENTS hint for reference counted types. Due to
1303 * reentrancy requirements and reference count assertions performed
1304 * by the signal emission code, reference counts should always be
1305 * incremented for reference counted contents stored in the `value->data`
1306 * array. To deviate from our string example for a moment, and taking
1307 * a look at an exemplary implementation for `GTypeValueTable.collect_value()`
1308 * of `GObject`:
1309 *
1310 * |[<!-- language="C" -->
1311 * GObject *object = G_OBJECT (collect_values[0].v_pointer);
1312 * g_return_val_if_fail (object != NULL,
1313 * g_strdup_printf ("Object %p passed as invalid NULL pointer", object));
1314 * // never honour G_VALUE_NOCOPY_CONTENTS for ref-counted types
1315 * value->data[0].v_pointer = g_object_ref (object);
1316 * return NULL;
1317 * ]|
1318 *
1319 * The reference count for valid objects is always incremented, regardless
1320 * of `collect_flags`. For invalid objects, the example returns a newly
1321 * allocated string without altering `value`.
1322 *
1323 * Upon success, `collect_value()` needs to return `NULL`. If, however,
1324 * an error condition occurred, `collect_value()` should return a newly
1325 * allocated string containing an error diagnostic.
1326 *
1327 * The calling code makes no assumptions about the `value` contents being
1328 * valid upon error returns, `value` is simply thrown away without further
1329 * freeing. As such, it is a good idea to not allocate `GValue` contents
1330 * prior to returning an error; however, `collect_values()` is not obliged
1331 * to return a correctly setup @value for error returns, simply because
1332 * any non-`NULL` return is considered a fatal programming error, and
1333 * further program behaviour is undefined.
1334 *
1335 * Returns: (transfer full) (nullable): `NULL` on success, otherwise a
1336 * newly allocated error string on failure
1337 *
1338 * Since: 2.78
1339 */
1340GOBJECT_AVAILABLE_TYPE_IN_2_78
1341typedef gchar * (* GTypeValueCollectFunc) (GValue *value,
1342 guint n_collect_values,
1343 GTypeCValue *collect_values,
1344 guint collect_flags);
1345
1346/**
1347 * GTypeValueLCopyFunc:
1348 * @value: the value to lcopy
1349 * @n_collect_values: the number of collected values
1350 * @collect_values: (array length=n_collect_values): the collected
1351 * locations for storage
1352 * @collect_flags: optional flags
1353 *
1354 * This function is responsible for storing the `value`
1355 * contents into arguments passed through a variadic argument list which
1356 * got collected into `collect_values` according to `lcopy_format`.
1357 *
1358 * The `n_collect_values` argument equals the string length of
1359 * `lcopy_format`, and `collect_flags` may contain %G_VALUE_NOCOPY_CONTENTS.
1360 *
1361 * In contrast to #GTypeValueCollectFunc, this function is obliged to always
1362 * properly support %G_VALUE_NOCOPY_CONTENTS.
1363 *
1364 * Similar to #GTypeValueCollectFunc the function may prematurely abort by
1365 * returning a newly allocated string describing an error condition. To
1366 * complete the string example:
1367 *
1368 * |[<!-- language="C" -->
1369 * gchar **string_p = collect_values[0].v_pointer;
1370 * g_return_val_if_fail (string_p != NULL,
1371 * g_strdup ("string location passed as NULL"));
1372 *
1373 * if (collect_flags & G_VALUE_NOCOPY_CONTENTS)
1374 * *string_p = value->data[0].v_pointer;
1375 * else
1376 * *string_p = g_strdup (value->data[0].v_pointer);
1377 * ]|
1378 *
1379 * And an illustrative version of this function for reference-counted
1380 * types:
1381 *
1382 * |[<!-- language="C" -->
1383 * GObject **object_p = collect_values[0].v_pointer;
1384 * g_return_val_if_fail (object_p != NULL,
1385 * g_strdup ("object location passed as NULL"));
1386 *
1387 * if (value->data[0].v_pointer == NULL)
1388 * *object_p = NULL;
1389 * else if (collect_flags & G_VALUE_NOCOPY_CONTENTS) // always honour
1390 * *object_p = value->data[0].v_pointer;
1391 * else
1392 * *object_p = g_object_ref (value->data[0].v_pointer);
1393 *
1394 * return NULL;
1395 * ]|
1396 *
1397 * Returns: (transfer full) (nullable): `NULL` on success, otherwise
1398 * a newly allocated error string on failure
1399 *
1400 * Since: 2.78
1401 */
1402GOBJECT_AVAILABLE_TYPE_IN_2_78
1403typedef gchar * (* GTypeValueLCopyFunc) (const GValue *value,
1404 guint n_collect_values,
1405 GTypeCValue *collect_values,
1406 guint collect_flags);
1407
1408/**
1409 * GTypeValueTable:
1410 * @value_init: Function to initialize a GValue
1411 * @value_free: Function to free a GValue
1412 * @value_copy: Function to copy a GValue
1413 * @value_peek_pointer: Function to peek the contents of a GValue if they fit
1414 * into a pointer
1415 * @collect_format: A string format describing how to collect the contents of
1416 * this value bit-by-bit. Each character in the format represents
1417 * an argument to be collected, and the characters themselves indicate
1418 * the type of the argument. Currently supported arguments are:
1419 * - `'i'`: Integers, passed as `collect_values[].v_int`
1420 * - `'l'`: Longs, passed as `collect_values[].v_long`
1421 * - `'d'`: Doubles, passed as `collect_values[].v_double`
1422 * - `'p'`: Pointers, passed as `collect_values[].v_pointer`
1423 * It should be noted that for variable argument list construction,
1424 * ANSI C promotes every type smaller than an integer to an int, and
1425 * floats to doubles. So for collection of short int or char, `'i'`
1426 * needs to be used, and for collection of floats `'d'`.
1427 * @collect_value: Function to initialize a GValue from the values
1428 * collected from variadic arguments
1429 * @lcopy_format: Format description of the arguments to collect for @lcopy_value,
1430 * analogous to @collect_format. Usually, @lcopy_format string consists
1431 * only of `'p'`s to provide lcopy_value() with pointers to storage locations.
1432 * @lcopy_value: Function to store the contents of a value into the
1433 * locations collected from variadic arguments
1434 *
1435 * The #GTypeValueTable provides the functions required by the #GValue
1436 * implementation, to serve as a container for values of a type.
1437 */
1438G_GNUC_BEGIN_IGNORE_DEPRECATIONS
1439struct _GTypeValueTable
1440{
1441 GTypeValueInitFunc value_init;
1442 GTypeValueFreeFunc value_free;
1443 GTypeValueCopyFunc value_copy;
1444 GTypeValuePeekPointerFunc value_peek_pointer;
1445
1446 const gchar *collect_format;
1447 GTypeValueCollectFunc collect_value;
1448
1449 const gchar *lcopy_format;
1450 GTypeValueLCopyFunc lcopy_value;
1451};
1452G_GNUC_END_IGNORE_DEPRECATIONS
1453
1454GOBJECT_AVAILABLE_IN_ALL
1455GType g_type_register_static (GType parent_type,
1456 const gchar *type_name,
1457 const GTypeInfo *info,
1458 GTypeFlags flags);
1459GOBJECT_AVAILABLE_IN_ALL
1460GType g_type_register_static_simple (GType parent_type,
1461 const gchar *type_name,
1462 guint class_size,
1463 GClassInitFunc class_init,
1464 guint instance_size,
1465 GInstanceInitFunc instance_init,
1466 GTypeFlags flags);
1467
1468GOBJECT_AVAILABLE_IN_ALL
1469GType g_type_register_dynamic (GType parent_type,
1470 const gchar *type_name,
1471 GTypePlugin *plugin,
1472 GTypeFlags flags);
1473GOBJECT_AVAILABLE_IN_ALL
1474GType g_type_register_fundamental (GType type_id,
1475 const gchar *type_name,
1476 const GTypeInfo *info,
1477 const GTypeFundamentalInfo *finfo,
1478 GTypeFlags flags);
1479GOBJECT_AVAILABLE_IN_ALL
1480void g_type_add_interface_static (GType instance_type,
1481 GType interface_type,
1482 const GInterfaceInfo *info);
1483GOBJECT_AVAILABLE_IN_ALL
1484void g_type_add_interface_dynamic (GType instance_type,
1485 GType interface_type,
1486 GTypePlugin *plugin);
1487GOBJECT_AVAILABLE_IN_ALL
1488void g_type_interface_add_prerequisite (GType interface_type,
1489 GType prerequisite_type);
1490GOBJECT_AVAILABLE_IN_ALL
1491GType*g_type_interface_prerequisites (GType interface_type,
1492 guint *n_prerequisites);
1493GOBJECT_AVAILABLE_IN_2_68
1494GType g_type_interface_instantiatable_prerequisite
1495 (GType interface_type);
1496GOBJECT_DEPRECATED_IN_2_58
1497void g_type_class_add_private (gpointer g_class,
1498 gsize private_size);
1499GOBJECT_AVAILABLE_IN_2_38
1500gint g_type_add_instance_private (GType class_type,
1501 gsize private_size);
1502GOBJECT_AVAILABLE_IN_ALL
1503gpointer g_type_instance_get_private (GTypeInstance *instance,
1504 GType private_type);
1505GOBJECT_AVAILABLE_IN_2_38
1506void g_type_class_adjust_private_offset (gpointer g_class,
1507 gint *private_size_or_offset);
1508
1509GOBJECT_AVAILABLE_IN_ALL
1510void g_type_add_class_private (GType class_type,
1511 gsize private_size);
1512GOBJECT_AVAILABLE_IN_ALL
1513gpointer g_type_class_get_private (GTypeClass *klass,
1514 GType private_type);
1515GOBJECT_AVAILABLE_IN_2_38
1516gint g_type_class_get_instance_private_offset (gpointer g_class);
1517
1518GOBJECT_AVAILABLE_IN_2_34
1519void g_type_ensure (GType type);
1520GOBJECT_AVAILABLE_IN_2_36
1521guint g_type_get_type_registration_serial (void);
1522
1523
1524/* --- GType boilerplate --- */
1525/**
1526 * G_DECLARE_FINAL_TYPE:
1527 * @ModuleObjName: The name of the new type, in camel case (like `GtkWidget`)
1528 * @module_obj_name: The name of the new type in lowercase, with words
1529 * separated by `_` (like `gtk_widget`)
1530 * @MODULE: The name of the module, in all caps (like `GTK`)
1531 * @OBJ_NAME: The bare name of the type, in all caps (like `WIDGET`)
1532 * @ParentName: the name of the parent type, in camel case (like `GtkWidget`)
1533 *
1534 * A convenience macro for emitting the usual declarations in the header file
1535 * for a type which is not (at the present time) intended to be subclassed.
1536 *
1537 * You might use it in a header as follows:
1538 *
1539 * |[<!-- language="C" -->
1540 * #ifndef _myapp_window_h_
1541 * #define _myapp_window_h_
1542 *
1543 * #include <gtk/gtk.h>
1544 *
1545 * #define MY_APP_TYPE_WINDOW my_app_window_get_type ()
1546 * G_DECLARE_FINAL_TYPE (MyAppWindow, my_app_window, MY_APP, WINDOW, GtkWindow)
1547 *
1548 * MyAppWindow * my_app_window_new (void);
1549 *
1550 * ...
1551 *
1552 * #endif
1553 * ]|
1554 *
1555 * And use it as follow in your C file:
1556 *
1557 * |[<!-- language="C" -->
1558 * struct _MyAppWindow
1559 * {
1560 * GtkWindow parent;
1561 * ...
1562 * };
1563 * G_DEFINE_TYPE (MyAppWindow, my_app_window, GTK_TYPE_WINDOW)
1564 * ]|
1565 *
1566 * This results in the following things happening:
1567 *
1568 * - the usual `my_app_window_get_type()` function is declared with a return type of #GType
1569 *
1570 * - the `MyAppWindow` type is defined as a `typedef` of `struct _MyAppWindow`. The struct itself is not
1571 * defined and should be defined from the .c file before G_DEFINE_TYPE() is used.
1572 *
1573 * - the `MY_APP_WINDOW()` cast is emitted as `static inline` function along with the `MY_APP_IS_WINDOW()` type
1574 * checking function
1575 *
1576 * - the `MyAppWindowClass` type is defined as a struct containing `GtkWindowClass`. This is done for the
1577 * convenience of the person defining the type and should not be considered to be part of the ABI. In
1578 * particular, without a firm declaration of the instance structure, it is not possible to subclass the type
1579 * and therefore the fact that the size of the class structure is exposed is not a concern and it can be
1580 * freely changed at any point in the future.
1581 *
1582 * - g_autoptr() support being added for your type, based on the type of your parent class
1583 *
1584 * You can only use this function if your parent type also supports g_autoptr().
1585 *
1586 * Because the type macro (`MY_APP_TYPE_WINDOW` in the above example) is not a callable, you must continue to
1587 * manually define this as a macro for yourself.
1588 *
1589 * The declaration of the `_get_type()` function is the first thing emitted by the macro. This allows this macro
1590 * to be used in the usual way with export control and API versioning macros.
1591 *
1592 * If you want to declare your own class structure, use G_DECLARE_DERIVABLE_TYPE().
1593 *
1594 * If you are writing a library, it is important to note that it is possible to convert a type from using
1595 * G_DECLARE_FINAL_TYPE() to G_DECLARE_DERIVABLE_TYPE() without breaking API or ABI. As a precaution, you
1596 * should therefore use G_DECLARE_FINAL_TYPE() until you are sure that it makes sense for your class to be
1597 * subclassed. Once a class structure has been exposed it is not possible to change its size or remove or
1598 * reorder items without breaking the API and/or ABI.
1599 *
1600 * Since: 2.44
1601 **/
1602#define G_DECLARE_FINAL_TYPE(ModuleObjName, module_obj_name, MODULE, OBJ_NAME, ParentName) \
1603 GType module_obj_name##_get_type (void); \
1604 G_GNUC_BEGIN_IGNORE_DEPRECATIONS \
1605 typedef struct _##ModuleObjName ModuleObjName; \
1606 typedef struct { ParentName##Class parent_class; } ModuleObjName##Class; \
1607 \
1608 _GLIB_DEFINE_AUTOPTR_CHAINUP (ModuleObjName, ParentName) \
1609 G_DEFINE_AUTOPTR_CLEANUP_FUNC (ModuleObjName##Class, g_type_class_unref) \
1610 \
1611 G_GNUC_UNUSED static inline ModuleObjName * MODULE##_##OBJ_NAME (gpointer ptr) { \
1612 return G_TYPE_CHECK_INSTANCE_CAST (ptr, module_obj_name##_get_type (), ModuleObjName); } \
1613 G_GNUC_UNUSED static inline gboolean MODULE##_IS_##OBJ_NAME (gpointer ptr) { \
1614 return G_TYPE_CHECK_INSTANCE_TYPE (ptr, module_obj_name##_get_type ()); } \
1615 G_GNUC_END_IGNORE_DEPRECATIONS
1616
1617/**
1618 * G_DECLARE_DERIVABLE_TYPE:
1619 * @ModuleObjName: The name of the new type, in camel case (like `GtkWidget`)
1620 * @module_obj_name: The name of the new type in lowercase, with words
1621 * separated by `_` (like `gtk_widget`)
1622 * @MODULE: The name of the module, in all caps (like `GTK`)
1623 * @OBJ_NAME: The bare name of the type, in all caps (like `WIDGET`)
1624 * @ParentName: the name of the parent type, in camel case (like `GtkWidget`)
1625 *
1626 * A convenience macro for emitting the usual declarations in the
1627 * header file for a type which is intended to be subclassed.
1628 *
1629 * You might use it in a header as follows:
1630 *
1631 * |[<!-- language="C" -->
1632 * #ifndef _gtk_frobber_h_
1633 * #define _gtk_frobber_h_
1634 *
1635 * #define GTK_TYPE_FROBBER gtk_frobber_get_type ()
1636 * GDK_AVAILABLE_IN_3_12
1637 * G_DECLARE_DERIVABLE_TYPE (GtkFrobber, gtk_frobber, GTK, FROBBER, GtkWidget)
1638 *
1639 * struct _GtkFrobberClass
1640 * {
1641 * GtkWidgetClass parent_class;
1642 *
1643 * void (* handle_frob) (GtkFrobber *frobber,
1644 * guint n_frobs);
1645 *
1646 * gpointer padding[12];
1647 * };
1648 *
1649 * GtkWidget * gtk_frobber_new (void);
1650 *
1651 * ...
1652 *
1653 * #endif
1654 * ]|
1655 *
1656 * Since the instance structure is public it is often needed to declare a
1657 * private struct as follow in your C file:
1658 *
1659 * |[<!-- language="C" -->
1660 * typedef struct _GtkFrobberPrivate GtkFrobberPrivate;
1661 * struct _GtkFrobberPrivate
1662 * {
1663 * ...
1664 * };
1665 * G_DEFINE_TYPE_WITH_PRIVATE (GtkFrobber, gtk_frobber, GTK_TYPE_WIDGET)
1666 * ]|
1667 *
1668 * This results in the following things happening:
1669 *
1670 * - the usual `gtk_frobber_get_type()` function is declared with a return type of #GType
1671 *
1672 * - the `GtkFrobber` struct is created with `GtkWidget` as the first and only item. You are expected to use
1673 * a private structure from your .c file to store your instance variables.
1674 *
1675 * - the `GtkFrobberClass` type is defined as a typedef to `struct _GtkFrobberClass`, which is left undefined.
1676 * You should do this from the header file directly after you use the macro.
1677 *
1678 * - the `GTK_FROBBER()` and `GTK_FROBBER_CLASS()` casts are emitted as `static inline` functions along with
1679 * the `GTK_IS_FROBBER()` and `GTK_IS_FROBBER_CLASS()` type checking functions and `GTK_FROBBER_GET_CLASS()`
1680 * function.
1681 *
1682 * - g_autoptr() support being added for your type, based on the type of your parent class
1683 *
1684 * You can only use this function if your parent type also supports g_autoptr().
1685 *
1686 * Because the type macro (`GTK_TYPE_FROBBER` in the above example) is not a callable, you must continue to
1687 * manually define this as a macro for yourself.
1688 *
1689 * The declaration of the `_get_type()` function is the first thing emitted by the macro. This allows this macro
1690 * to be used in the usual way with export control and API versioning macros.
1691 *
1692 * If you are writing a library, it is important to note that it is possible to convert a type from using
1693 * G_DECLARE_FINAL_TYPE() to G_DECLARE_DERIVABLE_TYPE() without breaking API or ABI. As a precaution, you
1694 * should therefore use G_DECLARE_FINAL_TYPE() until you are sure that it makes sense for your class to be
1695 * subclassed. Once a class structure has been exposed it is not possible to change its size or remove or
1696 * reorder items without breaking the API and/or ABI. If you want to declare your own class structure, use
1697 * G_DECLARE_DERIVABLE_TYPE(). If you want to declare a class without exposing the class or instance
1698 * structures, use G_DECLARE_FINAL_TYPE().
1699 *
1700 * If you must use G_DECLARE_DERIVABLE_TYPE() you should be sure to include some padding at the bottom of your
1701 * class structure to leave space for the addition of future virtual functions.
1702 *
1703 * Since: 2.44
1704 **/
1705#define G_DECLARE_DERIVABLE_TYPE(ModuleObjName, module_obj_name, MODULE, OBJ_NAME, ParentName) \
1706 GType module_obj_name##_get_type (void); \
1707 G_GNUC_BEGIN_IGNORE_DEPRECATIONS \
1708 typedef struct _##ModuleObjName ModuleObjName; \
1709 typedef struct _##ModuleObjName##Class ModuleObjName##Class; \
1710 struct _##ModuleObjName { ParentName parent_instance; }; \
1711 \
1712 _GLIB_DEFINE_AUTOPTR_CHAINUP (ModuleObjName, ParentName) \
1713 G_DEFINE_AUTOPTR_CLEANUP_FUNC (ModuleObjName##Class, g_type_class_unref) \
1714 \
1715 G_GNUC_UNUSED static inline ModuleObjName * MODULE##_##OBJ_NAME (gpointer ptr) { \
1716 return G_TYPE_CHECK_INSTANCE_CAST (ptr, module_obj_name##_get_type (), ModuleObjName); } \
1717 G_GNUC_UNUSED static inline ModuleObjName##Class * MODULE##_##OBJ_NAME##_CLASS (gpointer ptr) { \
1718 return G_TYPE_CHECK_CLASS_CAST (ptr, module_obj_name##_get_type (), ModuleObjName##Class); } \
1719 G_GNUC_UNUSED static inline gboolean MODULE##_IS_##OBJ_NAME (gpointer ptr) { \
1720 return G_TYPE_CHECK_INSTANCE_TYPE (ptr, module_obj_name##_get_type ()); } \
1721 G_GNUC_UNUSED static inline gboolean MODULE##_IS_##OBJ_NAME##_CLASS (gpointer ptr) { \
1722 return G_TYPE_CHECK_CLASS_TYPE (ptr, module_obj_name##_get_type ()); } \
1723 G_GNUC_UNUSED static inline ModuleObjName##Class * MODULE##_##OBJ_NAME##_GET_CLASS (gpointer ptr) { \
1724 return G_TYPE_INSTANCE_GET_CLASS (ptr, module_obj_name##_get_type (), ModuleObjName##Class); } \
1725 G_GNUC_END_IGNORE_DEPRECATIONS
1726
1727/**
1728 * G_DECLARE_INTERFACE:
1729 * @ModuleObjName: The name of the new type, in camel case (like `GtkWidget`)
1730 * @module_obj_name: The name of the new type in lowercase, with words
1731 * separated by `_` (like `gtk_widget`)
1732 * @MODULE: The name of the module, in all caps (like `GTK`)
1733 * @OBJ_NAME: The bare name of the type, in all caps (like `WIDGET`)
1734 * @PrerequisiteName: the name of the prerequisite type, in camel case (like `GtkWidget`)
1735 *
1736 * A convenience macro for emitting the usual declarations in the header file for a #GInterface type.
1737 *
1738 * You might use it in a header as follows:
1739 *
1740 * |[<!-- language="C" -->
1741 * #ifndef _my_model_h_
1742 * #define _my_model_h_
1743 *
1744 * #define MY_TYPE_MODEL my_model_get_type ()
1745 * GDK_AVAILABLE_IN_3_12
1746 * G_DECLARE_INTERFACE (MyModel, my_model, MY, MODEL, GObject)
1747 *
1748 * struct _MyModelInterface
1749 * {
1750 * GTypeInterface g_iface;
1751 *
1752 * gpointer (* get_item) (MyModel *model);
1753 * };
1754 *
1755 * gpointer my_model_get_item (MyModel *model);
1756 *
1757 * ...
1758 *
1759 * #endif
1760 * ]|
1761 *
1762 * And use it as follow in your C file:
1763 *
1764 * |[<!-- language="C" -->
1765 * G_DEFINE_INTERFACE (MyModel, my_model, G_TYPE_OBJECT);
1766 *
1767 * static void
1768 * my_model_default_init (MyModelInterface *iface)
1769 * {
1770 * ...
1771 * }
1772 * ]|
1773 *
1774 * This results in the following things happening:
1775 *
1776 * - the usual `my_model_get_type()` function is declared with a return type of #GType
1777 *
1778 * - the `MyModelInterface` type is defined as a typedef to `struct _MyModelInterface`,
1779 * which is left undefined. You should do this from the header file directly after
1780 * you use the macro.
1781 *
1782 * - the `MY_MODEL()` cast is emitted as `static inline` functions along with
1783 * the `MY_IS_MODEL()` type checking function and `MY_MODEL_GET_IFACE()` function.
1784 *
1785 * - g_autoptr() support being added for your type, based on your prerequisite type.
1786 *
1787 * You can only use this function if your prerequisite type also supports g_autoptr().
1788 *
1789 * Because the type macro (`MY_TYPE_MODEL` in the above example) is not a callable, you must continue to
1790 * manually define this as a macro for yourself.
1791 *
1792 * The declaration of the `_get_type()` function is the first thing emitted by the macro. This allows this macro
1793 * to be used in the usual way with export control and API versioning macros.
1794 *
1795 * Since: 2.44
1796 **/
1797#define G_DECLARE_INTERFACE(ModuleObjName, module_obj_name, MODULE, OBJ_NAME, PrerequisiteName) \
1798 GType module_obj_name##_get_type (void); \
1799 G_GNUC_BEGIN_IGNORE_DEPRECATIONS \
1800 typedef struct _##ModuleObjName ModuleObjName; \
1801 typedef struct _##ModuleObjName##Interface ModuleObjName##Interface; \
1802 \
1803 _GLIB_DEFINE_AUTOPTR_CHAINUP (ModuleObjName, PrerequisiteName) \
1804 \
1805 G_GNUC_UNUSED static inline ModuleObjName * MODULE##_##OBJ_NAME (gpointer ptr) { \
1806 return G_TYPE_CHECK_INSTANCE_CAST (ptr, module_obj_name##_get_type (), ModuleObjName); } \
1807 G_GNUC_UNUSED static inline gboolean MODULE##_IS_##OBJ_NAME (gpointer ptr) { \
1808 return G_TYPE_CHECK_INSTANCE_TYPE (ptr, module_obj_name##_get_type ()); } \
1809 G_GNUC_UNUSED static inline ModuleObjName##Interface * MODULE##_##OBJ_NAME##_GET_IFACE (gpointer ptr) { \
1810 return G_TYPE_INSTANCE_GET_INTERFACE (ptr, module_obj_name##_get_type (), ModuleObjName##Interface); } \
1811 G_GNUC_END_IGNORE_DEPRECATIONS
1812
1813/**
1814 * G_DEFINE_TYPE:
1815 * @TN: The name of the new type, in Camel case.
1816 * @t_n: The name of the new type, in lowercase, with words
1817 * separated by `_`.
1818 * @T_P: The #GType of the parent type.
1819 *
1820 * A convenience macro for type implementations, which declares a class
1821 * initialization function, an instance initialization function (see #GTypeInfo
1822 * for information about these) and a static variable named `t_n_parent_class`
1823 * pointing to the parent class. Furthermore, it defines a `*_get_type()` function.
1824 * See G_DEFINE_TYPE_EXTENDED() for an example.
1825 *
1826 * Since: 2.4
1827 */
1828#define G_DEFINE_TYPE(TN, t_n, T_P) G_DEFINE_TYPE_EXTENDED (TN, t_n, T_P, 0, {})
1829/**
1830 * G_DEFINE_TYPE_WITH_CODE:
1831 * @TN: The name of the new type, in Camel case.
1832 * @t_n: The name of the new type in lowercase, with words separated by `_`.
1833 * @T_P: The #GType of the parent type.
1834 * @_C_: Custom code that gets inserted in the `*_get_type()` function.
1835 *
1836 * A convenience macro for type implementations.
1837 *
1838 * Similar to G_DEFINE_TYPE(), but allows you to insert custom code into the
1839 * `*_get_type()` function, e.g. interface implementations via G_IMPLEMENT_INTERFACE().
1840 * See G_DEFINE_TYPE_EXTENDED() for an example.
1841 *
1842 * Since: 2.4
1843 */
1844#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()
1845/**
1846 * G_DEFINE_TYPE_WITH_PRIVATE:
1847 * @TN: The name of the new type, in Camel case.
1848 * @t_n: The name of the new type, in lowercase, with words
1849 * separated by `_`.
1850 * @T_P: The #GType of the parent type.
1851 *
1852 * A convenience macro for type implementations, which declares a class
1853 * initialization function, an instance initialization function (see #GTypeInfo
1854 * for information about these), a static variable named `t_n_parent_class`
1855 * pointing to the parent class, and adds private instance data to the type.
1856 *
1857 * Furthermore, it defines a `*_get_type()` function. See G_DEFINE_TYPE_EXTENDED()
1858 * for an example.
1859 *
1860 * Note that private structs added with this macros must have a struct
1861 * name of the form `TN ## Private`.
1862 *
1863 * The private instance data can be retrieved using the automatically generated
1864 * getter function `t_n_get_instance_private()`.
1865 *
1866 * See also: G_ADD_PRIVATE()
1867 *
1868 * Since: 2.38
1869 */
1870#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))
1871/**
1872 * G_DEFINE_ABSTRACT_TYPE:
1873 * @TN: The name of the new type, in Camel case.
1874 * @t_n: The name of the new type, in lowercase, with words
1875 * separated by `_`.
1876 * @T_P: The #GType of the parent type.
1877 *
1878 * A convenience macro for type implementations.
1879 *
1880 * Similar to G_DEFINE_TYPE(), but defines an abstract type.
1881 * See G_DEFINE_TYPE_EXTENDED() for an example.
1882 *
1883 * Since: 2.4
1884 */
1885#define G_DEFINE_ABSTRACT_TYPE(TN, t_n, T_P) G_DEFINE_TYPE_EXTENDED (TN, t_n, T_P, G_TYPE_FLAG_ABSTRACT, {})
1886/**
1887 * G_DEFINE_ABSTRACT_TYPE_WITH_CODE:
1888 * @TN: The name of the new type, in Camel case.
1889 * @t_n: The name of the new type, in lowercase, with words
1890 * separated by `_`.
1891 * @T_P: The #GType of the parent type.
1892 * @_C_: Custom code that gets inserted in the `type_name_get_type()` function.
1893 *
1894 * A convenience macro for type implementations.
1895 *
1896 * Similar to G_DEFINE_TYPE_WITH_CODE(), but defines an abstract type and
1897 * allows you to insert custom code into the `*_get_type()` function, e.g.
1898 * interface implementations via G_IMPLEMENT_INTERFACE().
1899 *
1900 * See G_DEFINE_TYPE_EXTENDED() for an example.
1901 *
1902 * Since: 2.4
1903 */
1904#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()
1905/**
1906 * G_DEFINE_ABSTRACT_TYPE_WITH_PRIVATE:
1907 * @TN: The name of the new type, in Camel case.
1908 * @t_n: The name of the new type, in lowercase, with words
1909 * separated by `_`.
1910 * @T_P: The #GType of the parent type.
1911 *
1912 * Similar to G_DEFINE_TYPE_WITH_PRIVATE(), but defines an abstract type.
1913 *
1914 * See G_DEFINE_TYPE_EXTENDED() for an example.
1915 *
1916 * Since: 2.38
1917 */
1918#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))
1919/**
1920 * G_DEFINE_FINAL_TYPE:
1921 * @TN: the name of the new type, in Camel case
1922 * @t_n: the name of the new type, in lower case, with words
1923 * separated by `_` (snake case)
1924 * @T_P: the #GType of the parent type
1925 *
1926 * A convenience macro for type implementations.
1927 *
1928 * Similar to G_DEFINE_TYPE(), but defines a final type.
1929 *
1930 * See G_DEFINE_TYPE_EXTENDED() for an example.
1931 *
1932 * Since: 2.70
1933 */
1934#define G_DEFINE_FINAL_TYPE(TN, t_n, T_P) G_DEFINE_TYPE_EXTENDED (TN, t_n, T_P, G_TYPE_FLAG_FINAL, {}) GOBJECT_AVAILABLE_MACRO_IN_2_70
1935/**
1936 * G_DEFINE_FINAL_TYPE_WITH_CODE:
1937 * @TN: the name of the new type, in Camel case
1938 * @t_n: the name of the new type, in lower case, with words
1939 * separated by `_` (snake case)
1940 * @T_P: the #GType of the parent type
1941 * @_C_: Custom code that gets inserted in the `type_name_get_type()` function.
1942 *
1943 * A convenience macro for type implementations.
1944 *
1945 * Similar to G_DEFINE_TYPE_WITH_CODE(), but defines a final type and
1946 * allows you to insert custom code into the `*_get_type()` function, e.g.
1947 * interface implementations via G_IMPLEMENT_INTERFACE().
1948 *
1949 * See G_DEFINE_TYPE_EXTENDED() for an example.
1950 *
1951 * Since: 2.70
1952 */
1953#define G_DEFINE_FINAL_TYPE_WITH_CODE(TN, t_n, T_P, _C_) _G_DEFINE_TYPE_EXTENDED_BEGIN (TN, t_n, T_P, G_TYPE_FLAG_FINAL) {_C_;} _G_DEFINE_TYPE_EXTENDED_END() GOBJECT_AVAILABLE_MACRO_IN_2_70
1954/**
1955 * G_DEFINE_FINAL_TYPE_WITH_PRIVATE:
1956 * @TN: the name of the new type, in Camel case
1957 * @t_n: the name of the new type, in lower case, with words
1958 * separated by `_` (snake case)
1959 * @T_P: the #GType of the parent type
1960 *
1961 * A convenience macro for type implementations.
1962 *
1963 * Similar to G_DEFINE_TYPE_WITH_PRIVATE(), but defines a final type.
1964 *
1965 * See G_DEFINE_TYPE_EXTENDED() for an example.
1966 *
1967 * Since: 2.70
1968 */
1969#define G_DEFINE_FINAL_TYPE_WITH_PRIVATE(TN, t_n, T_P) G_DEFINE_TYPE_EXTENDED (TN, t_n, T_P, G_TYPE_FLAG_FINAL, G_ADD_PRIVATE (TN)) GOBJECT_AVAILABLE_MACRO_IN_2_70
1970/**
1971 * G_DEFINE_TYPE_EXTENDED:
1972 * @TN: The name of the new type, in Camel case.
1973 * @t_n: The name of the new type, in lowercase, with words
1974 * separated by `_`.
1975 * @T_P: The #GType of the parent type.
1976 * @_f_: #GTypeFlags to pass to g_type_register_static()
1977 * @_C_: Custom code that gets inserted in the `*_get_type()` function.
1978 *
1979 * The most general convenience macro for type implementations, on which
1980 * G_DEFINE_TYPE(), etc are based.
1981 *
1982 * |[<!-- language="C" -->
1983 * G_DEFINE_TYPE_EXTENDED (GtkGadget,
1984 * gtk_gadget,
1985 * GTK_TYPE_WIDGET,
1986 * 0,
1987 * G_ADD_PRIVATE (GtkGadget)
1988 * G_IMPLEMENT_INTERFACE (TYPE_GIZMO,
1989 * gtk_gadget_gizmo_init));
1990 * ]|
1991 *
1992 * expands to
1993 *
1994 * |[<!-- language="C" -->
1995 * static void gtk_gadget_init (GtkGadget *self);
1996 * static void gtk_gadget_class_init (GtkGadgetClass *klass);
1997 * static gpointer gtk_gadget_parent_class = NULL;
1998 * static gint GtkGadget_private_offset;
1999 * static void gtk_gadget_class_intern_init (gpointer klass)
2000 * {
2001 * gtk_gadget_parent_class = g_type_class_peek_parent (klass);
2002 * if (GtkGadget_private_offset != 0)
2003 * g_type_class_adjust_private_offset (klass, &GtkGadget_private_offset);
2004 * gtk_gadget_class_init ((GtkGadgetClass*) klass);
2005 * }
2006 * static inline gpointer gtk_gadget_get_instance_private (GtkGadget *self)
2007 * {
2008 * return (G_STRUCT_MEMBER_P (self, GtkGadget_private_offset));
2009 * }
2010 *
2011 * GType
2012 * gtk_gadget_get_type (void)
2013 * {
2014 * static GType static_g_define_type_id = 0;
2015 * if (g_once_init_enter_pointer (&static_g_define_type_id))
2016 * {
2017 * GType g_define_type_id =
2018 * g_type_register_static_simple (GTK_TYPE_WIDGET,
2019 * g_intern_static_string ("GtkGadget"),
2020 * sizeof (GtkGadgetClass),
2021 * (GClassInitFunc) gtk_gadget_class_intern_init,
2022 * sizeof (GtkGadget),
2023 * (GInstanceInitFunc) gtk_gadget_init,
2024 * 0);
2025 * {
2026 * GtkGadget_private_offset =
2027 * g_type_add_instance_private (g_define_type_id, sizeof (GtkGadgetPrivate));
2028 * }
2029 * {
2030 * const GInterfaceInfo g_implement_interface_info = {
2031 * (GInterfaceInitFunc) gtk_gadget_gizmo_init
2032 * };
2033 * g_type_add_interface_static (g_define_type_id, TYPE_GIZMO, &g_implement_interface_info);
2034 * }
2035 * g_once_init_leave_pointer (&static_g_define_type_id, g_define_type_id);
2036 * }
2037 * return static_g_define_type_id;
2038 * }
2039 * ]|
2040 *
2041 * The only pieces which have to be manually provided are the definitions of
2042 * the instance and class structure and the definitions of the instance and
2043 * class init functions.
2044 *
2045 * Since: 2.4
2046 */
2047#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()
2048
2049/**
2050 * G_DEFINE_INTERFACE:
2051 * @TN: The name of the new type, in Camel case.
2052 * @t_n: The name of the new type, in lowercase, with words separated by `_`.
2053 * @T_P: The #GType of the prerequisite type for the interface, or %G_TYPE_INVALID
2054 * for no prerequisite type.
2055 *
2056 * A convenience macro for #GTypeInterface definitions, which declares
2057 * a default vtable initialization function and defines a `*_get_type()`
2058 * function.
2059 *
2060 * The macro expects the interface initialization function to have the
2061 * name `t_n ## _default_init`, and the interface structure to have the
2062 * name `TN ## Interface`.
2063 *
2064 * The initialization function has signature
2065 * `static void t_n ## _default_init (TypeName##Interface *klass);`, rather than
2066 * the full #GInterfaceInitFunc signature, for brevity and convenience. If you
2067 * need to use an initialization function with an `iface_data` argument, you
2068 * must write the #GTypeInterface definitions manually.
2069 *
2070 * Since: 2.24
2071 */
2072#define G_DEFINE_INTERFACE(TN, t_n, T_P) G_DEFINE_INTERFACE_WITH_CODE(TN, t_n, T_P, ;)
2073
2074/**
2075 * G_DEFINE_INTERFACE_WITH_CODE:
2076 * @TN: The name of the new type, in Camel case.
2077 * @t_n: The name of the new type, in lowercase, with words separated by `_`.
2078 * @T_P: The #GType of the prerequisite type for the interface, or %G_TYPE_INVALID
2079 * for no prerequisite type.
2080 * @_C_: Custom code that gets inserted in the `*_get_type()` function.
2081 *
2082 * A convenience macro for #GTypeInterface definitions.
2083 *
2084 * Similar to G_DEFINE_INTERFACE(), but allows you to insert custom code
2085 * into the `*_get_type()` function, e.g. additional interface implementations
2086 * via G_IMPLEMENT_INTERFACE(), or additional prerequisite types.
2087 *
2088 * See G_DEFINE_TYPE_EXTENDED() for a similar example using
2089 * G_DEFINE_TYPE_WITH_CODE().
2090 *
2091 * Since: 2.24
2092 */
2093#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()
2094
2095/**
2096 * G_IMPLEMENT_INTERFACE:
2097 * @TYPE_IFACE: The #GType of the interface to add
2098 * @iface_init: (type GInterfaceInitFunc): The interface init function, of type #GInterfaceInitFunc
2099 *
2100 * A convenience macro to ease interface addition in the `_C_` section
2101 * of G_DEFINE_TYPE_WITH_CODE() or G_DEFINE_ABSTRACT_TYPE_WITH_CODE().
2102 * See G_DEFINE_TYPE_EXTENDED() for an example.
2103 *
2104 * Note that this macro can only be used together with the `G_DEFINE_TYPE_*`
2105 * macros, since it depends on variable names from those macros.
2106 *
2107 * Since: 2.4
2108 */
2109#define G_IMPLEMENT_INTERFACE(TYPE_IFACE, iface_init) { \
2110 const GInterfaceInfo g_implement_interface_info = { \
2111 (GInterfaceInitFunc)(void (*)(void)) iface_init, NULL, NULL \
2112 }; \
2113 g_type_add_interface_static (g_define_type_id, TYPE_IFACE, &g_implement_interface_info); \
2114}
2115
2116/**
2117 * G_ADD_PRIVATE:
2118 * @TypeName: the name of the type in CamelCase
2119 *
2120 * A convenience macro to ease adding private data to instances of a new type
2121 * in the @_C_ section of G_DEFINE_TYPE_WITH_CODE() or
2122 * G_DEFINE_ABSTRACT_TYPE_WITH_CODE().
2123 *
2124 * For instance:
2125 *
2126 * |[<!-- language="C" -->
2127 * typedef struct _MyObject MyObject;
2128 * typedef struct _MyObjectClass MyObjectClass;
2129 *
2130 * typedef struct {
2131 * gint foo;
2132 * gint bar;
2133 * } MyObjectPrivate;
2134 *
2135 * G_DEFINE_TYPE_WITH_CODE (MyObject, my_object, G_TYPE_OBJECT,
2136 * G_ADD_PRIVATE (MyObject))
2137 * ]|
2138 *
2139 * Will add `MyObjectPrivate` as the private data to any instance of the
2140 * `MyObject` type.
2141 *
2142 * `G_DEFINE_TYPE_*` macros will automatically create a private function
2143 * based on the arguments to this macro, which can be used to safely
2144 * retrieve the private data from an instance of the type; for instance:
2145 *
2146 * |[<!-- language="C" -->
2147 * gint
2148 * my_object_get_foo (MyObject *obj)
2149 * {
2150 * MyObjectPrivate *priv = my_object_get_instance_private (obj);
2151 *
2152 * g_return_val_if_fail (MY_IS_OBJECT (obj), 0);
2153 *
2154 * return priv->foo;
2155 * }
2156 *
2157 * void
2158 * my_object_set_bar (MyObject *obj,
2159 * gint bar)
2160 * {
2161 * MyObjectPrivate *priv = my_object_get_instance_private (obj);
2162 *
2163 * g_return_if_fail (MY_IS_OBJECT (obj));
2164 *
2165 * if (priv->bar != bar)
2166 * priv->bar = bar;
2167 * }
2168 * ]|
2169 *
2170 * Since GLib 2.72, the returned `MyObjectPrivate` pointer is guaranteed to be
2171 * aligned to at least the alignment of the largest basic GLib type (typically
2172 * this is #guint64 or #gdouble). If you need larger alignment for an element in
2173 * the struct, you should allocate it on the heap (aligned), or arrange for your
2174 * `MyObjectPrivate` struct to be appropriately padded.
2175 *
2176 * Note that this macro can only be used together with the `G_DEFINE_TYPE_*`
2177 * macros, since it depends on variable names from those macros.
2178 *
2179 * Also note that private structs added with these macros must have a struct
2180 * name of the form `TypeNamePrivate`.
2181 *
2182 * It is safe to call the `_get_instance_private` function on %NULL or invalid
2183 * objects since it's only adding an offset to the instance pointer. In that
2184 * case the returned pointer must not be dereferenced.
2185 *
2186 * Since: 2.38
2187 */
2188#define G_ADD_PRIVATE(TypeName) { \
2189 TypeName##_private_offset = \
2190 g_type_add_instance_private (g_define_type_id, sizeof (TypeName##Private)); \
2191}
2192
2193/**
2194 * G_PRIVATE_OFFSET:
2195 * @TypeName: the name of the type in CamelCase
2196 * @field: the name of the field in the private data structure
2197 *
2198 * Evaluates to the offset of the @field inside the instance private data
2199 * structure for @TypeName.
2200 *
2201 * Note that this macro can only be used together with the `G_DEFINE_TYPE_*`
2202 * and G_ADD_PRIVATE() macros, since it depends on variable names from
2203 * those macros.
2204 *
2205 * Since: 2.38
2206 */
2207#define G_PRIVATE_OFFSET(TypeName, field) \
2208 (TypeName##_private_offset + (G_STRUCT_OFFSET (TypeName##Private, field)))
2209
2210/**
2211 * G_PRIVATE_FIELD_P:
2212 * @TypeName: the name of the type in CamelCase
2213 * @inst: the instance of @TypeName you wish to access
2214 * @field_name: the name of the field in the private data structure
2215 *
2216 * Evaluates to a pointer to the @field_name inside the @inst private data
2217 * structure for @TypeName.
2218 *
2219 * Note that this macro can only be used together with the `G_DEFINE_TYPE_*`
2220 * and G_ADD_PRIVATE() macros, since it depends on variable names from
2221 * those macros.
2222 *
2223 * Since: 2.38
2224 */
2225#define G_PRIVATE_FIELD_P(TypeName, inst, field_name) \
2226 G_STRUCT_MEMBER_P (inst, G_PRIVATE_OFFSET (TypeName, field_name))
2227
2228/**
2229 * G_PRIVATE_FIELD:
2230 * @TypeName: the name of the type in CamelCase
2231 * @inst: the instance of @TypeName you wish to access
2232 * @field_type: the type of the field in the private data structure
2233 * @field_name: the name of the field in the private data structure
2234 *
2235 * Evaluates to the @field_name inside the @inst private data
2236 * structure for @TypeName.
2237 *
2238 * Note that this macro can only be used together with the `G_DEFINE_TYPE_*`
2239 * and G_ADD_PRIVATE() macros, since it depends on variable names from
2240 * those macros.
2241 *
2242 * Since: 2.38
2243 */
2244#define G_PRIVATE_FIELD(TypeName, inst, field_type, field_name) \
2245 G_STRUCT_MEMBER (field_type, inst, G_PRIVATE_OFFSET (TypeName, field_name))
2246
2247/* we need to have this macro under conditional expansion, as it references
2248 * a function that has been added in 2.38. see bug:
2249 * https://bugzilla.gnome.org/show_bug.cgi?id=703191
2250 */
2251#if GLIB_VERSION_MAX_ALLOWED >= GLIB_VERSION_2_38
2252#define _G_DEFINE_TYPE_EXTENDED_CLASS_INIT(TypeName, type_name) \
2253static void type_name##_class_intern_init (gpointer klass) \
2254{ \
2255 type_name##_parent_class = g_type_class_peek_parent (klass); \
2256 if (TypeName##_private_offset != 0) \
2257 g_type_class_adjust_private_offset (klass, &TypeName##_private_offset); \
2258 type_name##_class_init ((TypeName##Class*) klass); \
2259}
2260
2261#else
2262#define _G_DEFINE_TYPE_EXTENDED_CLASS_INIT(TypeName, type_name) \
2263static void type_name##_class_intern_init (gpointer klass) \
2264{ \
2265 type_name##_parent_class = g_type_class_peek_parent (klass); \
2266 type_name##_class_init ((TypeName##Class*) klass); \
2267}
2268#endif /* GLIB_VERSION_MAX_ALLOWED >= GLIB_VERSION_2_38 */
2269
2270#if GLIB_VERSION_MAX_ALLOWED >= GLIB_VERSION_2_80
2271#define _g_type_once_init_type GType
2272#define _g_type_once_init_enter g_once_init_enter_pointer
2273#define _g_type_once_init_leave g_once_init_leave_pointer
2274#else /* if GLIB_VERSION_MAX_ALLOWED < GLIB_VERSION_2_80 */
2275#define _g_type_once_init_type gsize
2276#define _g_type_once_init_enter g_once_init_enter
2277#define _g_type_once_init_leave g_once_init_leave
2278#endif /* GLIB_VERSION_MAX_ALLOWED >= GLIB_VERSION_2_80 */
2279
2280/* Added for _G_DEFINE_TYPE_EXTENDED_WITH_PRELUDE */
2281#define _G_DEFINE_TYPE_EXTENDED_BEGIN_PRE(TypeName, type_name, TYPE_PARENT) \
2282\
2283static void type_name##_init (TypeName *self); \
2284static void type_name##_class_init (TypeName##Class *klass); \
2285static GType type_name##_get_type_once (void); \
2286static gpointer type_name##_parent_class = NULL; \
2287static gint TypeName##_private_offset; \
2288\
2289_G_DEFINE_TYPE_EXTENDED_CLASS_INIT(TypeName, type_name) \
2290\
2291G_GNUC_UNUSED \
2292static inline gpointer \
2293type_name##_get_instance_private (TypeName *self) \
2294{ \
2295 return (G_STRUCT_MEMBER_P (self, TypeName##_private_offset)); \
2296} \
2297\
2298GType \
2299type_name##_get_type (void) \
2300{ \
2301 static _g_type_once_init_type static_g_define_type_id = 0;
2302 /* Prelude goes here */
2303
2304/* Added for _G_DEFINE_TYPE_EXTENDED_WITH_PRELUDE */
2305#define _G_DEFINE_TYPE_EXTENDED_BEGIN_REGISTER(TypeName, type_name, TYPE_PARENT, flags) \
2306 if (_g_type_once_init_enter (&static_g_define_type_id)) \
2307 { \
2308 GType g_define_type_id = type_name##_get_type_once (); \
2309 _g_type_once_init_leave (&static_g_define_type_id, g_define_type_id); \
2310 } \
2311 return static_g_define_type_id; \
2312} /* closes type_name##_get_type() */ \
2313\
2314G_NO_INLINE \
2315static GType \
2316type_name##_get_type_once (void) \
2317{ \
2318 GType g_define_type_id = \
2319 g_type_register_static_simple (TYPE_PARENT, \
2320 g_intern_static_string (#TypeName), \
2321 sizeof (TypeName##Class), \
2322 (GClassInitFunc)(void (*)(void)) type_name##_class_intern_init, \
2323 sizeof (TypeName), \
2324 (GInstanceInitFunc)(void (*)(void)) type_name##_init, \
2325 (GTypeFlags) flags); \
2326 { /* custom code follows */
2327#define _G_DEFINE_TYPE_EXTENDED_END() \
2328 /* following custom code */ \
2329 } \
2330 return g_define_type_id; \
2331} /* closes type_name##_get_type_once() */
2332
2333/* This was defined before we had G_DEFINE_TYPE_WITH_CODE_AND_PRELUDE, it's simplest
2334 * to keep it.
2335 */
2336#define _G_DEFINE_TYPE_EXTENDED_BEGIN(TypeName, type_name, TYPE_PARENT, flags) \
2337 _G_DEFINE_TYPE_EXTENDED_BEGIN_PRE(TypeName, type_name, TYPE_PARENT) \
2338 _G_DEFINE_TYPE_EXTENDED_BEGIN_REGISTER(TypeName, type_name, TYPE_PARENT, flags) \
2339
2340/* Intentionally using (GTypeFlags) 0 instead of G_TYPE_FLAG_NONE here,
2341 * to avoid deprecation warnings with older GLIB_VERSION_MAX_ALLOWED */
2342#define _G_DEFINE_INTERFACE_EXTENDED_BEGIN(TypeName, type_name, TYPE_PREREQ) \
2343\
2344static void type_name##_default_init (TypeName##Interface *klass); \
2345\
2346GType \
2347type_name##_get_type (void) \
2348{ \
2349 static _g_type_once_init_type static_g_define_type_id = 0; \
2350 if (_g_type_once_init_enter (&static_g_define_type_id)) \
2351 { \
2352 GType g_define_type_id = \
2353 g_type_register_static_simple (G_TYPE_INTERFACE, \
2354 g_intern_static_string (#TypeName), \
2355 sizeof (TypeName##Interface), \
2356 (GClassInitFunc)(void (*)(void)) type_name##_default_init, \
2357 0, \
2358 (GInstanceInitFunc)NULL, \
2359 (GTypeFlags) 0); \
2360 if (TYPE_PREREQ != G_TYPE_INVALID) \
2361 g_type_interface_add_prerequisite (g_define_type_id, TYPE_PREREQ); \
2362 { /* custom code follows */
2363#define _G_DEFINE_INTERFACE_EXTENDED_END() \
2364 /* following custom code */ \
2365 } \
2366 _g_type_once_init_leave (&static_g_define_type_id, g_define_type_id); \
2367 } \
2368 return static_g_define_type_id; \
2369} /* closes type_name##_get_type() */
2370
2371/**
2372 * G_DEFINE_BOXED_TYPE:
2373 * @TypeName: The name of the new type, in Camel case
2374 * @type_name: The name of the new type, in lowercase, with words
2375 * separated by `_`
2376 * @copy_func: the #GBoxedCopyFunc for the new type
2377 * @free_func: the #GBoxedFreeFunc for the new type
2378 *
2379 * A convenience macro for defining a new custom boxed type.
2380 *
2381 * Using this macro is the recommended way of defining new custom boxed
2382 * types, over calling g_boxed_type_register_static() directly. It defines
2383 * a `type_name_get_type()` function which will return the newly defined
2384 * #GType, enabling lazy instantiation.
2385 *
2386 * You might start by putting declarations in a header as follows:
2387 *
2388 * |[<!-- language="C" -->
2389 * #define MY_TYPE_STRUCT my_struct_get_type ()
2390 * GType my_struct_get_type (void) G_GNUC_CONST;
2391 *
2392 * MyStruct * my_struct_new (void);
2393 * void my_struct_free (MyStruct *self);
2394 * MyStruct * my_struct_copy (MyStruct *self);
2395 * ]|
2396 *
2397 * And then use this macro and define your implementation in the source file as
2398 * follows:
2399 *
2400 * |[<!-- language="C" -->
2401 * MyStruct *
2402 * my_struct_new (void)
2403 * {
2404 * // ... your code to allocate a new MyStruct ...
2405 * }
2406 *
2407 * void
2408 * my_struct_free (MyStruct *self)
2409 * {
2410 * // ... your code to free a MyStruct ...
2411 * }
2412 *
2413 * MyStruct *
2414 * my_struct_copy (MyStruct *self)
2415 * {
2416 * // ... your code return a newly allocated copy of a MyStruct ...
2417 * }
2418 *
2419 * G_DEFINE_BOXED_TYPE (MyStruct, my_struct, my_struct_copy, my_struct_free)
2420 *
2421 * void
2422 * foo ()
2423 * {
2424 * MyStruct *ms;
2425 *
2426 * ms = my_struct_new ();
2427 * // ... your code ...
2428 * my_struct_free (ms);
2429 * }
2430 * ]|
2431 *
2432 * Since: 2.26
2433 */
2434#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, {})
2435/**
2436 * G_DEFINE_BOXED_TYPE_WITH_CODE:
2437 * @TypeName: The name of the new type, in Camel case
2438 * @type_name: The name of the new type, in lowercase, with words
2439 * separated by `_`
2440 * @copy_func: the #GBoxedCopyFunc for the new type
2441 * @free_func: the #GBoxedFreeFunc for the new type
2442 * @_C_: Custom code that gets inserted in the `*_get_type()` function
2443 *
2444 * A convenience macro for boxed type implementations.
2445 *
2446 * Similar to G_DEFINE_BOXED_TYPE(), but allows to insert custom code into the
2447 * `type_name_get_type()` function, e.g. to register value transformations with
2448 * g_value_register_transform_func(), for instance:
2449 *
2450 * |[<!-- language="C" -->
2451 * G_DEFINE_BOXED_TYPE_WITH_CODE (GdkRectangle, gdk_rectangle,
2452 * gdk_rectangle_copy,
2453 * gdk_rectangle_free,
2454 * register_rectangle_transform_funcs (g_define_type_id))
2455 * ]|
2456 *
2457 * Similarly to the `G_DEFINE_TYPE_*` family of macros, the #GType of the newly
2458 * defined boxed type is exposed in the `g_define_type_id` variable.
2459 *
2460 * Since: 2.26
2461 */
2462#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()
2463
2464/* Only use this in non-C++ on GCC >= 2.7, except for Darwin/ppc64.
2465 * See https://bugzilla.gnome.org/show_bug.cgi?id=647145
2466 */
2467#if !defined (G_CXX_STD_VERSION) && (G_GNUC_CHECK_VERSION(2, 7)) && \
2468 !(defined (__APPLE__) && defined (__ppc64__))
2469#define _G_DEFINE_BOXED_TYPE_BEGIN(TypeName, type_name, copy_func, free_func) \
2470static GType type_name##_get_type_once (void); \
2471\
2472GType \
2473type_name##_get_type (void) \
2474{ \
2475 static _g_type_once_init_type static_g_define_type_id = 0; \
2476 if (_g_type_once_init_enter (&static_g_define_type_id)) \
2477 { \
2478 GType g_define_type_id = type_name##_get_type_once (); \
2479 _g_type_once_init_leave (&static_g_define_type_id, g_define_type_id); \
2480 } \
2481 return static_g_define_type_id; \
2482} \
2483\
2484G_NO_INLINE \
2485static GType \
2486type_name##_get_type_once (void) \
2487{ \
2488 GType (* _g_register_boxed) \
2489 (const gchar *, \
2490 union \
2491 { \
2492 TypeName * (*do_copy_type) (TypeName *); \
2493 TypeName * (*do_const_copy_type) (const TypeName *); \
2494 GBoxedCopyFunc do_copy_boxed; \
2495 } __attribute__((__transparent_union__)), \
2496 union \
2497 { \
2498 void (* do_free_type) (TypeName *); \
2499 GBoxedFreeFunc do_free_boxed; \
2500 } __attribute__((__transparent_union__)) \
2501 ) = g_boxed_type_register_static; \
2502 GType g_define_type_id = \
2503 _g_register_boxed (g_intern_static_string (#TypeName), copy_func, free_func); \
2504 { /* custom code follows */
2505#else
2506#define _G_DEFINE_BOXED_TYPE_BEGIN(TypeName, type_name, copy_func, free_func) \
2507static GType type_name##_get_type_once (void); \
2508\
2509GType \
2510type_name##_get_type (void) \
2511{ \
2512 static _g_type_once_init_type static_g_define_type_id = 0; \
2513 if (_g_type_once_init_enter (&static_g_define_type_id)) \
2514 { \
2515 GType g_define_type_id = type_name##_get_type_once (); \
2516 _g_type_once_init_leave (&static_g_define_type_id, g_define_type_id); \
2517 } \
2518 return static_g_define_type_id; \
2519} \
2520\
2521G_NO_INLINE \
2522static GType \
2523type_name##_get_type_once (void) \
2524{ \
2525 GType g_define_type_id = \
2526 g_boxed_type_register_static (g_intern_static_string (#TypeName), \
2527 (GBoxedCopyFunc) copy_func, \
2528 (GBoxedFreeFunc) free_func); \
2529 { /* custom code follows */
2530#endif /* __GNUC__ */
2531
2532/**
2533 * G_DEFINE_POINTER_TYPE:
2534 * @TypeName: The name of the new type, in Camel case
2535 * @type_name: The name of the new type, in lowercase, with words
2536 * separated by `_`
2537 *
2538 * A convenience macro for pointer type implementations, which defines a
2539 * `type_name_get_type()` function registering the pointer type.
2540 *
2541 * Since: 2.26
2542 */
2543#define G_DEFINE_POINTER_TYPE(TypeName, type_name) G_DEFINE_POINTER_TYPE_WITH_CODE (TypeName, type_name, {})
2544/**
2545 * G_DEFINE_POINTER_TYPE_WITH_CODE:
2546 * @TypeName: The name of the new type, in Camel case
2547 * @type_name: The name of the new type, in lowercase, with words
2548 * separated by `_`
2549 * @_C_: Custom code that gets inserted in the `*_get_type()` function
2550 *
2551 * A convenience macro for pointer type implementations.
2552 * Similar to G_DEFINE_POINTER_TYPE(), but allows to insert
2553 * custom code into the `type_name_get_type()` function.
2554 *
2555 * Since: 2.26
2556 */
2557#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()
2558
2559#define _G_DEFINE_POINTER_TYPE_BEGIN(TypeName, type_name) \
2560static GType type_name##_get_type_once (void); \
2561\
2562GType \
2563type_name##_get_type (void) \
2564{ \
2565 static _g_type_once_init_type static_g_define_type_id = 0; \
2566 if (_g_type_once_init_enter (&static_g_define_type_id)) \
2567 { \
2568 GType g_define_type_id = type_name##_get_type_once (); \
2569 _g_type_once_init_leave (&static_g_define_type_id, g_define_type_id); \
2570 } \
2571 return static_g_define_type_id; \
2572} \
2573\
2574G_NO_INLINE \
2575static GType \
2576type_name##_get_type_once (void) \
2577{ \
2578 GType g_define_type_id = \
2579 g_pointer_type_register_static (g_intern_static_string (#TypeName)); \
2580 { /* custom code follows */
2581
2582/* --- protected (for fundamental type implementations) --- */
2583GOBJECT_AVAILABLE_IN_ALL
2584GTypePlugin* g_type_get_plugin (GType type);
2585GOBJECT_AVAILABLE_IN_ALL
2586GTypePlugin* g_type_interface_get_plugin (GType instance_type,
2587 GType interface_type);
2588GOBJECT_AVAILABLE_IN_ALL
2589GType g_type_fundamental_next (void);
2590GOBJECT_AVAILABLE_IN_ALL
2591GType g_type_fundamental (GType type_id);
2592GOBJECT_AVAILABLE_IN_ALL
2593GTypeInstance* g_type_create_instance (GType type);
2594GOBJECT_AVAILABLE_IN_ALL
2595void g_type_free_instance (GTypeInstance *instance);
2596
2597GOBJECT_AVAILABLE_IN_ALL
2598void g_type_add_class_cache_func (gpointer cache_data,
2599 GTypeClassCacheFunc cache_func);
2600GOBJECT_AVAILABLE_IN_ALL
2601void g_type_remove_class_cache_func (gpointer cache_data,
2602 GTypeClassCacheFunc cache_func);
2603GOBJECT_AVAILABLE_IN_ALL
2604void g_type_class_unref_uncached (gpointer g_class);
2605
2606GOBJECT_AVAILABLE_IN_ALL
2607void g_type_add_interface_check (gpointer check_data,
2608 GTypeInterfaceCheckFunc check_func);
2609GOBJECT_AVAILABLE_IN_ALL
2610void g_type_remove_interface_check (gpointer check_data,
2611 GTypeInterfaceCheckFunc check_func);
2612
2613GOBJECT_AVAILABLE_IN_ALL
2614GTypeValueTable* g_type_value_table_peek (GType type);
2615
2616
2617/*< private >*/
2618GOBJECT_AVAILABLE_IN_ALL
2619gboolean g_type_check_instance (GTypeInstance *instance) G_GNUC_PURE;
2620GOBJECT_AVAILABLE_IN_ALL
2621GTypeInstance* g_type_check_instance_cast (GTypeInstance *instance,
2622 GType iface_type);
2623GOBJECT_AVAILABLE_IN_ALL
2624gboolean g_type_check_instance_is_a (GTypeInstance *instance,
2625 GType iface_type) G_GNUC_PURE;
2626GOBJECT_AVAILABLE_IN_2_42
2627gboolean g_type_check_instance_is_fundamentally_a (GTypeInstance *instance,
2628 GType fundamental_type) G_GNUC_PURE;
2629GOBJECT_AVAILABLE_IN_ALL
2630GTypeClass* g_type_check_class_cast (GTypeClass *g_class,
2631 GType is_a_type);
2632GOBJECT_AVAILABLE_IN_ALL
2633gboolean g_type_check_class_is_a (GTypeClass *g_class,
2634 GType is_a_type) G_GNUC_PURE;
2635GOBJECT_AVAILABLE_IN_ALL
2636gboolean g_type_check_is_value_type (GType type) G_GNUC_CONST;
2637GOBJECT_AVAILABLE_IN_ALL
2638gboolean g_type_check_value (const GValue *value) G_GNUC_PURE;
2639GOBJECT_AVAILABLE_IN_ALL
2640gboolean g_type_check_value_holds (const GValue *value,
2641 GType type) G_GNUC_PURE;
2642GOBJECT_AVAILABLE_IN_ALL
2643gboolean g_type_test_flags (GType type,
2644 guint flags) G_GNUC_CONST;
2645
2646
2647/* --- debugging functions --- */
2648GOBJECT_AVAILABLE_IN_ALL
2649const gchar * g_type_name_from_instance (GTypeInstance *instance);
2650GOBJECT_AVAILABLE_IN_ALL
2651const gchar * g_type_name_from_class (GTypeClass *g_class);
2652
2653
2654/* --- implementation bits --- */
2655#if defined(G_DISABLE_CAST_CHECKS) || defined(__OPTIMIZE__)
2656# define _G_TYPE_CIC(ip, gt, ct) ((ct*) (void *) ip)
2657# define _G_TYPE_CCC(cp, gt, ct) ((ct*) (void *) cp)
2658#else
2659# define _G_TYPE_CIC(ip, gt, ct) \
2660 ((ct*) (void *) g_type_check_instance_cast ((GTypeInstance*) ip, gt))
2661# define _G_TYPE_CCC(cp, gt, ct) \
2662 ((ct*) (void *) g_type_check_class_cast ((GTypeClass*) cp, gt))
2663#endif
2664
2665#define _G_TYPE_CHI(ip) (g_type_check_instance ((GTypeInstance*) ip))
2666#define _G_TYPE_CHV(vl) (g_type_check_value ((GValue*) vl))
2667#define _G_TYPE_IGC(ip, gt, ct) ((ct*) (((GTypeInstance*) ip)->g_class))
2668#define _G_TYPE_IGI(ip, gt, ct) ((ct*) g_type_interface_peek (((GTypeInstance*) ip)->g_class, gt))
2669#define _G_TYPE_CIFT(ip, ft) (g_type_check_instance_is_fundamentally_a ((GTypeInstance*) ip, ft))
2670#ifdef __GNUC__
2671# define _G_TYPE_CIT(ip, gt) (G_GNUC_EXTENSION ({ \
2672 GTypeInstance *__inst = (GTypeInstance*) ip; GType __t = gt; gboolean __r; \
2673 if (!__inst) \
2674 __r = FALSE; \
2675 else if (__inst->g_class && __inst->g_class->g_type == __t) \
2676 __r = TRUE; \
2677 else \
2678 __r = g_type_check_instance_is_a (__inst, __t); \
2679 __r; \
2680}))
2681# define _G_TYPE_CCT(cp, gt) (G_GNUC_EXTENSION ({ \
2682 GTypeClass *__class = (GTypeClass*) cp; GType __t = gt; gboolean __r; \
2683 if (!__class) \
2684 __r = FALSE; \
2685 else if (__class->g_type == __t) \
2686 __r = TRUE; \
2687 else \
2688 __r = g_type_check_class_is_a (__class, __t); \
2689 __r; \
2690}))
2691# define _G_TYPE_CVH(vl, gt) (G_GNUC_EXTENSION ({ \
2692 const GValue *__val = (const GValue*) vl; GType __t = gt; gboolean __r; \
2693 if (!__val) \
2694 __r = FALSE; \
2695 else if (__val->g_type == __t) \
2696 __r = TRUE; \
2697 else \
2698 __r = g_type_check_value_holds (__val, __t); \
2699 __r; \
2700}))
2701#else /* !__GNUC__ */
2702# define _G_TYPE_CIT(ip, gt) (g_type_check_instance_is_a ((GTypeInstance*) ip, gt))
2703# define _G_TYPE_CCT(cp, gt) (g_type_check_class_is_a ((GTypeClass*) cp, gt))
2704# define _G_TYPE_CVH(vl, gt) (g_type_check_value_holds ((const GValue*) vl, gt))
2705#endif /* !__GNUC__ */
2706/**
2707 * G_TYPE_FLAG_RESERVED_ID_BIT:
2708 *
2709 * A bit in the type number that's supposed to be left untouched.
2710 */
2711#define G_TYPE_FLAG_RESERVED_ID_BIT ((GType) (1 << 0))
2712
2713/**
2714 * GPOINTER_TO_TYPE:
2715 * @p: The pointer to convert to a #GType
2716 *
2717 * This macro should be used instead of GPOINTER_TO_SIZE() to ensure
2718 * portability since #GType is not guaranteed to be the same as #gsize.
2719 *
2720 * Since: 2.80
2721 */
2722#define GPOINTER_TO_TYPE(p) ((GType) (guintptr) (p)) GOBJECT_AVAILABLE_MACRO_IN_2_80
2723/**
2724 * GTYPE_TO_POINTER:
2725 * @t: The #GType to convert to a pointer
2726 *
2727 * This macro should be used instead of GSIZE_TO_POINTER() to ensure
2728 * portability since #GType is not guaranteed to be the same as #gsize.
2729 *
2730 * Since: 2.80
2731 */
2732#define GTYPE_TO_POINTER(t) ((gpointer) (guintptr) (t)) GOBJECT_AVAILABLE_MACRO_IN_2_80
2733
2734G_END_DECLS
2735
2736#endif /* __G_TYPE_H__ */
2737