diff options
author | Philip Withnall <philip@tecnocode.co.uk> | 2011-07-05 20:53:57 +0100 |
---|---|---|
committer | Philip Withnall <philip@tecnocode.co.uk> | 2011-07-05 20:53:57 +0100 |
commit | 1c31b67da176018776aae951092414129ebd365d (patch) | |
tree | ba84ff721f647cdcfd0ef0ea8db30429312c020d /docs/reference/totem-plugins.xml | |
parent | aee1a5cc2d6105db1312a25b4bfc961ca48e3807 (diff) | |
download | totem-1c31b67da176018776aae951092414129ebd365d.tar.gz |
docs: Update the plugin writing guide
Diffstat (limited to 'docs/reference/totem-plugins.xml')
-rw-r--r-- | docs/reference/totem-plugins.xml | 73 |
1 files changed, 23 insertions, 50 deletions
diff --git a/docs/reference/totem-plugins.xml b/docs/reference/totem-plugins.xml index 5f10bae94..df5c64f96 100644 --- a/docs/reference/totem-plugins.xml +++ b/docs/reference/totem-plugins.xml @@ -19,7 +19,7 @@ (e.g. <filename class="directory">/usr/lib/totem/plugins/</filename>), or in a user's home directory (e.g. <filename class="directory">~/.local/share/totem/plugins/</filename>). In either case, each plugin resides in a subdirectory named after the plugin itself.</para> - <para>In addition, each plugin needs a <filename class="extension">.totem-plugin</filename> index file, residing inside the plugin + <para>In addition, each plugin needs a <filename class="extension">.plugin</filename> index file, residing inside the plugin directory. This gives the code name of the plugin, as well as some metadata about the plugin such as its human-readable name, description and author.</para> <example> @@ -28,7 +28,7 @@ <filename class="directory">/usr/lib/totem/plugins/subtitle-downloader</filename>, and would (at a minimum) have the following files: <itemizedlist> - <listitem><filename>subtitle-downloader.totem-plugin</filename></listitem> + <listitem><filename>subtitle-downloader.plugin</filename></listitem> <listitem><filename>libsubtitle-downloader.so</filename></listitem> </itemizedlist> </para> @@ -39,9 +39,9 @@ </refsect2> <refsect2> - <title>The <filename class="extension">.totem-plugin</filename> File</title> + <title>The <filename class="extension">.plugin</filename> File</title> <para>The file should use the following template: - <programlisting>[Totem Plugin] + <programlisting>[Plugin] Module=<replaceable>plugin-name</replaceable> IAge=<replaceable>plugin interface age (starting at 1)</replaceable> Builtin=<replaceable><literal>true</literal> or <literal>false</literal></replaceable> @@ -55,14 +55,15 @@ incremented when the binary interface of the plugin (as used by Totem) changes. If the plugin does not have its own website, Totem's website (<literal>http://projects.gnome.org/totem/</literal>) can be used.</para> <para>The library file containing the plugin's code should be named - <filename>lib<replaceable>plugin-name</replaceable>.so</filename> (for C, or other compiled-language, plugins) or - <filename><replaceable>plugin-name</replaceable>.py</filename> (for Python plugins).</para> + <filename>lib<replaceable>plugin-name</replaceable>.so</filename> (for C, or other compiled language, plugins) or + <filename><replaceable>pluginname</replaceable>.py</filename> (for Python plugins).</para> </refsect2> <refsect2> <title>Writing a Plugin</title> <para>Writing a plugin in C is a matter of creating a new <type><link linkend="GObject">GObject</link></type> which inherits - from <type><link linkend="TotemPlugin">TotemPlugin</link></type>. The following code will create a simple plugin + from <type><link linkend="PeasExtensionBase">PeasExtensionBase</link></type> and which implements + <type><link linkend="PeasActivatable">PeasActivatable</link></type>. The following code will create a simple plugin called <literal>foobar</literal>: <example> <title>Example Plugin Code</title> @@ -75,59 +76,30 @@ #define TOTEM_FOOBAR_PLUGIN_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), TOTEM_TYPE_FOOBAR_PLUGIN, TotemFoobarPluginClass)) typedef struct { - TotemPlugin parent; - /* plugin object members */ -} TotemFoobarPlugin; + /* Plugin private member variables */ +} TotemFoobarPluginPrivate; -typedef struct { - TotemPluginClass parent_class; -} TotemFoobarPluginClass; - -G_MODULE_EXPORT GType register_totem_plugin (GTypeModule *module); -GType totem_foobar_plugin_get_type (void) G_GNUC_CONST; - -static gboolean impl_activate (TotemPlugin *plugin, TotemObject *totem, GError **error); -static void impl_deactivate (TotemPlugin *plugin, TotemObject *totem); - -TOTEM_PLUGIN_REGISTER (TotemFoobarPlugin, totem_foobar_plugin) +TOTEM_PLUGIN_REGISTER (TOTEM_TYPE_FOOBAR_PLUGIN, TotemFoobarPlugin, totem_foobar_plugin); static void -totem_foobar_plugin_class_init (TotemFoobarPluginClass *klass) -{ - TotemPluginClass *plugin_class = TOTEM_PLUGIN_CLASS (klass); - - plugin_class->activate = impl_activate; - plugin_class->deactivate = impl_deactivate; -} - -static void -totem_foobar_plugin_init (TotemFoobarPlugin *plugin) -{ - /* Initialise resources, but only ones which should exist for the entire lifetime of Totem; - * those which should only exist for the lifetime of the plugin (which may be short, and may - * occur several times during one Totem session) should be created in impl_activate, and destroyed - * in impl_deactivate. */ -} - -static gboolean -impl_activate (TotemPlugin *plugin, TotemObject *totem, GError **error) +impl_activate (PeasActivatable *plugin) { TotemFoobarPlugin *self = TOTEM_FOOBAR_PLUGIN (plugin); + TotemFoobarPluginPrivate *priv = self->priv; + TotemObject *totem = g_object_get_data (G_OBJECT (plugin), "object"); /* Initialise resources, connect to events, create menu items and UI, etc., here. - * Note that impl_activate and impl_deactivate can be called multiple times in one - * Totem instance, though impl_activate will always be followed by impl_deactivate before - * it is called again. Similarly, impl_deactivate cannot be called twice in succession. */ - - return TRUE; + * Note that impl_activate() and impl_deactivate() can be called multiple times in one + * Totem instance, though impl_activate() will always be followed by impl_deactivate() before + * it is called again. Similarly, impl_deactivate() cannot be called twice in succession. */ } static void -impl_deactivate (TotemPlugin *plugin, TotemObject *totem) +impl_deactivate (PeasActivatable *plugin) { TotemFoobarPlugin *self = TOTEM_FOOBAR_PLUGIN (plugin); - /* Destroy resources created in impl_activate here. e.g. Disconnect from signals + /* Destroy resources created in impl_activate() here. e.g. Disconnect from signals * and remove menu entries and UI. */ }</programlisting> </example></para> @@ -139,9 +111,10 @@ impl_deactivate (TotemPlugin *plugin, TotemObject *totem) <para>Note that plugins can be activated and deactivated (e.g. from Totem's plugin manager) many times during one Totem session, so the <function>impl_activate</function> and <function>impl_deactivate</function> functions must be able to cope with this.</para> - <para>Any of the API documented in the rest of the Totem API reference can be used by plugins, though the bindings for Python - plugins are incomplete. Otherwise, Python plugins are written in the same way as C plugins, and are similarly implemented - as classes derived from <type><link linkend="TotemPlugin">TotemPlugin</link></type>.</para> + <para>Any of the API documented in the rest of the Totem API reference can be used by plugins. Python plugins are written in + the same way as C plugins, and are similarly implemented as classes derived from + <type><link linkend="PeasExtensionBase">PeasExtensionBase</link></type> and implementing + <type><link linkend="PeasActivatable">PeasActivatable</link></type>.</para> </refsect2> </refsect1> </refentry> |