2 <title>How To ?</title>
5 This chapter tries to answer the real-life questions of users and presents
6 the most common scenario use-cases I could come up with.
7 The use-cases are presented from most likely to less likely.
14 <sect1 id="howto-gobject">
15 <title>How To define and implement a new GObject ?</title>
18 Clearly, this is one of the most common question people ask: they just want to crank code and
19 implement a subclass of a GObject. Sometimes because they want to create their own class hierarchy,
20 sometimes because they want to subclass one of GTK+'s widget. This chapter will focus on the
21 implementation of a subtype of GObject. The sample source code
22 associated to this section can be found in the documentation's source tarball, in the
23 <filename>sample/gobject</filename> directory:
25 <listitem><para><filename>maman-bar.{h|c}</filename>: this is the source for a object which derives from
26 <type>GObject</type> and which shows how to declare different types of methods on the object.
28 <listitem><para><filename>maman-subbar.{h|c}</filename>: this is the source for a object which derives from
29 <type>MamanBar</type> and which shows how to override some of its parent's methods.
31 <listitem><para><filename>maman-foo.{h|c}</filename>: this is the source for an object which derives from
32 <type>GObject</type> and which declares a signal.
34 <listitem><para><filename>test.c</filename>: this is the main source which instantiates an instance of
35 type and exercises their API.
40 <sect2 id="howto-gobject-header">
41 <title>Boilerplate header code</title>
44 The first step before writing the code for your GObject is to write the type's header which contains
45 the needed type, function and macro definitions. Each of these elements is nothing but a convention
46 which is followed not only by GTK+'s code but also by most users of GObject. If you feel the need
47 not to obey the rules stated below, think about it twice:
49 <listitem><para>If your users are a bit accustomed to GTK+ code or any Glib code, they will
50 be a bit surprised and getting used to the conventions you decided upon will take time (money) and
51 will make them grumpy (not a good thing)
54 You must assess the fact that these conventions might have been designed by both smart
55 and experienced people: maybe they were at least partly right. Try to put your ego aside.
61 Pick a name convention for your headers and source code and stick to it:
64 use a dash to separate the prefix from the typename: <filename>maman-bar.h</filename> and
65 <filename>maman-bar.c</filename> (this is the convention used by Nautilus and most Gnome libraries).
68 use an underscore to separate the prefix from the typename: <filename>maman_bar.h</filename> and
69 <filename>maman_bar.c</filename>.
72 Do not separate the prefix from the typename: <filename>mamanbar.h</filename> and
73 <filename>mamanbar.c</filename>. (this is the convention used by GTK+)
76 I personally like the first solution better: it makes reading file names easier for those with poor
81 The basic conventions for any header which exposes a GType are described in
82 <xref linkend="gtype-conventions"/>. Most GObject-based code also obeys onf of the following
83 conventions: pick one and stick to it.
86 If you want to declare a type named bar with prefix maman, name the type instance
87 <function>MamanBar</function> and its class <function>MamanBarClass</function>
88 (name is case-sensitive). It is customary to declare them with code similar to the
92 * Copyright/Licensing information.
99 * Potentially, include other headers on which this header depends.
107 typedef struct _MamanBar MamanBar;
108 typedef struct _MamanBarClass MamanBarClass;
112 /* instance members */
115 struct _MamanBarClass {
120 /* used by MAMAN_BAR_TYPE */
121 GType maman_bar_get_type (void);
124 * Method definitions.
131 Most GTK+ types declare their private fields in the public header with a /* private */ comment,
132 relying on their user's intelligence not to try to play with these fields. Fields not marked private
133 are considered public by default. The /* protected */ comment (same semantics as those of C++)
134 is also used, mainly in the GType library, in code written by Tim Janik.
145 All of Nautilus code and a lot of Gnome libraries use private indirection members, as described
146 by Herb Sutter in his Pimpl articles (see <ulink></ulink>: Herb summarizes the different
147 issues better than I will):
149 typedef struct _MamanBarPrivate MamanBarPrivate;
154 MamanBarPrivate *priv;
157 The private structure is then defined in the .c file, instantiated in the object's XXX
158 function and destroyed in the object's XXX function.
164 Finally, there are different header include conventions. Again, pick one and stick to it. I personally
165 use indifferently any of the two, depending on the codebase I work on: the rule is consistency.
168 Some people add at the top of their headers a number of #include directives to pull in
169 all the headers needed to compile client code. This allows client code to simply
170 #include "maman-bar.h".
173 Other do not #include anything and expect the client to #include themselves the headers
174 they need before including your header. This speeds up compilation because it minimizes the
175 amount of pre-processor work. This can be used in conjunction with the re-declaration of certain
176 unused types in the client code to minimize compile-time dependencies and thus speed up
184 <sect2 id="howto-gobject-code">
185 <title>Boilerplate code</title>
188 In your code, the first step is to #include the needed headers: depending on your header include strategy, this
189 can be as simple as #include "maman-bar.h" or as complicated as tens of #include lines ending with
190 #include "maman-bar.h":
193 * Copyright information
196 #include "maman-bar.h"
198 /* If you use Pimpls, include the private structure
199 * definition here. Some people create a maman-bar-private.h header
200 * which is included by the maman-bar.c file and which contains the
201 * definition for this private structure.
203 struct _MamanBarPrivate {
209 * forward definitions
215 Implement <function>maman_bar_get_type</function> and make sure the code compiles:
218 maman_bar_get_type (void)
220 static GType type = 0;
222 static const GTypeInfo info = {
223 sizeof (MamanBarClass),
224 NULL, /* base_init */
225 NULL, /* base_finalize */
226 NULL, /* class_init */
227 NULL, /* class_finalize */
228 NULL, /* class_data */
231 NULL /* instance_init */
233 type = g_type_register_static (G_TYPE_OBJECT,
243 <sect2 id="howto-gobject-construction">
244 <title>Object Construction</title>
247 People often get confused when trying to construct their GObjects because of the
248 sheer number of different ways to hook into the objects's construction process: it is
249 difficult to figure which is the <emphasis>correct</emphasis>, recommended way.
253 <xref linkend="gobject-construction-table"/> shows what user-provided functions
254 are invoked during object instanciation and in which order they are invoked.
255 A user looking for the equivalent of the simple C++ constructor function should use
256 the instance_init method. It will be invoked after all the parent's instance_init
257 functions have been invoked. It cannot take arbitrary construction parameters
258 (as in C++) but if your object needs arbitrary parameters to complete initialization,
259 you can use construction properties.
263 Construction properties will be set only after all instance_init functions have run.
264 No object reference will be returned to the client of <function>g_object_new></function>
265 until all the construction properties have been set.
269 As such, I would recommend writing the following code first:
272 maman_bar_init (GTypeInstance *instance,
275 MamanBar *self = (MamanBar *)instance;
276 self->private = g_new0 (MamanBarPrivate, 1);
278 /* initialize all public and private members to reasonable default values. */
279 /* If you need specific consruction properties to complete initialization,
280 * delay initialization completion until the property is set.
284 And make sure that you set <function>maman_bar_init</function> as the type's instance_init function
285 in <function>maman_bar_get_type</function>. Make sure the code builds and runs: create an instance
286 of the object and make sure <function>maman_bar_init</function> is called (add a
287 <function>g_print</function> call in it).
291 Now, if you need special construction properties, install the properties in the class_init function,
292 override the set and get methods and implement the get and set methods as described in
293 <xref linkend="gobject-properties"/>. Make sure that these properties use a construct only
294 <type>GParamSpec</type> by setting the param spec's flag field to G_PARAM_CONSTRUCT_ONLY: this helps
295 GType ensure that these properties are not set again later by malicious user code.
298 bar_class_init (MamanBarClass *klass)
300 GObjectClass *gobject_class = G_OBJECT_CLASS (klass);
301 GParamSpec *maman_param_spec;
303 gobject_class->set_property = bar_set_property;
304 gobject_class->get_property = bar_get_property;
306 maman_param_spec = g_param_spec_string ("maman",
307 "Maman construct prop",
309 "no-name-set" /* default value */,
310 G_PARAM_CONSTRUCT_ONLY |G_PARAM_READWRITE);
312 g_object_class_install_property (gobject_class,
317 If you need this, make sure you can build and run code similar to the code shown above. Make sure
318 your construct properties can set correctly during construction, make sure you cannot set them
319 afterwards and make sure that if your users do not call <function>g_object_new</function>
320 with the required construction properties, these will be initialized with the default values.
324 I consider good taste to halt program execution if a construction property is set its
325 default value. This allows you to catch client code which does not give a reasonable
326 value to the construction properties. Of course, you are free to disagree but you
327 should have a good reason to do so.
330 <para>Some people sometimes need to construct their object but only after the construction properties
331 have been set. This is possible through the use of the constructor class method as described in
332 <xref linkend="gobject-instanciation"/>. However, I have yet to see <emphasis>any</emphasis> reasonable
333 use of this feature. As such, to initialize your object instances, use by default the base_init function
334 and construction properties.
338 <sect2 id="howto-gobject-destruction">
339 <title>Object Destruction</title>
342 Again, it is often difficult to figure out which mechanism to use to hook into the object's
343 destruction process: when the last <function>g_object_unref</function> function call is made,
344 a lot of things happen as described in <xref linkend="gobject-destruction-table"/>.
348 The destruction process of your object must be split is two different phases: you must override
349 both the dispose and the finalize class methods.
351 struct _MamanBarPrivate {
352 gboolean dispose_has_run;
356 bar_dispose (MamanBar *self)
358 if (self->private->dispose_has_run) {
359 /* If dispose did already run, return. */
362 /* Make sure dispose does not run twice. */
363 object->private->dispose_has_run = TRUE;
366 * In dispose, you are supposed to free all types referenced from this
367 * object which might themselves hold a reference to self. Generally,
368 * the most simple solution is to unref all members on which you own a
374 bar_finalize (MamanBar *self)
377 * Here, complete object destruction.
378 * You might not need to do much...
380 g_free (self->private);
384 bar_class_init (BarClass *klass)
386 GObjectClass *gobject_class = G_OBJECT_CLASS (klass);
388 gobject_class->dispose = bar_dispose;
389 gobject_class->finalize = bar_finalize;
393 maman_bar_init (GTypeInstance *instance,
396 MamanBar *self = (MamanBar *)instance;
397 self->private = g_new0 (MamanBarPrivate, 1);
398 self->private->dispose_has_run = FALSE;
404 Add similar code to your GObject, make sure the code still builds and runs: dispose and finalize must be called
405 during the last unref.
406 It is possible that object methods might be invoked after dispose is run and before finalize runs. GObject
407 does not consider this to be a program error: you must gracefully detect this and neither crash nor warn
408 the user. To do this, you need something like the following code at the start of each object method, to make
409 sure the object's data is still valid before manipulating it:
411 if (self->private->dispose_has_run) {
412 /* Dispose has run. Data is not valid anymore. */
419 <sect2 id="howto-gobject-methods">
420 <title>Object methods</title>
423 Just as with C++, there are many different ways to define object
424 methods and extend them: the following list and sections draw on C++ vocabulary.
425 (Readers are expected to know basic C++ buzzwords. Those who have not had to
426 write C++ code recently can refer to <ulink>XXXX</ulink> to refresh their
430 non-virtual public methods,
433 virtual public methods and
436 virtual private methods
442 <title>Non-virtual public methods</title>
445 These are the simplest: you want to provide a simple method which can act on your object. All you need
446 to do is to provide a function prototype in the header and an implementation of that prototype
449 /* declaration in the header. */
450 void maman_bar_do_action (MamanBar *self, /* parameters */);
451 /* implementation in the source file */
452 void maman_bar_do_action (MamanBar *self, /* parameters */)
459 <para>There is really nothing scary about this.</para>
463 <title>Virtual public methods</title>
466 This is the preferred way to create polymorphic GObjects. All you need to do is to
467 define the common method and its class function in the public header, implement the
468 common method in the source file and re-implement the class function in each object
469 which inherits from you.
471 /* declaration in maman-bar.h. */
472 struct _MamanBarClass {
476 void (*do_action) (MamanBar *self, /* parameters */);
478 void maman_bar_do_action (MamanBar *self, /* parameters */);
479 /* implementation in maman-bar.c */
480 void maman_bar_do_action (MamanBar *self, /* parameters */)
482 MAMAN_BAR_GET_CLASS (self)->do_action (self, /* parameters */);
485 The code above simply redirects the do_action call to the relevant class function. Some users,
486 concerned about performance, do not provide the <function>maman_bar_do_action</function>
487 wrapper function and require users to de-reference the class pointer themselves. This is not such
488 a great idea in terms of encapsulation and makes it difficult to change the object's implementation
489 afterwards, should this be needed.
493 Other users, also concerned by performance issues, declare the <function>maman_bar_do_action</function>
494 function inline in the header file. This, however, makes it difficult to change the
495 object's implementation later (although easier than requiring users to directly de-reference the class
496 function) and is often difficult to write in a portable way (the <emphasis>inline</emphasis> keyword
497 is not part of the C standard).
501 In doubt, unless a user shows you hard numbers about the performance cost of the function call,
502 just <function>maman_bar_do_action</function> in the source file.
506 Please, note that it is possible for you to provide a default implementation for this class method in
507 the object's class_init function: initialize the klass->do_action field to a pointer to the actual
508 implementation. You can also make this class method pure virtual by initializing the klass->do_action
512 maman_bar_real_do_action_two (MamanBar *self, /* parameters */)
514 /* Default implementation for the virtual method. */
518 maman_bar_class_init (BarClass *klass)
520 /* pure virtual method: mandates implementation in children. */
521 klass->do_action_one = NULL;
522 /* merely virtual method. */
523 klass->do_action_two = maman_bar_real_do_action_two;
526 void maman_bar_do_action_one (MamanBar *self, /* parameters */)
528 MAMAN_BAR_GET_CLASS (self)->do_action_one (self, /* parameters */);
530 void maman_bar_do_action_two (MamanBar *self, /* parameters */)
532 MAMAN_BAR_GET_CLASS (self)->do_action_two (self, /* parameters */);
539 <title>Virtual private Methods</title>
542 These are very similar to Virtual Public methods. They just don't have a public function to call the
543 function directly. The header file contains only a declaration of the class function:
545 /* declaration in maman-bar.h. */
546 struct _MamanBarClass {
550 void (*helper_do_specific_action) (MamanBar *self, /* parameters */);
552 void maman_bar_do_any_action (MamanBar *self, /* parameters */);
554 These class functions are often used to delegate part of the job to child classes:
556 /* this accessor function is static: it is not exported outside of this file. */
558 maman_bar_do_specific_action (MamanBar *self, /* parameters */)
560 MAMAN_BAR_GET_CLASS (self)->do_specific_action (self, /* parameters */);
563 void maman_bar_do_any_action (MamanBar *self, /* parameters */)
565 /* random code here */
568 * Try to execute the requested action. Maybe the requested action cannot be implemented
569 * here. So, we delegate its implementation to the child class:
571 maman_bar_do_specific_action (self, /* parameters */);
573 /* other random code here */
579 Again, it is possible to provide a default implementation for this private virtual class function:
582 maman_bar_class_init (MamanBarClass *klass)
584 /* pure virtual method: mandates implementation in children. */
585 klass->do_specific_action_one = NULL;
586 /* merely virtual method. */
587 klass->do_specific_action_two = maman_bar_real_do_specific_action_two;
593 Children can then implement the subclass with code such as:
596 maman_bar_subtype_class_init (MamanBarSubTypeClass *klass)
598 MamanBarClass *bar_class = MAMAN_BAR_CLASS (klass);
599 /* implement pure virtual class function. */
600 bar_class->do_specific_action_one = maman_bar_subtype_do_specific_action_one;
606 Finally, it is interesting to note that, just like in C++, it is possible
607 to make each object class method chain to its parent class method:
610 maman_bar_real_do_action_two (MamanBar *self, /* parameters */)
612 MamanBarClass *bar_class = g_type_class_peek_parent (klass);
614 bar_class->do_action (self, /* parameters */);
616 /* do local stuff here. */
620 maman_bar_subtype_class_init (MamanBarSubTypeClass *klass)
622 MamanBarClass *bar_class = MAMAN_BAR_CLASS (klass);
623 /* implement pure virtual class function. */
624 bar_class->do_specific_action_one = maman_bar_subtype_do_specific_action_one;
631 <sect2 id="howto-gobject-chainup">
632 <title>Chaining up</title>
634 <p>Chaining up is commonly used to implement the Chain Of Responsability pattern in C++: each class in a
635 given inheritance hierarchy is expected to override the same method and then call from within each method
636 the overriden method of the parent. Personally, I am not sure this is a very smart idea (a detailed explanation
637 of why I think it is a bad idea would take too much space for this document) but I can show you how to do it and
641 <p>To invoke the parent method XXX</p>
656 <sect1 id="howto-interface">
657 <title>How To define and implement Interfaces ?</title>
659 <sect2 id="howto-interface-define">
660 <title>How To define Interfaces ?</title>
663 The bulk of interface definition has already been shown in <xref linkend="gtype-non-instantiable-classed"/>
664 but I feel it is needed to show exactly how to create an interface. The sample source code
665 associated to this section can be found in the documentation's source tarball, in the
666 <filename>sample/interface/maman-ibaz.{h|c}</filename> file.
670 As above, the first step is to get the header right:
675 #include <glib-object.h>
677 #define MAMAN_TYPE_IBAZ (maman_ibaz_get_type ())
678 #define MAMAN_IBAZ(obj) (G_TYPE_CHECK_INSTANCE_CAST ((obj), MAMAN_TYPE_IBAZ, MamanIbaz))
679 #define MAMAN_IBAZ_CLASS(vtable) (G_TYPE_CHECK_CLASS_CAST ((vtable), MAMAN_TYPE_IBAZ, MamanIbazClass))
680 #define MAMAN_IS_IBAZ(obj) (G_TYPE_CHECK_INSTANCE_TYPE ((obj), MAMAN_TYPE_IBAZ))
681 #define MAMAN_IS_IBAZ_CLASS(vtable) (G_TYPE_CHECK_CLASS_TYPE ((vtable), MAMAN_TYPE_IBAZ))
682 #define MAMAN_IBAZ_GET_CLASS(inst) (G_TYPE_INSTANCE_GET_INTERFACE ((inst), MAMAN_TYPE_IBAZ, MamanIbazClass))
685 typedef struct _MamanIbaz MamanIbaz; /* dummy object */
686 typedef struct _MamanIbazClass MamanIbazClass;
688 struct _MamanIbazClass {
689 GTypeInterface parent;
691 void (*do_action) (MamanIbaz *self);
694 GType maman_ibaz_get_type (void);
696 void maman_ibaz_do_action (MamanIbaz *self);
698 #endif //MAMAN_IBAZ_H
700 This code is almost exactly similar to the code for a normal <type>GType</type>
701 which derives from a <type>GObject</type> except for a few details:
704 The <function>_GET_CLASS</function> macro is not implemented with
705 <function>G_TYPE_INSTANCE_GET_CLASS</function> but with <function>G_TYPE_INSTANCE_GET_INTERFACE</function>.
708 The instance type, <type>MamanIbaz</type> is not fully defined: it is used merely as an abstract
709 type which represents an instance of whatever object which implements the interface.
715 The implementation of the <type>MamanIbaz</type> type itself is trivial:
717 <listitem><para><function>maman_ibaz_get_type</function> registers the
718 type in the type system.
720 <listitem><para><function>maman_ibaz_base_init</function> is expected
721 to register the interface's signals if there are any (we will see a bit
722 (later how to use them). Make sure to use a static local boolean variable
723 to make sure not to run the initialization code twice (as described in
724 <xref linkend="gtype-non-instantiable-classed-init"/>,
725 <function>base_init</function> is run once for each interface implementation
726 instanciation)</para></listitem>
727 <listitem><para><function>maman_ibaz_do_action</function> de-references the class
728 structure to access its associated class function and calls it.
733 maman_ibaz_base_init (gpointer g_class)
735 static gboolean initialized = FALSE;
738 /* create interface signals here. */
744 maman_ibaz_get_type (void)
746 static GType type = 0;
748 static const GTypeInfo info = {
749 sizeof (MamanIbazClass),
750 maman_ibaz_base_init, /* base_init */
751 NULL, /* base_finalize */
752 NULL, /* class_init */
753 NULL, /* class_finalize */
754 NULL, /* class_data */
757 NULL /* instance_init */
759 type = g_type_register_static (G_TYPE_INTERFACE, "MamanIbaz", &info, 0);
764 void maman_ibaz_do_action (MamanIbaz *self)
766 MAMAN_IBAZ_GET_CLASS (self)->do_action (self);
772 <sect2 id="howto-interface-implement">
773 <title>How To define and implement an implementation of an Interface ?</title>
776 Once the interface is defined, implementing it is rather trivial. Source code showing how to do this
777 for the <type>IBaz</type> interface defined in the previous section is located in
778 <filename>sample/interface/maman-baz.{h|c}</filename>.
782 The first step is to define a normal GType. Here, we have decided to use a GType which derives from
783 GObject. Its name is <type>MamanBaz</type>:
788 #include <glib-object.h>
790 #define MAMAN_TYPE_BAZ (maman_baz_get_type ())
791 #define MAMAN_BAZ(obj) (G_TYPE_CHECK_INSTANCE_CAST ((obj), MAMAN_TYPE_BAZ, Mamanbaz))
792 #define MAMAN_BAZ_CLASS(vtable) (G_TYPE_CHECK_CLASS_CAST ((vtable), MAMAN_TYPE_BAZ, MamanbazClass))
793 #define MAMAN_IS_BAZ(obj) (G_TYPE_CHECK_INSTANCE_TYPE ((obj), MAMAN_TYPE_BAZ))
794 #define MAMAN_IS_BAZ_CLASS(vtable) (G_TYPE_CHECK_CLASS_TYPE ((vtable), MAMAN_TYPE_BAZ))
795 #define MAMAN_BAZ_GET_CLASS(inst) (G_TYPE_INSTANCE_GET_CLASS ((inst), MAMAN_TYPE_BAZ, MamanbazClass))
798 typedef struct _MamanBaz MamanBaz;
799 typedef struct _MamanBazClass MamanBazClass;
806 struct _MamanBazClass {
810 GType maman_baz_get_type (void);
815 There is clearly nothing specifically weird or scary about this header: it does not define any weird API
816 or derives from a weird type.
820 The second step is to implement <function>maman_baz_get_type</function>:
823 maman_baz_get_type (void)
825 static GType type = 0;
827 static const GTypeInfo info = {
828 sizeof (MamanBazClass),
829 NULL, /* base_init */
830 NULL, /* base_finalize */
831 NULL, /* class_init */
832 NULL, /* class_finalize */
833 NULL, /* class_data */
836 baz_instance_init /* instance_init */
838 static const GInterfaceInfo ibaz_info = {
839 (GInterfaceInitFunc) baz_interface_init, /* interface_init */
840 NULL, /* interface_finalize */
841 NULL /* interface_data */
843 type = g_type_register_static (G_TYPE_OBJECT,
846 g_type_add_interface_static (type,
853 This function is very much like all the similar functions we looked at previously. The only interface-specific
854 code present here is the call to <function>g_type_add_interface_static</function> which is used to inform
855 the type system that this just-registered <type>GType</type> also implements the interface
856 <function>MAMAN_TYPE_IBAZ</function>.
860 <function>baz_interface_init</function>, the interface initialization function, is also pretty simple:
862 static void baz_do_action (MamanBaz *self)
864 g_print ("Baz implementation of IBaz interface Action: 0x%x.\n", self->instance_member);
867 baz_interface_init (gpointer g_iface,
870 MamanIbazClass *klass = (MamanIbazClass *)g_iface;
871 klass->do_action = (void (*) (MamanIbaz *self))baz_do_action;
874 baz_instance_init (GTypeInstance *instance,
877 MamanBaz *self = (MamanBaz *)instance;
878 self->instance_member = 0xdeadbeaf;
881 <function>baz_interface_init</function> merely initializes the interface methods to the implementations
882 defined by <type>MamanBaz</type>: <function>maman_baz_do_action</function> does nothing very useful
889 <title>Interface definition prerequisites</title>
893 <para>To specify that an interface requires the presence of other interfaces when implemented,
894 GObject introduces the concept of <emphasis>prerequisites</emphasis>: it is possible to associate
895 a list of prerequisite interfaces to an interface. For example, if object A wishes to implement interface
896 I1, and if interface I1 has a prerequisite on interface I2, A has to implement both I1 and I2.
899 <para>The mechanism described above is, in practice, very similar to Java's interface I1 extends
900 interface I2. The example below shows the GObject equivalent:
903 type = g_type_register_static (G_TYPE_INTERFACE, "MamanIbar", &info, 0);
904 /* Make the MamanIbar interface require MamanIbaz interface. */
905 g_type_interface_add_prerequisite (type, MAMAN_TYPE_IBAZ);
907 The code shown above adds the MamanIbaz interface to the list of prerequisites of MamanIbar while the
908 code below shows how an implementation can implement both interfaces and register their implementations:
910 static void ibar_do_another_action (MamanBar *self)
912 g_print ("Bar implementation of IBar interface Another Action: 0x%x.\n", self->instance_member);
916 ibar_interface_init (gpointer g_iface,
919 MamanIbarClass *klass = (MamanIbarClass *)g_iface;
920 klass->do_another_action = (void (*) (MamanIbar *self))ibar_do_another_action;
924 static void ibaz_do_action (MamanBar *self)
926 g_print ("Bar implementation of IBaz interface Action: 0x%x.\n", self->instance_member);
930 ibaz_interface_init (gpointer g_iface,
933 MamanIbazClass *klass = (MamanIbazClass *)g_iface;
934 klass->do_action = (void (*) (MamanIbaz *self))ibaz_do_action;
939 bar_instance_init (GTypeInstance *instance,
942 MamanBar *self = (MamanBar *)instance;
943 self->instance_member = 0x666;
948 maman_bar_get_type (void)
950 static GType type = 0;
952 static const GTypeInfo info = {
953 sizeof (MamanBarClass),
954 NULL, /* base_init */
955 NULL, /* base_finalize */
956 NULL, /* class_init */
957 NULL, /* class_finalize */
958 NULL, /* class_data */
961 bar_instance_init /* instance_init */
963 static const GInterfaceInfo ibar_info = {
964 (GInterfaceInitFunc) ibar_interface_init, /* interface_init */
965 NULL, /* interface_finalize */
966 NULL /* interface_data */
968 static const GInterfaceInfo ibaz_info = {
969 (GInterfaceInitFunc) ibaz_interface_init, /* interface_init */
970 NULL, /* interface_finalize */
971 NULL /* interface_data */
973 type = g_type_register_static (G_TYPE_OBJECT,
976 g_type_add_interface_static (type,
979 g_type_add_interface_static (type,
986 It is very important to notice that the order in which interface implementations are added to the main object
987 is not random: <function>g_type_interface_static</function> must be invoked first on the interfaces which have
988 no prerequisites and then on the others.
992 Complete source code showing how to define the MamanIbar interface which requires MamanIbaz and how to
993 implement the MamanIbar interface is located in <filename>sample/interface/maman-ibar.{h|c}</filename>
994 and <filename>sample/interface/maman-bar.{h|c}</filename>.
1002 End Howto Interfaces
1011 <sect1 id="howto-signals">
1012 <title>Howto create and use signals</title>
1016 The signal system which was built in GType is pretty complex and flexible: it is possible for its users
1017 to connect at runtime any number of callbacks (implemented in any language for which a binding exists)
1019 <para>A python callback can be connected to any signal on any C-based GObject.
1023 to any signal and to stop the emission of any signal at any
1024 state of the signal emission process. This flexibility makes it possible to use GSignal for much more than
1025 just emit events which can be received by numerous clients.
1029 <title>Simple use of signals</title>
1031 <para>The most basic use of signals is to implement simple event notification: for example, if we have a
1032 MamanFile object, and if this object has a write method, we might wish to be notified whenever someone
1033 uses this method. The code below shows how the user can connect a callback to the write signal. Full code
1034 for this simple example is located in <filename>sample/signal/maman-file.{h|c}</filename> and
1035 in <filename>sample/signal/test.c</filename>
1037 file = g_object_new (MAMAN_FILE_TYPE, NULL);
1039 g_signal_connect (G_OBJECT (file), "write",
1040 (GCallback)write_event,
1043 maman_file_write (file, buffer, 50);
1048 The <type>MamanFile</type> signal is registered in the class_init function:
1050 klass->write_signal_id =
1051 g_signal_newv ("write",
1052 G_TYPE_FROM_CLASS (g_class),
1053 G_SIGNAL_RUN_LAST | G_SIGNAL_NO_RECURSE | G_SIGNAL_NO_HOOKS,
1054 NULL /* class closure */,
1055 NULL /* accumulator */,
1056 NULL /* accu_data */,
1057 g_cclosure_marshal_VOID__VOID,
1058 G_TYPE_NONE /* return_type */,
1060 NULL /* param_types */);
1062 and the signal is emited in <function>maman_file_write</function>:
1064 void maman_file_write (MamanFile *self, guint8 *buffer, guint32 size)
1066 /* First write data. */
1067 /* Then, notify user of data written. */
1068 g_signal_emit (self, MAMAN_FILE_GET_CLASS (self)->write_signal_id,
1073 As shown above, you can safely set the details parameter to zero if you do not know what it can be used for.
1074 For a discussion of what you could used it for, see <xref linkend="signal-detail"/>
1084 <title>How to provide more flexibility to users ?</title>
1086 <para>The previous implementation does the job but the signal facility of GObject can be used to provide
1087 even more flexibility to this file change notification mechanism. One of the key ideas is to make the process
1088 of writing data to the file part of the signal emission process to allow users to be notified either
1089 before or after the data is written to the file.
1092 <para>To integrate the process of writing the data to the file into the signal emission mechanism, we can
1093 register a default class closure for this signal which will be invoked during the signal emission, just like
1094 any other user-connected signal handler.
1097 <para>The first step to implement this idea is to change the signature of the signal: we need to pass
1098 around the buffer to write and its size. To do this, we use our own marshaller which will be generated
1099 through glib's genmarshall tool. We thus create a file named <filename>marshall.list</filename> which contains
1100 the following single line:
1104 and use the Makefile provided in <filename>sample/signal/Makefile</filename> to generate the file named
1105 <filename>maman-file-complex-marshall.c</filename>. This C file is finally included in
1106 <filename>maman-file-complex.c</filename>.
1109 <para>Once the marshaller is present, we register the signal and its marshaller in the class_init function
1110 of the object <type>MamanFileComplex</type> (full source for this object is included in
1111 <filename>sample/signal/maman-file-complex.{h|c}</filename>):
1113 GClosure *default_closure;
1114 GType param_types[2];
1116 default_closure = g_cclosure_new (G_CALLBACK (default_write_signal_handler),
1117 (gpointer)0xdeadbeaf /* user_data */,
1118 NULL /* destroy_data */);
1120 param_types[0] = G_TYPE_POINTER;
1121 param_types[1] = G_TYPE_UINT;
1122 klass->write_signal_id =
1123 g_signal_newv ("write",
1124 G_TYPE_FROM_CLASS (g_class),
1125 G_SIGNAL_RUN_LAST | G_SIGNAL_NO_RECURSE | G_SIGNAL_NO_HOOKS,
1126 default_closure /* class closure */,
1127 NULL /* accumulator */,
1128 NULL /* accu_data */,
1129 maman_file_complex_VOID__POINTER_UINT,
1130 G_TYPE_NONE /* return_type */,
1132 param_types /* param_types */);
1134 The code shown above first creates the closure which contains the code to complete the file write. This
1135 closure is registered as the default class_closure of the newly created signal.
1139 Of course, you need to implement completely the code for the default closure since I just provided
1143 default_write_signal_handler (GObject *obj, guint8 *buffer, guint size, gpointer user_data)
1145 g_assert (user_data == (gpointer)0xdeadbeaf);
1146 /* Here, we trigger the real file write. */
1147 g_print ("default signal handler: 0x%x %u\n", buffer, size);
1152 <para>Finally, the client code must invoke the <function>maman_file_complex_write</function> function which
1153 triggers the signal emission:
1155 void maman_file_complex_write (MamanFileComplex *self, guint8 *buffer, guint size)
1158 g_signal_emit (self,
1159 MAMAN_FILE_COMPLEX_GET_CLASS (self)->write_signal_id,
1166 <para>The client code (as shown in <filename>sample/signal/test.c</filename> and below) can now connect signal handlers before
1167 and after the file write is completed: since the default signal handler which does the write itself runs during the
1168 RUN_LAST phase of the signal emission, it will run after all handlers connected with <function>g_signal_connect</function>
1169 and before all handlers connected with <function>g_signal_connect_after</function>. If you intent to write a GObject
1170 which emits signals, I would thus urge you to create all your signals with the G_SIGNAL_RUN_LAST such that your users
1171 have a maximum of flexibility as to when to get the event. Here, we combined it with G_SIGNAL_NO_RECURSE and
1172 G_SIGNAL_NO_HOOKS to ensure our users will not try to do really weird things with our GObject. I strongly advise you
1173 to do the same unless you really know why (in which case you really know the inner workings of GSignal by heart and
1174 you are not reading this).
1179 static void complex_write_event_before (GObject *file, guint8 *buffer, guint size, gpointer user_data)
1181 g_assert (user_data == NULL);
1182 g_print ("Complex Write event before: 0x%x, %u\n", buffer, size);
1185 static void complex_write_event_after (GObject *file, guint8 *buffer, guint size, gpointer user_data)
1187 g_assert (user_data == NULL);
1188 g_print ("Complex Write event after: 0x%x, %u\n", buffer, size);
1191 static void test_file_complex (void)
1196 file = g_object_new (MAMAN_FILE_COMPLEX_TYPE, NULL);
1198 g_signal_connect (G_OBJECT (file), "write",
1199 (GCallback)complex_write_event_before,
1202 g_signal_connect_after (G_OBJECT (file), "write",
1203 (GCallback)complex_write_event_after,
1206 maman_file_complex_write (MAMAN_FILE_COMPLEX (file), buffer, 50);
1208 g_object_unref (G_OBJECT (file));
1211 The code above generates the following output on my machine:
1213 Complex Write event before: 0xbfffe280, 50
1214 default signal handler: 0xbfffe280 50
1215 Complex Write event after: 0xbfffe280, 50
1221 <title>How most people do the same thing with less code</title>
1223 <para>For many historic reasons related to how the ancestor of GObject used to work in GTK+ 1.x versions,
1224 there is a much <emphasis>simpler</emphasis>
1226 <para>I personally think that this method is horribly mind-twisting: it adds a new indirection
1227 which unecessarily complicates the overall code path. However, because this method is widely used
1228 by all of GTK+ and GObject code, readers need to understand it. The reason why this is done that way
1229 in most of GTK+ is related to the fact that the ancestor of GObject did not provide any other way to
1230 create a signal with a default handler than this one. Some people have tried to justify that it is done
1231 that way because it is better, faster (I am extremly doubtfull about the faster bit. As a matter of fact,
1232 the better bit also mystifies me ;-). I have the feeling no one really knows and everyone does it
1233 because they copy/pasted code from code which did the same. It is probably better to leave this
1234 specific trivia to hacker legends domain...
1237 way to create a signal with a default handler than to create
1238 a closure by hand and to use the <function>g_signal_newv</function>.
1241 <para>For example, <function>g_signal_new</function> can be used to create a signal which uses a default
1242 handler which is stored in the class structure of the object. More specifically, the class structure
1243 contains a function pointer which is accessed during signal emission to invoke the default handler and
1244 the user is expected to provide to <function>g_signal_new</function> the offset from the start of the
1245 class structure to the function pointer.
1247 <para>I would like to point out here that the reason why the default handler of a signal is named everywhere
1248 a class_closure is probably related to the fact that it used to be really a function pointer stored in
1249 the class structure.
1254 <para>The following code shows the declaration of the <type>MamanFileSimple</type> class structure which contains
1255 the <function>write</function> function pointer.
1257 struct _MamanFileSimpleClass {
1258 GObjectClass parent;
1260 guint write_signal_id;
1262 /* signal default handlers */
1263 void (*write) (MamanFileSimple *self, guint8 *buffer, guint size);
1266 The <function>write</function> function pointer is initialied in the class_init function of the object
1267 to <function>default_write_signal_handler</function>:
1270 maman_file_simple_class_init (gpointer g_class,
1271 gpointer g_class_data)
1273 GObjectClass *gobject_class = G_OBJECT_CLASS (g_class);
1274 MamanFileSimpleClass *klass = MAMAN_FILE_SIMPLE_CLASS (g_class);
1276 klass->write = default_write_signal_handler;
1278 Finally, the signal is created with <function>g_signal_new</function> in the same class_init function:
1280 klass->write_signal_id =
1281 g_signal_new ("write",
1282 G_TYPE_FROM_CLASS (g_class),
1283 G_SIGNAL_RUN_LAST | G_SIGNAL_NO_RECURSE | G_SIGNAL_NO_HOOKS,
1284 G_STRUCT_OFFSET (MamanFileSimpleClass, write),
1285 NULL /* accumulator */,
1286 NULL /* accu_data */,
1287 maman_file_complex_VOID__POINTER_UINT,
1288 G_TYPE_NONE /* return_type */,
1293 Of note, here, is the 4th argument to the function: it is an integer calculated by the <function>G_STRUCT_OFFSET</function>
1294 macro which indicates the offset of the member <emphasis>write</emphasis> from the start of the
1295 <type>MamanFileSimpleClass</type> class structure.
1297 <para>GSignal uses this offset to create a special wrapper closure
1298 which first retrieves the target function pointer before calling it.
1304 While the complete code for this type of default handler looks less clutered as shown in
1305 <filename>sample/signal/maman-file-simple.{h|c}</filename>, it contains numerous subtleties.
1306 The main subtle point which everyone must be aware of is that the signature of the default
1307 handler created that way does not have a user_data argument:
1308 <function>default_write_signal_handler</function> is different in
1309 <filename>sample/signal/maman-file-complex.c</filename> and in
1310 <filename>sample/signal/maman-file-simple.c</filename>.
1313 <para>If you have doubts about which method to use, I would advise you to use the second one which
1314 involves <function>g_signal_new</function> rather than <function>g_signal_newv</function>:
1315 it is better to write code which looks like the vast majority of other GTK+/Gobject code than to
1316 do it your own way. However, now, you know why.
1327 <title>How users can abuse signals (and why some think it is good)</title>
1329 <para>Now that you know how to create signals to which the users can connect easily and at any point in
1330 the signal emission process thanks to <function>g_signal_connect</function>,
1331 <function>g_signal_connect_after</function> and G_SIGNAL_RUN_LAST, it is time to look into how your
1332 users can and will screw you. This is also interesting to know how you too, can screw other people.
1333 This will make you feel good and eleet.
1336 <para>The users can:
1338 <listitem><para>stop the emission of the signal at anytime</para></listitem>
1339 <listitem><para>override the default handler of the signal if it is stored as a function
1340 pointer in the class structure (which is the prefered way to create a default signal handler,
1341 as discussed in the previous section).</para></listitem>
1345 <para>In both cases, the original programmer should be as careful as possible to write code which is
1346 resistant to the fact that the default handler of the signal might not able to run. This is obviously
1347 not the case in the example used in the previous sections since the write to the file depends on whether
1348 or not the default handler runs (however, this might be your goal: to allow the user to prevent the file
1349 write if he wishes to).
1352 <para>If all you want to do is to stop the signal emission from one of the callbacks you connected yourself,
1353 you can call <function>g_signal_stop_by_name</function>. Its use is very simple which is why I won't detail
1357 <para>If the signal's default handler is just a class function pointer, it is also possible to override
1358 it yourself from the class_init function of a type which derives from the parent. That way, when the signal
1359 is emitted, the parent class will use the function provided by the child as a signal default handler.
1360 Of course, it is also possible (and recommended) to chain up from the child to the parent's default signal
1361 handler to ensure the integrity of the parent object.
1364 <para>Overriding a class method and chaining up was demonstrated in <xref linkend="howto-gobject-methods"/>
1365 which is why I won't bother to show exactly how to do it here again.</para>
1374 <title>Warning on signal creation and default closure</title>
1377 Most of the existing code I have seen up to now (in both GTK+, Gnome libraries and
1378 many GTK+ and Gnome applications) using signals uses a small
1379 variation of the default handler pattern I have shown in the previous section.
1383 Usually, the <function>g_signal_new</function> function is preferred over
1384 <function>g_signal_newv</function>. When <function>g_signal_new</function>
1385 is used, the default closure is exported as a class function. For example,
1386 <filename>gobject.h</filename> contains the declaration of <type>GObjectClass</type>
1387 whose notify class function is the default handler for the <emphasis>notify</emphasis>
1390 struct _GObjectClass
1392 GTypeClass g_type_class;
1394 /* class methods and other stuff. */
1397 void (*notify) (GObject *object,
1404 <filename>gobject.c</filename>'s <function>g_object_do_class_init</function> function
1405 registers the <emphasis>notify</emphasis> signal and initializes this class function
1409 g_object_do_class_init (GObjectClass *class)
1414 class->notify = NULL;
1416 gobject_signals[NOTIFY] =
1417 g_signal_new ("notify",
1418 G_TYPE_FROM_CLASS (class),
1419 G_SIGNAL_RUN_FIRST | G_SIGNAL_NO_RECURSE | G_SIGNAL_DETAILED | G_SIGNAL_NO_HOOKS,
1420 G_STRUCT_OFFSET (GObjectClass, notify),
1422 g_cclosure_marshal_VOID__PARAM,
1427 <function>g_signal_new</function> creates a <type>GClosure</type> which de-references the
1428 type's class structure to access the class function pointer and invoke it if it not NULL. The
1429 class function is ignored it is set to NULL.
1433 To understand the reason for such a complex scheme to access the signal's default handler,
1434 you must remember the whole reason for the use of these signals. The goal here is to delegate
1435 a part of the process to the user without requiring the user to subclass the object to override
1436 one of the class functions. The alternative to subclassing, that is, the use of signals
1437 to delegate processing to the user, is, however, a bit less optimal in terms of speed: rather
1438 than just de-referencing a function pointer in a class structure, you must start the whole
1439 process of signal emission which is a bit heavyweight.
1443 This is why some people decided to use class functions for some signal's default handlers:
1444 rather than having users connect a handler to the signal and stop the signal emission
1445 from within that handler, you just need to override the default class function which is
1446 supposedly more efficient.
1454 <sect1 id="howto-doc">
1455 <title>How to generate API documentation for your type ?</title>