Default page

Edit File: howto-interface.html

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>How to define and implement interfaces: GObject Reference Manual</title>
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="index.html" title="GObject Reference Manual">
<link rel="up" href="pt02.html" title="Part IV. Tutorial">
<link rel="prev" href="howto-gobject-chainup.html" title="Chaining up">
<link rel="next" href="howto-interface-implement.html" title="Implementing interfaces">
<meta name="generator" content="GTK-Doc V1.32 (XML mode)">
<link rel="stylesheet" href="style.css" type="text/css">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="5"><tr valign="middle">
<td width="100%" align="left" class="shortcuts"></td>
<td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td>
<td><a accesskey="u" href="pt02.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td>
<td><a accesskey="p" href="howto-gobject-chainup.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td>
<td><a accesskey="n" href="howto-interface-implement.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td>
</tr></table>
<div class="chapter">
<div class="titlepage"><div><div><h2 class="title">
<a name="howto-interface"></a>How to define and implement interfaces</h2></div></div></div>
<div class="toc"><dl class="toc">
<dt><a href="howto-interface.html#howto-interface-define">Defining interfaces</a></dt>
<dt><a href="howto-interface-implement.html">Implementing interfaces</a></dt>
<dt><a href="howto-interface-prerequisite.html">Interface definition prerequisites</a></dt>
<dt><a href="howto-interface-properties.html">Interface properties</a></dt>
<dt><a href="howto-interface-override.html">Overriding interface methods</a></dt>
</dl></div>
<div class="sect1">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="howto-interface-define"></a>Defining interfaces</h2></div></div></div>

 The theory behind how GObject interfaces work is given in
 <a class="xref" href="gtype-non-instantiable-classed.html" title="Non-instantiable classed types: interfaces">the section called “Non-instantiable classed types: interfaces”</a>; this section covers how to
 define and implement an interface.
 

 The first step is to get the header right. This interface
 defines three methods:

<div class="informalexample">
 <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
 <tbody>
 <tr>
 <td class="listing_lines" align="right"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36</pre></td>
 <td class="listing_code"><pre class="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__ */</pre></td>
 </tr>
 </tbody>
 </table>
</div>

This code is the same as the code for a normal <a class="link" href="gobject-Type-Information.html#GType">GType</a>
 which derives from a <a class="link" href="gobject-The-Base-Object-Type.html#GObject">GObject</a> except for a few details:
 
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
 The <code class="function">_GET_CLASS</code> function is called
 <code class="function">_GET_IFACE</code> (and is defined by
 <a class="link" href="gobject-Type-Information.html#G-DECLARE-INTERFACE:CAPS" title="G_DECLARE_INTERFACE()"><code class="function">G_DECLARE_INTERFACE</code></a>).
 </li>
<li class="listitem">
 The instance type, ViewerEditable, is not fully defined: it is
 used merely as an abstract type which represents an instance of
 whatever object which implements the interface.
 </li>
<li class="listitem">
 The parent of the ViewerEditableInterface is
 GTypeInterface, not GObjectClass.
 </li>
</ul></div>

 

 The implementation of the ViewerEditable type itself is trivial:
 
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem"><code class="function"><a class="link" href="gobject-Type-Information.html#G-DEFINE-INTERFACE:CAPS" title="G_DEFINE_INTERFACE()">G_DEFINE_INTERFACE</a></code>
 creates a <code class="function">viewer_editable_get_type</code> function which registers the
 type in the type system. The third argument is used to define a
 <a class="link" href="howto-interface-prerequisite.html" title="Interface definition prerequisites">prerequisite interface</a>
 (which we'll talk about more later). Just pass <code class="code">0</code> for this
 argument when an interface has no prerequisite.
 </li>
<li class="listitem"><code class="function">viewer_editable_default_init</code> is expected
 to register the interface's signals if there are any (we will see a bit
 later how to use them).</li>
<li class="listitem">The interface methods <code class="function">viewer_editable_save</code>,
 <code class="function">viewer_editable_undo</code> and <code class="function">viewer_editable_redo</code> dereference the interface
 structure to access its associated interface function and call it.
 </li>
</ul></div>


<div class="informalexample">
 <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
 <tbody>
 <tr>
 <td class="listing_lines" align="right"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47</pre></td>
 <td class="listing_code"><pre class="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);
}</pre></td>
 </tr>
 </tbody>
 </table>
</div>

</div>
</div>
<div class="footer">
<hr>Generated by GTK-Doc V1.32</div>
</body>
</html>