Default page

Edit File: howto-gobject.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 a new GObject: 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="pt02.html" title="Part IV. Tutorial">
<link rel="next" href="howto-gobject-code.html" title="Boilerplate code">
<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="pt02.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td>
<td><a accesskey="n" href="howto-gobject-code.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-gobject"></a>How to define and implement a new GObject</h2></div></div></div>
<div class="toc"><dl class="toc">
<dt><a href="howto-gobject.html#howto-gobject-header">Boilerplate header code</a></dt>
<dt><a href="howto-gobject-code.html">Boilerplate code</a></dt>
<dt><a href="howto-gobject-construction.html">Object construction</a></dt>
<dt><a href="howto-gobject-destruction.html">Object destruction</a></dt>
<dt><a href="howto-gobject-methods.html">Object methods</a></dt>
<dd><dl>
<dt><a href="howto-gobject-methods.html#non-virtual-public-methods">Non-virtual public methods</a></dt>
<dt><a href="howto-gobject-methods.html#virtual-public-methods">Virtual public methods</a></dt>
<dt><a href="howto-gobject-methods.html#virtual-private-methods">Virtual private Methods</a></dt>
</dl></dd>
<dt><a href="howto-gobject-chainup.html">Chaining up</a></dt>
</dl></div>

 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.
 

 Throughout the chapter, a running example of a file viewer program is used,
 which has a ViewerFile 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 ViewerEditable interface.
 
<div class="sect1">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="howto-gobject-header"></a>Boilerplate header code</h2></div></div></div>

 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.
 

 Pick a name convention for your headers and source code and stick to it:
 
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">use a dash to separate the prefix from the typename:
 <code class="filename">viewer-file.h</code> and <code class="filename">viewer-file.c</code>
 (this is the convention used by Nautilus and most GNOME libraries).</li>
<li class="listitem">use an underscore to separate the prefix from the
 typename: <code class="filename">viewer_file.h</code> and
 <code class="filename">viewer_file.c</code>.</li>
<li class="listitem">Do not separate the prefix from the typename:
 <code class="filename">viewerfile.h</code> and <code class="filename">viewerfile.c</code>.
 (this is the convention used by GTK+)</li>
</ul></div>

 Some people like the first two solutions better: it makes reading file
 names easier for those with poor eyesight.
 

 The basic conventions for any header which exposes a GType are described
 in <a class="xref" href="gtype-conventions.html" title="Conventions">the section called “Conventions”</a>.
 

 If you want to declare a type named ‘file’ in namespace ‘viewer’, name the
 type instance <code class="function">ViewerFile</code> and its class
 <code class="function">ViewerFileClass</code> (names are case sensitive). The
 recommended method of declaring a type differs based on whether the type
 is final or derivable.
 

 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
 <a class="link" href="gobject-Type-Information.html#G-DECLARE-FINAL-TYPE:CAPS" title="G_DECLARE_FINAL_TYPE()"><code class="function">G_DECLARE_FINAL_TYPE</code></a>,
 and require a structure to hold the instance data to be declared in the
 source code (not the header file).

<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</pre></td>
 <td class="listing_code"><pre class="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__ */</pre></td>
 </tr>
 </tbody>
 </table>
</div>

Derivable types can 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
 <a class="link" href="gobject-Type-Information.html#G-DECLARE-DERIVABLE-TYPE:CAPS" title="G_DECLARE_DERIVABLE_TYPE()"><code class="function">G_DECLARE_DERIVABLE_TYPE</code></a>:

<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</pre></td>
 <td class="listing_code"><pre class="programlisting">/*
 * Copyright/Licensing information.
 */

/* inclusion guard */
#ifndef __VIEWER_FILE_H__
#define __VIEWER_FILE_H__

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__ */</pre></td>
 </tr>
 </tbody>
 </table>
</div>

The convention for header includes is to add the minimum number of
 <code class="function">#include</code> directives to the top of your headers needed
 to compile that header. This
 allows client code to simply <code class="function">#include "viewer-file.h"</code>,
 without needing to know the prerequisites for
 <code class="filename">viewer-file.h</code>.
 
</div>
</div>
<div class="footer">
<hr>Generated by GTK-Doc V1.32</div>
</body>
</html>