← Back to branch summary

~ubuntu-branches/ubuntu/lucid/rhythmbox/lucid

« back to all changes in this revision

Viewing changes to doc/reference/xml/rb-plugin.xml

  • Committer: Bazaar Package Importer
  • Author(s): Sebastien Bacher
  • Date: 2010-03-29 10:12:48 UTC
  • mfrom: (1.1.45 upstream)
  • Revision ID: james.westby@ubuntu.com-20100329101248-fu29j0q1s2dx8k99
Tags: 0.12.8-0ubuntu1
* New upstream version
* debian/patches/90_autoreconf.patch:
  - new version update

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/reference/xml/rb-plugin.xml
1
 
<?xml version="1.0"?>
2
 
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" 
3
 
               "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
4
 
<refentry id="RBPlugin">
5
 
<refmeta>
6
 
<refentrytitle role="top_of_page" id="RBPlugin.top_of_page">RBPlugin</refentrytitle>
7
 
<manvolnum>3</manvolnum>
8
 
<refmiscinfo>RHYTHMBOX Library</refmiscinfo>
9
 
</refmeta>
10
 
 
11
 
<refnamediv>
12
 
<refname>RBPlugin</refname>
13
 
<refpurpose>Base class for plugins</refpurpose>
14
 
</refnamediv>
15
 
 
16
 
<refsynopsisdiv id="RBPlugin.synopsis" role="synopsis">
17
 
<title role="synopsis.title">Synopsis</title>
18
 
 
19
 
<synopsis>
20
 
                    <link linkend="RBPlugin-struct">RBPlugin</link>;
21
 
                    <link linkend="RBPluginClass">RBPluginClass</link>;
22
 
<link linkend="void">void</link>                (<link linkend="RBPluginActivationFunc">*RBPluginActivationFunc</link>)           (<link linkend="RBPlugin">RBPlugin</link> *plugin,
23
 
                                                         <link linkend="RBShell">RBShell</link> *shell);
24
 
<link linkend="GtkWidget">GtkWidget</link> *         (<link linkend="RBPluginWidgetFunc">*RBPluginWidgetFunc</link>)               (<link linkend="RBPlugin">RBPlugin</link> *plugin);
25
 
<link linkend="gboolean">gboolean</link>            (<link linkend="RBPluginBooleanFunc">*RBPluginBooleanFunc</link>)              (<link linkend="RBPlugin">RBPlugin</link> *plugin);
26
 
<link linkend="void">void</link>                <link linkend="rb-plugin-activate">rb_plugin_activate</link>                  (<link linkend="RBPlugin">RBPlugin</link> *plugin,
27
 
                                                         <link linkend="RBShell">RBShell</link> *shell);
28
 
<link linkend="void">void</link>                <link linkend="rb-plugin-deactivate">rb_plugin_deactivate</link>                (<link linkend="RBPlugin">RBPlugin</link> *plugin,
29
 
                                                         <link linkend="RBShell">RBShell</link> *shell);
30
 
<link linkend="gboolean">gboolean</link>            <link linkend="rb-plugin-is-configurable">rb_plugin_is_configurable</link>           (<link linkend="RBPlugin">RBPlugin</link> *plugin);
31
 
<link linkend="GtkWidget">GtkWidget</link> *         <link linkend="rb-plugin-create-configure-dialog">rb_plugin_create_configure_dialog</link>   (<link linkend="RBPlugin">RBPlugin</link> *plugin);
32
 
<link linkend="char">char</link> *              <link linkend="rb-plugin-find-file">rb_plugin_find_file</link>                 (<link linkend="RBPlugin">RBPlugin</link> *plugin,
33
 
                                                         const <link linkend="char">char</link> *file);
34
 
<link linkend="GList">GList</link> *             <link linkend="rb-get-plugin-paths">rb_get_plugin_paths</link>                 (void);
35
 
#define             <link linkend="RB-PLUGIN-REGISTER--CAPS">RB_PLUGIN_REGISTER</link>                  (PluginName, plugin_name)
36
 
#define             <link linkend="RB-PLUGIN-REGISTER-TYPE--CAPS">RB_PLUGIN_REGISTER_TYPE</link>             (type_name)
37
 
#define             <link linkend="RB-PLUGIN-DEFINE-TYPE--CAPS">RB_PLUGIN_DEFINE_TYPE</link>               (TypeName, type_name, TYPE_PARENT)
38
 
</synopsis>
39
 
</refsynopsisdiv>
40
 
 
41
 
<refsect1 id="RBPlugin.object-hierarchy" role="object_hierarchy">
42
 
<title role="object_hierarchy.title">Object Hierarchy</title>
43
 
<synopsis>
44
 
  <link linkend="GObject">GObject</link>
45
 
   +----RBPlugin
46
 
</synopsis>
47
 
</refsect1>
48
 
 
49
 
 
50
 
 
51
 
 
52
 
 
53
 
<refsect1 id="RBPlugin.properties" role="properties">
54
 
<title role="properties.title">Properties</title>
55
 
<synopsis>
56
 
  &quot;<link linkend="RBPlugin--name">name</link>&quot;                     <link linkend="gchar">gchar</link>*                : Read / Write
57
 
</synopsis>
58
 
</refsect1>
59
 
 
60
 
 
61
 
 
62
 
<refsect1 id="RBPlugin.description" role="desc">
63
 
<title role="desc.title">Description</title>
64
 
<para>
65
 
This is the base class for all plugins.  It provides methods called
66
 
when activating, deactivating, and configuring plugins.</para>
67
 
<para>
68
 
</para>
69
 
</refsect1>
70
 
 
71
 
<refsect1 id="RBPlugin.details" role="details">
72
 
<title role="details.title">Details</title>
73
 
<refsect2 id="RBPlugin-struct" role="struct">
74
 
<title>RBPlugin</title>
75
 
<indexterm zone="RBPlugin-struct"><primary sortas="RBPlugin">RBPlugin</primary></indexterm><programlisting>typedef struct _RBPlugin RBPlugin;</programlisting>
76
 
<para>
77
 
</para></refsect2>
78
 
<refsect2 id="RBPluginClass" role="struct">
79
 
<title>RBPluginClass</title>
80
 
<indexterm zone="RBPluginClass"><primary sortas="RBPluginClass">RBPluginClass</primary></indexterm><programlisting>typedef struct {
81
 
        GObjectClass parent_class;
82
 
 
83
 
        /* Virtual public methods */
84
 
 
85
 
        RBPluginActivationFunc          activate;
86
 
        RBPluginActivationFunc          deactivate;
87
 
        RBPluginWidgetFunc              create_configure_dialog;
88
 
 
89
 
        /* Plugins should not override this, it's handled automatically by
90
 
           the RbPluginClass */
91
 
        RBPluginBooleanFunc             is_configurable;
92
 
} RBPluginClass;
93
 
</programlisting>
94
 
<para>
95
 
</para></refsect2>
96
 
<refsect2 id="RBPluginActivationFunc" role="function">
97
 
<title>RBPluginActivationFunc ()</title>
98
 
<indexterm zone="RBPluginActivationFunc"><primary sortas="RBPluginActivationFunc">RBPluginActivationFunc</primary></indexterm><programlisting><link linkend="void">void</link>                (*RBPluginActivationFunc)           (<link linkend="RBPlugin">RBPlugin</link> *plugin,
99
 
                                                         <link linkend="RBShell">RBShell</link> *shell);</programlisting>
100
 
<para>
101
 
Typedef for plugin activation and deactivation functions.
102
 
These functions include the <link linkend="RBShell"><type>RBShell</type></link> as an argument to allow
103
 
the plugin to locate other parts of Rhythmbox.</para>
104
 
<para>
105
 
</para><variablelist role="params">
106
 
<varlistentry><term><parameter>plugin</parameter>&#160;:</term>
107
 
<listitem><simpara> the <link linkend="RBPlugin"><type>RBPlugin</type></link>
108
 
</simpara></listitem></varlistentry>
109
 
<varlistentry><term><parameter>shell</parameter>&#160;:</term>
110
 
<listitem><simpara> the <link linkend="RBShell"><type>RBShell</type></link>
111
 
</simpara></listitem></varlistentry>
112
 
</variablelist></refsect2>
113
 
<refsect2 id="RBPluginWidgetFunc" role="function">
114
 
<title>RBPluginWidgetFunc ()</title>
115
 
<indexterm zone="RBPluginWidgetFunc"><primary sortas="RBPluginWidgetFunc">RBPluginWidgetFunc</primary></indexterm><programlisting><link linkend="GtkWidget">GtkWidget</link> *         (*RBPluginWidgetFunc)               (<link linkend="RBPlugin">RBPlugin</link> *plugin);</programlisting>
116
 
<para>
117
 
Typedef for plugin configuration functions.</para>
118
 
<para>
119
 
</para><variablelist role="params">
120
 
<varlistentry><term><parameter>plugin</parameter>&#160;:</term>
121
 
<listitem><simpara> the <link linkend="RBPlugin"><type>RBPlugin</type></link>
122
 
</simpara></listitem></varlistentry>
123
 
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a <link linkend="GtkWidget"><type>GtkWidget</type></link> for the plugin
124
 
</simpara></listitem></varlistentry>
125
 
</variablelist></refsect2>
126
 
<refsect2 id="RBPluginBooleanFunc" role="function">
127
 
<title>RBPluginBooleanFunc ()</title>
128
 
<indexterm zone="RBPluginBooleanFunc"><primary sortas="RBPluginBooleanFunc">RBPluginBooleanFunc</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            (*RBPluginBooleanFunc)              (<link linkend="RBPlugin">RBPlugin</link> *plugin);</programlisting>
129
 
<para>
130
 
Typedef for plugin functions that return a gboolean.</para>
131
 
<para>
132
 
</para><variablelist role="params">
133
 
<varlistentry><term><parameter>plugin</parameter>&#160;:</term>
134
 
<listitem><simpara> the <link linkend="RBPlugin"><type>RBPlugin</type></link>
135
 
</simpara></listitem></varlistentry>
136
 
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> something
137
 
</simpara></listitem></varlistentry>
138
 
</variablelist></refsect2>
139
 
<refsect2 id="rb-plugin-activate" role="function">
140
 
<title>rb_plugin_activate ()</title>
141
 
<indexterm zone="rb-plugin-activate"><primary sortas="rb_plugin_activate">rb_plugin_activate</primary></indexterm><programlisting><link linkend="void">void</link>                rb_plugin_activate                  (<link linkend="RBPlugin">RBPlugin</link> *plugin,
142
 
                                                         <link linkend="RBShell">RBShell</link> *shell);</programlisting>
143
 
<para>
144
 
Called when a plugin is being activated, either on startup or when
145
 
enabled in the plugin configuration dialog.</para>
146
 
<para>
147
 
</para><variablelist role="params">
148
 
<varlistentry><term><parameter>plugin</parameter>&#160;:</term>
149
 
<listitem><simpara> the <link linkend="RBPlugin"><type>RBPlugin</type></link> being activated
150
 
</simpara></listitem></varlistentry>
151
 
<varlistentry><term><parameter>shell</parameter>&#160;:</term>
152
 
<listitem><simpara> the <link linkend="RBShell"><type>RBShell</type></link>
153
 
</simpara></listitem></varlistentry>
154
 
</variablelist></refsect2>
155
 
<refsect2 id="rb-plugin-deactivate" role="function">
156
 
<title>rb_plugin_deactivate ()</title>
157
 
<indexterm zone="rb-plugin-deactivate"><primary sortas="rb_plugin_deactivate">rb_plugin_deactivate</primary></indexterm><programlisting><link linkend="void">void</link>                rb_plugin_deactivate                (<link linkend="RBPlugin">RBPlugin</link> *plugin,
158
 
                                                         <link linkend="RBShell">RBShell</link> *shell);</programlisting>
159
 
<para>
160
 
Called when a plugin is being deactivated, either on shutdown or
161
 
when disabled in the plugin configuration dialog.
162
 
</para>
163
 
<para>
164
 
Note that plugin instances are never destroyed, so the same plugin
165
 
instance can be deactivated and then reactivated.  After deactivation,
166
 
the plugin must be in a state where it can be reactivated.</para>
167
 
<para>
168
 
</para><variablelist role="params">
169
 
<varlistentry><term><parameter>plugin</parameter>&#160;:</term>
170
 
<listitem><simpara> the <link linkend="RBPlugin"><type>RBPlugin</type></link> being deactivated
171
 
</simpara></listitem></varlistentry>
172
 
<varlistentry><term><parameter>shell</parameter>&#160;:</term>
173
 
<listitem><simpara> the <link linkend="RBShell"><type>RBShell</type></link>
174
 
</simpara></listitem></varlistentry>
175
 
</variablelist></refsect2>
176
 
<refsect2 id="rb-plugin-is-configurable" role="function">
177
 
<title>rb_plugin_is_configurable ()</title>
178
 
<indexterm zone="rb-plugin-is-configurable"><primary sortas="rb_plugin_is_configurable">rb_plugin_is_configurable</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            rb_plugin_is_configurable           (<link linkend="RBPlugin">RBPlugin</link> *plugin);</programlisting>
179
 
<para>
180
 
Determines whether the plugin is configurable.</para>
181
 
<para>
182
 
</para><variablelist role="params">
183
 
<varlistentry><term><parameter>plugin</parameter>&#160;:</term>
184
 
<listitem><simpara> the <link linkend="RBPlugin"><type>RBPlugin</type></link>
185
 
</simpara></listitem></varlistentry>
186
 
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if configurable
187
 
</simpara></listitem></varlistentry>
188
 
</variablelist></refsect2>
189
 
<refsect2 id="rb-plugin-create-configure-dialog" role="function">
190
 
<title>rb_plugin_create_configure_dialog ()</title>
191
 
<indexterm zone="rb-plugin-create-configure-dialog"><primary sortas="rb_plugin_create_configure_dialog">rb_plugin_create_configure_dialog</primary></indexterm><programlisting><link linkend="GtkWidget">GtkWidget</link> *         rb_plugin_create_configure_dialog   (<link linkend="RBPlugin">RBPlugin</link> *plugin);</programlisting>
192
 
<para>
193
 
Creates a configuration dialog for <parameter>plugin</parameter>.  The plugin can store
194
 
the dialog instance the first time it is created and just return it
195
 
thereafter.</para>
196
 
<para>
197
 
</para><variablelist role="params">
198
 
<varlistentry><term><parameter>plugin</parameter>&#160;:</term>
199
 
<listitem><simpara> the <link linkend="RBPlugin"><type>RBPlugin</type></link>
200
 
</simpara></listitem></varlistentry>
201
 
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> configuration widget for <parameter>plugin</parameter>
202
 
</simpara></listitem></varlistentry>
203
 
</variablelist></refsect2>
204
 
<refsect2 id="rb-plugin-find-file" role="function">
205
 
<title>rb_plugin_find_file ()</title>
206
 
<indexterm zone="rb-plugin-find-file"><primary sortas="rb_plugin_find_file">rb_plugin_find_file</primary></indexterm><programlisting><link linkend="char">char</link> *              rb_plugin_find_file                 (<link linkend="RBPlugin">RBPlugin</link> *plugin,
207
 
                                                         const <link linkend="char">char</link> *file);</programlisting>
208
 
<para>
209
 
Searches for <parameter>file</parameter> in the install directory for <parameter>plugin</parameter>.
210
 
Plugins should use this to locate any data files they install.</para>
211
 
<para>
212
 
</para><variablelist role="params">
213
 
<varlistentry><term><parameter>plugin</parameter>&#160;:</term>
214
 
<listitem><simpara> the <link linkend="RBPlugin"><type>RBPlugin</type></link>
215
 
</simpara></listitem></varlistentry>
216
 
<varlistentry><term><parameter>file</parameter>&#160;:</term>
217
 
<listitem><simpara> file to search for
218
 
</simpara></listitem></varlistentry>
219
 
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> path to the file, must be freed by caller.
220
 
</simpara></listitem></varlistentry>
221
 
</variablelist></refsect2>
222
 
<refsect2 id="rb-get-plugin-paths" role="function">
223
 
<title>rb_get_plugin_paths ()</title>
224
 
<indexterm zone="rb-get-plugin-paths"><primary sortas="rb_get_plugin_paths">rb_get_plugin_paths</primary></indexterm><programlisting><link linkend="GList">GList</link> *             rb_get_plugin_paths                 (void);</programlisting>
225
 
<para>
226
 
Returns a list containing the paths to search for plugins.</para>
227
 
<para>
228
 
</para><variablelist role="params">
229
 
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> <link linkend="GList"><type>GList</type></link> of paths, must be freed by caller
230
 
</simpara></listitem></varlistentry>
231
 
</variablelist></refsect2>
232
 
<refsect2 id="RB-PLUGIN-REGISTER--CAPS" role="macro">
233
 
<title>RB_PLUGIN_REGISTER()</title>
234
 
<indexterm zone="RB-PLUGIN-REGISTER--CAPS"><primary sortas="RB_PLUGIN_REGISTER">RB_PLUGIN_REGISTER</primary></indexterm><programlisting>#define             RB_PLUGIN_REGISTER(PluginName, plugin_name)</programlisting>
235
 
<para>
236
 
Registers a Rhythmbox plugin type.  Use this instead of G_DEFINE_TYPE
237
 
(or similar) for RBPlugin implementations.</para>
238
 
<para>
239
 
</para><variablelist role="params">
240
 
<varlistentry><term><parameter>PluginName</parameter>&#160;:</term>
241
 
<listitem><simpara> plugin name in CamelCase
242
 
</simpara></listitem></varlistentry>
243
 
<varlistentry><term><parameter>plugin_name</parameter>&#160;:</term>
244
 
<listitem><simpara> plugin name in lowercase with words separated by '_'
245
 
</simpara></listitem></varlistentry>
246
 
</variablelist></refsect2>
247
 
<refsect2 id="RB-PLUGIN-REGISTER-TYPE--CAPS" role="macro">
248
 
<title>RB_PLUGIN_REGISTER_TYPE()</title>
249
 
<indexterm zone="RB-PLUGIN-REGISTER-TYPE--CAPS"><primary sortas="RB_PLUGIN_REGISTER_TYPE">RB_PLUGIN_REGISTER_TYPE</primary></indexterm><programlisting>#define             RB_PLUGIN_REGISTER_TYPE(type_name)</programlisting>
250
 
<para>
251
 
Registers additional types for the plugin.  This should be called in
252
 
the plugin class_init function for types besides the plugin itself that
253
 
need to be registered with the GObject type system.</para>
254
 
<para>
255
 
</para><variablelist role="params">
256
 
<varlistentry><term><parameter>type_name</parameter>&#160;:</term>
257
 
<listitem><simpara> CamelCase name of the type to register
258
 
</simpara></listitem></varlistentry>
259
 
</variablelist></refsect2>
260
 
<refsect2 id="RB-PLUGIN-DEFINE-TYPE--CAPS" role="macro">
261
 
<title>RB_PLUGIN_DEFINE_TYPE()</title>
262
 
<indexterm zone="RB-PLUGIN-DEFINE-TYPE--CAPS"><primary sortas="RB_PLUGIN_DEFINE_TYPE">RB_PLUGIN_DEFINE_TYPE</primary></indexterm><programlisting>#define             RB_PLUGIN_DEFINE_TYPE(TypeName, type_name, TYPE_PARENT)</programlisting>
263
 
<para>
264
 
Defines additional types for the plugin.  This should be used instead
265
 
of G_DEFINE_TYPE for additional object types that need to be registered
266
 
with the GObject type system.</para>
267
 
<para>
268
 
</para><variablelist role="params">
269
 
<varlistentry><term><parameter>TypeName</parameter>&#160;:</term>
270
 
<listitem><simpara> type name in CamelCase
271
 
</simpara></listitem></varlistentry>
272
 
<varlistentry><term><parameter>type_name</parameter>&#160;:</term>
273
 
<listitem><simpara> type name in lowercase with words separated by '_'
274
 
</simpara></listitem></varlistentry>
275
 
<varlistentry><term><parameter>TYPE_PARENT</parameter>&#160;:</term>
276
 
<listitem><simpara> GType macro for the parent type
277
 
</simpara></listitem></varlistentry>
278
 
</variablelist></refsect2>
279
 
 
280
 
</refsect1>
281
 
<refsect1 id="RBPlugin.property-details" role="property_details">
282
 
<title role="property_details.title">Property Details</title>
283
 
<refsect2 id="RBPlugin--name" role="property"><title>The <literal>&quot;name&quot;</literal> property</title>
284
 
<indexterm zone="RBPlugin--name"><primary sortas="RBPlugin:name">RBPlugin:name</primary></indexterm><programlisting>  &quot;name&quot;                     <link linkend="gchar">gchar</link>*                : Read / Write</programlisting>
285
 
<para>name.</para><para>Default value: NULL</para>
286
 
</refsect2>
287
 
</refsect1>
288
 
 
289
 
 
290
 
 
291
 
 
292
 
</refentry>