README for the apprentice print plug-ins developers
===================================================

  History
  -------

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.

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...

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!)).

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


  Architecture
  ------------

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.

Once the user has done with the GUI Gaby launches the script with the
informations the user gave in the interface.

That means a plug-in has two files: plugin_name.xml and plugin_name.py

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

  The XML File
  ------------

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

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

<pages> ... </pages>: everything is enclosed in this tag

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

The following types are possible:

- fields: a page with a list to select fields.
   It can enclose the following tags:
     <name>xxxx</name>: will identify the 'result' in the script
     <selection>nnn</selection>: 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 <selection type="last">nnn</selection>
 - records: a page to specify which records are to be printed.
    Enclosing: <name>xxxx</name>: (same purpose)
 - order: a page to specify how to sort the records
    Enclosing: <name>xxxx</name>: (same purpose)
 - misc: a page without a predefined purpose, enclosing different widgets.
    Enclosing:
      <widget label="xxxx" type="yyyy">
          <name>zzzz</name>
      </widget>
    with:
     - xxxx: label before the widget (or for the widget if == label)
     - yyyy: filesel (File selection), label, checkbox, entry
     - zzzz: (same purpose)

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

  The Python script
  -----------------

The informations about the user choice will be in gaby.PrintDict

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

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


Happy Hacking !

-- 
Frederic Peters - Wed, 22 Nov 2000 15:20:38 +0100

