README
======

NEW!
----

_After_ you built succesfully Gaby you may come back in this directory and
'make install-module'. This will allow you to use the Gaby module like any
other Python module (import gaby; ...)

Important note: this won't work if you compiled against GTK+/Gnome, you will
have to compile Gaby without GUI support: ./configure --disable-gui]

[this will be fixed. some day.]

Documentation moved !!!
-----------------------

The documentation of this Python plug-in is now available in DocBook format
(hence HTML, PostScript, ...) in the doc/ directory.

This file is here as an image of the past (but can still be used to get a quick
overview of what is done).

Brief introduction to script-fus
--------------------------------

The Python plug-in is a great step towards scripts-fus and thus to easy ways
to write extensions.

They can be used in several ways :

  - as actions (defined in a desc file) :

Begin actions
	Mail to ...
		!script_fu( AddressBook:E-Mail )
		#include mailto.py
	...

  - as actions (defined at run-time) :

[NOT YET really IMPLEMENTED] there is a 'home-brewed scripts' menu item that
allows to select in a file dialog box a script to run

  - as command-line scripts (thanks to gabyscript) :

<-- starts here -->
#! /usr/local/bin/gabyscript --as gaby --interpreter python

subtable = get_subtable_by_name('Address Book')

for i in subtable.fast_records_list():
	record = subtable.get_record_no(i)
	if ( len(record[7]) == 0 ):
		record[7] = 'Belgium'
	subtable.set_record_no(i, record)
<-- stops here -->

  - as scripts to be launched on startup :

(copy this to ~/.gaby/scripts/autoexec.gaby)

<-- starts here -->
# python

main_win = get_main_window()
st = get_subtable_by_name('Phone Book')
xlist_win = st.create_new_window( 'xlist' )

main_win.resize(400, 500)

main_win.add_bound_window(xlist_win)
xlist_win.add_bound_window(main_win)
<-- stops here -->

(the first line is used so Gaby knows it is a Python script)


but other ways are planned (with ideas going to rewriting views plug-ins in
python)

[note that when I speak about Python it's simply because it's currently the
only one interpreter available - things will work the same way with Perl, ...]

Python
------

There is actually a module called _gaby that provide a dumb way to do thing and
there _will_ be a module called gaby that will provide an object-oriented way
to do the same dumb things :) 
Update : the module is now called gaby and provide the oo-way.

Objects
.......

There are 2 new object types :

- GabyWindow:
(nothing to say here)

- GabySubTable:
it has a few attributes :
  - name : its name
  - i18n_name : its name translated in the current language
  - fields : a tuple with the names of the fields
  - i18n_fields : idem but translated in ...
  - table : the name of the table behind the subtable
it also has a few methods, documented in the source ...

Functions
.........

They are documented in the source code.

-- 
Frederic Peters - Sun, 10 Oct 1999 14:45:05 +0200
