← Back to branch summary

~ubuntu-branches/ubuntu/karmic/mergeant/karmic

« back to all changes in this revision

Viewing changes to doc/libmergeant/C/xml/mg-referer.xml

  • Committer: Bazaar Package Importer
  • Author(s): Gustavo R. Montesino
  • Date: 2007-11-29 08:44:48 UTC
  • mfrom: (2.1.4 hardy)
  • Revision ID: james.westby@ubuntu.com-20071129084448-6aon73d22bv6hzfw
Tags: 0.67-3
* Re-enable installation of the mime files in mergeant.install
* mergeant.dirs: create usr/share/mime/packages to make dh_installmime add
  the update-mime-database code snippets

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/libmergeant/C/xml/mg-referer.xml
1
 
<refentry id="MgReferer">
2
 
<refmeta>
3
 
<refentrytitle>MgReferer</refentrytitle>
4
 
<manvolnum>3</manvolnum>
5
 
<refmiscinfo>LIBMERGEANT Library</refmiscinfo>
6
 
</refmeta>
7
 
 
8
 
<refnamediv>
9
 
<refname>MgReferer</refname><refpurpose>Interface to know when on object is completely defined</refpurpose>
10
 
</refnamediv>
11
 
 
12
 
<refsynopsisdiv><title>Synopsis</title>
13
 
 
14
 
<synopsis>
15
 
 
16
 
 
17
 
 
18
 
struct      <link linkend="MgReferer-struct">MgReferer</link>;
19
 
<link linkend="GType">GType</link>       <link linkend="mg-referer-get-type">mg_referer_get_type</link>             (void);
20
 
<link linkend="gboolean">gboolean</link>    <link linkend="mg-referer-activate">mg_referer_activate</link>             (<link linkend="MgReferer">MgReferer</link> *iface);
21
 
<link linkend="void">void</link>        <link linkend="mg-referer-deactivate">mg_referer_deactivate</link>           (<link linkend="MgReferer">MgReferer</link> *iface);
22
 
<link linkend="gboolean">gboolean</link>    <link linkend="mg-referer-is-active">mg_referer_is_active</link>            (<link linkend="MgReferer">MgReferer</link> *iface);
23
 
<link linkend="GSList">GSList</link>*     <link linkend="mg-referer-get-ref-objects">mg_referer_get_ref_objects</link>      (<link linkend="MgReferer">MgReferer</link> *iface);
24
 
<link linkend="void">void</link>        <link linkend="mg-referer-replace-refs">mg_referer_replace_refs</link>         (<link linkend="MgReferer">MgReferer</link> *iface,
25
 
                                             <link linkend="GHashTable">GHashTable</link> *replacements);
26
 
</synopsis>
27
 
</refsynopsisdiv>
28
 
 
29
 
<refsect1>
30
 
<title>Object Hierarchy</title>
31
 
<synopsis>
32
 
 
33
 
  <link linkend="GInterface">GInterface</link>
34
 
   +----MgReferer
35
 
</synopsis>
36
 
 
37
 
</refsect1>
38
 
 
39
 
<refsect1>
40
 
<title>Prerequisites</title>
41
 
<para>
42
 
MgReferer requires
43
 
 <link linkend="GObject">GObject</link>.</para>
44
 
 
45
 
</refsect1>
46
 
 
47
 
 
48
 
 
49
 
<refsect1>
50
 
<title>Known Implementations</title>
51
 
<para>
52
 
MgReferer is implemented by
53
 
 <link linkend="MgQfValue">MgQfValue</link>,  <link linkend="MgQfField">MgQfField</link>,  <link linkend="MgTarget">MgTarget</link>,  <link linkend="MgDbConstraint">MgDbConstraint</link>,  <link linkend="MgQfAll">MgQfAll</link>,  <link linkend="MgCondition">MgCondition</link>,  <link linkend="MgQuery">MgQuery</link>,  <link linkend="MgJoin">MgJoin</link>,  <link linkend="MgQfFunc">MgQfFunc</link>,  <link linkend="MgCustomLayout">MgCustomLayout</link> and  <link linkend="MgParameter">MgParameter</link>.</para>
54
 
 
55
 
</refsect1>
56
 
 
57
 
 
58
 
<refsect1>
59
 
<title>Signal Prototypes</title>
60
 
<synopsis>
61
 
 
62
 
&quot;<link linkend="MgReferer-activated">activated</link>&quot; <link linkend="void">void</link>        user_function      (<link linkend="MgReferer">MgReferer</link> *mgreferer,
63
 
                                            <link linkend="gpointer">gpointer</link> user_data);
64
 
&quot;<link linkend="MgReferer-deactivated">deactivated</link>&quot;
65
 
            <link linkend="void">void</link>        user_function      (<link linkend="MgReferer">MgReferer</link> *mgreferer,
66
 
                                            <link linkend="gpointer">gpointer</link> user_data);
67
 
</synopsis>
68
 
</refsect1>
69
 
 
70
 
 
71
 
<refsect1>
72
 
<title>Description</title>
73
 
<para>
74
 
Some objects can be initialized in an uncomplete state. This is the case for example of
75
 
a primary key database constraint, when we don't know, at creation time, which field it applies to.
76
 
These objects implement this interface to at least signal when they are ready to be used.
77
 
</para>
78
 
<para>
79
 
Some objects need to be created _before_ other objects they will need to be operational even exist. They also
80
 
implement this interface.
81
 
</para>
82
 
</refsect1>
83
 
 
84
 
<refsect1>
85
 
<title>Details</title>
86
 
<refsect2>
87
 
<title><anchor id="MgReferer-struct"/>struct MgReferer</title>
88
 
<indexterm><primary>MgReferer</primary></indexterm><programlisting>struct MgReferer;</programlisting>
89
 
<para>
90
 
 
91
 
</para></refsect2>
92
 
<refsect2>
93
 
<title><anchor id="mg-referer-get-type"/>mg_referer_get_type ()</title>
94
 
<indexterm><primary>mg_referer_get_type</primary></indexterm><programlisting><link linkend="GType">GType</link>       mg_referer_get_type             (void);</programlisting>
95
 
<para>
96
 
 
97
 
</para><variablelist role="params">
98
 
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>
99
 
 
100
 
 
101
 
</simpara></listitem></varlistentry>
102
 
</variablelist></refsect2>
103
 
<refsect2>
104
 
<title><anchor id="mg-referer-activate"/>mg_referer_activate ()</title>
105
 
<indexterm><primary>mg_referer_activate</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>    mg_referer_activate             (<link linkend="MgReferer">MgReferer</link> *iface);</programlisting>
106
 
<para>
107
 
Tries to activate the object, does nothing if the object is already active.</para>
108
 
<para>
109
 
 
110
 
</para><variablelist role="params">
111
 
<varlistentry><term><parameter>iface</parameter>&nbsp;:</term>
112
 
<listitem><simpara> an object which implements the <link linkend="MgReferer"><type>MgReferer</type></link> interface
113
 
</simpara></listitem></varlistentry>
114
 
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> TRUE if the object is active after the call
115
 
</simpara></listitem></varlistentry>
116
 
</variablelist></refsect2>
117
 
<refsect2>
118
 
<title><anchor id="mg-referer-deactivate"/>mg_referer_deactivate ()</title>
119
 
<indexterm><primary>mg_referer_deactivate</primary></indexterm><programlisting><link linkend="void">void</link>        mg_referer_deactivate           (<link linkend="MgReferer">MgReferer</link> *iface);</programlisting>
120
 
<para>
121
 
Deactivates the object. This is the opposite to function <link linkend="mg-referer-activate"><function>mg_referer_activate()</function></link>.
122
 
If the object is already non active, then nothing happens.</para>
123
 
<para>
124
 
 
125
 
</para><variablelist role="params">
126
 
<varlistentry><term><parameter>iface</parameter>&nbsp;:</term>
127
 
<listitem><simpara> an object which implements the <link linkend="MgReferer"><type>MgReferer</type></link> interface
128
 
</simpara></listitem></varlistentry>
129
 
</variablelist></refsect2>
130
 
<refsect2>
131
 
<title><anchor id="mg-referer-is-active"/>mg_referer_is_active ()</title>
132
 
<indexterm><primary>mg_referer_is_active</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>    mg_referer_is_active            (<link linkend="MgReferer">MgReferer</link> *iface);</programlisting>
133
 
<para>
134
 
Get the status of an object</para>
135
 
<para>
136
 
 
137
 
</para><variablelist role="params">
138
 
<varlistentry><term><parameter>iface</parameter>&nbsp;:</term>
139
 
<listitem><simpara> an object which implements the <link linkend="MgReferer"><type>MgReferer</type></link> interface
140
 
</simpara></listitem></varlistentry>
141
 
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> TRUE if the object is active
142
 
</simpara></listitem></varlistentry>
143
 
</variablelist></refsect2>
144
 
<refsect2>
145
 
<title><anchor id="mg-referer-get-ref-objects"/>mg_referer_get_ref_objects ()</title>
146
 
<indexterm><primary>mg_referer_get_ref_objects</primary></indexterm><programlisting><link linkend="GSList">GSList</link>*     mg_referer_get_ref_objects      (<link linkend="MgReferer">MgReferer</link> *iface);</programlisting>
147
 
<para>
148
 
Get the list of objects which are referenced by <parameter>iface</parameter>. The returned list is a
149
 
new list. If <parameter>iface</parameter> is not active, then the returned list is incomplete.</para>
150
 
<para>
151
 
 
152
 
</para><variablelist role="params">
153
 
<varlistentry><term><parameter>iface</parameter>&nbsp;:</term>
154
 
<listitem><simpara> an object which implements the <link linkend="MgReferer"><type>MgReferer</type></link> interface
155
 
</simpara></listitem></varlistentry>
156
 
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> a new list of referenced objects
157
 
</simpara></listitem></varlistentry>
158
 
</variablelist></refsect2>
159
 
<refsect2>
160
 
<title><anchor id="mg-referer-replace-refs"/>mg_referer_replace_refs ()</title>
161
 
<indexterm><primary>mg_referer_replace_refs</primary></indexterm><programlisting><link linkend="void">void</link>        mg_referer_replace_refs         (<link linkend="MgReferer">MgReferer</link> *iface,
162
 
                                             <link linkend="GHashTable">GHashTable</link> *replacements);</programlisting>
163
 
<para>
164
 
Ask <parameter>iface</parameter> to replace references to objects listed as keys in the <parameter>replacements</parameter> hash table
165
 
with references to objects of the corresponding value.
166
 
</para>
167
 
<para>
168
 
It's up to the caller to make sure each pair of (key, value) objects in <parameter>replacements</parameter> are of the
169
 
same type, and that it makes sense to procede to the replacement.
170
 
</para>
171
 
<para>
172
 
The object implementing this interface will accept to do any work only if it is
173
 
already active.</para>
174
 
<para>
175
 
 
176
 
</para><variablelist role="params">
177
 
<varlistentry><term><parameter>iface</parameter>&nbsp;:</term>
178
 
<listitem><simpara> an object which implements the <link linkend="MgReferer"><type>MgReferer</type></link> interface
179
 
</simpara></listitem></varlistentry>
180
 
<varlistentry><term><parameter>replacements</parameter>&nbsp;:</term>
181
 
<listitem><simpara> a <link linkend="GHashTable"><type>GHashTable</type></link>
182
 
</simpara></listitem></varlistentry>
183
 
</variablelist></refsect2>
184
 
 
185
 
</refsect1>
186
 
 
187
 
<refsect1>
188
 
<title>Signals</title>
189
 
<refsect2><title><anchor id="MgReferer-activated"/>The &quot;activated&quot; signal</title>
190
 
<programlisting><link linkend="void">void</link>        user_function                  (<link linkend="MgReferer">MgReferer</link> *mgreferer,
191
 
                                            <link linkend="gpointer">gpointer</link> user_data);</programlisting>
192
 
<para>
193
 
 
194
 
</para><variablelist role="params">
195
 
<varlistentry><term><parameter>mgreferer</parameter>&nbsp;:</term>
196
 
<listitem><simpara>the object which received the signal.
197
 
 
198
 
</simpara></listitem></varlistentry>
199
 
<varlistentry><term><parameter>user_data</parameter>&nbsp;:</term>
200
 
<listitem><simpara>user data set when the signal handler was connected.</simpara></listitem></varlistentry>
201
 
</variablelist></refsect2><refsect2><title><anchor id="MgReferer-deactivated"/>The &quot;deactivated&quot; signal</title>
202
 
<programlisting><link linkend="void">void</link>        user_function                  (<link linkend="MgReferer">MgReferer</link> *mgreferer,
203
 
                                            <link linkend="gpointer">gpointer</link> user_data);</programlisting>
204
 
<para>
205
 
 
206
 
</para><variablelist role="params">
207
 
<varlistentry><term><parameter>mgreferer</parameter>&nbsp;:</term>
208
 
<listitem><simpara>the object which received the signal.
209
 
 
210
 
</simpara></listitem></varlistentry>
211
 
<varlistentry><term><parameter>user_data</parameter>&nbsp;:</term>
212
 
<listitem><simpara>user data set when the signal handler was connected.</simpara></listitem></varlistentry>
213
 
</variablelist></refsect2>
214
 
</refsect1>
215
 
 
216
 
 
217
 
 
218
 
</refentry>