aboutsummaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/devel/ChangeLog6
-rwxr-xr-xdoc/devel/build-eplugin-manual.pl8
-rw-r--r--doc/devel/evolution-plugin-manual.xml142
3 files changed, 156 insertions, 0 deletions
diff --git a/doc/devel/ChangeLog b/doc/devel/ChangeLog
index 69ef0b5226..c22feb3b29 100644
--- a/doc/devel/ChangeLog
+++ b/doc/devel/ChangeLog
@@ -1,3 +1,9 @@
+2005-07-12 Not Zed <NotZed@Ximian.com>
+
+ * build-eplugin-manual.pl:
+
+ * evolution-plugin-manual.xml: Added some e-import stuff.
+
2005-05-19 Not Zed <NotZed@Ximian.com>
* evolution-plugin-manual.xml: added some stuff about the pseudo
diff --git a/doc/devel/build-eplugin-manual.pl b/doc/devel/build-eplugin-manual.pl
index 8cb951a516..1ddcb795d9 100755
--- a/doc/devel/build-eplugin-manual.pl
+++ b/doc/devel/build-eplugin-manual.pl
@@ -24,6 +24,10 @@
{ 'files' => [ 'e-plugin.h', 'e-plugin.c' ],
'module' => 'e-util' },
+ 'e-import.xml' =>
+ { 'files' => [ 'e-import.c', 'e-import.c' ],
+ 'module' => 'e-util' },
+
'em-popup.xml' =>
{ 'files' => [ 'em-popup.h', 'em-popup.c' ],
'module' => 'mail' },
@@ -228,6 +232,10 @@ END
{ 'type' => 'HookPoint',
'files' => [ 'e-shell-window.c' ],
'module' => 'shell' },
+ 'es-importers.xml' =>
+ { 'type' => 'HookClass',
+ 'files' => [ 'e-import.c' ],
+ 'module' => 'e-util' },
'es-events.xml' =>
{ 'type' => 'Event',
'files' => [ 'e-shell.c' ],
diff --git a/doc/devel/evolution-plugin-manual.xml b/doc/devel/evolution-plugin-manual.xml
index d184259ae4..d94ec5cc25 100644
--- a/doc/devel/evolution-plugin-manual.xml
+++ b/doc/devel/evolution-plugin-manual.xml
@@ -12,6 +12,7 @@
<!ENTITY e-config-reference SYSTEM "e-config.xml">
<!ENTITY e-event-reference SYSTEM "e-event.xml">
<!ENTITY e-plugin-reference SYSTEM "e-plugin.xml">
+<!ENTITY e-import-reference SYSTEM "e-import.xml">
<!ENTITY em-popup-reference SYSTEM "em-popup.xml">
<!ENTITY em-format-reference SYSTEM "em-format.xml">
@@ -25,6 +26,7 @@
<!ENTITY es-events SYSTEM "es-events.xml">
<!ENTITY es-menus SYSTEM "es-menus.xml">
+<!ENTITY es-importers SYSTEM "es-importers.xml">
]>
<?xml-stylesheet href="sdocbook.css" type="text/css"?>
@@ -1810,6 +1812,119 @@
</para>
</sect2>
</sect1>
+
+ <sect1 id="plugin-hooks-import">
+ <title>
+ Importers
+ </title>
+ <para>
+ Importers let &Evolution; import data from other or older programs
+ into its native format.
+ </para>
+ <para>
+ Importers are driven from a druid in the shell, they can work on
+ individual files, or multiple component application data. All
+ importers go through the same interface, is this data
+ present/supported, how do you control the import, and import the data.
+ </para>
+ <sect2>
+ <title>Defining an import hook</title>
+ <programlisting>
+ <![CDATA[
+<hook class="org.gnome.evolution.import:1.0:1.0">
+ <importer
+ target="home | uri"
+ supported="funcion spec"
+ get-widget="function spec" ?
+ import="function spec"
+ cancel="function spec" ?
+ name="name"
+ description="description" ?/> *
+</hook>]]></programlisting>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>target</parameter></term>
+ <listitem>
+ <simpara>
+ The target type for this importer. File importers are of a
+ type <constant>uri</constant> and application importers are
+ of type <constant>home</constant> (indicating a 'home
+ directory').
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>supported</parameter></term>
+ <listitem>
+ <simpara>
+ A function to call to determine if the file is supported or
+ not. The function will be passed the target, and returns
+ non-NULL if the file is known or the application data exists.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>get-widget</parameter></term>
+ <listitem>
+ <simpara>
+ A factory method to get a widget to control the import. For
+ file-based importers, this should return a widget which lets
+ the user select the destination for the import. For
+ application importers this should return a widget which lets
+ the user choose what to import. Where possible, the
+ application importer should record whether or not the data
+ has already been imported and default any checkboxes
+ accordingly.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>import</parameter></term>
+ <listitem>
+ <simpara>
+ The function to call to import the data. This function
+ should generally invoke another thread, or run via an idle
+ handler callback. During the import it may call <link
+ linkend="API-e-import-status">e_import_status()</link> to
+ report progress. It must call <link
+ linkend="API-e-import-complete">e_import_complete()</link>
+ once the import is complete, or has failed, or there was no
+ work selected by the user.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>cancel</parameter></term>
+ <listitem>
+ <simpara>
+ This optional callback will be invoked if the user activates
+ the cancel button on the import window. It should try to
+ short-cut further processing where possible.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>name</parameter></term>
+ <listitem>
+ <simpara>
+ The short name description of the importer, which will be
+ used in the import type selection dropdown, or next to the
+ application importer widgets.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>description</parameter></term>
+ <listitem>
+ <simpara>
+ A longer description of the importer. Currently unused.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </sect2>
+ </sect1>
+
</chapter>
</part>
@@ -2745,6 +2860,22 @@
&es-events;
</sect1>
+ <sect1 id="shell-hooks-import">
+ <title>Importers</title>
+
+ <para>
+ Importers are currently global to the shell. The importer class is
+ <interfacename>org.gnome.evolution.import:1.0</interfacename>.
+ </para>
+ <para>
+ Each plugin callback is passed the target. Once the target has been
+ passed to get-widget, the same target will be passed to import or
+ cancel. This allows information to be stored non-globally across
+ invocations by utilising the GData field in the target.
+ </para>
+ &es-importers;
+ </sect1>
+
</chapter>
</part>
@@ -2871,6 +3002,17 @@
</para>
&em-format-reference;
</chapter>
+
+ <chapter>
+ <title>
+ EImport
+ </title>
+ <para>
+ The EImport object is used to hold a list of EImportImporter
+ structures, which are used to drive the importer window.
+ </para>
+ &e-import-reference;
+ </chapter>
</part>
</book>