Source code for envisage.ui.workbench.workbench_plugin
# (C) Copyright 2007-2023 Enthought, Inc., Austin, TX
# All rights reserved.
#
# This software is provided without warranty under the terms of the BSD
# license included in LICENSE.txt and may be redistributed only under
# the conditions described in the aforementioned license. The license
# is also available online at http://www.enthought.com/licenses/BSD.txt
#
# Thanks for using Enthought open source!
""" The Envisage workbench plugin. """
from traits.api import Callable, List
# Enthought library imports.
from envisage.api import ExtensionPoint, Plugin, ServiceOffer
# This module's package.
PKG = ".".join(__name__.split(".")[:-1])
[docs]class WorkbenchPlugin(Plugin):
"""The Envisage workbench plugin.
The workbench plugin uses the Pyface workbench to provide the basis of an
IDE-like user interface. The interface is made up of perspectives, views
and editors.
Note that this is not intended to be a 'general-purpose' plugin for user
interfaces - it provides an IDE-like style and that is all. If your
application requires another style of interface then write another plugin
(you can still re-use all the menu, group and action contribution stuff!).
"""
# The Ids of the extension points that this plugin offers.
ACTION_SETS = PKG + ".action_sets"
PERSPECTIVES = PKG + ".perspectives"
PREFERENCES_PAGES = PKG + ".preferences_pages"
WORKBENCH_SERVICE_OFFERS = PKG + ".service_offers"
VIEWS = PKG + ".views"
# The Ids of the extension points that this plugin contributes to.
PREFERENCES = "envisage.preferences"
SERVICE_OFFERS = "envisage.service_offers"
#### 'IPlugin' interface ##################################################
# The plugin's unique identifier.
id = "envisage.ui.workbench"
# The plugin's name (suitable for displaying to the user).
name = "Workbench"
#### Extension points offered by this plugin ##############################
action_sets = ExtensionPoint(
List(Callable),
id=ACTION_SETS,
desc="""
An action set contains the toobars, menus, groups and actions that you
would like to add to top-level workbench windows (i.e. the main
application window). You can create new toolbars, menus and groups
and/or add to existing ones.
Each contribution to this extension point must be a factory that
creates an action set, where 'factory' means any callable with the
following signature::
callable(**traits) -> IActionSet
The easiest way to contribute such a factory is to create a class
that derives from 'envisage.ui.action.api.ActionSet'.
""",
)
perspectives = ExtensionPoint(
List(Callable),
id=PERSPECTIVES,
desc="""
A perspective is simply an arrangment of views around the (optionally
hidden) editor area.
Each contribution to this extension point must be a factory that
creates a perspective, where 'factory' means any callable with the
following signature::
callable(**traits) -> IPerspective
The easiest way to contribute such a factory is to create a class
that derives from 'pyface.workbench.api.IPerspective'.
""",
)
preferences_pages = ExtensionPoint(
List(Callable),
id=PREFERENCES_PAGES,
desc="""
A preferences page appears in the preferences dialog to allow the user
to manipulate some preference values.
Each contribution to this extension point must be a factory that
creates a preferences page, where 'factory' means any callable with the
following signature::
callable(**traits) -> IPreferencesPage
The easiest way to contribute such a factory is to create a class
that derives from 'apptools.preferences.ui.api.IPreferencesPage'.
""",
)
service_offers = ExtensionPoint(
List(ServiceOffer),
id=WORKBENCH_SERVICE_OFFERS,
desc="""
Services are simply objects that a plugin wants to make available to
other plugins. This extension point allows you to offer 'per
window' services that are created 'on-demand' (where 'on demand' means
the first time somebody looks up a service of the appropriate
protocol).
.
e.g.
my_service_offer = ServiceOffer(
protocol = 'acme.IMyService',
factory = an_object_or_a_callable_that_creates_one,
properties = {'a dictionary' : 'that is passed to the factory'}
)
Any properties specified are passed as keywrod arguments to the
factory, i.e. the factory signature is::
callable(**properties)
""",
)
views = ExtensionPoint(
List(Callable),
id=VIEWS,
desc="""
A view provides information to the user to support their current
task. Views can contain anything you like(!) and are arranged around
the (optionally hidden) editor area. The user can re-arrange views as
he/she sees fit.
Each contribution to this extension point must be a factory that
creates a view, where 'factory' means any callable with the following
signature::
callable(**traits) -> IView
The easiest way to contribute such a factory is to create a class
that derives from 'pyface.workbench.api.View'.
It is also common to use a simple function (especially when a view
is a representation of a service) e.g::
def foo_view_factory(**traits):
' Create a view that is a representation of a service. '
foo = self.application.get_service('IFoo')
return FooView(foo=foo, **traits)
""",
)
#### Contributions to extension points made by this plugin ################
my_action_sets = List(contributes_to=ACTION_SETS)
def _my_action_sets_default(self):
"""Trait initializer."""
from .default_action_set import DefaultActionSet
return [DefaultActionSet]
my_preferences = List(contributes_to=PREFERENCES)
def _my_preferences_default(self):
"""Trait initializer."""
return ["pkgfile://envisage.ui.workbench/preferences.ini"]
my_preferences_pages = List(contributes_to=PREFERENCES_PAGES)
def _my_preferences_pages_default(self):
"""Trait initializer."""
from .workbench_preferences_page import WorkbenchPreferencesPage
return [WorkbenchPreferencesPage]
my_service_offers = List(contributes_to=SERVICE_OFFERS)
def _my_service_offers_default(self):
"""Trait initializer."""
preferences_manager_service_offer = ServiceOffer(
protocol="apptools.preferences.ui.preferences_manager"
".PreferencesManager",
factory=self._create_preferences_manager_service,
)
workbench_service_offer = ServiceOffer(
protocol="envisage.ui.workbench.workbench.Workbench",
factory=self._create_workbench_service,
)
return [preferences_manager_service_offer, workbench_service_offer]
###########################################################################
# Private interface.
###########################################################################
def _create_preferences_manager_service(self, **properties):
"""Factory method for the preferences manager service."""
from apptools.preferences.ui.api import PreferencesManager
preferences_manager = PreferencesManager(
pages=[factory() for factory in self.preferences_pages]
)
return preferences_manager
def _create_workbench_service(self, **properties):
"""Factory method for the workbench service."""
# We don't actually create the workbench here, we just return a
# reference to it.
#
# fixme: This guard is really just for testing when we have the
# workbench plugin as a source egg (i.e. if the egg is on our path
# then we get the plugin for any egg-based application, even if it is
# not a workbench application!).
return getattr(self.application, "workbench", None)
