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
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
|
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Anatomy of a Formatting Object header file</title>
<meta name="generator" content="DocBook XSL Stylesheets V1.73.2">
<meta name="description" content="Anatomy of a Formatting Object header file">
<link rel="start" href="index.html" title="xmlroff Reference Manual">
<link rel="up" href="developers.html" title="Developers' Guide">
<link rel="prev" href="directory-structure.html" title="Directory Structure">
<link rel="next" href="fo-c-file.html" title="Anatomy of a Formatting Object C source code file">
<meta name="generator" content="GTK-Doc V1.10 (XML mode)">
<link rel="stylesheet" href="style.css" type="text/css">
<link rel="chapter" href="users.html" title="Users' Guide">
<link rel="chapter" href="developers.html" title="Developers' Guide">
<link rel="chapter" href="object-hierarchy.html" title="Object Hierarchy">
<link rel="chapter" href="object.html" title="FoObject is wonderful">
<link rel="chapter" href="node.html" title="FoNode is wonderful">
<link rel="chapter" href="interfaces.html" title="Interfaces are truly wonderful">
<link rel="chapter" href="formatting-objects.html" title="Formatting Objects are truly wonderful">
<link rel="chapter" href="properties.html" title="Properties">
<link rel="chapter" href="areas.html" title="Area Objects">
<link rel="chapter" href="datatypes.html" title="Datatype Objects">
<link rel="chapter" href="context.html" title="Property Context Object">
<link rel="chapter" href="other-objects.html" title="Other Objects">
<link rel="chapter" href="utility-objects.html" title="Utility Objects">
<link rel="chapter" href="utility-modules.html" title="Utility Modules">
</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="2"><tr valign="middle">
<td><a accesskey="p" href="directory-structure.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
<td><a accesskey="u" href="developers.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
<td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
<th width="100%" align="center">xmlroff Reference Manual</th>
<td><a accesskey="n" href="fo-c-file.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
</tr></table>
<div class="section" lang="en">
<div class="titlepage"><div>
<div><h2 class="title" style="clear: both">
<a name="fo-h-file"></a>Anatomy of a Formatting Object header file</h2></div>
<div><h2 class="subtitle">FO .h File</h2></div>
<div><div class="abstract">
<p class="title"><b>Abstract</b></p>
<p>Anatomy of a Formatting Object header file</p>
</div></div>
</div></div>
<p>The public header files for Formatting Objects are autogenerated and, therefore, have a consistent structure. The header files for the few that are not autogenerated also follow this structure.</p>
<p>This example uses the header for the fo:root formatting object, largely because fo:root only has one property: media-usage.</p>
<p>In the example, 'Root' and 'ROOT' are part of the formatting object name, not some feature of the GObject object system.</p>
<p>All formatting object GObjects are subclasses of the FoFo GObject class.</p>
<p>The document describes the conventions current at the time of
this writing. Not only may the convention change in the future, some
of the older source code files may not yet have been updated to match
the current conventions.</p>
<div class="section" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="fo-h-initial-comment"></a>Initial comment</h3></div></div></div>
<pre class="programlisting">/* Fo
* fo-root.h: Root formatting object
*
* Copyright (C) 2001 Sun Microsystems
*
* $Id: fo-h-file.xml,v 1.1 2006/03/14 19:42:57 tonygraham Exp $
*
* See Copying for the status of this software.
*/</pre>
<p>Identifies the formatting object and states the copyright
owner.</p>
</div>
<div class="section" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="fo-h-initial-housekeeping"></a>Initial housekeeping</h3></div></div></div>
<pre class="programlisting">#ifndef FO_ROOT_H
#define FO_ROOT_H</pre>
<p><code class="code">#ifndef</code> and <code class="code">#define</code> so the header file is not included multiple times.</p>
<pre class="programlisting">#include <fo-utils.h>
#include <fo-property.h></pre>
<p><code class="code">#include</code>s for other header files.</p>
<pre class="programlisting">G_BEGIN_DECLS</pre>
<p>GLib macro that, for a C++ compiler, expands into something
useful for C++.</p>
</div>
<div class="section" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="fo-h-typedefs"></a>GObject typedefs</h3></div></div></div>
<p>Every GObject has these.</p>
<pre class="programlisting">typedef struct _FoRoot FoRoot;
typedef struct _FoRootClass FoRootClass;</pre>
<p>Typedefs for the object instance and object class.</p>
<p>The _FoRoot and _FoRootClass structures are defined in fo-root-private.h.</p>
<p>The effect is that the internals of the FoRoot and FoRootClass
are not publicly visible.</p>
</div>
<div class="section" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="fo-h-defines"></a>GObject #defines</h3></div></div></div>
<p>Every GObject has these.</p>
<pre class="programlisting">#define FO_TYPE_ROOT (fo_root_get_type ())</pre>
<p>Shorthand for the function that returns the object's GType. The GType identifies the object type.</p>
<pre class="programlisting">#define FO_ROOT(object) (G_TYPE_CHECK_INSTANCE_CAST ((object), FO_TYPE_ROOT, FoRoot))</pre>
<p>Macro for casting an object to the required type with a bit of checking that the object can be cast to the required type.</p>
<p>Will generate a warning message if the cast is not allowed.</p>
<pre class="programlisting">#define FO_ROOT_CLASS(klass) (G_TYPE_CHECK_CLASS_CAST ((klass), FO_TYPE_ROOT, FoRootClass))</pre>
<p>Macro for getting the named class structure. 'klass' is the class structure itself or the class structure of a subclass of the class. The macros use 'klass' instead of 'class' because 'class' is a C++ keyword.</p>
<pre class="programlisting">#define FO_IS_ROOT(object) (G_TYPE_CHECK_INSTANCE_TYPE ((object), FO_TYPE_ROOT))</pre>
<p>Macro for determining if 'object' is an instance of the specified class.</p>
<p>This macro type is frequently used in assertions.</p>
<pre class="programlisting">#define FO_IS_ROOT_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass), FO_TYPE_ROOT))</pre>
<p>Macro for determining if 'klass' is a class structure of the specified type.</p>
<pre class="programlisting">#define FO_ROOT_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS ((obj), FO_TYPE_ROOT, FoRootClass))</pre>
<p>Macro for getting the class structure for an instance of the specified type.</p>
<p>Will generate a warning message if the instance is not of the
specified class or of a subclass of the specified class.</p>
</div>
<div class="section" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="fo-h-gobject-functions"></a>GObject functions</h3></div></div></div>
<pre class="programlisting">GType fo_root_get_type (void) G_GNUC_CONST;</pre>
<p>Gets the GType for the object type.</p>
<pre class="programlisting">FoFo *fo_root_new (void);</pre>
<p>Gets a new instance of the object type.</p>
<p>All _new() functions for formatting objects return objects cast
to FoFo. Since the functions that manipulate formatting object objects
operate on FoFo objects, this avoids having to cast the specific
object type to FoFo on every one of those function calls.</p>
</div>
<div class="section" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="fo-h-non-property-functions"></a>Non-property functions</h3></div></div></div>
<p>A formatting object may have hand-generated functions that do
not just get and set property values. fo:root, however, does not have
any.</p>
</div>
<div class="section" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="fo-h-property-functions"></a>Property functions</h3></div></div></div>
<p>By a happy coincidence, the XSL properties of a formatting
object are expressed as GObject properties of the GObject for the
formatting object.</p>
<p>Every property of every formatting object has _get() and _set()
functions:</p>
<pre class="programlisting">FoProperty * fo_root_get_media_usage (FoFo *fo_fo);
void fo_root_set_media_usage (FoFo *fo_fo,
FoProperty *new_media_usage);</pre>
<p>The properties are registered with the GObject system as
G_PARAM_READABLE, so property values can also be accessed using
g_object_get_property().</p>
<p>The property values are not writeable, so they cannot be set
using g_object_set_property().</p>
</div>
<div class="section" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="fo-h-final-housekeeping"></a>Final housekeeping</h3></div></div></div>
<pre class="programlisting">G_END_DECLS</pre>
<p>Meaningful for C++.</p>
<pre class="programlisting">#endif /* !FO_ROOT_H */</pre>
<p>Matches earlier <code class="code">#ifndef</code>.</p>
</div>
</div>
<div class="footer">
<hr>
Generated by GTK-Doc V1.10</div>
</body>
</html>
|
