<Part id="developer"><title>Gaby Developers' Guide</title>

<toc></toc>

<chapter id="develintro"><title>Introduction</title>

<para>
This document stands for a documentation about plugins as used by Gaby; it is
only useful for developers who want to quickly learn about Gaby. Those who have
time should be better served reading code.
</para>

<important><para>In cases where the code conflicts with this document the
former wins.</para></important>

  <sect1><title>Plugins licence</title>

<para>
This is shamelessly copied from Gnumeric README.
</para>

<para>
The current plugin setup in Gaby is just a way to dynamically
load code at runtime into the address space of Gaby: they use and
invoke pieces of Gaby code directly.  This means that any plugin
written under this scheme has to fall under the license of the GNU GPL.
</para>

<para>
I agree there are other popular free licences (BSDish, Artistic, ...) and I'm
not (at all) against them; I just want to respect GPL.
</para>

</sect1>

  <sect1><title>What to know before writing Gaby plugins</title>

<itemizedlist>
<listitem>
<para>
C : Gaby is written in C and this is the only language I daily use.
It is certainly be possible to write plugins in C++ and it is sure you could
write a plugin which would load and execute Python or Perl code (but this is
another story). A side note about C : I prefer Linux Coding Standards to GNU
ones; therefore : <command>indent -kr -i8 *.c</command>
</para>
</listitem>

<listitem>
<para>
GLIB : things like GString's and GList's are often used as well as some
other convenience functions but you don't have to worry about GHashTable,
GTree, ...
</para>
</listitem>

<listitem>
<para>
GTK+ : I'd say 'tutorial + testgtk' but this could be less, or more.
</para>
</listitem>

<listitem>
<para>
Gnome : may be useful in some cases.
</para>
</listitem>
</itemizedlist>

<important><para>
Memory allocations (malloc, strdup, ...) are done using the GLIB library
(g_malloc, g_strdup, ...).  This allows to call
<function>g_mem_profile</function> to know about memory status.
</para></important>

</sect1>

</chapter>

<chapter id="functions"><title>Functions and structures</title>

<para>
Unlike the reference chapter this one is manually written and can be outdated
but I'll do my best to avoid this. I'll also try to provide examples and
purpose informations for most entries.
</para>

<sect1><title>Messages and errors</title>

<para>
Gaby provides a simple way to ensure that every message (being an informal
message, an emergency error or a critical error) get a correct and coherent
handling.
</para>

<para>
This is done using two global variable :

<itemizedlist>
<listitem>
<para>gaby_errno (int) holds a number that gives the type of message.
They are defined in <filename>gabyerror.h</filename>.</para>

<para>Today it looks like :
<programlisting>
#define NO_ERROR                0
#define CUSTOM_MESSAGE          1
#define CUSTOM_WARNING          2
#define CUSTOM_ERROR            3
#define ONLY_IN_GNOME           4
#define FILE_READ_ERROR         5
#define FILE_WRITE_ERROR        6
#define TEMPFILE_ERROR          7
#define LOAD_PLUGIN_ERROR       8

#define UNKNOWN_ERROR           999
</programlisting></para>
</listitem>
<listitem>
<para>gaby_message (char*) holds a string that has a different behaviour
regarding the value of gaby_errno</para>
</listitem>
</itemizedlist>
</para>

<para><emphasis>FIXME</emphasis>: this table is broken.</para>

<para>
<table>
<title></title>
<TGROUP ALIGN="char" CHAROFF="50" CHAR="." COLS="3">
<COLSPEC ALIGN="left" COLNUM="1" COLSEP="0" COLWIDTH="7pc">
<tbody>
<row>
<entry>NO_ERROR</entry>
<entry>NULL</entry>
<entry>Nothing</entry>
</row>
<row>
<entry>CUSTOM_MESSAGE</entry>
<entry>string to show</entry>
<entry>A string in an "Information Box"</entry>
</row>
<row>
<entry>CUSTOM_WARNING</entry>
<entry>string to show</entry>
<entry>A string in a "Warning Box"</entry>
</row>
<row>
<entry>CUSTOM_ERROR</entry>
<entry>string to show</entry>
<entry>A string in an "Error Box"</entry>
</row>
<row>
<entry>ONLY_IN_GNOME</entry>
<entry>NULL</entry>
<entry>A message to warn about a feature only available if it was compiled with
Gnome support</entry>
</row>
<row>
<entry>FILE_READ_ERROR</entry>
<entry>name of the file</entry>
<entry>A message telling that an error occured when reading a file</entry>
</row>
<row>
<entry>FILE_WRITE_ERROR</entry>
<entry>name of the file</entry>
<entry>A message telling that an error occured when writing a file</entry>
</row>

</tbody>
</tgroup>
</table>
</para>

<para>
The message is then issued when you call
<function>gaby_perror_in_a_box()</function>.
</para>

</sect1>

<sect1><title>Structures</title>

<para>They are defined in <filename>src/struct.h</filename>.</para>

<sect2><title>Basic structures</title>

<sect3><title>data</title>

<para>
The first basic structure is not a structure, it is an
<emphasis>union</emphasis> defined as :

<programlisting>
union data {
        GString *str;
        int i;
        float d;
        GDate *date;
        gboolean b;
        gpointer anything;
};
</programlisting>
</para>

<para>
Its main purpose is to hold different fields 'data.
</para>

<para><emphasis>FIXME</emphasis> : write a table with field types (T_*) and
corresponding field in union data</para>

</sect3>

<sect3><title>record</title>

<programlisting>
typedef struct _record          record;

struct _record {
        int id;
        union data *cont;
        struct location *file_loc;
};
</programlisting>

<para>
<itemizedlist>
<listitem><para>
<structfield>id</structfield> is the id of the record (each record has a
different id, 0 means that the record is unavailable (deleted, ...)).
</para></listitem>

<listitem><para>
<structfield>cont</structfield> is an array holding the different's field
(therefore it has a size = number of field in the table)
</para></listitem>

<listitem><para>
<structfield>file_loc</structfield> is used in file operations (loading/saving)
</para></listitem>

</itemizedlist>
</para>

</sect3>

<sect3><title>table</title>

<programlisting>
struct _table {
        gchar *name;
        char short_name[5];
        field *fields;
        int nb_fields;
        record **records;
        GList **indexes;
        int max_records;
        GList *locations;
};
</programlisting>

<para><itemizedlist>

<listitem><para>
<structfield>name</structfield> and <structfield>short_name</structfield> are
the name (and its short version) of the table </para></listitem>

<listitem><para>
<structfield>fields</structfield> is an array of size
<structfield>nb_fields</structfield> filled with <structname>field</structname>
structures (see below).</para></listitem>

<listitem><para>
<structfield>records</structfield> is an array of pointer to
<structname>record</structname> structures, the highest array position is given
by <structfield>max_records</structfield> but there may be NULL pointers in
this array (as well as records where id equals 0)
</para></listitem>

<listitem><para>
<structfield>indexes</structfield> and <structfield>locations</structfield>
shouldn't be used in plug-ins
</para></listitem>

</itemizedlist></para>

<sect3><title>field</title>

<programlisting>
struct _field {
        gchar *name;
        gchar *i18n_name;
        field_type type;
        property **properties;
        GList *ok_if;

};
</programlisting>

<para><itemizedlist>

<listitem><para>
<structfield>name</structfield> and <structfield>i18n_name</structfield> hold
the name (and its translation in the user favorite language) of the field
</para></listitem>

<listitem><para>
<structfield>type</structfield> holds the type of the field; given by 
<programlisting>
enum _field_type {
        T_STRING  = 0,
        T_STRINGS = 1,
        T_INTEGER = 2,
        T_REAL    = 3,
        T_DATE    = 4,
        T_BOOLEAN = 5,
        T_RECORD  = 6,
        T_RECORDS = 7,
        T_MULTIMEDIA = 8
};
</programlisting>
</para></listitem>

<listitem><para>
<structfield>properties</structfield> and <structfield>ok_if</structfield>
aren't useful :)
</para></listitem>

</itemizedlist></para>

</sect3>


<sect3><title>subtable</title>

<programlisting>
struct _subtable {
        gchar *name;
        gchar *i18n_name;
        table *table;
        st_field *fields;
        int nb_fields;
        condition *cond;
};
</programlisting>

<para><itemizedlist>

<listitem><para>
<structfield>name</structfield> and <structfield>i18n_name</structfield> have
the same meaning as for fields
</para></listitem>

<listitem><para>
<structfield>table</structfield> holds the table from which the subtable is
derived
</para></listitem>

<listitem><para>
<structfield>fields</structfield> holds an array (of size
<structfield>nb_fields</structfield>) filled with
<structname>st_field</structname> (see below).
</para></listitem>

<listitem><para>
<structfield>cond</structfield> isn't really for you
</para></listitem>

</itemizedlist></para>
</sect3>

<sect3><title>st_field</title>

<programlisting>
struct _st_field {
        gchar *name;
        gchar *i18n_name;
        int no;
        field_type type;
        GList *link_format;
        view *v;

};
</programlisting>

<para><itemizedlist>

<listitem><para>
<structfield>name</structfield> and <structfield>i18n_name</structfield> have
their usual meaning
</para></listitem>

<listitem><para>
<structfield>no</structfield> holds the index of the field of the table that
this field is derived from (is this clear ?). It may be -1 if
<structfield>type</structfield> is T_RECORDS
</para></listitem>

<listitem><para>
<structfield>type</structfield> has the same meaning as in
<structname>field</structname> with the extra value T_RECORDS.
</para></listitem>

<listitem><para>
<structfield>link_format</structfield> and <structfield>v</structfield> are
used for relations between tables and you don't need to know anything about
them
</para></listitem>

</itemizedlist></para>

</sect3>

</sect2>

<!--
<sect2><title>Misc structures</title>

</sect2>
-->
</sect1>

<!--
<sect1><title>Functions</title>
<sect2><title>For records</title>


<example><title><function>get_subtable_stringed_field_id</function></title>

<programlisting>
view *v;
int *id;
GString *str;
	.
	.
	.
/* get the first field of the subtable */
str = get_subtable_stringed_field_id(v->subtable, *id, 0 );

/* show the information */
	.
	.
	.
/* free the GString */
g_string_free(str, 1);

</programlisting>
</example>

</sect2>

</sect1>
-->

</chapter>

  <chapter id="plugin-view"><title>Views</title>

<important><para>I changed the view plug-in API recently and you should skip
this chapter waiting I rewrote it</para></important>

<para>
There is a sample plugin logically called 'hello' which is a minimal
implementation of a classic (it only shows one record at the same time) plugin.
</para>

  <sect1><title>Initialization</title>

<para>
When Gaby starts it reads the description of the database to be used (which is
guess from the name you used to invoke Gaby or from the --as flags). I'll not
talk about this file here but somewhere it will have a line like this :
<command>viewable as form,list,xlist.</command>
from which Gaby "guess" it has to load form, list and xlist plugins. The first
step is to initialize those plugins <footnote><para>Note that this could be done
only when the user asks for them but since it is not implemented this way ...
</para></footnote> which is done looking for a function like this in the plugin :
</para>

<FUNCSYNOPSIS>
<FUNCSYNOPSISINFO>#include &lt;gaby.h&gt;</FUNCSYNOPSISINFO>
<FUNCDEF>int <FUNCTION>init_view_plugin</FUNCTION></FUNCDEF>
<PARAMDEF>ViewPluginData *<PARAMETER>vpd</PARAMETER></PARAMDEF>
</FUNCSYNOPSIS>

<important><para>If you want your plug-in to support being part of the huge
binary produced when configuring with <quote>Miguel wishes</quote> you'll have
to enclose the function in a 
<literal>#ifndef FOLLOW_MIGUEL</literal>.</para></important>

<para>
The ViewPluginData structure is defined in <filename>gaby.h</filename> (like
all structures used in Gaby) :

<!-- TODO move structures explanations in a separate section -->

<programlisting>
typedef struct _ViewPluginData ViewPluginData;

struct _ViewPluginData {
        GModule *handle;
        int     (*init_plugin)  ( ViewPluginData *vpd );

        void    (*view_create)  (gabywindow *win, gboolean first);

        void    (*view_fill)    (gabywindow *win);
        void    (*view_save)    (gabywindow *win);
#ifndef NO_GTK
        GtkWidget* (*configure) (ViewPluginData *vpd);
#endif

        gchar *name;
        gchar *i18n_name;
        enum {
                ALL_RECORDS = 1 &lt;&lt; 0,
                ONE_RECORD = 1 &lt;&lt; 1,
                FILTER = 1 &lt;&lt; 2
        } type;
        enum {
                NONE = 0,
                EDITABLE = 1 &lt;&lt; 0,
                FILTERABLE = 1 &lt;&lt; 1,
        } capabilities;
};
</programlisting>

</para>

<para>
I believe you already have a good picture of what will have its place in
<function>init_view_plugin</function>. To confirm :

<example><title>Initializing a view plug-in</title>

<programlisting>
int init_view_plugin(ViewPluginData *vpd)
{
        vpd-&gt;view_create = hello_create;
        vpd-&gt;view_fill = hello_fill;
        vpd-&gt;configure = NULL;

        vpd-&gt;name = "hello";
        vpd-&gt;i18n_name = _("Hello");
        vpd-&gt;type = ONE_RECORD;
        vpd-&gt;capabilities = NONE;

        return 0;
}
</programlisting>
</example>

</para>
<para><emphasis>FIXME</emphasis>: a few comments would be welcomed.</para>

  <sect1><title>View creation</title>

<para>
It is the <command>vpd->view_create = hello_create;</command> with 
<command>hello_create</command>
being a function defined like this :

<FUNCSYNOPSIS>
<FUNCDEF>mstatic void* <FUNCTION>hello_create</FUNCTION></FUNCDEF>
<PARAMDEF>gabywindow* <PARAMETER>window</PARAMETER></PARAMDEF>
<PARAMDEF>gboolean <PARAMETER>first</PARAMETER></PARAMDEF>
</FUNCSYNOPSIS>

<important>
<para>
<function>hello_create</function> is defined as a <quote>mstatic</quote>
function, this means that it will be static <emphasis>excepted</emphasis> when
compiled with Miguel wishes.
</para>
</important>

Its purpose is to create a widget which will then be put either in the main
window of Gaby either in a separate window. This widget will then be recorded
at <structname>window->widget</structname>. This means that the widget has
<emphasis>not</emphasis> to be a  window with title bar and the like. It will
 commonly be a <command>Gtk[V,H]Box</command> but any GTK container will work.

</para>

<para>
Let's have an example :

<example><title>Creating a view</title>
<programlisting>
mstatic void hello_create ( gabywindow *window, gboolean first )
{
        GtkWidget *vbox;
        GtkWidget *label;
        GtkWidget *hbb;
        GtkWidget *button;
        int *id = &amp;(window-&gt;id);
        record *r;

        r = table_first(v->subtable->table, -1);
        *id = ( r == NULL ? 0 : r->id );

        r = table_first(window->view->subtable->table, -1);
        *id = ( r == NULL ? 0 : r->id );

        vbox = gtk_vbox_new(FALSE,0);
        window->widget = vbox;

        label = gtk_label_new("");
        gtk_widget_show(label);
        gtk_box_pack_start(GTK_BOX(vbox), label, FALSE, TRUE, 0);

        hbb = gtk_hbutton_box_new();
        gtk_widget_show(hbb);
        gtk_box_pack_start(GTK_BOX(vbox), hbb, FALSE, TRUE, 0);

        button = gtk_button_new_with_label(_("Previous"));
        gtk_widget_show(button);
        gtk_signal_connect(GTK_OBJECT(button), "clicked", \
                                GTK_SIGNAL_FUNC(previous_clicked), window);
        gtk_container_add(GTK_CONTAINER(hbb), button);

        button = gtk_button_new_with_label(_("Next"));
        gtk_widget_show(button);
        gtk_signal_connect(GTK_OBJECT(button), "clicked", \
                                GTK_SIGNAL_FUNC(next_clicked), window);
        gtk_container_add(GTK_CONTAINER(hbb), button);

        gtk_widget_show(vbox);

        return;
}
</programlisting>
</example>

Most lines are typical GTK as described in GTK documentation. The interesting
lines are :

<programlisting>
        int *id = &amp;(window->id);
        record *r;
        r = table_first(v->subtable->table, -1);
        *id = ( r == NULL ? 0 : r->id );
</programlisting>

This sets the record you're currently on to the first record of the table; or
to 0 if the table is empty.

<!--
<bf>FIXME :</bf> notes about structures view and subtable and functions
table_first and the like. This could be done in a separate section.<p>
-->

</para>

<para>Note that unlike the previous version of the API you don't have to play
with lots of <function>gtk_object_get_data</function> in your plug-ins, making
them cleaner.
</para>

  <sect1><title>View filling</title>

<para>
As I just said (and as the title says) this is the function which will take
datas from a table to show them in the beautiful widgets you just created.
</para>

<para>
Here is the code :

<example><title>Filling a view</title>
<programlisting>
mstatic void hello_fill ( gabywindow *window )
{
        view *v = window->view;
        int *id = &amp;(window->id);
        GtkWidget *label = gtk_object_get_data(GTK_OBJECT(win), "label");
        GString *str;
	
        if ( *id == 0 ) {
                gtk_label_set_text(GTK_LABEL(label), _("Hello, world !"));
                return;
        }

        str = get_subtable_stringed_field_id(v->subtable, *id, 0 );

        str = g_string_prepend(str, _("Hello, "));
        gtk_label_set_text(GTK_LABEL(label), str->str);
        g_string_free(str, 1);
}
</programlisting>
</example>

<para>
The first thing is to retrieve the label widget we'll use to show the
information :

<programlisting>
        GtkWidget *label = gtk_object_get_data(GTK_OBJECT(win), "label");
</programlisting>

</para>

<para>
Then we check if we have a record to show, since record ids start at 1, 0 means
no record to show :

<programlisting>
        if ( *id == 0 ) {
                gtk_label_set_text(GTK_LABEL(label), _("Hello, world !"));
                return;
        }
</programlisting>
</para>

<para>
The easy case is done. Now we know that we have a real record to show. Since
this is just an example, we'll just show one field and to be sure it will work
with any tables we'll show the first one.

<programlisting>
        str = get_subtable_stringed_field_id(v->subtable, *id, 0 );
</programlisting>

It is now easy as adding "Hello" before the string we got and showing it in a
widget :

<programlisting>
        str = g_string_prepend(str, _("Hello, "));
        gtk_label_set_text(GTK_LABEL(label), str->str);
</programlisting>

It is now finished, we free the string and leave.

</para>

  <sect1><title>Moving between records</title>

<para>

We have two buttons in our view (namely "Previous" and "Next"),
their purpose is evident, the way it is done also (hem hem).

</para>

<para>

<programlisting>
static void previous_clicked(GtkWidget *button, gabywindow *window)
{
        record *r;
        view *v = window->view;
        int *id = &amp;(window->id);

        r = get_record_no(v->subtable->table, *id);
        r = table_prev(v->subtable->table, r, -1);
        *id = ( r == NULL ) ? 0 : r->id;
        hello_fill(win);

        update_bound_windows(window);
}
</programlisting>


The interesting is <function>r = table_prev(v->subtable->table, r,
-1);</function>.

</para>

<para><emphasis>FIXME</emphasis>: here is a few notes, they should be moved
in a section with table_{first,last,next,prev} and get_record_no.</para>

<para>
<function>table_prev</function> takes 3 arguments :

<itemizedlist>
<listitem><para>
table which is the table in which the record is,
</para></listitem>
<listitem><para>r which is the record we were at,
</para></listitem>
<listitem><para>
sort_by which is a number explaining with which kind of sorting we want
to move (-1 means no sorting otherwise it is a field number).
</para></listitem>
</itemizedlist>

</para>

<para>
Then we fill again the view and tell gaby about this change so bound windows
are updated (with <function>update_bound_windows</function>).
</para>

<para>

<function>next_clicked</function> is the same with <function>table_next</function> instead of
<function>table_prev</function>. Note that you don't need to check if you're
on the first (or latest) record, it is handled by Gaby (previous when on first
and you'll stay on it, same with next on latest).

</para>

  <sect1><title>Configuring</title>

<para>
In <function>init_view_plugin</function> we affected something to
<structfield>vpd->configure</structfield>.
It is a function defined as :

<function>
mstatic GtkWidget* configure(ViewPluginData *vpd);
</function>

It is used in the 'configure' box inside Gaby. Since you don't have anything to
configure you may simply type (or affect <literal>NULL</literal> to the
variable :

<programlisting>
mstatic GtkWidget* configure(ViewPluginData *vpd)
{
        return NULL;
}
</programlisting>

</para>

</sect1>

</chapter>

  <chapter id="plugin-action"><title>Actions</title>

<para>
An important issue is that those are action<emphasis>s</emphasis> plugins, not
action plugins. This means that one plugin may (and usually do) contain more
than one action. For consistency they should be grouped by purpose (this may
have exceptions : if plugins are really specific to an app, they could belong
to a special plugin for this app).
</para>

<important><para>
There are <emphasis>no</emphasis> ways for the user or the writer of a
<filename>desc.</filename> file to know which functions are in your plug-ins so
<emphasis>you must document your plug-in</emphasis>. This could be done in
DocBook format so I can easily put it in this documentation.
</para></important>

<para>
Gaby needs to know what it should perform when an user choose "Mail to this
guy" in the "Actions" menu. On the other side I already said that Gaby has no
way to know the list of functions you export. So, how does it work ?

<orderedlist>
<listitem><para>The user choose "Mail to";</para></listitem>
<listitem><para>Gaby <emphasis>know</emphasis> that this command is "mail" in a
plug-in called "net" thanks to the desc file;</para></listitem>
<listitem><para>With this information, Gaby can load your plug-in but it doesn't
know (yet) where to find "mail";</para></listitem>
<listitem><para>Gaby calls a function <function>get_function_by_name</function>
which you have defined in your plug-in;</para></listitem>
<listitem><para>Now that Gaby has all the informations, it can call the right
function and the user is happy ...</para></listitem>
</orderedlist>

</para>

<para>In the next sections, I'll write (a little) about
<function>get_function_by_name</function> and (a lot) about the other
functions.
</para>

  <sect1><title>get_function_by_name</title>

<FUNCSYNOPSIS>
<FUNCDEF>void <FUNCTION>get_function_by_name</FUNCTION></FUNCDEF>
<PARAMDEF>gchar* <PARAMETER>name</PARAMETER></PARAMDEF>
<PARAMDEF>action* <PARAMETER>a</PARAMETER></PARAMDEF>
</FUNCSYNOPSIS>

<para>
This is a simple question whose job is to map functions names to functions.
Ususally it will be something like :

<example><title><function>get_function_by_name</function></title>
<programlisting>
void get_function_by_name (gchar *name, action *a)
{
        a->function = NULL;
        if ( strcmp(name, "mail") == 0 )
                a->function = mail;
        if ( strcmp(name, "phone") == 0 )
                a->function = phone;

}
</programlisting>
</example>

</para>

<para>
Simple enough to skip comments ...
</para>

</sect1>

<sect1><title>An action</title>

<para>I didn't speak about <function>mail</function> and
<function>phone</function> you read in the
<function>get_function_by_name</function> example. They were defined just
before the function as :

<programlisting>
static void mail (struct action_param fields[3], int *dec);
static void phone (struct action_param field[1], int *dec);
</programlisting>

</para>

<para>
In fact, the common form is :

<FUNCSYNOPSIS>
<FUNCDEF>static void <FUNCTION>action_foo</FUNCTION></FUNCDEF>
<PARAMDEF>struct action_param* <PARAMETER>params</PARAMETER></PARAMDEF>
<PARAMDEF>int* <PARAMETER>dec</PARAMETER></PARAMDEF>
</FUNCSYNOPSIS>

</para>

<para>
I'll first speak about the second parameter which is simply a counter used by
Gaby to know if it may free the plug-in. You only have to decrement it at the
end(s) of the action and <emphasis>not</emphasis> before (i.e. this means that
if you open a dialog you may only decrement it once the dialog is closed).
</para>

<note><para>
You can read more about <structname>action_param</structname> in the chapter
dedicated to structures.
</para></note>

<!-- TODO speak about different kinds of parameters (or put a "see the chapter
describing the actions part of a desc file") and put an example -->

</sect1>

</chapter>

  <chapter id="plugin-format"><title>Format</title>

<para>
You need two things to handle a file format : loading and saving. One day you
won't even have to provide a way to save informations because it will be
possible to load a file in a format and save it in another one (this might even
work in the other way (saving but no loading but I tend to prefer the first
one)).
</para>

<para>
Gaby is really simple since the two functions you will have to define are
<function>load_file</function> and <function>save_file</function>. It's even so
simple that I'd like to say you "read the source, Luke"
(<filename>vcard.c</filename> is around 6k long and is a good example).
</para>

<para>
Alternatively the functions can be named 
<function>&lt;plugin name&gt;_load_file</function> and
<function>&lt;plugin name&gt;_save_file</function>. This alternative may become
the standard way so you'd better use it.
</para>

<sect1><title>File loading</title>

<para>

<FUNCSYNOPSIS>
<FUNCDEF>gboolean <FUNCTION>load_file</FUNCTION></FUNCDEF>
<PARAMDEF>struct location* <PARAMETER>loc</PARAMETER></PARAMDEF>
</FUNCSYNOPSIS>

is what you will have to define in your plug-in to load a file.

</para>
<para>

<structname>struct location</structname> is defined in
<filename>gaby.h</filename> as :

<programlisting>
struct location {
        gchar *filename;
        gchar *type;
        int max_index;
        int offset;
        int reread;
        int timeout_tag;
        gboolean readonly;
        gboolean disabled;
        table *table;
};
</programlisting>

You may ignore everything except <structfield>filename</structfield> and
<structfield>table</structfield>.

<itemizedlist>
<listitem><para>
<structfield>filename</structfield> hold the name of the file you have to read;
</para></listitem>
<listitem><para>
<structfield>table</structfield> hold the table in which you'll put records you
read.
</para></listitem>
</itemizedlist>

</para>

<para>
Another thing you have to know is (logically) the
<structname>record</structname> structure. <!-- which should be described in a
chapter along with other structures -->
</para>

<para>
As soon as you know that the process is really simple :

<orderedlist>
<listitem><para>
Read a record from <structfield>loc->filename</structfield>
</para></listitem>
<listitem><para>
Store this record in a <structname>record</structname> structure.
</para></listitem>
<listitem><para>
Call <function>record_add</function>
</para></listitem>
</orderedlist>
</para>

</sect1>

<sect1><title>File saving</title>

<para>
It really looks like loading except that the function is :

<FUNCSYNOPSIS>
<FUNCDEF>gboolean <FUNCTION>save_file</FUNCTION></FUNCDEF>
<PARAMDEF>struct location* <PARAMETER>loc</PARAMETER></PARAMDEF>
</FUNCSYNOPSIS>
</para>

<para>
instead of <function>load_file</function>.
</para>

<note><para>
You may simply return FALSE if you don't want to support saving.
</para></note>

</sect1>

  </chapter>

  <chapter id="plugin-printing"><title>Printing</title>

<sect1><title>History</title>

<para>
Before 1.9.20 Gaby used a plug-in mechanism for print plug-ins similar to
the ones you can still find for formats, views and actions.
</para>

<para>
That mechanism meant plug-ins had to be written in C (actually it was
theorically possible to use C++ without much troubles) and that was
quite stupid since that meant dealing with strings and C is not the ideal
language to do that...
</para>

<para>
So I decided to move from C plug-ins to Python plug-ins (Python was chosen
over Perl or any language you might want because the only embedded interpreter
in Gaby is actually Python (and it's a nice language!)).
</para>

<para>
This file should explain you the basics you have to know to write print
plug-ins for Gaby.
</para>

</sect1>

<sect1><title>Architecture</title>

<para>
I didn't want each and every plug-in writing code to deal with a GUI since
that might (would) have led to writing each time the same code in a different
way and nothing in common between plug-ins. So the GUI is not created manually
by the script but automatically by Gaby thanks to an XML file provided by the
plug-in.
</para>

<para>
Once the user has done with the GUI Gaby launches the script with the
informations the user gave in the interface.
</para>

<para>
That means a plug-in has two files: plugin_name.xml and plugin_name.py
</para>

<para>
Actually there is also a third file: plugin_name.dsc, used by Gaby to
'register' the plug-in.
</para>

</sect1>

<sect1><title>The XML file</title>

<para>
The purpose of the XML file is to describe the contents of a notebook window,
giving each page a purpose and some widgets.
</para>

<para>
I'll try to talk about each aspect of the xml file but you should really read
current plug-ins.
</para>

<sect2><title>The tags</title>

<para>
&lt;pages&gt; ... &lt;/pages&gt;: everything is enclosed in this tag
</para>

<para>
&lt;page label="XXXX" type="YYYY"&gt; ... &lt;/page&gt;: enclosed in &lt;pages&gt; &lt;/pages&gt;,
those tags describe one page with a label 'XXXX' of type 'YYYY'.
</para>

<para>
The following types are possible:
</para>

<itemizedlist>
<listitem>
<para>
fields: a page with a list to select fields.
   It can enclose the following tags:
   <itemizedlist>
     <listitem><para>
     &lt;name&gt;xxxx&lt;/name&gt;: will identify the 'result' in the script
     </para></listitem>
     <listitem><para>
     &lt;selection&gt;nnn&lt;/selection&gt;: default selection for the list
     nnn should be a number or 'all' (meaning every fields selected)
     it is also possible to select a range of fields starting from
     the end of the list with &lt;selection type="last"&gt;nnn&lt;/selection&gt;
     </para></listitem>
   </itemizedlist>
</para>
</listitem>
<listitem><para>
records: a page to specify which records are to be printed.
    Enclosing: &lt;name&gt;xxxx&lt;/name&gt;: (same purpose)
</para></listitem>
<listitem><para>
 order: a page to specify how to sort the records
    Enclosing: &lt;name&gt;xxxx&lt;/name&gt;: (same purpose)
</para></listitem>
<listitem><para>
misc: a page without a predefined purpose, enclosing different widgets.
    Enclosing:
    <literallayout>
      &lt;widget label="xxxx" type="yyyy"&gt;
          &lt;name&gt;zzzz&lt;/name&gt;
      &lt;/widget&gt;
    </literallayout>
    with:
    <itemizedlist>
    <listitem><para>
    xxxx: label before the widget (or for the widget if == label)
    </para></listitem>
    <listitem><para>
     yyyy: filesel (File selection), label, checkbox, entry
    </para></listitem>
    <listitem><para>
     zzzz: (same purpose)
    </para></listitem>
    </itemizedlist>
</para></listitem>
</itemizedlist>

<para>
Once again: refer to the existing plug-ins (and to gaby source code) for
examples and explanations. (or send me a mail)
</para>

</sect2>
</sect1>

<sect1><title>The Python script</title>

<para>
The informations about the user choice will be in gaby.PrintDict
</para>

<itemizedlist>
<listitem><para>
For fields page: a list of field numbers
</para></listitem>
<listitem><para>
For records page: a list of records
</para></listitem>
<listitem><para>
For order page: a field number
</para></listitem>
<listitem><para>
For filesel and entry widgets: the text of the entry
</para></listitem>
<listitem><para>
For checkbox widgets: true or false (actually 0 or 1)
</para></listitem>
</itemizedlist>

<para>
Misc comments:
<itemizedlist>
<listitem><para>
 The gaby python module is automatically loaded. (refer to its documentation)
  (actually it might be quicker to refer to existing plug-ins)
</para></listitem>
<listitem><para>
you shouldn't sys.exit(0), use 'raise' to abort
</para></listitem>
<listitem><para>
 you should put the text strings through gaby.gettext so they are translated
  in the user language. The common way to do this:
  <programlisting>
&gt;&gt;&gt; _ = gaby.gettext
&gt;&gt;&gt; f.write( _("Sample document") )
  </programlisting>
</para></listitem>
</itemizedlist>

</sect1>

</chapter>

<chapter id="functions-auto"><title>Automagically generated reference</title>

<para>
This chapter is automagically generated from the source code and shouldn't be
outdated.
</para>

	&functions;

</chapter>

</part>