Writing Extensions

Most of Encode's functionality is split into separate modules which are loaded via an extension system. Third-party extension modules that implement new views or version control system adapters can be added easily, but the extension API tends to change with every release (before 1.0). This documentation applies to version 0.5.

Encode is licensed under the LGPL which means that there are no restrictions on the licensing terms of third-party extensions.

Implementation

Extensions are implemented using Python and PyGTK. An extension consists of Python modules and arbitrary data files. An appropriately named package/subdirectory should be used for the modules and data.

Modules

Extension modules may implement this initialization function:

init_extension(datadir): datadir is an absolute path for accessing the extension's data files. It is either Encode's system-wide data directory or the directory where the extension module was loaded from (if it was loaded from a custom location). This function is called by the extension system before any extension classes are instantiated.

Classes

Extensions classes inherit from gobject.GObject through a tag class which identifies the extension interface. Extension tag class names are suffixed with "Extension" by convention.

Interfaces

These extension tag classes are defined by Encode:

encode.environment.ViewExtension

Views can be attached to the environment window. They are created and attached at startup, manually by the user or as response to events. A view exists until it is detached from the environment or when it decides to destroy itself.

The GUI can be built directly using the GTK API or by loading XML interface descriptions using the Glade API. The interface descriptions can be created with Glade and Gazpacho. Note that the GUI designers create widget hierarchies rooted at a gtk.Window. You can design your view widgets inside a window and then either remove it by editing the XML file or remove your view widget from the window after loading the XML file. Also, doing small changes to the interface description is usually faster using a text editor than a GUI designer.

It is recommended to use encode.view.AbstractView or encode.view.AbstractEmbedder to implement views. encode.terminal.View is a simple example implementation.

encode.environment.HandlerExtension

Handlers are used for opening files for viewing or editing. Typically used in conjunction with a view.

poppler.poppler.Handler is a simple example implementation. encode.emacs.Handler uses an alternative approach.

encode.environment.DifferExtension

Displays differences between two text files. Typically used in conjunction with a view.

Encode doesn't currently provide any differ implementations.

encode.environment.OutputExtension

Displays output from command execution. Typically used in conjunction with a view.

encode.output.Output is an example implementation.

encode.project.OptionsExtension

Implements build, clean and run operations for a project directory.

The extension class should have a rules member which lists relative configuration file paths. The "$(DIRNAME)" string may be used to refer to the project directory name.

encode.options.GuessOptions is a simple example implementation.

encode.project.ControllerExtension

Controllers implement file and directory manipulation operations. Their purpose is to integrate the project tree with version control systems. A controller object is created and associated with a project directory when one is opened (its contents are shown). The object receives the "destroy" signal when the project directory is closed (its contents are hidden) and the object is discarded.

encode.darcs.Controller is a simple example implementation.

encode.settings.SettingsExtension

Settings provides a page for the preferences window. Settings objects should emit the "modified" signal when their values are changed by the user.

encode.output.Settings is a simple example implementation.

Deployment

While developing an extension, you can enable it by editing the /apps/encode/extensions GConf variable.

The easiest way to install extensions is to use Encode's installation directory. The binary packages install Python modules and data files under /usr/share/encode. Encode itself uses only the encode package/subdirectory.