mirror of
https://gitlab.gnome.org/GNOME/glib.git
synced 2024-12-28 00:16:15 +01:00
f722f11e57
GTK lost it's '+' suffix back in 2019, according to <https://mail.gnome.org/archives/gtk-devel-list/2019-February/msg00000.html> This commit can be re-generated with: git grep -l GTK+ \ | grep -v -e ^NEWS -e ^glib/tests/collate.c \ | xargs sed -i 's/GTK+/GTK/g' Most of the changes are in comments and documentation.
1536 lines
53 KiB
XML
1536 lines
53 KiB
XML
<?xml version='1.0' encoding="UTF-8"?>
|
||
<!DOCTYPE part PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
|
||
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
|
||
]>
|
||
<part label="IV">
|
||
<title>Tutorial</title>
|
||
<partintro>
|
||
<para>
|
||
This chapter tries to answer the real-life questions of users and presents
|
||
the most common use cases in order from most likely to least
|
||
likely.
|
||
</para>
|
||
</partintro>
|
||
|
||
<chapter id="howto-gobject">
|
||
<title>How to define and implement a new GObject</title>
|
||
|
||
<para>
|
||
This chapter focuses on the implementation of a subtype of GObject, for
|
||
example to create a custom class hierarchy, or to subclass a GTK widget.
|
||
</para>
|
||
|
||
<para>
|
||
Throughout the chapter, a running example of a file viewer program is used,
|
||
which has a <type>ViewerFile</type> class to represent a single file being
|
||
viewed, and various derived classes for different types of files with
|
||
special functionality, such as audio files. The example application also
|
||
supports editing files (for example, to tweak a photo being viewed), using
|
||
a <type>ViewerEditable</type> interface.
|
||
</para>
|
||
|
||
<sect1 id="howto-gobject-header">
|
||
<title>Boilerplate header code</title>
|
||
|
||
<para>
|
||
The first step before writing the code for your GObject is to write the
|
||
type's header which contains the needed type, function and macro
|
||
definitions. Each of these elements is nothing but a convention which
|
||
is followed by almost all users of GObject, and has been refined over
|
||
multiple years of experience developing GObject-based code. If you are
|
||
writing a library, it is particularly important for you to adhere closely
|
||
to these conventions; users of your library will assume that you have.
|
||
Even if not writing a library, it will help other people who want to work
|
||
on your project.
|
||
</para>
|
||
|
||
<para>
|
||
Pick a name convention for your headers and source code and stick to it:
|
||
<itemizedlist>
|
||
<listitem><para>use a dash to separate the prefix from the typename:
|
||
<filename>viewer-file.h</filename> and <filename>viewer-file.c</filename>
|
||
(this is the convention used by Nautilus and most GNOME libraries).</para></listitem>
|
||
<listitem><para>use an underscore to separate the prefix from the
|
||
typename: <filename>viewer_file.h</filename> and
|
||
<filename>viewer_file.c</filename>.</para></listitem>
|
||
<listitem><para>Do not separate the prefix from the typename:
|
||
<filename>viewerfile.h</filename> and <filename>viewerfile.c</filename>.
|
||
(this is the convention used by GTK)</para></listitem>
|
||
</itemizedlist>
|
||
Some people like the first two solutions better: it makes reading file
|
||
names easier for those with poor eyesight.
|
||
</para>
|
||
|
||
<para>
|
||
The basic conventions for any header which exposes a GType are described
|
||
in <xref linkend="gtype-conventions"/>.
|
||
</para>
|
||
|
||
<para>
|
||
If you want to declare a type named ‘file’ in namespace ‘viewer’, name the
|
||
type instance <function>ViewerFile</function> and its class
|
||
<function>ViewerFileClass</function> (names are case sensitive). The
|
||
recommended method of declaring a type differs based on whether the type
|
||
is final or derivable.
|
||
</para>
|
||
|
||
<para>
|
||
Final types cannot be subclassed further, and should be the default choice
|
||
for new types — changing a final type to be derivable is always a change
|
||
that will be compatible with existing uses of the code, but the converse
|
||
will often cause problems. Final types are declared using
|
||
<link linkend="G-DECLARE-FINAL-TYPE:CAPS"><function>G_DECLARE_FINAL_TYPE</function></link>,
|
||
and require a structure to hold the instance data to be declared in the
|
||
source code (not the header file).
|
||
|
||
<informalexample><programlisting>
|
||
/*
|
||
* Copyright/Licensing information.
|
||
*/
|
||
|
||
/* inclusion guard */
|
||
#ifndef __VIEWER_FILE_H__
|
||
#define __VIEWER_FILE_H__
|
||
|
||
#include <glib-object.h>
|
||
/*
|
||
* Potentially, include other headers on which this header depends.
|
||
*/
|
||
|
||
G_BEGIN_DECLS
|
||
|
||
/*
|
||
* Type declaration.
|
||
*/
|
||
#define VIEWER_TYPE_FILE viewer_file_get_type ()
|
||
G_DECLARE_FINAL_TYPE (ViewerFile, viewer_file, VIEWER, FILE, GObject)
|
||
|
||
/*
|
||
* Method definitions.
|
||
*/
|
||
ViewerFile *viewer_file_new (void);
|
||
|
||
G_END_DECLS
|
||
|
||
#endif /* __VIEWER_FILE_H__ */
|
||
</programlisting></informalexample>
|
||
</para>
|
||
|
||
<para>
|
||
Derivable types <emphasis>can</emphasis> be subclassed further, and their class and
|
||
instance structures form part of the public API which must not be changed
|
||
if API stability is cared about. They are declared using
|
||
<link linkend="G-DECLARE-DERIVABLE-TYPE:CAPS"><function>G_DECLARE_DERIVABLE_TYPE</function></link>:
|
||
<informalexample><programlisting>
|
||
/*
|
||
* Copyright/Licensing information.
|
||
*/
|
||
|
||
/* inclusion guard */
|
||
#ifndef __VIEWER_FILE_H__
|
||
#define __VIEWER_FILE_H__
|
||
|
||
#include <glib-object.h>
|
||
/*
|
||
* Potentially, include other headers on which this header depends.
|
||
*/
|
||
|
||
G_BEGIN_DECLS
|
||
|
||
/*
|
||
* Type declaration.
|
||
*/
|
||
#define VIEWER_TYPE_FILE viewer_file_get_type ()
|
||
G_DECLARE_DERIVABLE_TYPE (ViewerFile, viewer_file, VIEWER, FILE, GObject)
|
||
|
||
struct _ViewerFileClass
|
||
{
|
||
GObjectClass parent_class;
|
||
|
||
/* Class virtual function fields. */
|
||
void (* open) (ViewerFile *file,
|
||
GError **error);
|
||
|
||
/* Padding to allow adding up to 12 new virtual functions without
|
||
* breaking ABI. */
|
||
gpointer padding[12];
|
||
};
|
||
|
||
/*
|
||
* Method definitions.
|
||
*/
|
||
ViewerFile *viewer_file_new (void);
|
||
|
||
G_END_DECLS
|
||
|
||
#endif /* __VIEWER_FILE_H__ */
|
||
</programlisting></informalexample>
|
||
</para>
|
||
|
||
<para>
|
||
The convention for header includes is to add the minimum number of
|
||
<function>#include</function> directives to the top of your headers needed
|
||
to compile that header. This
|
||
allows client code to simply <function>#include "viewer-file.h"</function>,
|
||
without needing to know the prerequisites for
|
||
<filename>viewer-file.h</filename>.
|
||
</para>
|
||
</sect1>
|
||
|
||
<sect1 id="howto-gobject-code">
|
||
<title>Boilerplate code</title>
|
||
|
||
<para>
|
||
In your code, the first step is to <function>#include</function> the
|
||
needed headers:
|
||
<informalexample><programlisting>
|
||
/*
|
||
* Copyright information
|
||
*/
|
||
|
||
#include "viewer-file.h"
|
||
|
||
/* Private structure definition. */
|
||
typedef struct {
|
||
gchar *filename;
|
||
/* stuff */
|
||
} ViewerFilePrivate;
|
||
|
||
/*
|
||
* forward definitions
|
||
*/
|
||
</programlisting></informalexample>
|
||
</para>
|
||
|
||
<para>
|
||
If the class is being declared as final using
|
||
<function>G_DECLARE_FINAL_TYPE</function>, its instance structure should
|
||
be defined in the C file:
|
||
<informalexample><programlisting>
|
||
struct _ViewerFile
|
||
{
|
||
GObject parent_instance;
|
||
|
||
/* Other members, including private data. */
|
||
};
|
||
</programlisting></informalexample>
|
||
</para>
|
||
|
||
<para>
|
||
Call the <function>G_DEFINE_TYPE</function> macro (or
|
||
<function>G_DEFINE_TYPE_WITH_PRIVATE</function> if your class needs
|
||
private data — final types do <emphasis>not</emphasis> need private data)
|
||
using the name
|
||
of the type, the prefix of the functions and the parent GType to
|
||
reduce the amount of boilerplate needed. This macro will:
|
||
|
||
<itemizedlist>
|
||
<listitem><simpara>implement the <function>viewer_file_get_type</function>
|
||
function</simpara></listitem>
|
||
<listitem><simpara>define a parent class pointer accessible from
|
||
the whole .c file</simpara></listitem>
|
||
<listitem><simpara>add private instance data to the type (if using
|
||
<function>G_DEFINE_TYPE_WITH_PRIVATE</function>)</simpara></listitem>
|
||
</itemizedlist>
|
||
</para>
|
||
|
||
<para>
|
||
If the class has been declared as final using
|
||
<function>G_DECLARE_FINAL_TYPE</function> (see
|
||
<xref linkend="howto-gobject-header"/>), private data should be placed in
|
||
the instance structure, <type>ViewerFile</type>, and
|
||
<function>G_DEFINE_TYPE</function> should be used instead of
|
||
<function>G_DEFINE_TYPE_WITH_PRIVATE</function>. The instance structure
|
||
for a final class is not exposed publicly, and is not embedded in the
|
||
instance structures of any derived classes (because the class is final);
|
||
so its size can vary without causing incompatibilities for code which uses
|
||
the class. Conversely, private data for derivable classes
|
||
<emphasis>must</emphasis> be included in a private structure, and
|
||
<function>G_DEFINE_TYPE_WITH_PRIVATE</function> must be used.
|
||
|
||
<informalexample><programlisting>
|
||
G_DEFINE_TYPE (ViewerFile, viewer_file, G_TYPE_OBJECT)
|
||
</programlisting></informalexample>
|
||
or
|
||
<informalexample><programlisting>
|
||
G_DEFINE_TYPE_WITH_PRIVATE (ViewerFile, viewer_file, G_TYPE_OBJECT)
|
||
</programlisting></informalexample>
|
||
</para>
|
||
|
||
<para>
|
||
It is also possible to use the
|
||
<function>G_DEFINE_TYPE_WITH_CODE</function> macro to control the
|
||
<function>get_type</function> function implementation — for instance, to
|
||
add a call to the <function>G_IMPLEMENT_INTERFACE</function> macro to
|
||
implement an interface.
|
||
</para>
|
||
</sect1>
|
||
|
||
<sect1 id="howto-gobject-construction">
|
||
<title>Object construction</title>
|
||
|
||
<para>
|
||
People often get confused when trying to construct their GObjects because of the
|
||
sheer number of different ways to hook into the objects's construction process: it is
|
||
difficult to figure which is the <emphasis>correct</emphasis>, recommended way.
|
||
</para>
|
||
|
||
<para>
|
||
<xref linkend="gobject-construction-table"/> shows what user-provided functions
|
||
are invoked during object instantiation and in which order they are invoked.
|
||
A user looking for the equivalent of the simple C++ constructor function should use
|
||
the <function>instance_init</function> method. It will be invoked after
|
||
all the parents’ <function>instance_init</function>
|
||
functions have been invoked. It cannot take arbitrary construction parameters
|
||
(as in C++) but if your object needs arbitrary parameters to complete initialization,
|
||
you can use construction properties.
|
||
</para>
|
||
|
||
<para>
|
||
Construction properties will be set only after all
|
||
<function>instance_init</function> functions have run.
|
||
No object reference will be returned to the client of <function><link linkend="g-object-new">g_object_new</link></function>
|
||
until all the construction properties have been set.
|
||
</para>
|
||
|
||
<para>
|
||
It is important to note that object construction cannot <emphasis>ever</emphasis>
|
||
fail. If you require a fallible GObject construction, you can use the
|
||
<link linkend="GInitable"><type>GInitable</type></link> and
|
||
<link linkend="GAsyncInitable"><type>GAsyncInitable</type></link>
|
||
interfaces provided by the GIO library.
|
||
</para>
|
||
|
||
<para>
|
||
You should write the following code first:
|
||
<informalexample><programlisting>
|
||
G_DEFINE_TYPE_WITH_PRIVATE (ViewerFile, viewer_file, G_TYPE_OBJECT)
|
||
|
||
static void
|
||
viewer_file_class_init (ViewerFileClass *klass)
|
||
{
|
||
}
|
||
|
||
static void
|
||
viewer_file_init (ViewerFile *self)
|
||
{
|
||
ViewerFilePrivate *priv = viewer_file_get_instance_private (self);
|
||
|
||
/* initialize all public and private members to reasonable default values.
|
||
* They are all automatically initialized to 0 to begin with. */
|
||
}
|
||
</programlisting></informalexample>
|
||
</para>
|
||
|
||
<para>
|
||
If you need special construction properties (with
|
||
<link linkend="G-PARAM-CONSTRUCT-ONLY:CAPS"><function>G_PARAM_CONSTRUCT_ONLY</function></link>
|
||
set), install the properties in
|
||
the <function>class_init()</function> function, override the <function>set_property()</function>
|
||
and <function>get_property()</function> methods of the GObject class,
|
||
and implement them as described by <xref linkend="gobject-properties"/>.
|
||
</para>
|
||
|
||
<para>
|
||
Property IDs must start from 1, as 0 is reserved for internal use by
|
||
GObject.
|
||
<informalexample><programlisting>
|
||
enum
|
||
{
|
||
PROP_FILENAME = 1,
|
||
PROP_ZOOM_LEVEL,
|
||
N_PROPERTIES
|
||
};
|
||
|
||
static GParamSpec *obj_properties[N_PROPERTIES] = { NULL, };
|
||
|
||
static void
|
||
viewer_file_class_init (ViewerFileClass *klass)
|
||
{
|
||
GObjectClass *object_class = G_OBJECT_CLASS (klass);
|
||
|
||
object_class->set_property = viewer_file_set_property;
|
||
object_class->get_property = viewer_file_get_property;
|
||
|
||
obj_properties[PROP_FILENAME] =
|
||
g_param_spec_string ("filename",
|
||
"Filename",
|
||
"Name of the file to load and display from.",
|
||
NULL /* default value */,
|
||
G_PARAM_CONSTRUCT_ONLY | G_PARAM_READWRITE);
|
||
|
||
obj_properties[PROP_ZOOM_LEVEL] =
|
||
g_param_spec_uint ("zoom-level",
|
||
"Zoom level",
|
||
"Zoom level to view the file at.",
|
||
0 /* minimum value */,
|
||
10 /* maximum value */,
|
||
2 /* default value */,
|
||
G_PARAM_READWRITE);
|
||
|
||
g_object_class_install_properties (object_class,
|
||
N_PROPERTIES,
|
||
obj_properties);
|
||
}
|
||
</programlisting></informalexample>
|
||
If you need this, make sure you can build and run code similar to the
|
||
code shown above. Also, make sure your construct properties can be set
|
||
without side effects during construction.
|
||
</para>
|
||
|
||
<para>
|
||
Some people sometimes need to complete the initialization of an instance
|
||
of a type only after the properties passed to the constructors have been
|
||
set. This is possible through the use of the <function>constructor()</function>
|
||
class method as described in <xref linkend="gobject-instantiation"/> or,
|
||
more simply, using the <function>constructed()</function> class method.
|
||
Note that the <function>constructed()</function>
|
||
virtual function will only be invoked after the properties marked as
|
||
<function>G_PARAM_CONSTRUCT_ONLY</function> or
|
||
<function>G_PARAM_CONSTRUCT</function> have been consumed, but
|
||
before the regular properties passed to <function>g_object_new()</function>
|
||
have been set.
|
||
</para>
|
||
</sect1>
|
||
|
||
<sect1 id="howto-gobject-destruction">
|
||
<title>Object destruction</title>
|
||
|
||
<para>
|
||
Again, it is often difficult to figure out which mechanism to use to
|
||
hook into the object's destruction process: when the last
|
||
<function><link linkend="g-object-unref">g_object_unref</link></function>
|
||
function call is made, a lot of things happen as described in
|
||
<xref linkend="gobject-destruction-table"/>.
|
||
</para>
|
||
|
||
<para>
|
||
The destruction process of your object is in two phases: dispose and
|
||
finalize. This split is necessary to handle
|
||
potential cycles due to the nature of the reference counting mechanism
|
||
used by GObject, as well as dealing with temporary revival of
|
||
instances in case of signal emission during the destruction sequence.
|
||
See <xref linkend="gobject-memory-cycles"/> for more information.
|
||
<informalexample><programlisting>
|
||
struct _ViewerFilePrivate
|
||
{
|
||
gchar *filename;
|
||
guint zoom_level;
|
||
|
||
GInputStream *input_stream;
|
||
};
|
||
|
||
G_DEFINE_TYPE_WITH_PRIVATE (ViewerFile, viewer_file, G_TYPE_OBJECT)
|
||
|
||
static void
|
||
viewer_file_dispose (GObject *gobject)
|
||
{
|
||
ViewerFilePrivate *priv = viewer_file_get_instance_private (VIEWER_FILE (gobject));
|
||
|
||
/* In dispose(), you are supposed to free all types referenced from this
|
||
* object which might themselves hold a reference to self. Generally,
|
||
* the most simple solution is to unref all members on which you own a
|
||
* reference.
|
||
*/
|
||
|
||
/* dispose() might be called multiple times, so we must guard against
|
||
* calling g_object_unref() on an invalid GObject by setting the member
|
||
* NULL; g_clear_object() does this for us.
|
||
*/
|
||
g_clear_object (&priv->input_stream);
|
||
|
||
/* Always chain up to the parent class; there is no need to check if
|
||
* the parent class implements the dispose() virtual function: it is
|
||
* always guaranteed to do so
|
||
*/
|
||
G_OBJECT_CLASS (viewer_file_parent_class)->dispose (gobject);
|
||
}
|
||
|
||
static void
|
||
viewer_file_finalize (GObject *gobject)
|
||
{
|
||
ViewerFilePrivate *priv = viewer_file_get_instance_private (VIEWER_FILE (gobject));
|
||
|
||
g_free (priv->filename);
|
||
|
||
/* Always chain up to the parent class; as with dispose(), finalize()
|
||
* is guaranteed to exist on the parent's class virtual function table
|
||
*/
|
||
G_OBJECT_CLASS (viewer_file_parent_class)->finalize (gobject);
|
||
}
|
||
|
||
static void
|
||
viewer_file_class_init (ViewerFileClass *klass)
|
||
{
|
||
GObjectClass *object_class = G_OBJECT_CLASS (klass);
|
||
|
||
object_class->dispose = viewer_file_dispose;
|
||
object_class->finalize = viewer_file_finalize;
|
||
}
|
||
|
||
static void
|
||
viewer_file_init (ViewerFile *self);
|
||
{
|
||
ViewerFilePrivate *priv = viewer_file_get_instance_private (self);
|
||
|
||
priv->input_stream = g_object_new (VIEWER_TYPE_INPUT_STREAM, NULL);
|
||
priv->filename = /* would be set as a property */;
|
||
}
|
||
</programlisting></informalexample>
|
||
</para>
|
||
|
||
<para>
|
||
It is possible that object methods might be invoked after dispose is
|
||
run and before finalize runs. GObject does not consider this to be a
|
||
program error: you must gracefully detect this and neither crash nor
|
||
warn the user, by having a disposed instance revert to an inert state.
|
||
</para>
|
||
</sect1>
|
||
|
||
<sect1 id="howto-gobject-methods">
|
||
<title>Object methods</title>
|
||
|
||
<para>
|
||
Just as with C++, there are many different ways to define object
|
||
methods and extend them: the following list and sections draw on
|
||
C++ vocabulary. (Readers are expected to know basic C++ concepts.
|
||
Those who have not had to write C++ code recently can refer to e.g.
|
||
<ulink url="http://www.cplusplus.com/doc/tutorial/"/> to refresh
|
||
their memories.)
|
||
<itemizedlist>
|
||
<listitem><para>
|
||
non-virtual public methods,
|
||
</para></listitem>
|
||
<listitem><para>
|
||
virtual public methods and
|
||
</para></listitem>
|
||
<listitem><para>
|
||
virtual private methods
|
||
</para></listitem>
|
||
</itemizedlist>
|
||
</para>
|
||
|
||
<sect2 id="non-virtual-public-methods">
|
||
<title>Non-virtual public methods</title>
|
||
|
||
<para>
|
||
These are the simplest, providing a simple method which
|
||
acts on the object. Provide a function
|
||
prototype in the header and an implementation of that prototype
|
||
in the source file.
|
||
<informalexample><programlisting>
|
||
/* declaration in the header. */
|
||
void viewer_file_open (ViewerFile *self,
|
||
GError **error);
|
||
|
||
/* implementation in the source file */
|
||
void
|
||
viewer_file_open (ViewerFile *self,
|
||
GError **error)
|
||
{
|
||
g_return_if_fail (VIEWER_IS_FILE (self));
|
||
g_return_if_fail (error == NULL || *error == NULL);
|
||
|
||
/* do stuff here. */
|
||
}
|
||
</programlisting></informalexample>
|
||
</para>
|
||
</sect2>
|
||
|
||
<sect2 id="virtual-public-methods">
|
||
<title>Virtual public methods</title>
|
||
|
||
<para>
|
||
This is the preferred way to create GObjects with overridable methods:
|
||
<itemizedlist>
|
||
<listitem><para>
|
||
Define the common method and its virtual function in the
|
||
class structure in the public header
|
||
</para></listitem>
|
||
<listitem><para>
|
||
Define the common method in the header file and implement it in the
|
||
source file
|
||
</para></listitem>
|
||
<listitem><para>
|
||
Implement a base version of the virtual function in the source
|
||
file and initialize the virtual function pointer to this
|
||
implementation in the object’s <function>class_init</function>
|
||
function; or leave it as <constant>NULL</constant> for a ‘pure
|
||
virtual’ method which must be overridden by derived classes
|
||
</para></listitem>
|
||
<listitem><para>
|
||
Re-implement the virtual function in each derived class which needs
|
||
to override it
|
||
</para></listitem>
|
||
</itemizedlist>
|
||
</para>
|
||
<para>
|
||
Note that virtual functions can only be defined if the class is
|
||
derivable, declared using
|
||
<link linkend="G-DECLARE-DERIVABLE-TYPE:CAPS"><function>G_DECLARE_DERIVABLE_TYPE</function></link>
|
||
so the class structure can be defined.
|
||
<informalexample><programlisting>
|
||
/* declaration in viewer-file.h. */
|
||
#define VIEWER_TYPE_FILE viewer_file_get_type ()
|
||
G_DECLARE_DERIVABLE_TYPE (ViewerFile, viewer_file, VIEWER, FILE, GObject)
|
||
|
||
struct _ViewerFileClass
|
||
{
|
||
GObjectClass parent_class;
|
||
|
||
/* stuff */
|
||
void (*open) (ViewerFile *self,
|
||
GError **error);
|
||
|
||
/* Padding to allow adding up to 12 new virtual functions without
|
||
* breaking ABI. */
|
||
gpointer padding[12];
|
||
};
|
||
|
||
void viewer_file_open (ViewerFile *self,
|
||
GError **error);
|
||
|
||
/* implementation in viewer-file.c */
|
||
void
|
||
viewer_file_open (ViewerFile *self,
|
||
GError **error)
|
||
{
|
||
ViewerFileClass *klass;
|
||
|
||
g_return_if_fail (VIEWER_IS_FILE (self));
|
||
g_return_if_fail (error == NULL || *error == NULL);
|
||
|
||
klass = VIEWER_FILE_GET_CLASS (self);
|
||
g_return_if_fail (klass->open != NULL);
|
||
|
||
klass->open (self, error);
|
||
}
|
||
</programlisting></informalexample>
|
||
The code above simply redirects the <function>open</function> call
|
||
to the relevant virtual function.
|
||
</para>
|
||
|
||
<para>
|
||
It is possible to provide a default
|
||
implementation for this class method in the object's
|
||
<function>class_init</function> function: initialize the
|
||
<function>klass->open</function> field to a pointer to the
|
||
actual implementation.
|
||
By default, class methods that are not inherited are initialized to
|
||
<function>NULL</function>, and thus are to be considered "pure virtual".
|
||
<informalexample><programlisting>
|
||
static void
|
||
viewer_file_real_close (ViewerFile *self,
|
||
GError **error)
|
||
{
|
||
/* Default implementation for the virtual method. */
|
||
}
|
||
|
||
static void
|
||
viewer_file_class_init (ViewerFileClass *klass)
|
||
{
|
||
/* this is not necessary, except for demonstration purposes.
|
||
*
|
||
* pure virtual method: mandates implementation in children.
|
||
*/
|
||
klass->open = NULL;
|
||
|
||
/* merely virtual method. */
|
||
klass->close = viewer_file_real_close;
|
||
}
|
||
|
||
void
|
||
viewer_file_open (ViewerFile *self,
|
||
GError **error)
|
||
{
|
||
ViewerFileClass *klass;
|
||
|
||
g_return_if_fail (VIEWER_IS_FILE (self));
|
||
g_return_if_fail (error == NULL || *error == NULL);
|
||
|
||
klass = VIEWER_FILE_GET_CLASS (self);
|
||
|
||
/* if the method is purely virtual, then it is a good idea to
|
||
* check that it has been overridden before calling it, and,
|
||
* depending on the intent of the class, either ignore it silently
|
||
* or warn the user.
|
||
*/
|
||
g_return_if_fail (klass->open != NULL);
|
||
klass->open (self, error);
|
||
}
|
||
|
||
void
|
||
viewer_file_close (ViewerFile *self,
|
||
GError **error)
|
||
{
|
||
ViewerFileClass *klass;
|
||
|
||
g_return_if_fail (VIEWER_IS_FILE (self));
|
||
g_return_if_fail (error == NULL || *error == NULL);
|
||
|
||
klass = VIEWER_FILE_GET_CLASS (self);
|
||
if (klass->close != NULL)
|
||
klass->close (self, error);
|
||
}
|
||
</programlisting></informalexample>
|
||
</para>
|
||
</sect2>
|
||
|
||
<sect2 id="virtual-private-methods">
|
||
<title>Virtual private Methods</title>
|
||
|
||
<para>
|
||
These are very similar to <link linkend="virtual-public-methods">virtual
|
||
public methods</link>. They just don't
|
||
have a public function to call directly. The header
|
||
file contains only a declaration of the virtual function:
|
||
<informalexample><programlisting>
|
||
/* declaration in viewer-file.h. */
|
||
struct _ViewerFileClass
|
||
{
|
||
GObjectClass parent;
|
||
|
||
/* Public virtual method as before. */
|
||
void (*open) (ViewerFile *self,
|
||
GError **error);
|
||
|
||
/* Private helper function to work out whether the file can be loaded via
|
||
* memory mapped I/O, or whether it has to be read as a stream. */
|
||
gboolean (*can_memory_map) (ViewerFile *self);
|
||
|
||
/* Padding to allow adding up to 12 new virtual functions without
|
||
* breaking ABI. */
|
||
gpointer padding[12];
|
||
};
|
||
|
||
void viewer_file_open (ViewerFile *self, GError **error);
|
||
</programlisting></informalexample>
|
||
These virtual functions are often used to delegate part of the job
|
||
to child classes:
|
||
<informalexample><programlisting>
|
||
/* this accessor function is static: it is not exported outside of this file. */
|
||
static gboolean
|
||
viewer_file_can_memory_map (ViewerFile *self)
|
||
{
|
||
return VIEWER_FILE_GET_CLASS (self)->can_memory_map (self);
|
||
}
|
||
|
||
void
|
||
viewer_file_open (ViewerFile *self,
|
||
GError **error)
|
||
{
|
||
g_return_if_fail (VIEWER_IS_FILE (self));
|
||
g_return_if_fail (error == NULL || *error == NULL);
|
||
|
||
/*
|
||
* Try to load the file using memory mapped I/O, if the implementation of the
|
||
* class determines that is possible using its private virtual method.
|
||
*/
|
||
if (viewer_file_can_memory_map (self))
|
||
{
|
||
/* Load the file using memory mapped I/O. */
|
||
}
|
||
else
|
||
{
|
||
/* Fall back to trying to load the file using streaming I/O… */
|
||
}
|
||
}
|
||
</programlisting></informalexample>
|
||
</para>
|
||
|
||
<para>
|
||
Again, it is possible to provide a default implementation for this
|
||
private virtual function:
|
||
<informalexample><programlisting>
|
||
static gboolean
|
||
viewer_file_real_can_memory_map (ViewerFile *self)
|
||
{
|
||
/* As an example, always return false. Or, potentially return true if the
|
||
* file is local. */
|
||
return FALSE;
|
||
}
|
||
|
||
static void
|
||
viewer_file_class_init (ViewerFileClass *klass)
|
||
{
|
||
/* non-pure virtual method; does not have to be implemented in children. */
|
||
klass->can_memory_map = viewer_file_real_can_memory_map;
|
||
}
|
||
</programlisting></informalexample>
|
||
</para>
|
||
|
||
<para>
|
||
Derived classes can then override the method with code such as:
|
||
<informalexample><programlisting>
|
||
static void
|
||
viewer_audio_file_class_init (ViewerAudioFileClass *klass)
|
||
{
|
||
ViewerFileClass *file_class = VIEWER_FILE_CLASS (klass);
|
||
|
||
/* implement pure virtual function. */
|
||
file_class->can_memory_map = viewer_audio_file_can_memory_map;
|
||
}
|
||
</programlisting></informalexample>
|
||
</para>
|
||
</sect2>
|
||
</sect1>
|
||
|
||
<sect1 id="howto-gobject-chainup">
|
||
<title>Chaining up</title>
|
||
|
||
<para>Chaining up is often loosely defined by the following set of
|
||
conditions:
|
||
<itemizedlist>
|
||
<listitem><para>Parent class A defines a public virtual method named <function>foo</function> and
|
||
provides a default implementation.</para></listitem>
|
||
<listitem><para>Child class B re-implements method <function>foo</function>.</para></listitem>
|
||
<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>
|
||
</itemizedlist>
|
||
There are various uses of this idiom:
|
||
<itemizedlist>
|
||
<listitem><para>You need to extend the behaviour of a class without modifying its code. You create
|
||
a subclass to inherit its implementation, re-implement a public virtual method to modify the behaviour
|
||
and chain up to ensure that the previous behaviour is not really modified, just extended.
|
||
</para></listitem>
|
||
<listitem><para>You need to implement the
|
||
<ulink url="http://en.wikipedia.org/wiki/Chain-of-responsibility_pattern">Chain
|
||
Of Responsibility pattern</ulink>: each object of the inheritance
|
||
tree chains up to its parent (typically, at the beginning or the end of the method) to ensure that
|
||
each handler is run in turn.</para></listitem>
|
||
</itemizedlist>
|
||
</para>
|
||
|
||
<para>
|
||
To explicitly chain up to the implementation of the virtual method in the parent class,
|
||
you first need a handle to the original parent class structure. This pointer can then be used to
|
||
access the original virtual function pointer and invoke it directly.
|
||
<footnote>
|
||
<para>
|
||
The <emphasis>original</emphasis> adjective used in this sentence is not innocuous. To fully
|
||
understand its meaning, recall how class structures are initialized: for each object type,
|
||
the class structure associated with this object is created by first copying the class structure of its
|
||
parent type (a simple <function>memcpy</function>) and then by invoking the <function>class_init</function> callback on
|
||
the resulting class structure. Since the <function>class_init</function> callback is responsible for overwriting the class structure
|
||
with the user re-implementations of the class methods, the modified copy of the parent class
|
||
structure stored in the derived instance cannot be used. A copy of the class structure of an instance of the parent
|
||
class is needed.
|
||
</para>
|
||
</footnote>
|
||
</para>
|
||
|
||
<para>
|
||
Use the <function>parent_class</function> pointer created and initialized
|
||
by the
|
||
<link linkend="G-DEFINE-TYPE:CAPS"><function>G_DEFINE_TYPE</function></link>
|
||
family of macros, for instance:
|
||
<informalexample><programlisting>
|
||
static void
|
||
b_method_to_call (B *obj, gint some_param)
|
||
{
|
||
/* do stuff before chain up */
|
||
|
||
/* call the method_to_call() virtual function on the
|
||
* parent of BClass, AClass.
|
||
*
|
||
* remember the explicit cast to AClass*
|
||
*/
|
||
A_CLASS (b_parent_class)->method_to_call (obj, some_param);
|
||
|
||
/* do stuff after chain up */
|
||
}
|
||
</programlisting></informalexample>
|
||
</para>
|
||
|
||
</sect1>
|
||
|
||
</chapter>
|
||
<!-- End Howto GObject -->
|
||
|
||
<chapter id="howto-interface">
|
||
<title>How to define and implement interfaces</title>
|
||
|
||
<sect1 id="howto-interface-define">
|
||
<title>Defining interfaces</title>
|
||
|
||
<para>
|
||
The theory behind how GObject interfaces work is given in
|
||
<xref linkend="gtype-non-instantiatable-non-classed"/>; this section covers how to
|
||
define and implement an interface.
|
||
</para>
|
||
|
||
<para>
|
||
The first step is to get the header right. This interface
|
||
defines three methods:
|
||
<informalexample><programlisting>
|
||
/*
|
||
* Copyright/Licensing information.
|
||
*/
|
||
|
||
#ifndef __VIEWER_EDITABLE_H__
|
||
#define __VIEWER_EDITABLE_H__
|
||
|
||
#include <glib-object.h>
|
||
|
||
G_BEGIN_DECLS
|
||
|
||
#define VIEWER_TYPE_EDITABLE viewer_editable_get_type ()
|
||
G_DECLARE_INTERFACE (ViewerEditable, viewer_editable, VIEWER, EDITABLE, GObject)
|
||
|
||
struct _ViewerEditableInterface
|
||
{
|
||
GTypeInterface parent_iface;
|
||
|
||
void (*save) (ViewerEditable *self,
|
||
GError **error);
|
||
void (*undo) (ViewerEditable *self,
|
||
guint n_steps);
|
||
void (*redo) (ViewerEditable *self,
|
||
guint n_steps);
|
||
};
|
||
|
||
void viewer_editable_save (ViewerEditable *self,
|
||
GError **error);
|
||
void viewer_editable_undo (ViewerEditable *self,
|
||
guint n_steps);
|
||
void viewer_editable_redo (ViewerEditable *self,
|
||
guint n_steps);
|
||
|
||
G_END_DECLS
|
||
|
||
#endif /* __VIEWER_EDITABLE_H__ */
|
||
</programlisting></informalexample>
|
||
This code is the same as the code for a normal <link linkend="GType"><type>GType</type></link>
|
||
which derives from a <link linkend="GObject"><type>GObject</type></link> except for a few details:
|
||
<itemizedlist>
|
||
<listitem><para>
|
||
The <function>_GET_CLASS</function> function is called
|
||
<function>_GET_IFACE</function> (and is defined by
|
||
<link linkend="G-DECLARE-INTERFACE:CAPS"><function>G_DECLARE_INTERFACE</function></link>).
|
||
</para></listitem>
|
||
<listitem><para>
|
||
The instance type, <type>ViewerEditable</type>, is not fully defined: it is
|
||
used merely as an abstract type which represents an instance of
|
||
whatever object which implements the interface.
|
||
</para></listitem>
|
||
<listitem><para>
|
||
The parent of the <type>ViewerEditableInterface</type> is
|
||
<type>GTypeInterface</type>, not <type>GObjectClass</type>.
|
||
</para></listitem>
|
||
</itemizedlist>
|
||
</para>
|
||
|
||
<para>
|
||
The implementation of the <type>ViewerEditable</type> type itself is trivial:
|
||
<itemizedlist>
|
||
<listitem><para><function><link linkend="G-DEFINE-INTERFACE:CAPS">G_DEFINE_INTERFACE</link></function>
|
||
creates a <function>viewer_editable_get_type</function> function which registers the
|
||
type in the type system. The third argument is used to define a
|
||
<link linkend="howto-interface-prerequisite">prerequisite interface</link>
|
||
(which we'll talk about more later). Just pass <code>0</code> for this
|
||
argument when an interface has no prerequisite.
|
||
</para></listitem>
|
||
<listitem><para><function>viewer_editable_default_init</function> is expected
|
||
to register the interface's signals if there are any (we will see a bit
|
||
later how to use them).</para></listitem>
|
||
<listitem><para>The interface methods <function>viewer_editable_save</function>,
|
||
<function>viewer_editable_undo</function> and <function>viewer_editable_redo</function> dereference the interface
|
||
structure to access its associated interface function and call it.
|
||
</para></listitem>
|
||
</itemizedlist>
|
||
<informalexample><programlisting>
|
||
G_DEFINE_INTERFACE (ViewerEditable, viewer_editable, G_TYPE_OBJECT)
|
||
|
||
static void
|
||
viewer_editable_default_init (ViewerEditableInterface *iface)
|
||
{
|
||
/* add properties and signals to the interface here */
|
||
}
|
||
|
||
void
|
||
viewer_editable_save (ViewerEditable *self,
|
||
GError **error)
|
||
{
|
||
ViewerEditableInterface *iface;
|
||
|
||
g_return_if_fail (VIEWER_IS_EDITABLE (self));
|
||
g_return_if_fail (error == NULL || *error == NULL);
|
||
|
||
iface = VIEWER_EDITABLE_GET_IFACE (self);
|
||
g_return_if_fail (iface->save != NULL);
|
||
iface->save (self, error);
|
||
}
|
||
|
||
void
|
||
viewer_editable_undo (ViewerEditable *self,
|
||
guint n_steps)
|
||
{
|
||
ViewerEditableInterface *iface;
|
||
|
||
g_return_if_fail (VIEWER_IS_EDITABLE (self));
|
||
|
||
iface = VIEWER_EDITABLE_GET_IFACE (self);
|
||
g_return_if_fail (iface->undo != NULL);
|
||
iface->undo (self, n_steps);
|
||
}
|
||
|
||
void
|
||
viewer_editable_redo (ViewerEditable *self,
|
||
guint n_steps)
|
||
{
|
||
ViewerEditableInterface *iface;
|
||
|
||
g_return_if_fail (VIEWER_IS_EDITABLE (self));
|
||
|
||
iface = VIEWER_EDITABLE_GET_IFACE (self);
|
||
g_return_if_fail (iface->redo != NULL);
|
||
iface->redo (self, n_steps);
|
||
}
|
||
</programlisting></informalexample>
|
||
</para>
|
||
</sect1>
|
||
|
||
<sect1 id="howto-interface-implement">
|
||
<title>Implementing interfaces</title>
|
||
|
||
<para>
|
||
Once the interface is defined, implementing it is rather trivial.
|
||
</para>
|
||
|
||
<para>
|
||
The first step is to define a normal final GObject class exactly as in
|
||
<xref linkend="howto-gobject-header"/>.
|
||
</para>
|
||
|
||
<para>
|
||
The second step is to implement <type>ViewerFile</type> by defining
|
||
it using
|
||
<function><link linkend="G-DEFINE-TYPE-WITH-CODE:CAPS">G_DEFINE_TYPE_WITH_CODE</link></function>
|
||
and
|
||
<function><link linkend="G-IMPLEMENT-INTERFACE:CAPS">G_IMPLEMENT_INTERFACE</link></function>
|
||
instead of
|
||
<function><link linkend="G-DEFINE-TYPE:CAPS">G_DEFINE_TYPE</link></function>:
|
||
<informalexample><programlisting>
|
||
static void viewer_file_editable_interface_init (ViewerEditableInterface *iface);
|
||
|
||
G_DEFINE_TYPE_WITH_CODE (ViewerFile, viewer_file, G_TYPE_OBJECT,
|
||
G_IMPLEMENT_INTERFACE (VIEWER_TYPE_EDITABLE,
|
||
viewer_file_editable_interface_init))
|
||
</programlisting></informalexample>
|
||
This definition is very much like all the similar functions seen
|
||
previously. The only interface-specific code present here is the use of
|
||
<function><link linkend="G-IMPLEMENT-INTERFACE:CAPS">G_IMPLEMENT_INTERFACE</link></function>.
|
||
</para>
|
||
|
||
<note><para>Classes can implement multiple interfaces by using multiple calls to
|
||
<function><link linkend="G-IMPLEMENT-INTERFACE:CAPS">G_IMPLEMENT_INTERFACE</link></function>
|
||
inside the call to
|
||
<function><link linkend="G-DEFINE-TYPE-WITH-CODE:CAPS">G_DEFINE_TYPE_WITH_CODE</link></function>
|
||
</para></note>
|
||
|
||
<para>
|
||
<function>viewer_file_editable_interface_init</function>, the interface
|
||
initialization function: inside it every virtual method of the interface
|
||
must be assigned to its implementation:
|
||
<informalexample><programlisting>
|
||
static void
|
||
viewer_file_editable_save (ViewerFile *self,
|
||
GError **error)
|
||
{
|
||
g_print ("File implementation of editable interface save method: %s.\n",
|
||
self->filename);
|
||
}
|
||
|
||
static void
|
||
viewer_file_editable_undo (ViewerFile *self,
|
||
guint n_steps)
|
||
{
|
||
g_print ("File implementation of editable interface undo method: %s.\n",
|
||
self->filename);
|
||
}
|
||
|
||
static void
|
||
viewer_file_editable_redo (ViewerFile *self,
|
||
guint n_steps)
|
||
{
|
||
g_print ("File implementation of editable interface redo method: %s.\n",
|
||
self->filename);
|
||
}
|
||
|
||
static void
|
||
viewer_file_editable_interface_init (ViewerEditableInterface *iface)
|
||
{
|
||
iface->save = viewer_file_editable_save;
|
||
iface->undo = viewer_file_editable_undo;
|
||
iface->redo = viewer_file_editable_redo;
|
||
}
|
||
|
||
static void
|
||
viewer_file_init (ViewerFile *self)
|
||
{
|
||
/* Instance variable initialisation code. */
|
||
}
|
||
</programlisting></informalexample>
|
||
</para>
|
||
<para>
|
||
If the object is not of final type, e.g. was declared using
|
||
<function><link linkend="G-DECLARE-DERIVABLE-TYPE:CAPS">G_DECLARE_DERIVABLE_TYPE</link></function>
|
||
then
|
||
<function><link linkend="G-ADD-PRIVATE:CAPS">G_ADD_PRIVATE</link></function>
|
||
macro should be added. The private structure should be declared exactly
|
||
as for a normal derivable object, see <xref linkend="howto-gobject-code"/>.
|
||
<informalexample><programlisting>
|
||
G_DEFINE_TYPE_WITH_CODE (ViewerFile, viewer_file, G_TYPE_OBJECT,
|
||
G_ADD_PRIVATE (ViewerFile)
|
||
G_IMPLEMENT_INTERFACE (VIEWER_TYPE_EDITABLE,
|
||
viewer_file_editable_interface_init))
|
||
</programlisting></informalexample>
|
||
</para>
|
||
</sect1>
|
||
|
||
<sect1 id="howto-interface-prerequisite">
|
||
<title>Interface definition prerequisites</title>
|
||
|
||
<para>
|
||
To specify that an interface requires the presence of other interfaces
|
||
when implemented, GObject introduces the concept of
|
||
<emphasis>prerequisites</emphasis>: it is possible to associate
|
||
a list of prerequisite types to an interface. For example, if
|
||
object A wishes to implement interface I1, and if interface I1 has a
|
||
prerequisite on interface I2, A has to implement both I1 and I2.
|
||
</para>
|
||
|
||
<para>
|
||
The mechanism described above is, in practice, very similar to
|
||
Java's interface I1 extends interface I2. The example below shows
|
||
the GObject equivalent:
|
||
<informalexample><programlisting>
|
||
/* Make the ViewerEditableLossy interface require ViewerEditable interface. */
|
||
G_DEFINE_INTERFACE (ViewerEditableLossy, viewer_editable_lossy, VIEWER_TYPE_EDITABLE)
|
||
</programlisting></informalexample>
|
||
In the <function><link linkend="G-DEFINE-INTERFACE:CAPS">G_DEFINE_INTERFACE</link></function>
|
||
call above, the third parameter defines the prerequisite type. This
|
||
is the GType of either an interface or a class. In this case
|
||
the <type>ViewerEditable</type> interface is a prerequisite of
|
||
<type>ViewerEditableLossy</type>. The code
|
||
below shows how an implementation can implement both interfaces and
|
||
register their implementations:
|
||
<informalexample><programlisting>
|
||
static void
|
||
viewer_file_editable_lossy_compress (ViewerEditableLossy *editable)
|
||
{
|
||
ViewerFile *self = VIEWER_FILE (editable);
|
||
|
||
g_print ("File implementation of lossy editable interface compress method: %s.\n",
|
||
self->filename);
|
||
}
|
||
|
||
static void
|
||
viewer_file_editable_lossy_interface_init (ViewerEditableLossyInterface *iface)
|
||
{
|
||
iface->compress = viewer_file_editable_lossy_compress;
|
||
}
|
||
|
||
static void
|
||
viewer_file_editable_save (ViewerEditable *editable,
|
||
GError **error)
|
||
{
|
||
ViewerFile *self = VIEWER_FILE (editable);
|
||
|
||
g_print ("File implementation of editable interface save method: %s.\n",
|
||
self->filename);
|
||
}
|
||
|
||
static void
|
||
viewer_file_editable_undo (ViewerEditable *editable,
|
||
guint n_steps)
|
||
{
|
||
ViewerFile *self = VIEWER_FILE (editable);
|
||
|
||
g_print ("File implementation of editable interface undo method: %s.\n",
|
||
self->filename);
|
||
}
|
||
|
||
static void
|
||
viewer_file_editable_redo (ViewerEditable *editable,
|
||
guint n_steps)
|
||
{
|
||
ViewerFile *self = VIEWER_FILE (editable);
|
||
|
||
g_print ("File implementation of editable interface redo method: %s.\n",
|
||
self->filename);
|
||
}
|
||
|
||
static void
|
||
viewer_file_editable_interface_init (ViewerEditableInterface *iface)
|
||
{
|
||
iface->save = viewer_file_editable_save;
|
||
iface->undo = viewer_file_editable_undo;
|
||
iface->redo = viewer_file_editable_redo;
|
||
}
|
||
|
||
static void
|
||
viewer_file_class_init (ViewerFileClass *klass)
|
||
{
|
||
/* Nothing here. */
|
||
}
|
||
|
||
static void
|
||
viewer_file_init (ViewerFile *self)
|
||
{
|
||
/* Instance variable initialisation code. */
|
||
}
|
||
|
||
G_DEFINE_TYPE_WITH_CODE (ViewerFile, viewer_file, G_TYPE_OBJECT,
|
||
G_IMPLEMENT_INTERFACE (VIEWER_TYPE_EDITABLE,
|
||
viewer_file_editable_interface_init)
|
||
G_IMPLEMENT_INTERFACE (VIEWER_TYPE_EDITABLE_LOSSY,
|
||
viewer_file_editable_lossy_interface_init))
|
||
</programlisting></informalexample>
|
||
It is very important to notice that the order in which interface
|
||
implementations are added to the main object is not random:
|
||
<function><link linkend="g-type-add-interface-static">g_type_add_interface_static</link></function>,
|
||
which is called by
|
||
<function><link linkend="G-DEFINE-INTERFACE:CAPS">G_IMPLEMENT_INTERFACE</link></function>,
|
||
must be invoked first on the interfaces which have no prerequisites and then on
|
||
the others.
|
||
</para>
|
||
</sect1>
|
||
|
||
<sect1 id="howto-interface-properties">
|
||
<title>Interface properties</title>
|
||
|
||
<para>
|
||
GObject interfaces can also have
|
||
properties. Declaration of the interface properties is similar to
|
||
declaring the properties of ordinary GObject types as explained in
|
||
<xref linkend="gobject-properties"/>, except that
|
||
<function><link linkend="g-object-interface-install-property">g_object_interface_install_property</link></function>
|
||
is used to declare the properties instead of
|
||
<function><link linkend="g-object-class-install-property">g_object_class_install_property</link></function>.
|
||
</para>
|
||
|
||
<para>
|
||
To include a property named 'autosave-frequency' of type <type>gdouble</type> in the
|
||
<type>ViewerEditable</type> interface example code above, we only need to
|
||
add one call in <function>viewer_editable_default_init</function> as shown
|
||
below:
|
||
<informalexample><programlisting>
|
||
static void
|
||
viewer_editable_default_init (ViewerEditableInterface *iface)
|
||
{
|
||
g_object_interface_install_property (iface,
|
||
g_param_spec_double ("autosave-frequency",
|
||
"Autosave frequency",
|
||
"Frequency (in per-seconds) to autosave backups of the editable content at. "
|
||
"Or zero to disable autosaves.",
|
||
0.0, /* minimum */
|
||
G_MAXDOUBLE, /* maximum */
|
||
0.0, /* default */
|
||
G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
|
||
}
|
||
</programlisting></informalexample>
|
||
</para>
|
||
|
||
<para>
|
||
One point worth noting is that the declared property wasn't assigned an
|
||
integer ID. The reason being that integer IDs of properties are used
|
||
only inside the <function>get_property</function> and
|
||
<function>set_property</function> virtual methods. Since interfaces
|
||
declare but do not <emphasis>implement</emphasis> properties, there is no
|
||
need to assign integer IDs to them.
|
||
</para>
|
||
|
||
<para>
|
||
An implementation declares and defines its properties in the usual
|
||
way as explained in <xref linkend="gobject-properties"/>, except for one
|
||
small change: it can declare the properties of the interface it
|
||
implements using <function><link linkend="g-object-class-override-property">g_object_class_override_property</link></function>
|
||
instead of <function><link linkend="g-object-class-install-property">g_object_class_install_property</link></function>.
|
||
The following code snippet shows the modifications needed in the
|
||
<type>ViewerFile</type> declaration and implementation above:
|
||
<informalexample><programlisting>
|
||
struct _ViewerFile
|
||
{
|
||
GObject parent_instance;
|
||
|
||
gdouble autosave_frequency;
|
||
};
|
||
|
||
enum
|
||
{
|
||
PROP_AUTOSAVE_FREQUENCY = 1,
|
||
N_PROPERTIES
|
||
};
|
||
|
||
static void
|
||
viewer_file_set_property (GObject *object,
|
||
guint prop_id,
|
||
const GValue *value,
|
||
GParamSpec *pspec)
|
||
{
|
||
ViewerFile *file = VIEWER_FILE (object);
|
||
|
||
switch (prop_id)
|
||
{
|
||
case PROP_AUTOSAVE_FREQUENCY:
|
||
file->autosave_frequency = g_value_get_double (value);
|
||
break;
|
||
|
||
default:
|
||
G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
|
||
break;
|
||
}
|
||
}
|
||
|
||
static void
|
||
viewer_file_get_property (GObject *object,
|
||
guint prop_id,
|
||
GValue *value,
|
||
GParamSpec *pspec)
|
||
{
|
||
ViewerFile *file = VIEWER_FILE (object);
|
||
|
||
switch (prop_id)
|
||
{
|
||
case PROP_AUTOSAVE_FREQUENCY:
|
||
g_value_set_double (value, file->autosave_frequency);
|
||
break;
|
||
|
||
default:
|
||
G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
|
||
break;
|
||
}
|
||
}
|
||
|
||
static void
|
||
viewer_file_class_init (ViewerFileClass *klass)
|
||
{
|
||
GObjectClass *object_class = G_OBJECT_CLASS (klass);
|
||
|
||
object_class->set_property = viewer_file_set_property;
|
||
object_class->get_property = viewer_file_get_property;
|
||
|
||
g_object_class_override_property (object_class, PROP_AUTOSAVE_FREQUENCY, "autosave-frequency");
|
||
}
|
||
</programlisting></informalexample>
|
||
</para>
|
||
|
||
</sect1>
|
||
|
||
<sect1 id="howto-interface-override">
|
||
<title>Overriding interface methods</title>
|
||
|
||
<para>
|
||
If a base class already implements an interface and a derived
|
||
class needs to implement the same interface but needs to override certain
|
||
methods, you must reimplement the interface and set only the interface
|
||
methods which need overriding.
|
||
</para>
|
||
|
||
<para>
|
||
In this example, <type>ViewerAudioFile</type> is derived from
|
||
<type>ViewerFile</type>. Both implement the <type>ViewerEditable</type>
|
||
interface. <type>ViewerAudioFile</type> only implements one method of the
|
||
<type>ViewerEditable</type> interface and uses the base class implementation of
|
||
the other.
|
||
<informalexample><programlisting>
|
||
static void
|
||
viewer_audio_file_editable_save (ViewerEditable *editable,
|
||
GError **error)
|
||
{
|
||
ViewerAudioFile *self = VIEWER_AUDIO_FILE (editable);
|
||
|
||
g_print ("Audio file implementation of editable interface save method.\n");
|
||
}
|
||
|
||
static void
|
||
viewer_audio_file_editable_interface_init (ViewerEditableInterface *iface)
|
||
{
|
||
/* Override the implementation of save(). */
|
||
iface->save = viewer_audio_file_editable_save;
|
||
|
||
/*
|
||
* Leave iface->undo and ->redo alone, they are already set to the
|
||
* base class implementation.
|
||
*/
|
||
}
|
||
|
||
G_DEFINE_TYPE_WITH_CODE (ViewerAudioFile, viewer_audio_file, VIEWER_TYPE_FILE,
|
||
G_IMPLEMENT_INTERFACE (VIEWER_TYPE_EDITABLE,
|
||
viewer_audio_file_editable_interface_init))
|
||
|
||
static void
|
||
viewer_audio_file_class_init (ViewerAudioFileClass *klass)
|
||
{
|
||
/* Nothing here. */
|
||
}
|
||
|
||
static void
|
||
viewer_audio_file_init (ViewerAudioFile *self)
|
||
{
|
||
/* Nothing here. */
|
||
}
|
||
</programlisting></informalexample>
|
||
</para>
|
||
|
||
<para>
|
||
To access the base class interface implementation use
|
||
<function><link linkend="g-type-interface-peek-parent">g_type_interface_peek_parent</link></function>
|
||
from within an interface's <function>default_init</function> function.
|
||
</para>
|
||
|
||
<para>
|
||
To call the base class implementation of an interface
|
||
method from a derived class where than interface method has been
|
||
overridden, stash away the pointer returned from
|
||
<function><link linkend="g-type-interface-peek-parent">g_type_interface_peek_parent</link></function>
|
||
in a global variable.
|
||
</para>
|
||
|
||
<para>
|
||
In this example <type>ViewerAudioFile</type> overrides the
|
||
<function>save</function> interface method. In its overridden method
|
||
it calls the base class implementation of the same interface method.
|
||
<informalexample><programlisting>
|
||
static ViewerEditableInterface *viewer_editable_parent_interface = NULL;
|
||
|
||
static void
|
||
viewer_audio_file_editable_save (ViewerEditable *editable,
|
||
GError **error)
|
||
{
|
||
ViewerAudioFile *self = VIEWER_AUDIO_FILE (editable);
|
||
|
||
g_print ("Audio file implementation of editable interface save method.\n");
|
||
|
||
/* Now call the base implementation */
|
||
viewer_editable_parent_interface->save (editable, error);
|
||
}
|
||
|
||
static void
|
||
viewer_audio_file_editable_interface_init (ViewerEditableInterface *iface)
|
||
{
|
||
viewer_editable_parent_interface = g_type_interface_peek_parent (iface);
|
||
|
||
iface->save = viewer_audio_file_editable_save;
|
||
}
|
||
|
||
G_DEFINE_TYPE_WITH_CODE (ViewerAudioFile, viewer_audio_file, VIEWER_TYPE_FILE,
|
||
G_IMPLEMENT_INTERFACE (VIEWER_TYPE_EDITABLE,
|
||
viewer_audio_file_editable_interface_init))
|
||
|
||
static void
|
||
viewer_audio_file_class_init (ViewerAudioFileClass *klass)
|
||
{
|
||
/* Nothing here. */
|
||
}
|
||
|
||
static void
|
||
viewer_audio_file_init (ViewerAudioFile *self)
|
||
{
|
||
/* Nothing here. */
|
||
}
|
||
</programlisting></informalexample>
|
||
</para>
|
||
|
||
</sect1>
|
||
|
||
</chapter>
|
||
<!-- End Howto Interfaces -->
|
||
|
||
<chapter id="howto-signals">
|
||
<title>How to create and use signals</title>
|
||
|
||
<para>
|
||
The signal system in GType is pretty complex and
|
||
flexible: it is possible for its users to connect at runtime any
|
||
number of callbacks (implemented in any language for which a binding
|
||
exists)
|
||
<footnote>
|
||
<para>A Python callback can be connected to any signal on any
|
||
C-based GObject, and vice versa, assuming that the Python object
|
||
inherits from GObject.</para>
|
||
</footnote>
|
||
to any signal and to stop the emission of any signal at any
|
||
state of the signal emission process. This flexibility makes it
|
||
possible to use GSignal for much more than just emitting signals to
|
||
multiple clients.
|
||
</para>
|
||
|
||
<sect1 id="howto-simple-signals">
|
||
<title>Simple use of signals</title>
|
||
|
||
<para>
|
||
The most basic use of signals is to implement event
|
||
notification. For example, given a <type>ViewerFile</type> object with
|
||
a <function>write</function> method, a signal could be emitted whenever
|
||
the file is changed using that method.
|
||
The code below shows how the user can connect a callback to the
|
||
"changed" signal.
|
||
<informalexample><programlisting>
|
||
file = g_object_new (VIEWER_FILE_TYPE, NULL);
|
||
|
||
g_signal_connect (file, "changed", (GCallback) changed_event, NULL);
|
||
|
||
viewer_file_write (file, buffer, strlen (buffer));
|
||
</programlisting></informalexample>
|
||
</para>
|
||
|
||
<para>
|
||
The <type>ViewerFile</type> signal is registered in the
|
||
<function>class_init</function> function:
|
||
<informalexample><programlisting>
|
||
file_signals[CHANGED] =
|
||
g_signal_newv ("changed",
|
||
G_TYPE_FROM_CLASS (object_class),
|
||
G_SIGNAL_RUN_LAST | G_SIGNAL_NO_RECURSE | G_SIGNAL_NO_HOOKS,
|
||
NULL /* closure */,
|
||
NULL /* accumulator */,
|
||
NULL /* accumulator data */,
|
||
NULL /* C marshaller */,
|
||
G_TYPE_NONE /* return_type */,
|
||
0 /* n_params */,
|
||
NULL /* param_types */);
|
||
</programlisting></informalexample>
|
||
and the signal is emitted in <function>viewer_file_write</function>:
|
||
<informalexample><programlisting>
|
||
void
|
||
viewer_file_write (ViewerFile *self,
|
||
const guint8 *buffer,
|
||
gsize size)
|
||
{
|
||
g_return_if_fail (VIEWER_IS_FILE (self));
|
||
g_return_if_fail (buffer != NULL || size == 0);
|
||
|
||
/* First write data. */
|
||
|
||
/* Then, notify user of data written. */
|
||
g_signal_emit (self, file_signals[CHANGED], 0 /* details */);
|
||
}
|
||
</programlisting></informalexample>
|
||
As shown above, the details parameter can safely be set to zero if no
|
||
detail needs to be conveyed. For a discussion of what it can be used for,
|
||
see <xref linkend="signal-detail"/>
|
||
</para>
|
||
|
||
<para>
|
||
The C signal marshaller should always be <literal>NULL</literal>, in which
|
||
case the best marshaller for the given closure type will be chosen by
|
||
GLib. This may be an internal marshaller specific to the closure type, or
|
||
<function>g_cclosure_marshal_generic</function>, which implements generic
|
||
conversion of arrays of parameters to C callback invocations. GLib used to
|
||
require the user to write or generate a type-specific marshaller and pass
|
||
that, but that has been deprecated in favour of automatic selection of
|
||
marshallers.
|
||
</para>
|
||
|
||
<para>
|
||
Note that <function>g_cclosure_marshal_generic</function> is slower than
|
||
non-generic marshallers, so should be avoided for performance critical
|
||
code. However, performance critical code should rarely be using signals
|
||
anyway, as emitting a signal blocks on emitting it to all listeners, which
|
||
has potentially unbounded cost.
|
||
</para>
|
||
</sect1>
|
||
</chapter>
|
||
</part>
|