blob: 94996ed07774d6ba828b3cbb53bee70785684910 [file] [log] [blame]
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Conventions: 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="chapter-gtype.html" title="The GLib Dynamic Type System">
<link rel="prev" href="chapter-gtype.html" title="The GLib Dynamic Type System">
<link rel="next" href="gtype-non-instantiable.html" title="Non-instantiable non-classed fundamental types">
<meta name="generator" content="GTK-Doc V1.25.1 (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="chapter-gtype.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td>
<td><a accesskey="p" href="chapter-gtype.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td>
<td><a accesskey="n" href="gtype-non-instantiable.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td>
</tr></table>
<div class="sect1">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="gtype-conventions"></a>Conventions</h2></div></div></div>
<p>
There are a number of conventions users are expected to follow when creating new types
which are to be exported in a header file:
</p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem"><p>
Type names (including object names) must be at least three
characters long and start with ‘a–z’, ‘A–Z’ or ‘_’.
</p></li>
<li class="listitem"><p>
Use the <code class="function">object_method</code> pattern for function names: to invoke
the method named <code class="function">save</code> on an instance of object type <span class="type">file</span>, call
<code class="function">file_save</code>.
</p></li>
<li class="listitem"><p>Use prefixing to avoid namespace conflicts with other projects.
If your library (or application) is named <span class="emphasis"><em>Viewer</em></span>,
prefix all your function names with <span class="emphasis"><em>viewer_</em></span>.
For example: <code class="function">viewer_object_method</code>.
</p></li>
<li class="listitem"><p>Create a macro named <code class="function">PREFIX_TYPE_OBJECT</code> which always
returns the GType for the associated object type. For an object of type
<span class="emphasis"><em>File</em></span> in the <span class="emphasis"><em>Viewer</em></span> namespace,
use: <code class="function">VIEWER_TYPE_FILE</code>.
This macro is implemented using a function named
<code class="function">prefix_object_get_type</code>; for example, <code class="function">viewer_file_get_type</code>.
</p></li>
<li class="listitem">
<p>
Use <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>
or <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>
to define various other conventional macros for your object:
</p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; ">
<li class="listitem"><p><code class="function">PREFIX_OBJECT (obj)</code>, which
returns a pointer of type <span class="type">PrefixObject</span>. This macro is used to enforce
static type safety by doing explicit casts wherever needed. It also enforces
dynamic type safety by doing runtime checks. It is possible to disable the dynamic
type checks in production builds (see building GLib).
For example, we would create
<code class="function">VIEWER_FILE (obj)</code> to keep the previous example.
</p></li>
<li class="listitem"><p><code class="function">PREFIX_OBJECT_CLASS (klass)</code>, which
is strictly equivalent to the previous casting macro: it does static casting with
dynamic type checking of class structures. It is expected to return a pointer
to a class structure of type <span class="type">PrefixObjectClass</span>. An example is:
<code class="function">VIEWER_FILE_CLASS</code>.
</p></li>
<li class="listitem"><p><code class="function">PREFIX_IS_OBJECT (obj)</code>, which
returns a <span class="type">gboolean</span> which indicates whether the input
object instance pointer is non-<span class="type">NULL</span> and of type <span class="type">OBJECT</span>.
For example, <code class="function">VIEWER_IS_FILE</code>.
</p></li>
<li class="listitem"><p><code class="function">PREFIX_IS_OBJECT_CLASS (klass)</code>, which returns a boolean
if the input class pointer is a pointer to a class of type OBJECT.
For example, <code class="function">VIEWER_IS_FILE_CLASS</code>.
</p></li>
<li class="listitem"><p><code class="function">PREFIX_OBJECT_GET_CLASS (obj)</code>,
which returns the class pointer associated to an instance of a given type. This macro
is used for static and dynamic type safety purposes (just like the previous casting
macros).
For example, <code class="function">VIEWER_FILE_GET_CLASS</code>.
</p></li>
</ul></div>
</li>
</ul></div>
<p>
The implementation of these macros is pretty straightforward: a number of simple-to-use
macros are provided in <code class="filename">gtype.h</code>. For the example we used above, we would
write the following trivial code to declare the macros:
</p>
<div class="informalexample">
<table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
<tbody>
<tr>
<td class="listing_lines" align="right"><pre>1
2</pre></td>
<td class="listing_code"><pre class="programlisting"><span class="preproc">#define</span><span class="normal"> </span><span class="usertype">VIEWER_TYPE_FILE</span><span class="normal"> </span><span class="function">viewer_file_get_type</span><span class="normal"> </span><span class="symbol">()</span>
<span class="function"><a href="gobject-Type-Information.html#G-DECLARE-FINAL-TYPE:CAPS">G_DECLARE_FINAL_TYPE</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">ViewerFile</span><span class="symbol">,</span><span class="normal"> viewer_file</span><span class="symbol">,</span><span class="normal"> VIEWER</span><span class="symbol">,</span><span class="normal"> FILE</span><span class="symbol">,</span><span class="normal"> <a href="gobject-The-Base-Object-Type.html#GObject-struct">GObject</a></span><span class="symbol">)</span></pre></td>
</tr>
</tbody>
</table>
</div>
<p>
</p>
<p>
Unless your code has special requirements, you can use the
<code class="function"><a class="link" href="gobject-Type-Information.html#G-DEFINE-TYPE:CAPS" title="G_DEFINE_TYPE()">G_DEFINE_TYPE</a></code>
macro to define a class:
</p>
<div class="informalexample">
<table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
<tbody>
<tr>
<td class="listing_lines" align="right"><pre>1</pre></td>
<td class="listing_code"><pre class="programlisting"><span class="function"><a href="gobject-Type-Information.html#G-DEFINE-TYPE:CAPS">G_DEFINE_TYPE</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">ViewerFile</span><span class="symbol">,</span><span class="normal"> viewer_file</span><span class="symbol">,</span><span class="normal"> <a href="gobject-Type-Information.html#G-TYPE-OBJECT:CAPS">G_TYPE_OBJECT</a></span><span class="symbol">)</span></pre></td>
</tr>
</tbody>
</table>
</div>
<p>
</p>
<p>
Otherwise, the <code class="function">viewer_file_get_type</code> function must be
implemented manually:
</p>
<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</pre></td>
<td class="listing_code"><pre class="programlisting"><span class="usertype">GType</span><span class="normal"> </span><span class="function">viewer_file_get_type</span><span class="normal"> </span><span class="symbol">(</span><span class="type">void</span><span class="symbol">)</span>
<span class="cbracket">{</span>
<span class="normal"> </span><span class="keyword">static</span><span class="normal"> </span><span class="usertype">GType</span><span class="normal"> type </span><span class="symbol">=</span><span class="normal"> </span><span class="number">0</span><span class="symbol">;</span>
<span class="normal"> </span><span class="keyword">if</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">type </span><span class="symbol">==</span><span class="normal"> </span><span class="number">0</span><span class="symbol">)</span><span class="normal"> </span><span class="cbracket">{</span>
<span class="normal"> </span><span class="keyword">const</span><span class="normal"> </span><span class="usertype">GTypeInfo</span><span class="normal"> info </span><span class="symbol">=</span><span class="normal"> </span><span class="cbracket">{</span>
<span class="normal"> </span><span class="comment">/* You fill this structure. */</span>
<span class="normal"> </span><span class="cbracket">}</span><span class="symbol">;</span>
<span class="normal"> type </span><span class="symbol">=</span><span class="normal"> </span><span class="function"><a href="gobject-Type-Information.html#g-type-register-static">g_type_register_static</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal"><a href="gobject-Type-Information.html#G-TYPE-OBJECT:CAPS">G_TYPE_OBJECT</a></span><span class="symbol">,</span>
<span class="normal"> </span><span class="string">"ViewerFile"</span><span class="symbol">,</span>
<span class="normal"> </span><span class="symbol">&amp;</span><span class="normal">info</span><span class="symbol">,</span><span class="normal"> </span><span class="number">0</span><span class="symbol">);</span>
<span class="normal"> </span><span class="cbracket">}</span>
<span class="normal"> </span><span class="keyword">return</span><span class="normal"> type</span><span class="symbol">;</span>
<span class="cbracket">}</span></pre></td>
</tr>
</tbody>
</table>
</div>
<p>
</p>
</div>
<div class="footer">
<hr>Generated by GTK-Doc V1.25.1</div>
</body>
</html>