← Back to branch summary

~kaozilon/totem/test

« back to all changes in this revision

Viewing changes to docs/reference/xml/totem-plugin.xml

  • Committer: Bazaar Package Importer
  • Author(s): Sjoerd Simons, Josselin Mouette, Sjoerd Simons, Emilio Pozuelo Monfort
  • Date: 2009-04-19 17:28:51 UTC
  • mfrom: (1.2.52 upstream) (5.1.1 squeeze)
  • Revision ID: james.westby@ubuntu.com-20090419172851-epoqimnq62akn294
Tags: 2.26.1-1
http://bugs.debian.org/523582
http://bugs.debian.org/523052
[ Josselin Mouette ]
* totem-plugins depends on python-gdbm. Closes: #523582.

[ Sjoerd Simons ]
* New upstream release (2.26.1)
* debian/patches/02_flv.patch: Dropped, fixed upstream
* debian/patches/04_tracker_build.patch: Dropped, fixed upstream
* debian/patches/01_fake_keypresses.patch: Updated and simplified
* debian/patches/70_bbc_plugin.patch: Updated
* debian/patches/90_autotools.patch: Updated

[ Emilio Pozuelo Monfort ]
* Recommend gnome-codec-install rather than gnome-app-install.
  Closes: #523052.

Show diffs side-by-side

added added

removed removed

Lines of Context:
docs/reference/xml/totem-plugin.xml
 
1
<?xml version="1.0"?>
 
2
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
 
3
        <!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'">
 
4
        <!ENTITY version SYSTEM "version.xml">
 
5
        <!ENTITY slash "/">
 
6
]>
 
7
<refentry id="TotemPlugin">
 
8
<refmeta>
 
9
<refentrytitle role="top_of_page" id="TotemPlugin.top_of_page">TotemPlugin</refentrytitle>
 
10
<manvolnum>3</manvolnum>
 
11
<refmiscinfo>TOTEM Library</refmiscinfo>
 
12
</refmeta>
 
13
 
 
14
<refnamediv>
 
15
<refname>TotemPlugin</refname>
 
16
<refpurpose>base plugin class and loading/unloading functions</refpurpose>
 
17
</refnamediv>
 
18
<refsect1 id="TotemPlugin.stability-level">
 
19
<title>Stability Level</title>
 
20
Unstable, unless otherwise indicated
 
21
</refsect1>
 
22
 
 
23
<refsynopsisdiv id="TotemPlugin.synopsis" role="synopsis">
 
24
<title role="synopsis.title">Synopsis</title>
 
25
 
 
26
<synopsis>
 
27
 
 
28
#include &lt;totem-plugin.h&gt;
 
29
 
 
30
                    <link linkend="TotemPlugin-struct">TotemPlugin</link>;
 
31
                    <link linkend="TotemPluginClass">TotemPluginClass</link>;
 
32
enum                <link linkend="TotemPluginError">TotemPluginError</link>;
 
33
<link linkend="gboolean">gboolean</link>            <link linkend="totem-plugin-activate">totem_plugin_activate</link>               (<link linkend="TotemPlugin">TotemPlugin</link> *plugin,
 
34
                                                         <link linkend="TotemObject">TotemObject</link> *totem,
 
35
                                                         <link linkend="GError">GError</link> **error);
 
36
<link linkend="void">void</link>                <link linkend="totem-plugin-deactivate">totem_plugin_deactivate</link>             (<link linkend="TotemPlugin">TotemPlugin</link> *plugin,
 
37
                                                         <link linkend="TotemObject">TotemObject</link> *totem);
 
38
<link linkend="GtkWidget">GtkWidget</link> *         <link linkend="totem-plugin-create-configure-dialog">totem_plugin_create_configure_dialog</link>
 
39
                                                        (<link linkend="TotemPlugin">TotemPlugin</link> *plugin);
 
40
<link linkend="gboolean">gboolean</link>            <link linkend="totem-plugin-is-configurable">totem_plugin_is_configurable</link>        (<link linkend="TotemPlugin">TotemPlugin</link> *plugin);
 
41
<link linkend="GtkBuilder">GtkBuilder</link> *        <link linkend="totem-plugin-load-interface">totem_plugin_load_interface</link>         (<link linkend="TotemPlugin">TotemPlugin</link> *plugin,
 
42
                                                         const <link linkend="char">char</link> *name,
 
43
                                                         <link linkend="gboolean">gboolean</link> fatal,
 
44
                                                         <link linkend="GtkWindow">GtkWindow</link> *parent,
 
45
                                                         <link linkend="gpointer">gpointer</link> user_data);
 
46
<link linkend="char">char</link> *              <link linkend="totem-plugin-find-file">totem_plugin_find_file</link>              (<link linkend="TotemPlugin">TotemPlugin</link> *plugin,
 
47
                                                         const <link linkend="char">char</link> *file);
 
48
</synopsis>
 
49
</refsynopsisdiv>
 
50
 
 
51
<refsect1 id="TotemPlugin.object-hierarchy" role="object_hierarchy">
 
52
<title role="object_hierarchy.title">Object Hierarchy</title>
 
53
<synopsis>
 
54
  <link linkend="GObject">GObject</link>
 
55
   +----TotemPlugin
 
56
</synopsis>
 
57
</refsect1>
 
58
 
 
59
 
 
60
 
 
61
 
 
62
 
 
63
<refsect1 id="TotemPlugin.properties" role="properties">
 
64
<title role="properties.title">Properties</title>
 
65
<synopsis>
 
66
  &quot;<link linkend="TotemPlugin--name">name</link>&quot;                     <link linkend="gchar">gchar</link>*                : Read / Write
 
67
</synopsis>
 
68
</refsect1>
 
69
 
 
70
 
 
71
 
 
72
<refsect1 id="TotemPlugin.description" role="desc">
 
73
<title role="desc.title">Description</title>
 
74
<para>
 
75
<link linkend="TotemPlugin"><type>TotemPlugin</type></link> is a general-purpose architecture for adding plugins to Totem, with
 
76
derived support for different programming languages.</para>
 
77
<para>
 
78
</para>
 
79
</refsect1>
 
80
 
 
81
<refsect1 id="TotemPlugin.details" role="details">
 
82
<title role="details.title">Details</title>
 
83
<refsect2 id="TotemPlugin-struct" role="struct">
 
84
<title>TotemPlugin</title>
 
85
<indexterm zone="TotemPlugin-struct"><primary sortas="Plugin">TotemPlugin</primary></indexterm><programlisting>typedef struct _TotemPlugin TotemPlugin;</programlisting>
 
86
<para>
 
87
All the fields in the <link linkend="TotemPlugin"><type>TotemPlugin</type></link> structure are private and should never be accessed directly.</para>
 
88
<para>
 
89
</para></refsect2>
 
90
<refsect2 id="TotemPluginClass" role="struct">
 
91
<title>TotemPluginClass</title>
 
92
<indexterm zone="TotemPluginClass"><primary sortas="PluginClass">TotemPluginClass</primary></indexterm><programlisting>typedef struct {
 
93
        GObjectClass parent_class;
 
94
 
 
95
        /* Virtual public methods */
 
96
 
 
97
        TotemPluginActivationFunc&nbsp;activate;
 
98
        TotemPluginDeactivationFunc&nbsp;deactivate;
 
99
        TotemPluginWidgetFunc           create_configure_dialog;
 
100
} TotemPluginClass;
 
101
</programlisting>
 
102
<para>
 
103
The class structure for the <link linkend="TotemPlParser"><type>TotemPlParser</type></link> type.</para>
 
104
<para>
 
105
</para><variablelist role="struct">
 
106
<varlistentry>
 
107
<term><link linkend="GObjectClass">GObjectClass</link>&#160;<structfield>parent_class</structfield>;</term>
 
108
<listitem><simpara> the parent class
 
109
</simpara></listitem>
 
110
</varlistentry>
 
111
<varlistentry>
 
112
<term><link linkend="TotemPluginActivationFunc">TotemPluginActivationFunc</link>&#160;<structfield>activate</structfield>;</term>
 
113
<listitem><simpara> function called when activating a plugin using <link linkend="totem-plugin-activate"><function>totem_plugin_activate()</function></link>.
 
114
It must be set by inheriting classes, and should return <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if it successfully created/got handles to
 
115
the resources needed by the plugin. If it returns <link linkend="FALSE:CAPS"><literal>FALSE</literal></link>, loading the plugin is abandoned.
 
116
</simpara></listitem>
 
117
</varlistentry>
 
118
<varlistentry>
 
119
<term><link linkend="TotemPluginDeactivationFunc">TotemPluginDeactivationFunc</link>&#160;<structfield>deactivate</structfield>;</term>
 
120
<listitem><simpara> function called when deactivating a plugin using <link linkend="totem-plugin-deactivate"><function>totem_plugin_deactivate()</function></link>;
 
121
It must be set by inheriting classes, and should free/unref any resources the plugin used.
 
122
</simpara></listitem>
 
123
</varlistentry>
 
124
<varlistentry>
 
125
<term><link linkend="TotemPluginWidgetFunc">TotemPluginWidgetFunc</link>&#160;<structfield>create_configure_dialog</structfield>;</term>
 
126
<listitem><simpara> function called when configuring a plugin using <link linkend="totem-plugin-create-configure-dialog"><function>totem_plugin_create_configure_dialog()</function></link>.
 
127
If non-<link linkend="NULL:CAPS"><literal>NULL</literal></link>, it should create and return the plugin's configuration dialog. If <link linkend="NULL:CAPS"><literal>NULL</literal></link>, the plugin is not
 
128
configurable.
 
129
</simpara></listitem>
 
130
</varlistentry>
 
131
</variablelist></refsect2>
 
132
<refsect2 id="TotemPluginError" role="enum">
 
133
<title>enum TotemPluginError</title>
 
134
<indexterm zone="TotemPluginError"><primary sortas="PluginError">TotemPluginError</primary></indexterm><programlisting>typedef enum {
 
135
        TOTEM_PLUGIN_ERROR_ACTIVATION
 
136
} TotemPluginError;
 
137
</programlisting>
 
138
<para>
 
139
Error codes returned by <link linkend="TotemPlugin"><type>TotemPlugin</type></link> operations.</para>
 
140
<para>
 
141
</para><variablelist role="enum">
 
142
<varlistentry id="TOTEM-PLUGIN-ERROR-ACTIVATION:CAPS" role="constant">
 
143
<term><literal>TOTEM_PLUGIN_ERROR_ACTIVATION</literal></term>
 
144
<listitem><simpara> there was an error activating the plugin
 
145
</simpara></listitem>
 
146
</varlistentry>
 
147
</variablelist></refsect2>
 
148
<refsect2 id="totem-plugin-activate" role="function">
 
149
<title>totem_plugin_activate ()</title>
 
150
<indexterm zone="totem-plugin-activate"><primary sortas="plugin_activate">totem_plugin_activate</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            totem_plugin_activate               (<link linkend="TotemPlugin">TotemPlugin</link> *plugin,
 
151
                                                         <link linkend="TotemObject">TotemObject</link> *totem,
 
152
                                                         <link linkend="GError">GError</link> **error);</programlisting>
 
153
<para>
 
154
Activates the passed <parameter>plugin</parameter> by calling its activate method.</para>
 
155
<para>
 
156
</para><variablelist role="params">
 
157
<varlistentry><term><parameter>plugin</parameter>&#160;:</term>
 
158
<listitem><simpara> a <link linkend="TotemPlugin"><type>TotemPlugin</type></link>
 
159
</simpara></listitem></varlistentry>
 
160
<varlistentry><term><parameter>totem</parameter>&#160;:</term>
 
161
<listitem><simpara> a <link linkend="TotemObject"><type>TotemObject</type></link>
 
162
</simpara></listitem></varlistentry>
 
163
<varlistentry><term><parameter>error</parameter>&#160;:</term>
 
164
<listitem><simpara> return location for a <link linkend="GError"><type>GError</type></link>, or <link linkend="NULL:CAPS"><literal>NULL</literal></link>
 
165
</simpara></listitem></varlistentry>
 
166
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> on success
 
167
</simpara></listitem></varlistentry>
 
168
</variablelist></refsect2>
 
169
<refsect2 id="totem-plugin-deactivate" role="function">
 
170
<title>totem_plugin_deactivate ()</title>
 
171
<indexterm zone="totem-plugin-deactivate"><primary sortas="plugin_deactivate">totem_plugin_deactivate</primary></indexterm><programlisting><link linkend="void">void</link>                totem_plugin_deactivate             (<link linkend="TotemPlugin">TotemPlugin</link> *plugin,
 
172
                                                         <link linkend="TotemObject">TotemObject</link> *totem);</programlisting>
 
173
<para>
 
174
Deactivates <parameter>plugin</parameter> by calling its deactivate method.</para>
 
175
<para>
 
176
</para><variablelist role="params">
 
177
<varlistentry><term><parameter>plugin</parameter>&#160;:</term>
 
178
<listitem><simpara> a <link linkend="TotemPlugin"><type>TotemPlugin</type></link>
 
179
</simpara></listitem></varlistentry>
 
180
<varlistentry><term><parameter>totem</parameter>&#160;:</term>
 
181
<listitem><simpara> a <link linkend="TotemObject"><type>TotemObject</type></link>
 
182
</simpara></listitem></varlistentry>
 
183
</variablelist></refsect2>
 
184
<refsect2 id="totem-plugin-create-configure-dialog" role="function">
 
185
<title>totem_plugin_create_configure_dialog ()</title>
 
186
<indexterm zone="totem-plugin-create-configure-dialog"><primary sortas="plugin_create_configure_dialog">totem_plugin_create_configure_dialog</primary></indexterm><programlisting><link linkend="GtkWidget">GtkWidget</link> *         totem_plugin_create_configure_dialog
 
187
                                                        (<link linkend="TotemPlugin">TotemPlugin</link> *plugin);</programlisting>
 
188
<para>
 
189
Returns the plugin's configuration dialog, as created by
 
190
the plugin's create_configure_dialog method.</para>
 
191
<para>
 
192
</para><variablelist role="params">
 
193
<varlistentry><term><parameter>plugin</parameter>&#160;:</term>
 
194
<listitem><simpara> a <link linkend="TotemPlugin"><type>TotemPlugin</type></link>
 
195
</simpara></listitem></varlistentry>
 
196
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the configuration dialog, or <link linkend="NULL:CAPS"><literal>NULL</literal></link>
 
197
</simpara></listitem></varlistentry>
 
198
</variablelist></refsect2>
 
199
<refsect2 id="totem-plugin-is-configurable" role="function">
 
200
<title>totem_plugin_is_configurable ()</title>
 
201
<indexterm zone="totem-plugin-is-configurable"><primary sortas="plugin_is_configurable">totem_plugin_is_configurable</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            totem_plugin_is_configurable        (<link linkend="TotemPlugin">TotemPlugin</link> *plugin);</programlisting>
 
202
<para>
 
203
Returns <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if the plugin is configurable and has a
 
204
configuration dialog. It calls the plugin's
 
205
is_configurable method.</para>
 
206
<para>
 
207
</para><variablelist role="params">
 
208
<varlistentry><term><parameter>plugin</parameter>&#160;:</term>
 
209
<listitem><simpara> a <link linkend="TotemPlugin"><type>TotemPlugin</type></link>
 
210
</simpara></listitem></varlistentry>
 
211
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if the plugin is configurable
 
212
</simpara></listitem></varlistentry>
 
213
</variablelist></refsect2>
 
214
<refsect2 id="totem-plugin-load-interface" role="function">
 
215
<title>totem_plugin_load_interface ()</title>
 
216
<indexterm zone="totem-plugin-load-interface"><primary sortas="plugin_load_interface">totem_plugin_load_interface</primary></indexterm><programlisting><link linkend="GtkBuilder">GtkBuilder</link> *        totem_plugin_load_interface         (<link linkend="TotemPlugin">TotemPlugin</link> *plugin,
 
217
                                                         const <link linkend="char">char</link> *name,
 
218
                                                         <link linkend="gboolean">gboolean</link> fatal,
 
219
                                                         <link linkend="GtkWindow">GtkWindow</link> *parent,
 
220
                                                         <link linkend="gpointer">gpointer</link> user_data);</programlisting>
 
221
<para>
 
222
Loads an interface file (GtkBuilder UI file) for a plugin, given its filename and
 
223
assuming it's installed in the plugin's data directory.
 
224
</para>
 
225
<para>
 
226
This should be used instead of attempting to load interfaces manually in plugins.</para>
 
227
<para>
 
228
</para><variablelist role="params">
 
229
<varlistentry><term><parameter>plugin</parameter>&#160;:</term>
 
230
<listitem><simpara> a <link linkend="TotemPlugin"><type>TotemPlugin</type></link>
 
231
</simpara></listitem></varlistentry>
 
232
<varlistentry><term><parameter>name</parameter>&#160;:</term>
 
233
<listitem><simpara> interface filename
 
234
</simpara></listitem></varlistentry>
 
235
<varlistentry><term><parameter>fatal</parameter>&#160;:</term>
 
236
<listitem><simpara> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if it's a fatal error if the interface can't be loaded
 
237
</simpara></listitem></varlistentry>
 
238
<varlistentry><term><parameter>parent</parameter>&#160;:</term>
 
239
<listitem><simpara> the interface's parent <link linkend="GtkWindow"><type>GtkWindow</type></link>
 
240
</simpara></listitem></varlistentry>
 
241
<varlistentry><term><parameter>user_data</parameter>&#160;:</term>
 
242
<listitem><simpara> a pointer to be passed to each signal handler in the interface when they're called
 
243
</simpara></listitem></varlistentry>
 
244
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the <link linkend="GtkBuilder"><type>GtkBuilder</type></link> instance for the interface
 
245
</simpara></listitem></varlistentry>
 
246
</variablelist></refsect2>
 
247
<refsect2 id="totem-plugin-find-file" role="function">
 
248
<title>totem_plugin_find_file ()</title>
 
249
<indexterm zone="totem-plugin-find-file"><primary sortas="plugin_find_file">totem_plugin_find_file</primary></indexterm><programlisting><link linkend="char">char</link> *              totem_plugin_find_file              (<link linkend="TotemPlugin">TotemPlugin</link> *plugin,
 
250
                                                         const <link linkend="char">char</link> *file);</programlisting>
 
251
<para>
 
252
Finds the specified <parameter>file</parameter> by looking in the plugin paths
 
253
listed by <link linkend="totem-get-plugin-paths"><function>totem_get_plugin_paths()</function></link> and then in the system
 
254
Totem data directory.
 
255
</para>
 
256
<para>
 
257
This should be used by plugins to find plugin-specific
 
258
resource files.</para>
 
259
<para>
 
260
</para><variablelist role="params">
 
261
<varlistentry><term><parameter>plugin</parameter>&#160;:</term>
 
262
<listitem><simpara> a <link linkend="TotemPlugin"><type>TotemPlugin</type></link>
 
263
</simpara></listitem></varlistentry>
 
264
<varlistentry><term><parameter>file</parameter>&#160;:</term>
 
265
<listitem><simpara> the file to find
 
266
</simpara></listitem></varlistentry>
 
267
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a newly-allocated absolute path for the file, or <link linkend="NULL:CAPS"><literal>NULL</literal></link>
 
268
</simpara></listitem></varlistentry>
 
269
</variablelist></refsect2>
 
270
 
 
271
</refsect1>
 
272
<refsect1 id="TotemPlugin.property-details" role="property_details">
 
273
<title role="property_details.title">Property Details</title>
 
274
<refsect2 id="TotemPlugin--name" role="property"><title>The <literal>&quot;name&quot;</literal> property</title>
 
275
<indexterm zone="TotemPlugin--name"><primary sortas="Plugin:name">TotemPlugin:name</primary></indexterm><programlisting>  &quot;name&quot;                     <link linkend="gchar">gchar</link>*                : Read / Write</programlisting>
 
276
<para>
 
277
The plugin's name. It should be a construction property, but due to the Python plugin hack, it
 
278
can't be: do not change the name after construction. Should be the same as used for naming plugin-
 
279
specific resources.</para>
 
280
<para>
 
281
</para><para>Default value: NULL</para>
 
282
</refsect2>
 
283
</refsect1>
 
284
 
 
285
 
 
286
 
 
287
 
 
288
</refentry>