• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1<?xml version='1.0' encoding="UTF-8"?>
2<!DOCTYPE part PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3               "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
4]>
5<part label="IV">
6  <title>Tutorial</title>
7  <partintro>
8    <para>
9      This chapter tries to answer the real-life questions of users and presents
10      the most common use cases in order from most likely to least
11      likely.
12    </para>
13  </partintro>
14
15<chapter id="howto-gobject">
16  <title>How to define and implement a new GObject</title>
17
18  <para>
19    This chapter focuses on the implementation of a subtype of GObject, for
20    example to create a custom class hierarchy, or to subclass a GTK+ widget.
21  </para>
22
23  <para>
24    Throughout the chapter, a running example of a file viewer program is used,
25    which has a <type>ViewerFile</type> class to represent a single file being
26    viewed, and various derived classes for different types of files with
27    special functionality, such as audio files. The example application also
28    supports editing files (for example, to tweak a photo being viewed), using
29    a <type>ViewerEditable</type> interface.
30  </para>
31
32  <sect1 id="howto-gobject-header">
33    <title>Boilerplate header code</title>
34
35    <para>
36      The first step before writing the code for your GObject is to write the
37      type's header which contains the needed type, function and macro
38      definitions. Each of these elements is nothing but a convention which
39      is followed by almost all users of GObject, and has been refined over
40      multiple years of experience developing GObject-based code. If you are
41      writing a library, it is particularly important for you to adhere closely
42      to these conventions; users of your library will assume that you have.
43      Even if not writing a library, it will help other people who want to work
44      on your project.
45    </para>
46
47    <para>
48      Pick a name convention for your headers and source code and stick to it:
49      <itemizedlist>
50        <listitem><para>use a dash to separate the prefix from the typename:
51        <filename>viewer-file.h</filename> and <filename>viewer-file.c</filename>
52        (this is the convention used by Nautilus and most GNOME libraries).</para></listitem>
53        <listitem><para>use an underscore to separate the prefix from the
54        typename: <filename>viewer_file.h</filename> and
55        <filename>viewer_file.c</filename>.</para></listitem>
56        <listitem><para>Do not separate the prefix from the typename:
57        <filename>viewerfile.h</filename> and <filename>viewerfile.c</filename>.
58        (this is the convention used by GTK+)</para></listitem>
59      </itemizedlist>
60      Some people like the first two solutions better: it makes reading file
61      names easier for those with poor eyesight.
62    </para>
63
64    <para>
65      The basic conventions for any header which exposes a GType are described
66      in <xref linkend="gtype-conventions"/>.
67    </para>
68
69    <para>
70      If you want to declare a type named ‘file’ in namespace ‘viewer’, name the
71      type instance <function>ViewerFile</function> and its class
72      <function>ViewerFileClass</function> (names are case sensitive). The
73      recommended method of declaring a type differs based on whether the type
74      is final or derivable.
75    </para>
76
77    <para>
78      Final types cannot be subclassed further, and should be the default choice
79      for new types — changing a final type to be derivable is always a change
80      that will be compatible with existing uses of the code, but the converse
81      will often cause problems. Final types are declared using
82      <link linkend="G-DECLARE-FINAL-TYPE:CAPS"><function>G_DECLARE_FINAL_TYPE</function></link>,
83      and require a structure to hold the instance data to be declared in the
84      source code (not the header file).
85
86<informalexample><programlisting>
87/*
88 * Copyright/Licensing information.
89 */
90
91/* inclusion guard */
92#ifndef __VIEWER_FILE_H__
93#define __VIEWER_FILE_H__
94
95#include &lt;glib-object.h&gt;
96/*
97 * Potentially, include other headers on which this header depends.
98 */
99
100G_BEGIN_DECLS
101
102/*
103 * Type declaration.
104 */
105#define VIEWER_TYPE_FILE viewer_file_get_type ()
106G_DECLARE_FINAL_TYPE (ViewerFile, viewer_file, VIEWER, FILE, GObject)
107
108/*
109 * Method definitions.
110 */
111ViewerFile *viewer_file_new (void);
112
113G_END_DECLS
114
115#endif /* __VIEWER_FILE_H__ */
116</programlisting></informalexample>
117    </para>
118
119    <para>
120      Derivable types <emphasis>can</emphasis> be subclassed further, and their class and
121      instance structures form part of the public API which must not be changed
122      if API stability is cared about. They are declared using
123      <link linkend="G-DECLARE-DERIVABLE-TYPE:CAPS"><function>G_DECLARE_DERIVABLE_TYPE</function></link>:
124<informalexample><programlisting>
125/*
126 * Copyright/Licensing information.
127 */
128
129/* inclusion guard */
130#ifndef __VIEWER_FILE_H__
131#define __VIEWER_FILE_H__
132
133#include &lt;glib-object.h&gt;
134/*
135 * Potentially, include other headers on which this header depends.
136 */
137
138G_BEGIN_DECLS
139
140/*
141 * Type declaration.
142 */
143#define VIEWER_TYPE_FILE viewer_file_get_type ()
144G_DECLARE_DERIVABLE_TYPE (ViewerFile, viewer_file, VIEWER, FILE, GObject)
145
146struct _ViewerFileClass
147{
148  GObjectClass parent_class;
149
150  /* Class virtual function fields. */
151  void (* open) (ViewerFile  *file,
152                 GError     **error);
153
154  /* Padding to allow adding up to 12 new virtual functions without
155   * breaking ABI. */
156  gpointer padding[12];
157};
158
159/*
160 * Method definitions.
161 */
162ViewerFile *viewer_file_new (void);
163
164G_END_DECLS
165
166#endif /* __VIEWER_FILE_H__ */
167</programlisting></informalexample>
168    </para>
169
170    <para>
171      The convention for header includes is to add the minimum number of
172      <function>#include</function> directives to the top of your headers needed
173      to compile that header. This
174      allows client code to simply <function>#include "viewer-file.h"</function>,
175      without needing to know the prerequisites for
176      <filename>viewer-file.h</filename>.
177    </para>
178  </sect1>
179
180  <sect1 id="howto-gobject-code">
181    <title>Boilerplate code</title>
182
183    <para>
184      In your code, the first step is to <function>#include</function> the
185      needed headers:
186<informalexample><programlisting>
187/*
188 * Copyright information
189 */
190
191#include "viewer-file.h"
192
193/* Private structure definition. */
194typedef struct {
195  gchar *filename;
196  /* stuff */
197} ViewerFilePrivate;
198
199/*
200 * forward definitions
201 */
202</programlisting></informalexample>
203    </para>
204
205    <para>
206      If the class is being declared as final using
207      <function>G_DECLARE_FINAL_TYPE</function>, its instance structure should
208      be defined in the C file:
209<informalexample><programlisting>
210struct _ViewerFile
211{
212  GObject parent_instance;
213
214  /* Other members, including private data. */
215};
216</programlisting></informalexample>
217    </para>
218
219    <para>
220      Call the <function>G_DEFINE_TYPE</function> macro (or
221      <function>G_DEFINE_TYPE_WITH_PRIVATE</function> if your class needs
222      private data — final types do <emphasis>not</emphasis> need private data)
223      using the name
224      of the type, the prefix of the functions and the parent GType to
225      reduce the amount of boilerplate needed. This macro will:
226
227      <itemizedlist>
228        <listitem><simpara>implement the <function>viewer_file_get_type</function>
229        function</simpara></listitem>
230        <listitem><simpara>define a parent class pointer accessible from
231        the whole .c file</simpara></listitem>
232        <listitem><simpara>add private instance data to the type (if using
233        <function>G_DEFINE_TYPE_WITH_PRIVATE</function>)</simpara></listitem>
234      </itemizedlist>
235    </para>
236
237    <para>
238      If the class has been declared as final using
239      <function>G_DECLARE_FINAL_TYPE</function> (see
240      <xref linkend="howto-gobject-header"/>), private data should be placed in
241      the instance structure, <type>ViewerFile</type>, and
242      <function>G_DEFINE_TYPE</function> should be used instead of
243      <function>G_DEFINE_TYPE_WITH_PRIVATE</function>. The instance structure
244      for a final class is not exposed publicly, and is not embedded in the
245      instance structures of any derived classes (because the class is final);
246      so its size can vary without causing incompatibilities for code which uses
247      the class. Conversely, private data for derivable classes
248      <emphasis>must</emphasis> be included in a private structure, and
249      <function>G_DEFINE_TYPE_WITH_PRIVATE</function> must be used.
250
251<informalexample><programlisting>
252G_DEFINE_TYPE (ViewerFile, viewer_file, G_TYPE_OBJECT)
253</programlisting></informalexample>
254or
255<informalexample><programlisting>
256G_DEFINE_TYPE_WITH_PRIVATE (ViewerFile, viewer_file, G_TYPE_OBJECT)
257</programlisting></informalexample>
258    </para>
259
260    <para>
261      It is also possible to use the
262      <function>G_DEFINE_TYPE_WITH_CODE</function> macro to control the
263      <function>get_type</function> function implementation — for instance, to
264      add a call to the <function>G_IMPLEMENT_INTERFACE</function> macro to
265      implement an interface.
266    </para>
267  </sect1>
268
269  <sect1 id="howto-gobject-construction">
270    <title>Object construction</title>
271
272    <para>
273      People often get confused when trying to construct their GObjects because of the
274      sheer number of different ways to hook into the objects's construction process: it is
275      difficult to figure which is the <emphasis>correct</emphasis>, recommended way.
276    </para>
277
278    <para>
279      <xref linkend="gobject-construction-table"/> shows what user-provided functions
280      are invoked during object instantiation and in which order they are invoked.
281      A user looking for the equivalent of the simple C++ constructor function should use
282      the <function>instance_init</function> method. It will be invoked after
283      all the parents’ <function>instance_init</function>
284      functions have been invoked. It cannot take arbitrary construction parameters
285      (as in C++) but if your object needs arbitrary parameters to complete initialization,
286      you can use construction properties.
287    </para>
288
289    <para>
290      Construction properties will be set only after all
291      <function>instance_init</function> functions have run.
292      No object reference will be returned to the client of <function><link linkend="g-object-new">g_object_new</link></function>
293      until all the construction properties have been set.
294    </para>
295
296    <para>
297      It is important to note that object construction cannot <emphasis>ever</emphasis>
298      fail. If you require a fallible GObject construction, you can use the
299      <link linkend="GInitable"><type>GInitable</type></link> and
300      <link linkend="GAsyncInitable"><type>GAsyncInitable</type></link>
301      interfaces provided by the GIO library.
302    </para>
303
304    <para>
305      You should write the following code first:
306<informalexample><programlisting>
307G_DEFINE_TYPE_WITH_PRIVATE (ViewerFile, viewer_file, G_TYPE_OBJECT)
308
309static void
310viewer_file_class_init (ViewerFileClass *klass)
311{
312}
313
314static void
315viewer_file_init (ViewerFile *self)
316{
317  ViewerFilePrivate *priv = viewer_file_get_instance_private (self);
318
319  /* initialize all public and private members to reasonable default values.
320   * They are all automatically initialized to 0 to begin with. */
321}
322</programlisting></informalexample>
323    </para>
324
325    <para>
326      If you need special construction properties (with
327      <link linkend="G-PARAM-CONSTRUCT-ONLY:CAPS"><function>G_PARAM_CONSTRUCT_ONLY</function></link>
328      set), install the properties in
329      the <function>class_init()</function> function, override the <function>set_property()</function>
330      and <function>get_property()</function> methods of the GObject class,
331      and implement them as described by <xref linkend="gobject-properties"/>.
332    </para>
333
334    <para>
335      Property IDs must start from 1, as 0 is reserved for internal use by
336      GObject.
337<informalexample><programlisting>
338enum
339{
340  PROP_FILENAME = 1,
341  PROP_ZOOM_LEVEL,
342  N_PROPERTIES
343};
344
345static GParamSpec *obj_properties[N_PROPERTIES] = { NULL, };
346
347static void
348viewer_file_class_init (ViewerFileClass *klass)
349{
350  GObjectClass *object_class = G_OBJECT_CLASS (klass);
351
352  object_class->set_property = viewer_file_set_property;
353  object_class->get_property = viewer_file_get_property;
354
355  obj_properties[PROP_FILENAME] =
356    g_param_spec_string ("filename",
357                         "Filename",
358                         "Name of the file to load and display from.",
359                         NULL  /* default value */,
360                         G_PARAM_CONSTRUCT_ONLY | G_PARAM_READWRITE);
361
362  obj_properties[PROP_ZOOM_LEVEL] =
363    g_param_spec_uint ("zoom-level",
364                       "Zoom level",
365                       "Zoom level to view the file at.",
366                       0  /* minimum value */,
367                       10 /* maximum value */,
368                       2  /* default value */,
369                       G_PARAM_READWRITE);
370
371  g_object_class_install_properties (object_class,
372                                     N_PROPERTIES,
373                                     obj_properties);
374}
375</programlisting></informalexample>
376      If you need this, make sure you can build and run code similar to the
377      code shown above. Also, make sure your construct properties can be set
378      without side effects during construction.
379    </para>
380
381    <para>
382      Some people sometimes need to complete the initialization of an instance
383      of a type only after the properties passed to the constructors have been
384      set. This is possible through the use of the <function>constructor()</function>
385      class method as described in <xref linkend="gobject-instantiation"/> or,
386      more simply, using the <function>constructed()</function> class method.
387      Note that the <function>constructed()</function>
388      virtual function will only be invoked after the properties marked as
389      <function>G_PARAM_CONSTRUCT_ONLY</function> or
390      <function>G_PARAM_CONSTRUCT</function> have been consumed, but
391      before the regular properties passed to <function>g_object_new()</function>
392      have been set.
393    </para>
394  </sect1>
395
396  <sect1 id="howto-gobject-destruction">
397    <title>Object destruction</title>
398
399    <para>
400      Again, it is often difficult to figure out which mechanism to use to
401      hook into the object's destruction process: when the last
402      <function><link linkend="g-object-unref">g_object_unref</link></function>
403      function call is made, a lot of things happen as described in
404      <xref linkend="gobject-destruction-table"/>.
405    </para>
406
407    <para>
408      The destruction process of your object is in two phases: dispose and
409      finalize. This split is necessary to handle
410      potential cycles due to the nature of the reference counting mechanism
411      used by GObject, as well as dealing with temporary revival of
412      instances in case of signal emission during the destruction sequence.
413      See <xref linkend="gobject-memory-cycles"/> for more information.
414<informalexample><programlisting>
415struct _ViewerFilePrivate
416{
417  gchar *filename;
418  guint zoom_level;
419
420  GInputStream *input_stream;
421};
422
423G_DEFINE_TYPE_WITH_PRIVATE (ViewerFile, viewer_file, G_TYPE_OBJECT)
424
425static void
426viewer_file_dispose (GObject *gobject)
427{
428  ViewerFilePrivate *priv = viewer_file_get_instance_private (VIEWER_FILE (gobject));
429
430  /* In dispose(), you are supposed to free all types referenced from this
431   * object which might themselves hold a reference to self. Generally,
432   * the most simple solution is to unref all members on which you own a
433   * reference.
434   */
435
436  /* dispose() might be called multiple times, so we must guard against
437   * calling g_object_unref() on an invalid GObject by setting the member
438   * NULL; g_clear_object() does this for us.
439   */
440  g_clear_object (&amp;priv->input_stream);
441
442  /* Always chain up to the parent class; there is no need to check if
443   * the parent class implements the dispose() virtual function: it is
444   * always guaranteed to do so
445   */
446  G_OBJECT_CLASS (viewer_file_parent_class)->dispose (gobject);
447}
448
449static void
450viewer_file_finalize (GObject *gobject)
451{
452  ViewerFilePrivate *priv = viewer_file_get_instance_private (VIEWER_FILE (gobject));
453
454  g_free (priv->filename);
455
456  /* Always chain up to the parent class; as with dispose(), finalize()
457   * is guaranteed to exist on the parent's class virtual function table
458   */
459  G_OBJECT_CLASS (viewer_file_parent_class)->finalize (gobject);
460}
461
462static void
463viewer_file_class_init (ViewerFileClass *klass)
464{
465  GObjectClass *object_class = G_OBJECT_CLASS (klass);
466
467  object_class->dispose = viewer_file_dispose;
468  object_class->finalize = viewer_file_finalize;
469}
470
471static void
472viewer_file_init (ViewerFile *self);
473{
474  ViewerFilePrivate *priv = viewer_file_get_instance_private (self);
475
476  priv->input_stream = g_object_new (VIEWER_TYPE_INPUT_STREAM, NULL);
477  priv->filename = /* would be set as a property */;
478}
479</programlisting></informalexample>
480    </para>
481
482    <para>
483      It is possible that object methods might be invoked after dispose is
484      run and before finalize runs. GObject does not consider this to be a
485      program error: you must gracefully detect this and neither crash nor
486      warn the user, by having a disposed instance revert to an inert state.
487    </para>
488  </sect1>
489
490  <sect1 id="howto-gobject-methods">
491    <title>Object methods</title>
492
493    <para>
494      Just as with C++, there are many different ways to define object
495      methods and extend them: the following list and sections draw on
496      C++ vocabulary. (Readers are expected to know basic C++ concepts.
497      Those who have not had to write C++ code recently can refer to e.g.
498      <ulink url="http://www.cplusplus.com/doc/tutorial/"/> to refresh
499      their memories.)
500      <itemizedlist>
501        <listitem><para>
502            non-virtual public methods,
503          </para></listitem>
504        <listitem><para>
505            virtual public methods and
506          </para></listitem>
507        <listitem><para>
508            virtual private methods
509          </para></listitem>
510      </itemizedlist>
511    </para>
512
513    <sect2 id="non-virtual-public-methods">
514      <title>Non-virtual public methods</title>
515
516      <para>
517        These are the simplest, providing a simple method which
518        acts on the object. Provide a function
519        prototype in the header and an implementation of that prototype
520        in the source file.
521<informalexample><programlisting>
522/* declaration in the header. */
523void viewer_file_open (ViewerFile  *self,
524                       GError     **error);
525
526/* implementation in the source file */
527void
528viewer_file_open (ViewerFile  *self,
529                  GError     **error)
530{
531  g_return_if_fail (VIEWER_IS_FILE (self));
532  g_return_if_fail (error == NULL || *error == NULL);
533
534  /* do stuff here. */
535}
536</programlisting></informalexample>
537      </para>
538    </sect2>
539
540    <sect2 id="virtual-public-methods">
541      <title>Virtual public methods</title>
542
543      <para>
544        This is the preferred way to create GObjects with overridable methods:
545        <itemizedlist>
546          <listitem><para>
547            Define the common method and its virtual function in the
548            class structure in the public header
549          </para></listitem>
550          <listitem><para>
551            Define the common method in the header file and implement it in the
552            source file
553          </para></listitem>
554          <listitem><para>
555            Implement a base version of the virtual function in the source
556            file and initialize the virtual function pointer to this
557            implementation in the object’s <function>class_init</function>
558            function; or leave it as <constant>NULL</constant> for a ‘pure
559            virtual’ method which must be overridden by derived classes
560          </para></listitem>
561          <listitem><para>
562            Re-implement the virtual function in each derived class which needs
563            to override it
564          </para></listitem>
565        </itemizedlist>
566      </para>
567      <para>
568        Note that virtual functions can only be defined if the class is
569        derivable, declared using
570        <link linkend="G-DECLARE-DERIVABLE-TYPE:CAPS"><function>G_DECLARE_DERIVABLE_TYPE</function></link>
571        so the class structure can be defined.
572<informalexample><programlisting>
573/* declaration in viewer-file.h. */
574#define VIEWER_TYPE_FILE viewer_file_get_type ()
575G_DECLARE_DERIVABLE_TYPE (ViewerFile, viewer_file, VIEWER, FILE, GObject)
576
577struct _ViewerFileClass
578{
579  GObjectClass parent_class;
580
581  /* stuff */
582  void (*open) (ViewerFile  *self,
583                GError     **error);
584
585  /* Padding to allow adding up to 12 new virtual functions without
586   * breaking ABI. */
587  gpointer padding[12];
588};
589
590void viewer_file_open (ViewerFile  *self,
591                       GError     **error);
592
593/* implementation in viewer-file.c */
594void
595viewer_file_open (ViewerFile  *self,
596                  GError     **error)
597{
598  ViewerFileClass *klass;
599
600  g_return_if_fail (VIEWER_IS_FILE (self));
601  g_return_if_fail (error == NULL || *error == NULL);
602
603  klass = VIEWER_FILE_GET_CLASS (self);
604  g_return_if_fail (klass->open != NULL);
605
606  klass->open (self, error);
607}
608</programlisting></informalexample>
609        The code above simply redirects the <function>open</function> call
610        to the relevant virtual function.
611      </para>
612
613      <para>
614        It is possible to provide a default
615        implementation for this class method in the object's
616        <function>class_init</function> function: initialize the
617        <function>klass-&gt;open</function> field to a pointer to the
618        actual implementation.
619        By default, class methods that are not inherited are initialized to
620        <function>NULL</function>, and thus are to be considered "pure virtual".
621<informalexample><programlisting>
622static void
623viewer_file_real_close (ViewerFile  *self,
624                        GError     **error)
625{
626  /* Default implementation for the virtual method. */
627}
628
629static void
630viewer_file_class_init (ViewerFileClass *klass)
631{
632  /* this is not necessary, except for demonstration purposes.
633   *
634   * pure virtual method: mandates implementation in children.
635   */
636  klass->open = NULL;
637
638  /* merely virtual method. */
639  klass->close = viewer_file_real_close;
640}
641
642void
643viewer_file_open (ViewerFile  *self,
644                  GError     **error)
645{
646  ViewerFileClass *klass;
647
648  g_return_if_fail (VIEWER_IS_FILE (self));
649  g_return_if_fail (error == NULL || *error == NULL);
650
651  klass = VIEWER_FILE_GET_CLASS (self);
652
653  /* if the method is purely virtual, then it is a good idea to
654   * check that it has been overridden before calling it, and,
655   * depending on the intent of the class, either ignore it silently
656   * or warn the user.
657   */
658  g_return_if_fail (klass->open != NULL);
659  klass->open (self, error);
660}
661
662void
663viewer_file_close (ViewerFile  *self,
664                   GError     **error)
665{
666  ViewerFileClass *klass;
667
668  g_return_if_fail (VIEWER_IS_FILE (self));
669  g_return_if_fail (error == NULL || *error == NULL);
670
671  klass = VIEWER_FILE_GET_CLASS (self);
672  if (klass->close != NULL)
673    klass->close (self, error);
674}
675</programlisting></informalexample>
676      </para>
677    </sect2>
678
679    <sect2 id="virtual-private-methods">
680      <title>Virtual private Methods</title>
681
682      <para>
683        These are very similar to <link linkend="virtual-public-methods">virtual
684        public methods</link>. They just don't
685        have a public function to call directly. The header
686        file contains only a declaration of the virtual function:
687<informalexample><programlisting>
688/* declaration in viewer-file.h. */
689struct _ViewerFileClass
690{
691  GObjectClass parent;
692
693  /* Public virtual method as before. */
694  void     (*open)           (ViewerFile  *self,
695                              GError     **error);
696
697  /* Private helper function to work out whether the file can be loaded via
698   * memory mapped I/O, or whether it has to be read as a stream. */
699  gboolean (*can_memory_map) (ViewerFile *self);
700
701  /* Padding to allow adding up to 12 new virtual functions without
702   * breaking ABI. */
703  gpointer padding[12];
704};
705
706void viewer_file_open (ViewerFile *self, GError **error);
707</programlisting></informalexample>
708        These virtual functions are often used to delegate part of the job
709        to child classes:
710<informalexample><programlisting>
711/* this accessor function is static: it is not exported outside of this file. */
712static gboolean
713viewer_file_can_memory_map (ViewerFile *self)
714{
715  return VIEWER_FILE_GET_CLASS (self)->can_memory_map (self);
716}
717
718void
719viewer_file_open (ViewerFile  *self,
720                  GError     **error)
721{
722  g_return_if_fail (VIEWER_IS_FILE (self));
723  g_return_if_fail (error == NULL || *error == NULL);
724
725  /*
726   * Try to load the file using memory mapped I/O, if the implementation of the
727   * class determines that is possible using its private virtual method.
728   */
729  if (viewer_file_can_memory_map (self))
730    {
731      /* Load the file using memory mapped I/O. */
732    }
733  else
734    {
735      /* Fall back to trying to load the file using streaming I/O… */
736    }
737}
738</programlisting></informalexample>
739      </para>
740
741      <para>
742        Again, it is possible to provide a default implementation for this
743        private virtual function:
744<informalexample><programlisting>
745static gboolean
746viewer_file_real_can_memory_map (ViewerFile *self)
747{
748  /* As an example, always return false. Or, potentially return true if the
749   * file is local. */
750  return FALSE;
751}
752
753static void
754viewer_file_class_init (ViewerFileClass *klass)
755{
756  /* non-pure virtual method; does not have to be implemented in children. */
757  klass->can_memory_map = viewer_file_real_can_memory_map;
758}
759</programlisting></informalexample>
760      </para>
761
762      <para>
763        Derived classes can then override the method with code such as:
764<informalexample><programlisting>
765static void
766viewer_audio_file_class_init (ViewerAudioFileClass *klass)
767{
768  ViewerFileClass *file_class = VIEWER_FILE_CLASS (klass);
769
770  /* implement pure virtual function. */
771  file_class->can_memory_map = viewer_audio_file_can_memory_map;
772}
773</programlisting></informalexample>
774      </para>
775    </sect2>
776  </sect1>
777
778  <sect1 id="howto-gobject-chainup">
779    <title>Chaining up</title>
780
781    <para>Chaining up is often loosely defined by the following set of
782    conditions:
783      <itemizedlist>
784        <listitem><para>Parent class A defines a public virtual method named <function>foo</function> and
785        provides a default implementation.</para></listitem>
786        <listitem><para>Child class B re-implements method <function>foo</function>.</para></listitem>
787        <listitem><para>B’s implementation of <function>foo</function> calls (‘chains up to’) its parent class A’s implementation of <function>foo</function>.</para></listitem>
788      </itemizedlist>
789      There are various uses of this idiom:
790      <itemizedlist>
791        <listitem><para>You need to extend the behaviour of a class without modifying its code. You create
792          a subclass to inherit its implementation, re-implement a public virtual method to modify the behaviour
793          and chain up to ensure that the previous behaviour is not really modified, just extended.
794          </para></listitem>
795        <listitem><para>You need to implement the
796          <ulink url="http://en.wikipedia.org/wiki/Chain-of-responsibility_pattern">Chain
797          Of Responsibility pattern</ulink>: each object of the inheritance
798          tree chains up to its parent (typically, at the beginning or the end of the method) to ensure that
799          each handler is run in turn.</para></listitem>
800      </itemizedlist>
801    </para>
802
803    <para>
804      To explicitly chain up to the implementation of the virtual method in the parent class,
805      you first need a handle to the original parent class structure. This pointer can then be used to
806      access the original virtual function pointer and invoke it directly.
807      <footnote>
808        <para>
809          The <emphasis>original</emphasis> adjective used in this sentence is not innocuous. To fully
810          understand its meaning, recall how class structures are initialized: for each object type,
811          the class structure associated with this object is created by first copying the class structure of its
812          parent type (a simple <function>memcpy</function>) and then by invoking the <function>class_init</function> callback on
813          the resulting class structure. Since the <function>class_init</function> callback is responsible for overwriting the class structure
814          with the user re-implementations of the class methods, the modified copy of the parent class
815          structure stored in the derived instance cannot be used. A copy of the class structure of an instance of the parent
816          class is needed.
817        </para>
818      </footnote>
819    </para>
820
821    <para>
822      Use the <function>parent_class</function> pointer created and initialized
823      by the
824      <link linkend="G-DEFINE-TYPE:CAPS"><function>G_DEFINE_TYPE</function></link>
825      family of macros, for instance:
826<informalexample><programlisting>
827static void
828b_method_to_call (B *obj, gint some_param)
829{
830  /* do stuff before chain up */
831
832  /* call the method_to_call() virtual function on the
833   * parent of BClass, AClass.
834   *
835   * remember the explicit cast to AClass*
836   */
837  A_CLASS (b_parent_class)->method_to_call (obj, some_param);
838
839  /* do stuff after chain up */
840}
841</programlisting></informalexample>
842  </para>
843
844  </sect1>
845
846</chapter>
847<!-- End Howto GObject -->
848
849<chapter id="howto-interface">
850  <title>How to define and implement interfaces</title>
851
852  <sect1 id="howto-interface-define">
853    <title>Defining interfaces</title>
854
855  <para>
856    The theory behind how GObject interfaces work is given in
857    <xref linkend="gtype-non-instantiatable-classed"/>; this section covers how to
858    define and implement an interface.
859  </para>
860
861  <para>
862    The first step is to get the header right. This interface
863    defines three methods:
864<informalexample><programlisting>
865/*
866 * Copyright/Licensing information.
867 */
868
869#ifndef __VIEWER_EDITABLE_H__
870#define __VIEWER_EDITABLE_H__
871
872#include &lt;glib-object.h&gt;
873
874G_BEGIN_DECLS
875
876#define VIEWER_TYPE_EDITABLE viewer_editable_get_type ()
877G_DECLARE_INTERFACE (ViewerEditable, viewer_editable, VIEWER, EDITABLE, GObject)
878
879struct _ViewerEditableInterface
880{
881  GTypeInterface parent_iface;
882
883  void (*save) (ViewerEditable  *self,
884                GError         **error);
885  void (*undo) (ViewerEditable  *self,
886                guint            n_steps);
887  void (*redo) (ViewerEditable  *self,
888                guint            n_steps);
889};
890
891void viewer_editable_save (ViewerEditable  *self,
892                           GError         **error);
893void viewer_editable_undo (ViewerEditable  *self,
894                           guint            n_steps);
895void viewer_editable_redo (ViewerEditable  *self,
896                           guint            n_steps);
897
898G_END_DECLS
899
900#endif /* __VIEWER_EDITABLE_H__ */
901</programlisting></informalexample>
902    This code is the same as the code for a normal <link linkend="GType"><type>GType</type></link>
903    which derives from a <link linkend="GObject"><type>GObject</type></link> except for a few details:
904    <itemizedlist>
905      <listitem><para>
906        The <function>_GET_CLASS</function> function is called
907        <function>_GET_IFACE</function> (and is defined by
908        <link linkend="G-DECLARE-INTERFACE:CAPS"><function>G_DECLARE_INTERFACE</function></link>).
909      </para></listitem>
910      <listitem><para>
911        The instance type, <type>ViewerEditable</type>, is not fully defined: it is
912        used merely as an abstract type which represents an instance of
913        whatever object which implements the interface.
914      </para></listitem>
915      <listitem><para>
916        The parent of the <type>ViewerEditableInterface</type> is
917        <type>GTypeInterface</type>, not <type>GObjectClass</type>.
918      </para></listitem>
919    </itemizedlist>
920  </para>
921
922  <para>
923    The implementation of the <type>ViewerEditable</type> type itself is trivial:
924    <itemizedlist>
925      <listitem><para><function><link linkend="G-DEFINE-INTERFACE:CAPS">G_DEFINE_INTERFACE</link></function>
926       creates a <function>viewer_editable_get_type</function> function which registers the
927       type in the type system. The third argument is used to define a
928       <link linkend="howto-interface-prerequisite">prerequisite interface</link>
929       (which we'll talk about more later). Just pass <code>0</code> for this
930       argument when an interface has no prerequisite.
931       </para></listitem>
932      <listitem><para><function>viewer_editable_default_init</function> is expected
933      to register the interface's signals if there are any (we will see a bit
934      later how to use them).</para></listitem>
935      <listitem><para>The interface methods <function>viewer_editable_save</function>,
936      <function>viewer_editable_undo</function> and <function>viewer_editable_redo</function> dereference the interface
937      structure to access its associated interface function and call it.
938      </para></listitem>
939    </itemizedlist>
940<informalexample><programlisting>
941G_DEFINE_INTERFACE (ViewerEditable, viewer_editable, G_TYPE_OBJECT)
942
943static void
944viewer_editable_default_init (ViewerEditableInterface *iface)
945{
946    /* add properties and signals to the interface here */
947}
948
949void
950viewer_editable_save (ViewerEditable  *self,
951                      GError         **error)
952{
953  ViewerEditableInterface *iface;
954
955  g_return_if_fail (VIEWER_IS_EDITABLE (self));
956  g_return_if_fail (error == NULL || *error == NULL);
957
958  iface = VIEWER_EDITABLE_GET_IFACE (self);
959  g_return_if_fail (iface->save != NULL);
960  iface->save (self, error);
961}
962
963void
964viewer_editable_undo (ViewerEditable *self,
965                      guint           n_steps)
966{
967  ViewerEditableInterface *iface;
968
969  g_return_if_fail (VIEWER_IS_EDITABLE (self));
970
971  iface = VIEWER_EDITABLE_GET_IFACE (self);
972  g_return_if_fail (iface->undo != NULL);
973  iface->undo (self, n_steps);
974}
975
976void
977viewer_editable_redo (ViewerEditable *self,
978                      guint           n_steps)
979{
980  ViewerEditableInterface *iface;
981
982  g_return_if_fail (VIEWER_IS_EDITABLE (self));
983
984  iface = VIEWER_EDITABLE_GET_IFACE (self);
985  g_return_if_fail (iface->redo != NULL);
986  iface->redo (self, n_steps);
987}
988</programlisting></informalexample>
989    </para>
990  </sect1>
991
992  <sect1 id="howto-interface-implement">
993    <title>Implementing interfaces</title>
994
995    <para>
996      Once the interface is defined, implementing it is rather trivial.
997    </para>
998
999    <para>
1000      The first step is to define a normal final GObject class exactly as in
1001      <xref linkend="howto-gobject-header"/>.
1002    </para>
1003
1004    <para>
1005      The second step is to implement <type>ViewerFile</type> by defining
1006      it using
1007      <function><link linkend="G-DEFINE-TYPE-WITH-CODE:CAPS">G_DEFINE_TYPE_WITH_CODE</link></function>
1008      and
1009      <function><link linkend="G-IMPLEMENT-INTERFACE:CAPS">G_IMPLEMENT_INTERFACE</link></function>
1010      instead of
1011      <function><link linkend="G-DEFINE-TYPE:CAPS">G_DEFINE_TYPE</link></function>:
1012<informalexample><programlisting>
1013static void viewer_file_editable_interface_init (ViewerEditableInterface *iface);
1014
1015G_DEFINE_TYPE_WITH_CODE (ViewerFile, viewer_file, G_TYPE_OBJECT,
1016                         G_IMPLEMENT_INTERFACE (VIEWER_TYPE_EDITABLE,
1017                                                viewer_file_editable_interface_init))
1018</programlisting></informalexample>
1019      This definition is very much like all the similar functions seen
1020      previously. The only interface-specific code present here is the use of
1021      <function><link linkend="G-IMPLEMENT-INTERFACE:CAPS">G_IMPLEMENT_INTERFACE</link></function>.
1022    </para>
1023
1024    <note><para>Classes can implement multiple interfaces by using multiple calls to
1025    <function><link linkend="G-IMPLEMENT-INTERFACE:CAPS">G_IMPLEMENT_INTERFACE</link></function>
1026    inside the call to
1027    <function><link linkend="G-DEFINE-TYPE-WITH-CODE:CAPS">G_DEFINE_TYPE_WITH_CODE</link></function>
1028    </para></note>
1029
1030    <para>
1031      <function>viewer_file_editable_interface_init</function>, the interface
1032      initialization function: inside it every virtual method of the interface
1033      must be assigned to its implementation:
1034<informalexample><programlisting>
1035static void
1036viewer_file_editable_save (ViewerFile  *self,
1037                           GError     **error)
1038{
1039  g_print ("File implementation of editable interface save method: %s.\n",
1040           self->filename);
1041}
1042
1043static void
1044viewer_file_editable_undo (ViewerFile *self,
1045                           guint       n_steps)
1046{
1047  g_print ("File implementation of editable interface undo method: %s.\n",
1048           self->filename);
1049}
1050
1051static void
1052viewer_file_editable_redo (ViewerFile *self,
1053                           guint       n_steps)
1054{
1055  g_print ("File implementation of editable interface redo method: %s.\n",
1056           self->filename);
1057}
1058
1059static void
1060viewer_file_editable_interface_init (ViewerEditableInterface *iface)
1061{
1062  iface->save = viewer_file_editable_save;
1063  iface->undo = viewer_file_editable_undo;
1064  iface->redo = viewer_file_editable_redo;
1065}
1066
1067static void
1068viewer_file_init (ViewerFile *self)
1069{
1070  /* Instance variable initialisation code. */
1071}
1072</programlisting></informalexample>
1073    </para>
1074    <para>
1075      If the object is not of final type, e.g. was declared using
1076      <function><link linkend="G-DECLARE-DERIVABLE-TYPE:CAPS">G_DECLARE_DERIVABLE_TYPE</link></function>
1077      then
1078      <function><link linkend="G-ADD-PRIVATE:CAPS">G_ADD_PRIVATE</link></function>
1079      macro should be added. The private structure should be declared exactly
1080      as for a normal derivable object, see <xref linkend="howto-gobject-code"/>.
1081<informalexample><programlisting>
1082G_DEFINE_TYPE_WITH_CODE (ViewerFile, viewer_file, G_TYPE_OBJECT,
1083                         G_ADD_PRIVATE (ViewerFile)
1084                         G_IMPLEMENT_INTERFACE (VIEWER_TYPE_EDITABLE,
1085                                                viewer_file_editable_interface_init))
1086</programlisting></informalexample>
1087    </para>
1088  </sect1>
1089
1090  <sect1 id="howto-interface-prerequisite">
1091    <title>Interface definition prerequisites</title>
1092
1093    <para>
1094      To specify that an interface requires the presence of other interfaces
1095      when implemented, GObject introduces the concept of
1096      <emphasis>prerequisites</emphasis>: it is possible to associate
1097      a list of prerequisite types to an interface. For example, if
1098      object A wishes to implement interface I1, and if interface I1 has a
1099      prerequisite on interface I2, A has to implement both I1 and I2.
1100    </para>
1101
1102    <para>
1103      The mechanism described above is, in practice, very similar to
1104      Java's interface I1 extends interface I2. The example below shows
1105      the GObject equivalent:
1106<informalexample><programlisting>
1107/* Make the ViewerEditableLossy interface require ViewerEditable interface. */
1108G_DEFINE_INTERFACE (ViewerEditableLossy, viewer_editable_lossy, VIEWER_TYPE_EDITABLE)
1109</programlisting></informalexample>
1110      In the <function><link linkend="G-DEFINE-INTERFACE:CAPS">G_DEFINE_INTERFACE</link></function>
1111      call above, the third parameter defines the prerequisite type. This
1112      is the GType of either an interface or a class. In this case
1113      the <type>ViewerEditable</type> interface is a prerequisite of
1114      <type>ViewerEditableLossy</type>. The code
1115      below shows how an implementation can implement both interfaces and
1116      register their implementations:
1117<informalexample><programlisting>
1118static void
1119viewer_file_editable_lossy_compress (ViewerEditableLossy *editable)
1120{
1121  ViewerFile *self = VIEWER_FILE (editable);
1122
1123  g_print ("File implementation of lossy editable interface compress method: %s.\n",
1124           self->filename);
1125}
1126
1127static void
1128viewer_file_editable_lossy_interface_init (ViewerEditableLossyInterface *iface)
1129{
1130  iface->compress = viewer_file_editable_lossy_compress;
1131}
1132
1133static void
1134viewer_file_editable_save (ViewerEditable  *editable,
1135                           GError         **error)
1136{
1137  ViewerFile *self = VIEWER_FILE (editable);
1138
1139  g_print ("File implementation of editable interface save method: %s.\n",
1140           self->filename);
1141}
1142
1143static void
1144viewer_file_editable_undo (ViewerEditable *editable,
1145                           guint           n_steps)
1146{
1147  ViewerFile *self = VIEWER_FILE (editable);
1148
1149  g_print ("File implementation of editable interface undo method: %s.\n",
1150           self->filename);
1151}
1152
1153static void
1154viewer_file_editable_redo (ViewerEditable *editable,
1155                           guint           n_steps)
1156{
1157  ViewerFile *self = VIEWER_FILE (editable);
1158
1159  g_print ("File implementation of editable interface redo method: %s.\n",
1160           self->filename);
1161}
1162
1163static void
1164viewer_file_editable_interface_init (ViewerEditableInterface *iface)
1165{
1166  iface->save = viewer_file_editable_save;
1167  iface->undo = viewer_file_editable_undo;
1168  iface->redo = viewer_file_editable_redo;
1169}
1170
1171static void
1172viewer_file_class_init (ViewerFileClass *klass)
1173{
1174  /* Nothing here. */
1175}
1176
1177static void
1178viewer_file_init (ViewerFile *self)
1179{
1180  /* Instance variable initialisation code. */
1181}
1182
1183G_DEFINE_TYPE_WITH_CODE (ViewerFile, viewer_file, G_TYPE_OBJECT,
1184                         G_IMPLEMENT_INTERFACE (VIEWER_TYPE_EDITABLE,
1185                                                viewer_file_editable_interface_init)
1186                         G_IMPLEMENT_INTERFACE (VIEWER_TYPE_EDITABLE_LOSSY,
1187                                                viewer_file_editable_lossy_interface_init))
1188</programlisting></informalexample>
1189      It is very important to notice that the order in which interface
1190      implementations are added to the main object is not random:
1191      <function><link linkend="g-type-add-interface-static">g_type_add_interface_static</link></function>,
1192      which is called by
1193      <function><link linkend="G-DEFINE-INTERFACE:CAPS">G_IMPLEMENT_INTERFACE</link></function>,
1194      must be invoked first on the interfaces which have no prerequisites and then on
1195      the others.
1196    </para>
1197  </sect1>
1198
1199  <sect1 id="howto-interface-properties">
1200    <title>Interface properties</title>
1201
1202    <para>
1203      GObject interfaces can also have
1204      properties. Declaration of the interface properties is similar to
1205      declaring the properties of ordinary GObject types as explained in
1206      <xref linkend="gobject-properties"/>, except that
1207      <function><link linkend="g-object-interface-install-property">g_object_interface_install_property</link></function>
1208      is used to declare the properties instead of
1209      <function><link linkend="g-object-class-install-property">g_object_class_install_property</link></function>.
1210    </para>
1211
1212    <para>
1213      To include a property named 'autosave-frequency' of type <type>gdouble</type> in the
1214      <type>ViewerEditable</type> interface example code above, we only need to
1215      add one call in <function>viewer_editable_default_init</function> as shown
1216      below:
1217<informalexample><programlisting>
1218static void
1219viewer_editable_default_init (ViewerEditableInterface *iface)
1220{
1221  g_object_interface_install_property (iface,
1222                                       g_param_spec_double ("autosave-frequency",
1223                                                            "Autosave frequency",
1224                                                            "Frequency (in per-seconds) to autosave backups of the editable content at. "
1225                                                            "Or zero to disable autosaves.",
1226                                                            0.0,  /* minimum */
1227                                                            G_MAXDOUBLE,  /* maximum */
1228                                                            0.0,  /* default */
1229                                                            G_PARAM_READWRITE));
1230}
1231</programlisting></informalexample>
1232    </para>
1233
1234    <para>
1235      One point worth noting is that the declared property wasn't assigned an
1236      integer ID. The reason being that integer IDs of properties are used
1237      only inside the <function>get_property</function> and
1238      <function>set_property</function> virtual methods. Since interfaces
1239      declare but do not <emphasis>implement</emphasis> properties, there is no
1240      need to assign integer IDs to them.
1241    </para>
1242
1243    <para>
1244      An implementation declares and defines its properties in the usual
1245      way as explained in <xref linkend="gobject-properties"/>, except for one
1246      small change: it can declare the properties of the interface it
1247      implements using <function><link linkend="g-object-class-override-property">g_object_class_override_property</link></function>
1248      instead of <function><link linkend="g-object-class-install-property">g_object_class_install_property</link></function>.
1249      The following code snippet shows the modifications needed in the
1250      <type>ViewerFile</type> declaration and implementation above:
1251<informalexample><programlisting>
1252struct _ViewerFile
1253{
1254  GObject parent_instance;
1255
1256  gdouble autosave_frequency;
1257};
1258
1259enum
1260{
1261  PROP_AUTOSAVE_FREQUENCY = 1,
1262  N_PROPERTIES
1263};
1264
1265static void
1266viewer_file_set_property (GObject      *object,
1267                          guint         prop_id,
1268                          const GValue *value,
1269                          GParamSpec   *pspec)
1270{
1271  ViewerFile *file = VIEWER_FILE (object);
1272
1273  switch (prop_id)
1274    {
1275    case PROP_AUTOSAVE_FREQUENCY:
1276      file->autosave_frequency = g_value_get_double (value);
1277      break;
1278
1279    default:
1280      G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
1281      break;
1282    }
1283}
1284
1285static void
1286viewer_file_get_property (GObject    *object,
1287                          guint       prop_id,
1288                          GValue     *value,
1289                          GParamSpec *pspec)
1290{
1291  ViewerFile *file = VIEWER_FILE (object);
1292
1293  switch (prop_id)
1294    {
1295    case PROP_AUTOSAVE_FREQUENCY:
1296      g_value_set_double (value, file->autosave_frequency);
1297      break;
1298
1299    default:
1300      G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
1301      break;
1302    }
1303}
1304
1305static void
1306viewer_file_class_init (ViewerFileClass *klass)
1307{
1308  GObjectClass *object_class = G_OBJECT_CLASS (klass);
1309
1310  object_class->set_property = viewer_file_set_property;
1311  object_class->get_property = viewer_file_get_property;
1312
1313  g_object_class_override_property (object_class, PROP_AUTOSAVE_FREQUENCY, "autosave-frequency");
1314}
1315</programlisting></informalexample>
1316    </para>
1317
1318  </sect1>
1319
1320  <sect1 id="howto-interface-override">
1321    <title>Overriding interface methods</title>
1322
1323    <para>
1324      If a base class already implements an interface and a derived
1325      class needs to implement the same interface but needs to override certain
1326      methods, you must reimplement the interface and set only the interface
1327      methods which need overriding.
1328    </para>
1329
1330    <para>
1331      In this example, <type>ViewerAudioFile</type> is derived from
1332      <type>ViewerFile</type>. Both implement the <type>ViewerEditable</type>
1333      interface. <type>ViewerAudioFile</type> only implements one method of the
1334      <type>ViewerEditable</type> interface and uses the base class implementation of
1335      the other.
1336<informalexample><programlisting>
1337static void
1338viewer_audio_file_editable_save (ViewerEditable  *editable,
1339                                 GError         **error)
1340{
1341  ViewerAudioFile *self = VIEWER_AUDIO_FILE (editable);
1342
1343  g_print ("Audio file implementation of editable interface save method.\n");
1344}
1345
1346static void
1347viewer_audio_file_editable_interface_init (ViewerEditableInterface *iface)
1348{
1349  /* Override the implementation of save(). */
1350  iface->save = viewer_audio_file_editable_save;
1351
1352  /*
1353   * Leave iface->undo and ->redo alone, they are already set to the
1354   * base class implementation.
1355   */
1356}
1357
1358G_DEFINE_TYPE_WITH_CODE (ViewerAudioFile, viewer_audio_file, VIEWER_TYPE_FILE,
1359                         G_IMPLEMENT_INTERFACE (VIEWER_TYPE_EDITABLE,
1360                                                viewer_audio_file_editable_interface_init))
1361
1362static void
1363viewer_audio_file_class_init (ViewerAudioFileClass *klass)
1364{
1365  /* Nothing here. */
1366}
1367
1368static void
1369viewer_audio_file_init (ViewerAudioFile *self)
1370{
1371  /* Nothing here. */
1372}
1373</programlisting></informalexample>
1374    </para>
1375
1376    <para>
1377      To access the base class interface implementation use
1378      <function><link linkend="g-type-interface-peek-parent">g_type_interface_peek_parent</link></function>
1379      from within an interface's <function>default_init</function> function.
1380    </para>
1381
1382    <para>
1383      To call the base class implementation of an interface
1384      method from a derived class where than interface method has been
1385      overridden, stash away the pointer returned from
1386      <function><link linkend="g-type-interface-peek-parent">g_type_interface_peek_parent</link></function>
1387      in a global variable.
1388    </para>
1389
1390    <para>
1391      In this example <type>ViewerAudioFile</type> overrides the
1392      <function>save</function> interface method. In its overridden method
1393      it calls the base class implementation of the same interface method.
1394<informalexample><programlisting>
1395static ViewerEditableInterface *viewer_editable_parent_interface = NULL;
1396
1397static void
1398viewer_audio_file_editable_save (ViewerEditable  *editable,
1399                                 GError         **error)
1400{
1401  ViewerAudioFile *self = VIEWER_AUDIO_FILE (editable);
1402
1403  g_print ("Audio file implementation of editable interface save method.\n");
1404
1405  /* Now call the base implementation */
1406  viewer_editable_parent_interface->save (editable, error);
1407}
1408
1409static void
1410viewer_audio_file_editable_interface_init (ViewerEditableInterface *iface)
1411{
1412  viewer_editable_parent_interface = g_type_interface_peek_parent (iface);
1413
1414  iface->save = viewer_audio_file_editable_save;
1415}
1416
1417G_DEFINE_TYPE_WITH_CODE (ViewerAudioFile, viewer_audio_file, VIEWER_TYPE_FILE,
1418                         G_IMPLEMENT_INTERFACE (VIEWER_TYPE_EDITABLE,
1419                                                viewer_audio_file_editable_interface_init))
1420
1421static void
1422viewer_audio_file_class_init (ViewerAudioFileClass *klass)
1423{
1424  /* Nothing here. */
1425}
1426
1427static void
1428viewer_audio_file_init (ViewerAudioFile *self)
1429{
1430  /* Nothing here. */
1431}
1432</programlisting></informalexample>
1433    </para>
1434
1435  </sect1>
1436
1437</chapter>
1438<!-- End Howto Interfaces -->
1439
1440<chapter id="howto-signals">
1441  <title>How to create and use signals</title>
1442
1443  <para>
1444    The signal system in GType is pretty complex and
1445    flexible: it is possible for its users to connect at runtime any
1446    number of callbacks (implemented in any language for which a binding
1447    exists)
1448    <footnote>
1449      <para>A Python callback can be connected to any signal on any
1450      C-based GObject, and vice versa, assuming that the Python object
1451      inherits from GObject.</para>
1452    </footnote>
1453    to any signal and to stop the emission of any signal at any
1454    state of the signal emission process. This flexibility makes it
1455    possible to use GSignal for much more than just emitting signals to
1456    multiple clients.
1457  </para>
1458
1459  <sect1 id="howto-simple-signals">
1460    <title>Simple use of signals</title>
1461
1462    <para>
1463      The most basic use of signals is to implement event
1464      notification. For example, given a <type>ViewerFile</type> object with
1465      a <function>write</function> method, a signal could be emitted whenever
1466      the file is changed using that method.
1467      The code below shows how the user can connect a callback to the
1468      "changed" signal.
1469<informalexample><programlisting>
1470file = g_object_new (VIEWER_FILE_TYPE, NULL);
1471
1472g_signal_connect (file, "changed", (GCallback) changed_event, NULL);
1473
1474viewer_file_write (file, buffer, strlen (buffer));
1475</programlisting></informalexample>
1476    </para>
1477
1478    <para>
1479      The <type>ViewerFile</type> signal is registered in the
1480      <function>class_init</function> function:
1481<informalexample><programlisting>
1482file_signals[CHANGED] =
1483  g_signal_newv ("changed",
1484                 G_TYPE_FROM_CLASS (object_class),
1485                 G_SIGNAL_RUN_LAST | G_SIGNAL_NO_RECURSE | G_SIGNAL_NO_HOOKS,
1486                 NULL /* closure */,
1487                 NULL /* accumulator */,
1488                 NULL /* accumulator data */,
1489                 NULL /* C marshaller */,
1490                 G_TYPE_NONE /* return_type */,
1491                 0     /* n_params */,
1492                 NULL  /* param_types */);
1493</programlisting></informalexample>
1494      and the signal is emitted in <function>viewer_file_write</function>:
1495<informalexample><programlisting>
1496void
1497viewer_file_write (ViewerFile   *self,
1498                   const guint8 *buffer,
1499                   gsize         size)
1500{
1501  g_return_if_fail (VIEWER_IS_FILE (self));
1502  g_return_if_fail (buffer != NULL || size == 0);
1503
1504  /* First write data. */
1505
1506  /* Then, notify user of data written. */
1507  g_signal_emit (self, file_signals[CHANGED], 0 /* details */);
1508}
1509</programlisting></informalexample>
1510      As shown above, the details parameter can safely be set to zero if no
1511      detail needs to be conveyed. For a discussion of what it can be used for,
1512      see <xref linkend="signal-detail"/>
1513    </para>
1514
1515    <para>
1516      The C signal marshaller should always be <literal>NULL</literal>, in which
1517      case the best marshaller for the given closure type will be chosen by
1518      GLib. This may be an internal marshaller specific to the closure type, or
1519      <function>g_cclosure_marshal_generic</function>, which implements generic
1520      conversion of arrays of parameters to C callback invocations. GLib used to
1521      require the user to write or generate a type-specific marshaller and pass
1522      that, but that has been deprecated in favour of automatic selection of
1523      marshallers.
1524    </para>
1525
1526    <para>
1527      Note that <function>g_cclosure_marshal_generic</function> is slower than
1528      non-generic marshallers, so should be avoided for performance critical
1529      code. However, performance critical code should rarely be using signals
1530      anyway, as emitting a signal blocks on emitting it to all listeners, which
1531      has potentially unbounded cost.
1532    </para>
1533  </sect1>
1534</chapter>
1535</part>
1536