[Gazpacho] Plugin system proposal

[Lorenzo Gil Sanchez]

Hi everybody,

this is a draft for a plugin system I want to implement in Gazpacho.

Comments and suggestions are very wellcomed.

Best regards

Lorenzo



Gazpacho plugins proposal
=========================

This document describes a plugin system for Gazpacho.

Goals
-----

- Plugins should be easy (and fun) to write

- Plugins should be easy to install / uninstall

- Users shold be able to active just the plugins they want

What can a plugin do?
---------------------

In this section I will describe the things a plugin can do.

* Create its own menus or toolbar items

  A plugin can create custom menus and/or toolbar items and enable
  or disable them dynamically depending on the current project state.

  Gazpacho class UIMState can be a base to implement such dynamic
  menus and toolbar items.

* Define its own commands

  If the main purpose of a plugin is to modify a project in some way,
  it should be a good Gazpacho citizen and provide a way to the user
  to undo those changes. In other words, it should provide its custom
  commands, derived from Gazpacho Command.

What's the difference between a widget library and a plugin
-----------------------------------------------------------

A widet library is a package that adds support to those widgets into
Gazpacho. It is the responsible of creating a widget palette and
make it work. Examples of widget libraries supported by gazpacho with
additional (3rd party) packages are the Kiwi widgets and the Hildon
widgets.

A plugin is a package that adds functionality to Gazpacho that is too
specific or experimental to be included in Gazpacho mainstream.

Unfortunately right now widget library are somewhere called plugins and
it makes this classification not obvious.

Anatomy of a plugin
-------------------
When Gazpacho starts up it searchs for plugins in the plugin directory.
A plugin is a Python package so every subdirectory in the plugin
directory will be treated as a plugin. Every plugin should have at
least:

* A __init__.py file. Otherwise it won't be a Python package. In this
file,
  the plugin metadata is located in the form of the following variables:

   - 'id': This is a unique string identifying the plugin. Java like
   package names are recommended for plugin identifiers.
   Example: biz.sicem.gazpacho.MyPlugin

   - 'title': A human readable short string

   - 'description': Long string describing what this plugin does

   - 'author': Name of the author/s of this plugin

   - 'class_name': This is the name of the class that defines this
plugin

* A plugin.py file where a subclass of gazpacho.plugin.Plugin should
  be defined. The name of this class should be the same as the string
  'plugin_class' found in the __init__.py file

The system plugin directory is located at $datadir/plugins which usually
means /user/share/gazpacho/plugins in a Linux system.

There is also a user specific plugin directory at ~/.gazpacho/plugins
This way users that does not have administrator privileges can install
their plugins in their home directory.

If a plugin is located in both the system plugin directory and the user
plugin directory only the later one will be used.

Plugin Manager
--------------
The Plugin Manager is instantiated by Gazpacho at start up time and it
loads all the plugins. This mean that it maintains a list of PluginInfo
objects. Each PluginInfo object has meta information about the plugin
such as:

   - Plugin Id

   - Plugin Title

   - Plugin Description

   - Plugin Author

   - Plugin module

   - Plugin class name

Then it looks for the user configuration file and instantiate all the
plugins that the user has enabled.

How to enable/disable a Plugin
------------------------------
There is a menu item in Gazpacho that let the user open the Plugin
Preferences Dialog. In this Dialog there is a list of all the plugins
that are installed in the system. Next to each plugin there is a check
box that says if the plugin is enabled or disabled.

In the Gazpacho configuration file (~/.gazpacho/config) there is a
section called [Plugins] which have the list of plugins that are enabled
for that user.

In the future, every plugin could have their own user specific options.
This feature is not covered by this proposal.

Plugin Initialization
---------------------
A plugin instance is created at start up time if the user configuration
says that plugin is enabled. If the user enables the plugin using the
Plugin Preferences Dialog it's also created. This instances are stored
in the Plugin Manager.

When a plugin is created its UI string definition is merged into
Gazpacho UI. If the user disables the plugin later on, the Plugin UI
will be unmerged.

The UI String is something suitable for use in Gazpacho UI Manager, that
is nothing but a Gtk+ UI Manager.

It is responsability of the Plugin Manager to the merging/unmerging of
the UI, not of the Plugin itself. The plugin should also provide a list
of actions that match the UI string it gave.

Plugin base class (gazpacho.plugin.Plugin)
------------------------------------------
This class is provided by Gazpacho core and should be used as the base
class for every plugin.

class GazpachoPlugin(object):

  def get_ui(self):
    """Returns the UI string for this plugin"""

  def get_actions(self):
    """Returns a list of actions that match the UI string definition"""

  def on_object_selected(self):
    """This will be called every time an object/widget is selected"""

  def on_project_changed(self):
    """This will be called when a project is opened or selected"""