Re: Plugin interface questions

[Jody Goldberg <jody gnome org>]

On Thu, Feb 27, 2003 at 08:51:15PM +0100, Laurent Guerby wrote:
> 1/ Following the instructions from
> http://grub.ath.cx/gnumeric-python/
>
> I just added a few lines to ~/.gnumeric/rc.py and got
> my function after restarting gnumeric. Good, is this
> documented somewhere? I'm thinking of the magic file name, the spec
> of the python functions involved like register / unregister
> or more advanced like how to move the cursor, set and get cell
> values, etc...

There are several pieces there, some documented more than others.

a) Function definitions (non python specific)
    In the current development series the file
        gnumeric/doc/developer/writing-functions.sgml
    has the details of the argument types and arguments when
    registering functions.  Something similar existed in the 1.0.x
    series as
        gnumeric/doc/writing-functions.sgml

b) The python specific aspects of things.
    The web page you site you mention is a good overview.  You
    should note that the function name is _not_ magic.  It is
    specified in the plugin.xml file (or the plugin.xml.in if you
    want things translated).

c) The primary interface for adding functions is actually the C
   interface.  Python is supported as a useful prototyping tool, but
   for serious analytics we assume you'll want to avoid the
   overhead.  The code in
       gnumeric/plugins/derivatives
   (Again assuming current cvs rather than 1.0.x) is a work in
   progress with respect to the functions themselves, but the
   framework of defining them and making them available within
   gnumeric is easy to read.  Any of the other function plugins 
   would be usable as examples, but the options analytics may be of
   interest.

d) Macros vs Functions
    Note : This focuses on adding _functions_ to the spreadsheet.
    That, as you note, is very well defined and quite stable.  Your
    question regarding macros or procedures steps into an area that
    is still open to development.  There is a sample interface for
    manipulating things from python.  There is also a CORBA binding.
    However, it is they are just samples.  I have intentionally
    avoided specifying a scripting api until there is enough
    implementation experience to produce something solid.  For now
    new commands are primarily written in C.  Its not terribly
    difficult, but the documentation is limited to api docs.  There
    are no tutorials as yet.

> 3/ Is it possible to register functions or control gnumeric
> from the outside dynamically? For example I'm running gnumeric, edit myblurb.py,
> run python myblurb.py (or do something from gnumeric)
> et voila I have my new function within gnumeric or my gnumeric spreadsheet
> is filled with values from my script, etc...
Hmm.  Interesting.  There is no dynamic monitoring of plugins right
now.  The trivial solution would be to unload and reload a plugin (C
or python).  A more complex solution to allow external notification
would be possible, but I would worry about the implications for the
calculations, silently changing the behaviour of the calculations is
a bit scary.

> 4/ Same as 3 but with a C shared library.
> Where to read in the gnumeric sources is fine with me,
> it looks like there's a generic plugin loader architecture,
> so there must be plugin loaders, and at last plugins :).
There are lots of examples.  You are probably best to look at the
1.1.x development series here.  Although the interface has not
changed much (we added a few additional pieces of information)
almost all of the functions are now in plugins.
    gnumeric/plugins/fn-*
should get you started.

> I have gnumeric-1.0.9 from RH8, no problem to update if necessary.
> I have also the sources from CVS, and I volunteer
> to contribute a document if it doesn't already exist  elsewhere.

The main changes between 1.0.9 and 1.0.12 related to working around
libxml1 breakage with non-ascii characters.  You may want to update
when you start putting french text into spreadsheets.

The development series (1.1.x) is fairly stable and will be freezing
in preparation for release shortly.  There are lots of new features,
including clean support for real time data feeds.  There is also one
feature regression, graphs, I'm still working on those and hope to
restore them shortly so that we can release.

You may want to play with both to see which better suits your needs.

Hope that helps
    Jody