Developping the advene code
===========================

Where to start reading the Advene code ?
----------------------------------------

The Advene model (``lib/advene/model``) is independant of the rest of the
application, and can be reused in other applications. 

The main configuration options of the applications are located in
``advene.core.config``. The module, upon load, defines a
``advene.core.config.data`` instance which holds configuration values
and is a singleton shared by all other modules importing
``advene.core.config``.  A common idiom is to import it through
``import advene.core.config as config`` and to access ``config.data``.

The Advene application is articulated around the
``advene.core.controller`` class. This class holds a reference to 
- the player (``controller.player``, generated by the advene.core.mediacontrol factory)
- the ECA engine (``controller.event_handler``, instance of advene.rules.ecaengine)
- the loaded package (``controller.package``, instance of advene.model.package)
- the list of loaded packages (``controller.packages``, dictionary)
- the webserver (``controller.server``, instance of advene.core.webserver)
- the GUI (``controller.gui``, may be None if we are only running the webserver)

It also maintains important state information such as
``controller.active_annotations``, constantly updated while the player
is running.

The controller should centralize all interaction (esp. interaction
with the player through the ``controller.update_status`` method) in order
to take advantage of the event notification system. Modules that
update the state of the application or the data should invoke the
``controller.notify()`` method with the right parameters. The list of
events is defined in ``advene.rules.elements.ECACatalog``.

The update of the information implies that the ``controller.update``
method is called regularly. This is done by the GUI mainloop for the
GUI version. The ``self_loop`` method allows to start a mainloop
without a GUI.

The GUI code is intialized in ``advene.gui.__init__`` and starts in
``advene.gui.main``.

Localization
------------

To update the translation, go to the ``po/`` directory, and use the
``make POTFILES`` command to generate the list of python files
containing translated text. Then, use ``make pot`` to generate the
translation templates, and ``make update-po`` to update the various
translation files (``fr.po`` for instance).

Release
-------

To release a new version, you have to update :
- ``lib/advene/core/version.py`` -- the version module
- ``advene.iss`` -- the Windows installer config file
- ``CHANGES.txt`` -- the changelog file

View plugin infrastructure
--------------------------

The views and edit plugins are based on the MVC Model. The edited data
is the model, the View or Edit plugin is the controller, which holds a
reference to a view (accessible through the ``widget`` attribute or
property).

A common API is defined for the views in
``lib/advene/gui/views/viewplugin.py``. Some documentation is
available in ``adhoc-views.txt``.
