documentation/plugin.txt

A plugin architecture for openlp 2.0
------------------------------------

Why?
----
To allow easy development of new "things to display". Examples:
* Bible passages
* Video
* Powerpoint/Openoffice Impress
* Lyrics :) (with chords, rich text, etc...)
* Musical score
* Midi files (hmmm, that's not a thing to display, but feels like it should be
  there...)
* Audio files, CDs (hmmm again)
* Collections of pictures
* Alerts to members of the congregation
... etc.

The scope of these plugins is "things for display purposes", so each needs to
be able to:
* Render their display (on the projection screen and in a "shrunken form"
  for preview purposes)

These plugins need to be part of a service.  This means they need to 
* Be able to tell the service manager code what to put in the service for their
  "bit"
* Have a "tab" in the media manager, which they can render on request
  to allow bits to be added to the service (or indeed shown live)

In addition, some plugins need to be able to show
* How their multiple screens of data are split (eg verses)
* be told which screen to display

Some plugins will also have things to configure, so will need
* to tell the core app that they need a preferences page
* and be able to render it and handle those prefs

Some plugins may need to define
* Hot keys for their display actions.  The core will have to pass these on...

Other basic things all plugins will need:
* A name
* A version number
* Helpfile?

Funnily enough, the core lyrics engine fits those requirements, so could
actually form a plugin...

Each service entry may be made up of multiple plugins (to do text on video), so
each plugin that contributes to a service item will need a "layering"
priority.

Plugin management
-----------------

Plugins will be packages within the plugins/ directory.  The plugin manager
will scan this directory when openlp loads for any class which is based on the
base Plugin class (or should we call it the DisplayPlugin class to allow for
other sorts??)

These plugins are then queried for their capabilities/requirements and
spaces made in the prefs UI as required, and in the media manager.

The service manager can find out what plugins it has available (we need to
report missing plugins when a service is loaded).

The display manager will get a ref to a/some plugin(s) from the service
manager when each service item is made live, and can then call on each to
render their display.

Each plugin will have basic attributes for 
* name
* version number 
* capabilities/requirements 
  (eg:
  needs a prefs page, 
  needs key presses forwarding
  has multiple screensful?
  )

and a set of API functions for
* media manager rendering and handling
* creating service data
* being told service data
* set paint context
* render
* selecting a screen to display
* handling preferences
* shortcut key handling...


Other things to add:
Multiple monitors
Openoffice like plugins  - external rendering.
update hook for rendering?
Event hook from app
Event hook to app (MIDI events....)