Preferences with Envisage

Envisage presents preferences with two different extension points:

  • PREFERENCES = ‘envisage.preferences’

  • PREFERENCES_PAGES = ‘envisage.ui.workbench.preferences_pages’

The first one is only model-related and is for programmatic access to preferences, whereas the second one is for displaying UIs to the user in the workbench plugin.

Preferences

The contribution point is simply a list of URLs to the preference file, e.g.:

preferences_pages = List(
      ['pkgfile://acme.acmelab/preferences.ini'],
      contributes_to=PREFERENCES_PAGES)

where acme.acmelab is the python-module-like path to the package in which the default preferences.ini is stored.

A plugin usually needs only one preferences file, regardless of how many preference pages or settings it has.

Preferences pages

The preference pages are a Traits UI view to wrap the preferences and allow the user to modify them. A preference page is defined as in the preference_manager example in the AppTools examples. It can than be contributed to the workbench, as in:

preferences_pages = List(contributes_to=PREFERENCES_PAGES)

def _preferences_pages_default(self):
        """ Trait initializer. """
        from acme.preference_pages \
                        import ACMEPreferencePages
        return [ACMEPreferencePages, ]

A plugin needs to contribute a preferences pages class for each category of preferences it contributes.