[totem] docs: Update the plugin writing guide

[Philip Withnall <pwithnall src gnome org>]

commit 1c31b67da176018776aae951092414129ebd365d
Author: Philip Withnall <philip tecnocode co uk>
Date:   Tue Jul 5 20:53:57 2011 +0100

    docs: Update the plugin writing guide

 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 5f10bae..df5c64f 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>