nexmon – Blame information for rev 1

Subversion Repositories:
Rev:
Rev Author Line No. Line
1 office 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  
100 G_BEGIN_DECLS
101  
102 /*
103 * Type declaration.
104 */
105 #define VIEWER_TYPE_FILE viewer_file_get_type ()
106 G_DECLARE_FINAL_TYPE (ViewerFile, viewer_file, VIEWER, FILE, GObject)
107  
108 /*
109 * Method definitions.
110 */
111 ViewerFile *viewer_file_new (void);
112  
113 G_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  
138 G_BEGIN_DECLS
139  
140 /*
141 * Type declaration.
142 */
143 #define VIEWER_TYPE_FILE viewer_file_get_type ()
144 G_DECLARE_DERIVABLE_TYPE (ViewerFile, viewer_file, VIEWER, FILE, GObject)
145  
146 struct _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 */
162 ViewerFile *viewer_file_new (void);
163  
164 G_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. */
194 typedef 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>
210 struct _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>
252 G_DEFINE_TYPE (ViewerFile, viewer_file, G_TYPE_OBJECT)
253 </programlisting></informalexample>
254 or
255 <informalexample><programlisting>
256 G_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>
307 G_DEFINE_TYPE_WITH_PRIVATE (ViewerFile, viewer_file, G_TYPE_OBJECT)
308  
309 static void
310 viewer_file_class_init (ViewerFileClass *klass)
311 {
312 }
313  
314 static void
315 viewer_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>
338 enum
339 {
340 PROP_FILENAME = 1,
341 PROP_ZOOM_LEVEL,
342 N_PROPERTIES
343 };
344  
345 static GParamSpec *obj_properties[N_PROPERTIES] = { NULL, };
346  
347 static void
348 viewer_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  
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 a 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>
415 struct _ViewerFilePrivate
416 {
417 gchar *filename;
418 guint zoom_level;
419  
420 GInputStream *input_stream;
421 };
422  
423 G_DEFINE_TYPE_WITH_PRIVATE (ViewerFile, viewer_file, G_TYPE_OBJECT)
424  
425 static void
426 viewer_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  
449 static void
450 viewer_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  
462 static void
463 viewer_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  
471 static void
472 viewer_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. */
523 void viewer_file_open (ViewerFile *self,
524 GError **error);
525  
526 /* implementation in the source file */
527 void
528 viewer_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 ()
575 G_DECLARE_DERIVABLE_TYPE (ViewerFile, viewer_file, VIEWER, FILE, GObject)
576  
577 struct _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  
590 void viewer_file_open (ViewerFile *self,
591 GError **error);
592  
593 /* implementation in viewer-file.c */
594 void
595 viewer_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>
622 static void
623 viewer_file_real_close (ViewerFile *self,
624 GError **error)
625 {
626 /* Default implementation for the virtual method. */
627 }
628  
629 static void
630 viewer_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  
642 void
643 viewer_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  
662 void
663 viewer_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. */
689 struct _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  
706 void 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. */
712 static gboolean
713 viewer_file_can_memory_map (ViewerFile *self)
714 {
715 return VIEWER_FILE_GET_CLASS (self)->can_memory_map (self);
716 }
717  
718 void
719 viewer_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>
745 static gboolean
746 viewer_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  
753 static void
754 viewer_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>
765 static void
766 viewer_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>
827 static void
828 b_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-instantiable-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 two 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  
874 G_BEGIN_DECLS
875  
876 #define VIEWER_TYPE_EDITABLE viewer_editable_get_type ()
877 G_DECLARE_INTERFACE (ViewerEditable, viewer_editable, VIEWER, EDITABLE, GObject)
878  
879 struct _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  
891 void viewer_editable_save (ViewerEditable *self,
892 GError **error);
893 void viewer_editable_undo (ViewerEditable *self,
894 guint n_steps);
895 void viewer_editable_redo (ViewerEditable *self,
896 guint n_steps);
897  
898 G_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>
941 G_DEFINE_INTERFACE (ViewerEditable, viewer_editable, G_TYPE_OBJECT);
942  
943 static void
944 viewer_editable_default_init (ViewerEditableInterface *iface)
945 {
946 /* add properties and signals to the interface here */
947 }
948  
949 void
950 viewer_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  
963 void
964 viewer_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  
976 void
977 viewer_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>
1013 static void viewer_file_editable_interface_init (ViewerEditableInterface *iface);
1014  
1015 G_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>
1035 static void
1036 viewer_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  
1043 static void
1044 viewer_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  
1051 static void
1052 viewer_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  
1059 static void
1060 viewer_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  
1067 static void
1068 viewer_file_init (ViewerFile *self)
1069 {
1070 /* Instance variable initialisation code. */
1071 }
1072 </programlisting></informalexample>
1073 </para>
1074 </sect1>
1075  
1076 <sect1 id="howto-interface-prerequisite">
1077 <title>Interface definition prerequisites</title>
1078  
1079 <para>
1080 To specify that an interface requires the presence of other interfaces
1081 when implemented, GObject introduces the concept of
1082 <emphasis>prerequisites</emphasis>: it is possible to associate
1083 a list of prerequisite types to an interface. For example, if
1084 object A wishes to implement interface I1, and if interface I1 has a
1085 prerequisite on interface I2, A has to implement both I1 and I2.
1086 </para>
1087  
1088 <para>
1089 The mechanism described above is, in practice, very similar to
1090 Java's interface I1 extends interface I2. The example below shows
1091 the GObject equivalent:
1092 <informalexample><programlisting>
1093 /* Make the ViewerEditableLossy interface require ViewerEditable interface. */
1094 G_DEFINE_INTERFACE (ViewerEditableLossy, viewer_editable_lossy, VIEWER_TYPE_EDITABLE);
1095 </programlisting></informalexample>
1096 In the <function><link linkend="G-DEFINE-INTERFACE:CAPS">G_DEFINE_INTERFACE</link></function>
1097 call above, the third parameter defines the prerequisite type. This
1098 is the GType of either an interface or a class. In this case
1099 the <type>ViewerEditable</type> interface is a prerequisite of
1100 <type>ViewerEditableLossy</type>. The code
1101 below shows how an implementation can implement both interfaces and
1102 register their implementations:
1103 <informalexample><programlisting>
1104 static void
1105 viewer_file_editable_lossy_compress (ViewerEditableLossy *editable)
1106 {
1107 ViewerFile *self = VIEWER_FILE (editable);
1108  
1109 g_print ("File implementation of lossy editable interface compress method: %s.\n",
1110 self->filename);
1111 }
1112  
1113 static void
1114 viewer_file_editable_lossy_interface_init (ViewerEditableLossyInterface *iface)
1115 {
1116 iface->compress = viewer_file_editable_lossy_compress;
1117 }
1118  
1119 static void
1120 viewer_file_editable_save (ViewerEditable *editable,
1121 GError **error)
1122 {
1123 ViewerFile *self = VIEWER_FILE (editable);
1124  
1125 g_print ("File implementation of editable interface save method: %s.\n",
1126 self->filename);
1127 }
1128  
1129 static void
1130 viewer_file_editable_undo (ViewerEditable *editable,
1131 guint n_steps)
1132 {
1133 ViewerFile *self = VIEWER_FILE (editable);
1134  
1135 g_print ("File implementation of editable interface undo method: %s.\n",
1136 self->filename);
1137 }
1138  
1139 static void
1140 viewer_file_editable_redo (ViewerEditable *editable,
1141 guint n_steps)
1142 {
1143 ViewerFile *self = VIEWER_FILE (editable);
1144  
1145 g_print ("File implementation of editable interface redo method: %s.\n",
1146 self->filename);
1147 }
1148  
1149 static void
1150 viewer_file_editable_interface_init (ViewerEditableInterface *iface)
1151 {
1152 iface->save = viewer_file_editable_save;
1153 iface->undo = viewer_file_editable_undo;
1154 iface->redo = viewer_file_editable_redo;
1155 }
1156  
1157 static void
1158 viewer_file_class_init (ViewerFileClass *klass)
1159 {
1160 /* Nothing here. */
1161 }
1162  
1163 static void
1164 viewer_file_init (ViewerFile *self)
1165 {
1166 /* Instance variable initialisation code. */
1167 }
1168  
1169 G_DEFINE_TYPE_WITH_CODE (ViewerFile, viewer_file, G_TYPE_OBJECT,
1170 G_IMPLEMENT_INTERFACE (VIEWER_TYPE_EDITABLE,
1171 viewer_file_editable_interface_init)
1172 G_IMPLEMENT_INTERFACE (VIEWER_TYPE_EDITABLE_LOSSY,
1173 viewer_file_editable_lossy_interface_init))
1174 </programlisting></informalexample>
1175 It is very important to notice that the order in which interface
1176 implementations are added to the main object is not random:
1177 <function><link linkend="g-type-add-interface-static">g_type_add_interface_static</link></function>,
1178 which is called by
1179 <function><link linkend="G-DEFINE-INTERFACE:CAPS">G_IMPLEMENT_INTERFACE</link></function>,
1180 must be invoked first on the interfaces which have no prerequisites and then on
1181 the others.
1182 </para>
1183 </sect1>
1184  
1185 <sect1 id="howto-interface-properties">
1186 <title>Interface properties</title>
1187  
1188 <para>
1189 GObject interfaces can also have
1190 properties. Declaration of the interface properties is similar to
1191 declaring the properties of ordinary GObject types as explained in
1192 <xref linkend="gobject-properties"/>, except that
1193 <function><link linkend="g-object-interface-install-property">g_object_interface_install_property</link></function>
1194 is used to declare the properties instead of
1195 <function><link linkend="g-object-class-install-property">g_object_class_install_property</link></function>.
1196 </para>
1197  
1198 <para>
1199 To include a property named 'autosave-frequency' of type <type>gdouble</type> in the
1200 <type>ViewerEditable</type> interface example code above, we only need to
1201 add one call in <function>viewer_editable_default_init</function> as shown
1202 below:
1203 <informalexample><programlisting>
1204 static void
1205 viewer_editable_default_init (ViewerEditableInterface *iface)
1206 {
1207 g_object_interface_install_property (iface,
1208 g_param_spec_double ("autosave-frequency",
1209 "Autosave frequency",
1210 "Frequency (in per-seconds) to autosave backups of the editable content at. "
1211 "Or zero to disable autosaves.",
1212 0.0, /* minimum */
1213 G_MAXDOUBLE, /* maximum */
1214 0.0, /* default */
1215 G_PARAM_READWRITE));
1216 }
1217 </programlisting></informalexample>
1218 </para>
1219  
1220 <para>
1221 One point worth noting is that the declared property wasn't assigned an
1222 integer ID. The reason being that integer IDs of properties are used
1223 only inside the <function>get_property</function> and
1224 <function>set_property</function> virtual methods. Since interfaces
1225 declare but do not <emphasis>implement</emphasis> properties, there is no
1226 need to assign integer IDs to them.
1227 </para>
1228  
1229 <para>
1230 An implementation declares and defines its properties in the usual
1231 way as explained in <xref linkend="gobject-properties"/>, except for one
1232 small change: it can declare the properties of the interface it
1233 implements using <function><link linkend="g-object-class-override-property">g_object_class_override_property</link></function>
1234 instead of <function><link linkend="g-object-class-install-property">g_object_class_install_property</link></function>.
1235 The following code snippet shows the modifications needed in the
1236 <type>ViewerFile</type> declaration and implementation above:
1237 <informalexample><programlisting>
1238 struct _ViewerFile
1239 {
1240 GObject parent_instance;
1241  
1242 gdouble autosave_frequency;
1243 };
1244  
1245 enum
1246 {
1247 PROP_AUTOSAVE_FREQUENCY = 1,
1248 N_PROPERTIES
1249 };
1250  
1251 static void
1252 viewer_file_set_property (GObject *object,
1253 guint prop_id,
1254 const GValue *value,
1255 GParamSpec *pspec)
1256 {
1257 ViewerFile *file = VIEWER_FILE (object);
1258  
1259 switch (prop_id)
1260 {
1261 case PROP_AUTOSAVE_FREQUENCY:
1262 file->autosave_frequency = g_value_get_double (value);
1263 break;
1264  
1265 default:
1266 G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
1267 break;
1268 }
1269 }
1270  
1271 static void
1272 viewer_file_get_property (GObject *object,
1273 guint prop_id,
1274 GValue *value,
1275 GParamSpec *pspec)
1276 {
1277 ViewerFile *file = VIEWER_FILE (object);
1278  
1279 switch (prop_id)
1280 {
1281 case PROP_AUTOSAVE_FREQUENCY:
1282 g_value_set_double (value, file->autosave_frequency);
1283 break;
1284  
1285 default:
1286 G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
1287 break;
1288 }
1289 }
1290  
1291 static void
1292 viewer_file_class_init (ViewerFileClass *klass)
1293 {
1294 GObjectClass *object_class = G_OBJECT_CLASS (klass);
1295  
1296 object_class->set_property = viewer_file_set_property;
1297 object_class->get_property = viewer_file_get_property;
1298  
1299 g_object_class_override_property (object_class, PROP_AUTOSAVE_FREQUENCY, "autosave-frequency");
1300 }
1301 </programlisting></informalexample>
1302 </para>
1303  
1304 </sect1>
1305  
1306 <sect1 id="howto-interface-override">
1307 <title>Overriding interface methods</title>
1308  
1309 <para>
1310 If a base class already implements an interface and a derived
1311 class needs to implement the same interface but needs to override certain
1312 methods, you must reimplement the interface and set only the interface
1313 methods which need overriding.
1314 </para>
1315  
1316 <para>
1317 In this example, <type>ViewerAudioFile</type> is derived from
1318 <type>ViewerFile</type>. Both implement the <type>ViewerEditable</type>
1319 interface. <type>ViewerAudioFile</type> only implements one method of the
1320 <type>ViewerEditable</type> interface and uses the base class implementation of
1321 the other.
1322 <informalexample><programlisting>
1323 static void
1324 viewer_audio_file_editable_save (ViewerEditable *editable,
1325 GError **error)
1326 {
1327 ViewerAudioFile *self = VIEWER_AUDIO_FILE (editable);
1328  
1329 g_print ("Audio file implementation of editable interface save method.\n");
1330 }
1331  
1332 static void
1333 viewer_audio_file_editable_interface_init (ViewerEditableInterface *iface)
1334 {
1335 /* Override the implementation of save(). */
1336 iface->save = viewer_audio_file_editable_save;
1337  
1338 /*
1339 * Leave iface->undo and ->redo alone, they are already set to the
1340 * base class implementation.
1341 */
1342 }
1343  
1344 G_DEFINE_TYPE_WITH_CODE (ViewerAudioFile, viewer_audio_file, VIEWER_TYPE_FILE,
1345 G_IMPLEMENT_INTERFACE (VIEWER_TYPE_EDITABLE,
1346 viewer_audio_file_editable_interface_init))
1347  
1348 static void
1349 viewer_audio_file_class_init (ViewerAudioFileClass *klass)
1350 {
1351 /* Nothing here. */
1352 }
1353  
1354 static void
1355 viewer_audio_file_init (ViewerAudioFile *self)
1356 {
1357 /* Nothing here. */
1358 }
1359 </programlisting></informalexample>
1360 </para>
1361  
1362 <para>
1363 To access the base class interface implementation use
1364 <function><link linkend="g-type-interface-peek-parent">g_type_interface_peek_parent</link></function>
1365 from within an interface's <function>default_init</function> function.
1366 </para>
1367  
1368 <para>
1369 To call the base class implementation of an interface
1370 method from an derived class where than interface method has been
1371 overridden, stash away the pointer returned from
1372 <function><link linkend="g-type-interface-peek-parent">g_type_interface_peek_parent</link></function>
1373 in a global variable.
1374 </para>
1375  
1376 <para>
1377 In this example <type>ViewerAudioFile</type> overrides the
1378 <function>save</function> interface method. In its overridden method
1379 it calls the base class implementation of the same interface method.
1380 <informalexample><programlisting>
1381 static ViewerEditableInterface *viewer_editable_parent_interface = NULL;
1382  
1383 static void
1384 viewer_audio_file_editable_save (ViewerEditable *editable,
1385 GError **error)
1386 {
1387 ViewerAudioFile *self = VIEWER_AUDIO_FILE (editable);
1388  
1389 g_print ("Audio file implementation of editable interface save method.\n");
1390  
1391 /* Now call the base implementation */
1392 viewer_editable_parent_interface->save (editable, error);
1393 }
1394  
1395 static void
1396 viewer_audio_file_editable_interface_init (ViewerEditableInterface *iface)
1397 {
1398 viewer_editable_parent_interface = g_type_interface_peek_parent (iface);
1399  
1400 iface->save = viewer_audio_file_editable_save;
1401 }
1402  
1403 G_DEFINE_TYPE_WITH_CODE (ViewerAudioFile, viewer_audio_file, VIEWER_TYPE_FILE,
1404 G_IMPLEMENT_INTERFACE (VIEWER_TYPE_EDITABLE,
1405 viewer_audio_file_editable_interface_init))
1406  
1407 static void
1408 viewer_audio_file_class_init (ViewerAudioFileClass *klass)
1409 {
1410 /* Nothing here. */
1411 }
1412  
1413 static void
1414 viewer_audio_file_init (ViewerAudioFile *self)
1415 {
1416 /* Nothing here. */
1417 }
1418 </programlisting></informalexample>
1419 </para>
1420  
1421 </sect1>
1422  
1423 </chapter>
1424 <!-- End Howto Interfaces -->
1425  
1426 <chapter id="howto-signals">
1427 <title>How to create and use signals</title>
1428  
1429 <para>
1430 The signal system in GType is pretty complex and
1431 flexible: it is possible for its users to connect at runtime any
1432 number of callbacks (implemented in any language for which a binding
1433 exists)
1434 <footnote>
1435 <para>A Python callback can be connected to any signal on any
1436 C-based GObject, and vice versa, assuming that the Python object
1437 inherits from GObject.</para>
1438 </footnote>
1439 to any signal and to stop the emission of any signal at any
1440 state of the signal emission process. This flexibility makes it
1441 possible to use GSignal for much more than just emitting signals to
1442 multiple clients.
1443 </para>
1444  
1445 <sect1 id="howto-simple-signals">
1446 <title>Simple use of signals</title>
1447  
1448 <para>
1449 The most basic use of signals is to implement event
1450 notification. For example, given a <type>ViewerFile</type> object with
1451 a <function>write</function> method, a signal could be emitted whenever
1452 the file is changed using that method.
1453 The code below shows how the user can connect a callback to the
1454 "changed" signal.
1455 <informalexample><programlisting>
1456 file = g_object_new (VIEWER_FILE_TYPE, NULL);
1457  
1458 g_signal_connect (file, "changed", (GCallback) changed_event, NULL);
1459  
1460 viewer_file_write (file, buffer, strlen (buffer));
1461 </programlisting></informalexample>
1462 </para>
1463  
1464 <para>
1465 The <type>ViewerFile</type> signal is registered in the
1466 <function>class_init</function> function:
1467 <informalexample><programlisting>
1468 file_signals[CHANGED] =
1469 g_signal_newv ("changed",
1470 G_TYPE_FROM_CLASS (object_class),
1471 G_SIGNAL_RUN_LAST | G_SIGNAL_NO_RECURSE | G_SIGNAL_NO_HOOKS,
1472 NULL /* closure */,
1473 NULL /* accumulator */,
1474 NULL /* accumulator data */,
1475 NULL /* C marshaller */,
1476 G_TYPE_NONE /* return_type */,
1477  
1478 NULL /* param_types */);
1479 </programlisting></informalexample>
1480 and the signal is emitted in <function>viewer_file_write</function>:
1481 <informalexample><programlisting>
1482 void
1483 viewer_file_write (ViewerFile *self,
1484 const guint8 *buffer,
1485 gsize size)
1486 {
1487 g_return_if_fail (VIEWER_IS_FILE (self));
1488 g_return_if_fail (buffer != NULL || size == 0);
1489  
1490 /* First write data. */
1491  
1492 /* Then, notify user of data written. */
1493 g_signal_emit (self, file_signals[CHANGED], 0 /* details */);
1494 }
1495 </programlisting></informalexample>
1496 As shown above, the details parameter can safely be set to zero if no
1497 detail needs to be conveyed. For a discussion of what it can be used for,
1498 see <xref linkend="signal-detail"/>
1499 </para>
1500  
1501 <para>
1502 The C signal marshaller should always be <literal>NULL</literal>, in which
1503 case the best marshaller for the given closure type will be chosen by
1504 GLib. This may be an internal marshaller specific to the closure type, or
1505 <function>g_cclosure_marshal_generic</function>, which implements generic
1506 conversion of arrays of parameters to C callback invocations. GLib used to
1507 require the user to write or generate a type-specific marshaller and pass
1508 that, but that has been deprecated in favour of automatic selection of
1509 marshallers.
1510 </para>
1511  
1512 <para>
1513 Note that <function>g_cclosure_marshal_generic</function> is slower than
1514 non-generic marshallers, so should be avoided for performance critical
1515 code. However, performance critical code should rarely be using signals
1516 anyway, as emitting a signal blocks on emitting it to all listeners, which
1517 has potentially unbounded cost.
1518 </para>
1519 </sect1>
1520 </chapter>
1521 </part>