Last revised 17:00 EST December 15, 2003
The primary goal of the Eclipse Platform has been providing an open IDE for integrating a wide range of development tools. This is the design center, and the current area of expertise of the Eclipse development team.
The objective of the Eclipse Rich Client Platform (RCP) effort is to enable Eclipse to be used in a wide range of end-user applications that are not IDEs. However, just because we want Eclipse to be useful for more than just IDEs, that doesn't mean we want to shift our focus away from building IDEs nor do we want to undermine the success of the Eclipse Platform. IDEs are our bread and butter. The primary goal of the Eclipse Platform is still IDEs. Enabling Eclipse to be used for non-IDE applications is a secondary goal.
As there are many plug-ins that target the existing Eclipse Platform, the implications of breaking APIs are serious. As you will see in the following sections, the proposed approach is a compromise between preserving 100% compatibility with existing plug-ins and breaking APIs to make it more convenient to develop new applications.
The proposed approach is to factor out the generally useful portions of the existing Eclipse workbench into a generic Eclipse workbench. The generic workbench is still based on views, editors, and perspectives; however, it does not have any of the IDE-specific mechanisms, APIs, or extension points. The generic workbench is configurable so that key UI policy decisions, like whether the workbench window has a tool bar; these are provided by new APIs available to the designer of the application. The Eclipse IDE workbench is built atop the generic Eclipse workbench and uses these new APIs to impose particular policies that give it its distinctive IDE "personality". The generic workbench is located in a plug-in separate from the IDE workbench to allow applications to be built on top of the generic workbench alone, and not require any of the IDE-specific Eclipse plug-ins.
The Eclipse UI is organized around the Eclipse workbench, which is based on views, editors, perspectives. From the point of view of someone wishing to build a (non-IDE) application based on Eclipse and its workbench, the current Eclipse UI has a number of problems. You only have to look at the workbench window for a bare-bones Eclipse Platform install (i.e., with no JDT, PDE, or other plug-ins) to appreciate why.
First of all, the Eclipse workbench window contains several things that are idiosyncratic to IDEs, including: a resource perspective, a resource navigator view, and "Navigate", "Project", and "Run" menus. None of these are likely to make sense in the UI of a non-IDE application.
Second, we see that the Eclipse workbench window enshrines a set of visual design choices about how a UI is organized. For example, workbench window always has a menu bar, a tool bar, a shortcut bar, and a status line; certain colors and gradients are used consistently in banners to give things an integrated and distinctive appearance; views always have titles with certain actions in their title bar; the workbench always has "File", "Edit", "Window", and "Help" items; and a chunk of each perspective is set aside as an editor area (of which there is exactly one). Each of these choices might need to be made differently in a non-IDE application.
And there are numerous other UI-related aspects not visible in the screenshot that are an important part of the UI, including user configurability and customizability. For example, the workbench allows the user to rearrange the perspective by dragging and dropping views, and to maximize a view by double-clicking on its title bar. A non-IDE application might want to decide whether and how the user can affect the layout.
That said, the inherent extensibility of platforms based on Eclipse as well as generic UI concepts such as preferences, action sets, perspectives, views, and editors may be useful for building generic applications.
The "generic workbench" is the core of the Eclipse Platform UI stripped of its former IDE-specific personality, predilections, and biases. The high-level picture of the Eclipse workbench is painted in the Eclipse Technical Overview. With minor modifications, it can paint a good high-level picture of what we're calling the generic workbench (new or modified passages are underlined):
Unlike SWT and JFace, which are both general purpose UI toolkits, the workbench provides overall UI organization and supplies the structures in which an application interacts with the user. The workbench API is dependent on the SWT API, and to a lesser extent on the JFace API. The workbench implementation is built using both SWT and JFace; Java AWT and Swing are not used.
The Eclipse Platform UI paradigm is based on editors, views, and perspectives. From the user's standpoint, a workbench window consists visually of views and editors. Perspectives manifest themselves in the selection and arrangements of editors and views visible on the screen.
Editors allow the user to open, edit, and save objects. They follow an open-save-close lifecycle much like file system based tools, but are more tightly integrated into the workbench. When active, an editor can contribute actions to the workbench menus and tool bar. The generic workbench has no built-in editors. There is a separate plug-in containing the standard text editor and text editor framework. This plug-in is an optional component that can be used with the generic workbench in applications.
Views provide information about some object that the user is working with in the workbench. A view may assist an editor by providing information about the document being edited. For example, the standard content outline view shows a structured outline for the content of the active editor if one is available. A view may augment other views by providing information about the currently selected object. For example, the standard properties view presents the properties of the object selected in another view. Views have a simpler lifecycle than editors: modifications made in a view (such as changing a property value) are generally saved immediately, and the changes are reflected immediately in other related parts of the UI. The generic workbench has no built-in views. There is a separate plug-in containing the properties view and the content outline view. This plug-in is an optional component that can be used with the generic workbench in applications.
A workbench window can have several separate perspectives, only one of which is visible at any given moment. Each perspective has its own views and editors that are arranged (tiled, stacked, or detached) for presentation on the screen (some may be hidden at any given moment). Several different types of views and editors can be open at the same time within a perspective. A perspective controls initial view visibility, layout, and action visibility. The user can quickly switch perspective to work on a different task, and can easily rearrange and customize a perspective to better suit a particular task. The generic workbench has no built-in perspectives. The application must supply at least a default perspective.
Tools integrate into this editors-views-perspectives UI paradigm in well-defined ways. The main extension points allow tools to augment the workbench:
Add new types of editors.
Add new types of views.
- Add new perspectives, which arrange old and new views to suit new user tasks.
The properties view, the content outline view, the standard text editor, and the default perspective are all contributed using these mechanisms.
Tools may also augment existing editors, views, and perspectives:
Add new actions to an existing view's local menu and tool bar.
Add new actions to the workbench menu and tool bar when an existing editor becomes active.
Add new actions to the pop-up content menu of an existing view or editor.
Add new views, action sets, and shortcuts to an existing perspective.
The Platform takes care of all aspects of workbench window and perspective management. Editors and views are automatically instantiated as needed, and disposed of when no longer needed. The display labels and icons for actions contributed by a tool are listed in the plug-in manifest so that the workbench can create menus and tool bars without activating the contributing plug-ins. The workbench does not activate the plug-in until the user attempts to use functionality that the plug-in provides.
Once an editor or view becomes an active part of a perspective it can use workbench services for tracking activation and selection. The part service tracks view and editor activation within the perspective, reporting activation and deactivation events to registered listeners. A view or editor can also register with the selection service as a source for selections. The selection service feeds selection change events to all parties that have registered interest. This is how, for example, the standard properties view is notified of the domain object selected in the currently active editor or view.
We now describe the proposed design of the generic workbench.
In order to understand the various design alternatives, it is important to understand their impact on the resulting footprint of the generic workbench, and on the dependencies between the resulting plug-ins.
How do we go about finding the minimal set of plug-ins that will be needed in all RCP configurations? The following table lists the plug-ins in the Eclipse Platform (2.1.1 Platform drop for Win32) and their sizes on disk:
|
Plug-in id |
Disk size (MB) |
| org.apache.ant | 1.34 |
| org.apache.lucene | 0.17 |
| org.apache.xerces | 1.20 |
| org.eclipse.ant.core | 0.06 |
| org.eclipse.compare | 0.41 |
| org.eclipse.core.boot | 0.25 |
| org.eclipse.core.resources (including org.eclipse.core.resources.win32) | 0.61 |
| org.eclipse.core.runtime | 0.22 |
| org.eclipse.debug.core | 0.12 |
| org.eclipse.debug.ui | 0.56 |
| org.eclipse.help | 0.26 |
| org.eclipse.help.appserver | 0.02 |
| org.eclipse.help.ui (including org.eclipse.help.ui.win32) | 0.13 |
| org.eclipse.help.webapp | 0.37 |
| org.eclipse.jface | 0.43 |
| org.eclipse.jface.text | 0.34 |
| org.eclipse.platform (including org.eclipse.platform.win32) | 0.51 |
| org.eclipse.platform.doc.user | 3.20 |
| org.eclipse.search | 0.20 |
| org.eclipse.swt (including org.eclipse.swt.win32) | 1.23 |
| org.eclipse.team.core | 0.10 |
| org.eclipse.team.ui | 0.30 |
| org.eclipse.team.cvs.core | 0.42 |
| org.eclipse.team.cvs.ssh | 0.05 |
| org.eclipse.team.cvs.ui | 0.88 |
| org.eclipse.text | 0.07 |
| org.eclipse.tomcat | 1.39 |
| org.eclipse.ui (including org.eclipse.ui.win32) | 0.21 |
| org.eclipse.ui.editors | 0.10 |
| org.eclipse.ui.externaltools | 0.86 |
| org.eclipse.ui.versioncheck | 0.01 |
| org.eclipse.ui.views | 0.32 |
| org.eclipse.ui.workbench | 2.08 |
| org.eclipse.ui.workbench.texteditor | 0.23 |
| org.eclipse.update.core (including org.eclipse.update.core.win32) | 0.39 |
| org.eclipse.update.ui (including org.eclipse.update.ui.win32) | 0.76 |
| org.eclipse.update.ui.forms | 0.15 |
| Total | 19.80 |
It would be relatively straightforward to omit the following Eclipse Platform plug-ins from the minimal RCP configuration:
The rest of the Eclipse Platform plug-ins would need to be included in the minimal RCP configuration:
To maintain binary compatibility, we would add the new application workbench APIs into the existing UI plug-in (org.eclipse.ui and its buddy org.eclipse.ui.workbench have most of the code). We would create a new plug-in for the IDE (org.eclipse.ui.ide). This new plug-in would contain the implementation of the IDE application, although much of the IDE would still be implemented by code within the existing org.eclipse.ui.workbench plug-in, since that it where it is now. The new plug-in would make IDE-specific contributions to the workbench extension points. The new plug-in would not be included in the minimal RCP configuration, ensuring that the generic workbench does not include IDE-specific perspectives, views, actions, etc.
This approach would provide binary compatibility of 3.0 plug-ins over 2.1, while allowing us to introduce new mechanisms so that non-IDE applications could be built on the RCP base. This approach, however, has three shortcomings:
As the Eclipse workbench grows in future releases with new APIs and extension points, it is likely that the API clutter and disk bloat will also increase because it will not always be possible to avoid putting new IDE-specific pieces into plug-ins in the RCP base. So both of these problems will tend to get worse as Eclipse evolves.
These shortcomings are significant enough to warrant considering breaking API binary compatibility in order to address them.
Severing ties to resources (and the IDE-specific dialogs, etc.) would reduce the minimum RCP configuration by about 0.8 MB. Severing the ties to text editors would reduce it by 0.74 MB; to the standard views, by another 0.32 MB. All this would reduce the minimal RCP configuration from 8.04 MB to about 6.1 MB. Of that 6.1 MB, 2.06 MB is the runtime, 0.26 MB is help, and the rest (3.75 MB) is the workbench UI. There are no straightforward ways to reduce the size of the workbench UI further, so 6.1 MB can be considered a lower bound on the size of the minimum RCP configuration (obviously, this bound changes if the size of the Platform runtime changes, which is likely due to 3.0 efforts on other fronts).
Severing ties to text editors is quite simple (most of the hard work was already done in 2.1). The only breaking API changes required to achieve this are:
Porting in light of this kind of breakage is straightforward: it involves changing existing plug-in manifest files; plug-in code does not need to be changed or recompiled.
Severing ties to resource- and IDE-specific things is only a bit more work. The breaking API changes required to achieve this are:
The first 3 kinds of changes are similar to the above: porting involves changing existing plug-in manifest files. The last kind of breakage involves changing code. By design, the Eclipse workbench APIs are generic and independent of particular editors and views, and the underlying data model is largely independent of the workspace. Unfortunately, a small number of unwanted dependencies crept in late in the 1.0 release. There are a handful of API methods that would need to be removed in order to make the workbench API completely generic and free from IDE-specific influences:
This modest amount of breakage is all that would be required to both eliminate the API clutter of IDE-specific elements and reduce the disk footprint of the RCP configuration to the practical minimum. Somewhat perversely, the damage from these changes only befalls existing customers of the Eclipse IDE (there are no Eclipse RCP customers to break yet). To existing IDE customers, the RCP is orthogonal to their direct interests. So they should not be expected to be particularly sympathetic to changes which can be seen as netting them nothing. The benefits of the breakage accrue to the RCP customers; the pain, to existing IDE customers.
It comes down to this question: in the big Eclipse picture, would the long terms gains of making these breaking changes outweigh the short term pain to existing clients?
We think so. We believe that these breaking changes will lead to a significantly cleaner and smaller Eclipse RCP, which will provide the best possible starting point for growing a future base of applications based on the Eclipse RCP, including the Eclipse IDE. We therefore advocate this second approach, rather than the first one which would preserve binary compatibility but would result in a less than ideal starting point for the Eclipse RCP.
For the sake of completeness, here are the alternative approaches to minimizing breakage that we considered but rejected.
We considered splitting API interfaces into a generic interface with a resource-specific subinterface. For example, we considered introducing the interface IGenericWorkbenchPage and changing IWorkbenchPage to be a subclass of it; most of the existing methods would remain on IGenericWorkbenchPage, and IWorkbenchPage would have only the resource-specific openEditor methods. We quickly concluded that this would not be very tasty because of page listeners with methods like IPageListener.pageActivated(IWorkbenchPage) which would now need to accept IGenericWorkbenchPage; adding such a method to the IPageListener interface would break binary compatibility because clients implement this interface. This would force us to instead create of a new interface, IGenericPageListener, and a new set of methods on IGenericWorkbenchPage for adding and removing these listeners. This ripple effect would duplicate a lot of the existing workbench API interfaces and methods, making the API more bloated for everyone. So we abandoned this approach.
We considered leaving the org.eclipse.core.resources plug-in as a part of the minimal configuration, and allowing the generic workbench to pre-req it. We could do this and still rid the workbench implementation of the assumption that the workspace is the underlying data model. This would eliminate the API breakage due to removing the resources plug-in as a pre-req of org.eclipse.ui. However, this arrangement means that there is still the risk that resource dependencies will creep back in (as they did in the past), and that the code for the org.eclipse.core.resources plug-in (0.61 MB) is still in the base configuration. The footprint matter could be addressed by providing a dummy org.eclipse.core.resources plug-in to be used in configurations where resources are not needed. The code JAR for this plug-in would contain dummy declarations for the minimal set of API interfaces and classes needed to satisfy the class loader when loading API from the org.eclipse.ui plug-in. While this approach would have a minimal footprint, it was rejected because of the general complications and myriad possibilities for confusion surrounding this dummy plug-in (which would need to share the plug-in id and version id with the real plug-in but have different contents), and still runs the risk that resource dependencies will creep back.
What does this really mean for existing plug-ins?
For existing plug-ins you will be affected by three types of API breakage:
The only changes that you to make in order to handle the first two cases is to update your plug-in manifest files. The section that identifies the required plug-ins may need to be changed and you may also need to change the ids of the extension points that you contribute to. In many cases this will be all that is required. 3.0 core runtime will have a 2.1 plug-in compatibility mode which automatically detects 2.1 plug-ins and compensates for (1) and (2) as it builds the plug-in registry from the plug-in manifest. (And PDE has a similar command (PDE Tools > Migrate to 3.0) for converting the manifest of a 2.1 plug-in in the workspace.)
Wherever possible, we've chosen to deprecate API. The deprecated API will continue to work in 3.0. However, there are a small number of cases where we did not deprecate. In these cases you are broken and you will need to call new API. The good news is that the transformation is straight forward and we are looking at providing additional porting tools to make it even easier.
In the Eclipse world, the "main program" for an application is an IPlatformRunnable contributed to the org.eclipse.core.runtime.application extension point. The IPlatformRunnable's run(Object args) method gets control once the Eclipse Platform Runtime has brought itself into existence. The plug-in that contributes this class is the first real plug-in to be activated. The application is responsible for opening the workbench using PlatformUI.createAndRunWorkbench. (PlatformUI is in the org.eclipse.ui API package in the org.eclipse.ui plug-in.) This method creates the workbench, opens the initial workbench window, and then processes UI events until the user calls it quits. The application is also responsible for creating an SWT display, using PlatformUI.createDisplay, and passing it to PlatformUI.createAndRunWorkbench.
public class MyApplication implements IPlatformRunnable {
public Object run(Object args) {
WorkbenchAdvisor workbenchAdvisor = new MyWorkbenchAdvisor();
Display display = PlatformUI.createDisplay();
int returnCode = PlatformUI.createAndRunWorkbench(display,
workbenchAdvisor);
if (returnCode == PlatformUI.RETURN_RESTART) {
return IPlatformRunnable.EXIT_RESTART;
} else {
return IPlatformRunnable.EXIT_OK;
}
}
}
The application is responsible for more that just bringing up the workbench. The application is also responsible for configuring the workbench and its windows. Without some configuration, the workbench window is useless because its menu bar and tool bar are completely empty. The application must supply a workbench advisor object when it creates the workbench. The various methods on the workbench advisor are called at well-defined points in the life cycle of the workbench, and it is by implementing these methods that the application has the opportunity to configure the workbench. (It's called a workbench "advisor" because this object influences how the workbench works. The application does not "implement" the workbench; the implementation of the workbench is still internal, meaning most of the mechanism is still hidden.) The API for workspace advisor and other things that an application needs to configure the workbench are located in the org.eclipse.ui.application package (in the org.eclipse.ui plug-in). The API in this package is not of interest (or use) to other plug-ins.
The application is involved in key global decisions:
Opening a workbench window (IWorkbench.openWorkbenchWindow) requires there to be a perspective. You either specify one explicitly, or allow the workbench to use the default one. This means that an application must contribute at least one perspective via the org.eclipse.ui.perspectives extension point, and must name one of them as the workbench's default perspective. The default perspective is controlled by a workbench preference. The application must establish a meaningful value for this preference before opening the first window (the preference does not have a useful default value).
A workbench window's menu bar consists of a row of individual menus. The application is responsible for defining the foundation items in the menu bar of a workbench window, and the foundation items and groups within each menu. Initially, the menu bar of a newly created workbench window is completely empty. Once the application has established the foundation, the workbench's action set mechanism allows additional menus and menu items to be added (but not removed or replaced). Action set contributions are handled automatically by the generic workbench, without further assistance from the application's workbench advisor. Action set contributions reference menu locations using a path composed from menu item ids. A typical application would provide as API the ids and paths of the places where plug-ins are allowed to make action contributions, and omit (or keep secret) ids for menu items that it does not want plug-ins contributing to. The application is also free to add or remove foundation items at any time.
Here is an example of how an application uses its workbench advisor to configure the menu bar of a new workbench window. This should be done in the WorkbenchAdvisor.fillActionBars method. Building the individual menus and sub-menus is done using standard JFace API (in the org.eclipse.jface.action package). The top-level menus are then added to the workbench window's menu bar, which the workbench advisor can obtain via IActionBarConfigurer.getMenuManager. Here's a simple example of what this code looks like (momentarily ignoring the vexing issue of proxy configurers):
public void fillActionBars(IWorkbenchWindow window,
IActionBarConfigurer configurer, int flags) {
if ((flags & WorkbenchAdvisor.FILL_MENU_BAR) != 0
&& (flags &
WorkbenchAdvisor.FILL_PROXY) == 0) {
IMenuManager mm = configurer.getMenuManager();
// build a File menu with 1 empty group and
3 commands
IMenuManager fileMenu = new MenuManager("&File",
"file");
fileMenu.add(new
GroupMarker("file.start"));
fileMenu.add(new MyAction("hello"));
IAction quit =
ActionFactory.QUIT.create(window);
configurer.registerGlobalAction(quit);
fileMenu.add(quit);
// add File menu to workbench window menu
bar
mm.add(fileMenu);
}
...
}
Workbench retarget actions (like CUT, COPY, PASTE) must be registered as global actions in order to work properly. Also, actions must be registered as global actions in order to work properly with key bindings.
While the above simple code works for this, it has a serious flaw for applications that make use of the Customize Perspective action (not used here). The Customize Perspective action creates a proxy action configurer and passes it to fillActionBars method with the FILL_PROXY flag set. The body of fillActionBars uses ActionFactory to create new action instances. The issue is that each of these actions may registers listeners with the window, and these listeners will not go away until the window is closed. This means the performance of the workbench will degrade to the extent that the user uses Customize Perspective to change a window. Applications that make use of the Customize Perspective action can avoid this problem by using the same action objects in the proxies as in the real action bars (requires remembering and reusing the action instances on a per window basis).
Note: The workbench story for action contributions to menus and tool bars is likely to change for 3.0. When it does, this story will be revised to bring it into line.
The workbench is responsible for the standard window operations, including resizing, maximizing and minimizing, and closing. The workbench immediately tells the window to close (IWorkbenchWindow.close) when the window's close button is pushed.
The story is basically the same as for the menu bar; the only real differences are in the mechanics.
The application is responsible for defining the foundation items in the tool bar of a workbench window, and the foundation items and groups within each tool bar. Initially, the tool bar of a newly created workbench window is completely empty. Once the application has established the foundation, the workbench's action set mechanism allows addition tool bars and tool bar items to be added (but not removed or replaced). Action set contributions are handled automatically by the generic workbench, without further assistance from the application's workbench advisor. Action set contributions reference tool bar locations using a path composed from tool item ids. A typical application would provide as API the ids and paths of the places where plug-ins are allowed to make action contributions, and omit (or keep secret) ids for tool items that it does not want plug-ins contributing to. The application is also free to add or remove foundation items at any time.
Here is an example of how an application uses its workbench advisor to
configure the tool bar of a new workbench window. This should be done in the WorkbenchAdvisor.fillActionBars
method. Building the individual tool bars is done using standard JFace API (in
the org.eclipse.jface.action package). A workbench window's tool
bar is actually a JFace cool bar. A cool bar contains cool items which in turn
contain tool bars. Individual cool items can be added to the workbench through
the workbench advisor via IActionBarConfigurer.getCoolBarManager.
Here's a simple example of what this code looks like:
public void fillActionBars(IWorkbenchWindow window,
IActionBarConfigurer configurer, int flags) {
...
if ((flags & WorkbenchAdvisor.FILL_TOOL_BAR) != 0
&& (flags &
WorkbenchAdvisor.FILL_PROXY) == 0) {
ICoolBarManager coolBarManager =
configurer.getCoolBarManager();
IToolbarManager mainTool = new
ToolBarManager();
mainTool.add(new MyAction("hello"));
IAction quit =
ActionFactory.QUIT.create(configurer.getWindow());
configurer.registerGlobalAction(quit);
mainTool.add(quit);
ToolBarContributionItem tbItem = new
ToolBarContributionItem(mainTool,"main");
coolBarManager.add(tbItem);
}
}
The cool bar manager, like all other contribution managers, can contain any
type of contribution item. In most cases, it makes sense that the contribution
items of a cool bar manager be tool bar managers. Since contribution managers
only accept contribution items, each tool bar manager is wrapped in a ToolBarContributionItem.
Every tool bar contribution item corresponds to a cool item (the movable widget
in a cool bar) on the cool bar. To add a new action to the cool item, a standard
JFace tool bar manager must be created. After populating the tool bar manager
with actions, a tool bar contribution item is created from the tool bar manager
and subsequently added to the cool bar manager.
Workbench retarget actions (like CUT, COPY, PASTE) must be registered as global actions in order to work property. Also, actions must be registered as global actions in order to work property with key bindings.
While the above simple code works for this, it has a serious flaw for applications that make use of the Customize Perspective action (not used here). The Customize Perspective action creates a proxy action configurer and passes it to fillActionBars method with the FILL_PROXY flag set. The body of fillActionBars uses ActionFactory to create new action instances. The issue is that each of these actions may registers listeners with the window, and these listeners will not go away until the window is closed. This means the performance of the workbench will degrade to the extent that the user uses Customize Perspective to change a window. Applications that make use of the Customize Perspective action can avoid this problem by using the same action objects in the proxies as in the real action bars (requires remembering and reusing the action instances on a per window basis).
Note: The workbench story for action contributions to menus and tool bars is likely to change for 3.0. When it does, this story will be revised to bring it into line.
IWorkbench.getSharedImages() provides regular plug-ins access to a pool of images and image descriptors maintained by the workbench. The generic workbench has some built-in ones (their names are given by constants in the ISharedImages interface). The application can add to the set of workbench images by IWorkbenchConfigurer.declareImage. The application is responsible for documenting any additional images it makes available through this mechanism if it expect their names to be known to other plug-ins.
public void initialize(IWorkbenchConfigurer configurer)
{
...
// declare public "shared" image
ImageDescriptor yoyoLogo = new URLImageDescriptor(new
java.net.URL("..."));
configurer.declareImage("yoyodyne", yoyoLogo,
true);
// declare public "non-shared" image
ImageDescriptor yoyoWizardBanner = new URLImageDescriptor(new
java.net.URL("..."));
configurer.declareImage("com.yoyodyne.internal.wizardBanner",
yoyoWizardBanner, false);
...
}
The generic workbench contains the extension point and API for plug-ins to contribute arbitrary editors. The generic workbench does not include any particular editors.
For applications that do not need editors, the overhead of the mechanism built in to the generic workbench is minimal. Even though all workbench pages have a special editor area, the editor area does not need to be visible. The visible views will make use of the screen real estate, so there is no waste when editors are not used in an application.
The generic workbench has no built-in support for text editors. However, the text editor framework is available as a separate optional component (the org.eclipse.ui.workbench.texteditor plug-in, along with the two plug-ins it depends on: org.eclipse.text and org.eclipse.jface.text).
The generic workbench has no built-in support for OLE-based editors. The support for embedding any OLE document as an editor (Windows only) is available as a separate optional component (the org.eclipse.ui.win32 plug-in fragment).
The generic workbench contains the extension points for plug-in to contribute help content, including help books and context (F1) help. It includes the API interfaces used by the generic workbench (and other plug-ins) to request that help content be displayed. What the generic workbench is missing, however, is any way of actually displaying the help content (i.e., it has no help UI).
For applications that do not need a help system, the overhead of the mechanism built in to the generic workbench is minimal (under 100KB code size).
Applications that want to make use of the Eclipse help system will need a UI for presenting the info to the user. Here there are two options:
The generic workbench has no built-in support for downloading and installing new or updated features and plug-ins.
Applications that want to make use of the existing Eclipse update component have two options:
The generic workbench does not support workspaces and resources. These are only available in the Eclipse IDE. An application that would make use of the workspace and resources should probably be viewed instead as a tool (or set of tools) that plug in to an Eclipse IDE.
As of I20031202, the minimal set of plug-ins needed to run the generic workbench is:
The application will have to provide at least one plug-in of its own to contribute to the org.eclipse.core.runtime.application extension point.
Text editors (optional) requires all of the following plug-ins in addition to those required for the generic workbench:
Support for OLE-based editor (optional) requires the following plug-in fragment in addition to those required for the generic workbench:
The content outline and properties views (optional) are in the following plug-in:
Help system (optional) requires all of the following plug-ins in addition to those required for the generic workbench:
Update manager (optional) requires all of the following plug-ins in addition to those required for the generic workbench:
[TBD] The application should probably define a primary feature and primary feature plug-in because certain key pieces of information used to configure the Eclipse runtime come from the feature. The file eclipse/install.ini contains the ids of the default feature and default application. Use org.eclipse.platform as a guide for defining a primary feature and its plug-in.
[TBD] The generic workbench defines the org.eclipse.ui.preferencePages extension point for preference pages, and the IWorkbenchPreferencePage API interface. What are the options for an application to show preferences to the user?
Each workbench window has an editor area (although it need not be visible). When the editor area is visible, it can be used as a target for drag and drop operations. For example, this is used by the IDE to open an editor on a file dropped on the editor area. The editor area may be blank; it need not have an editor in it. Internally, this means that the drop target listener is associated with the control for the editor area itself --- something which no editor can do. By default, workbench windows do not support drag and drop for the editor area. However, an application can configure a window's editor area via two IWorkbenchWindowConfigurer methods. There are two parts: defining the transfer types that will be allowed, and providing the drop target listener that will get to handle these types. Here's a simple example of what this code looks like:
public void preWindowOpen(IWorkbenchWindowConfigurer
configurer) {
...
// for dropping a standard IEditorInput
configurer.addEditorAreaTransfer(EditorInputTransfer.getInstance());
// for dropping application-specific transfer types A and B
configurer.addEditorAreaTransfer(MyATransfer.getInstance());
configurer.addEditorAreaTransfer(MyBTransfer.getInstance());
// listener for handling drops of type IEditorInput, MyA, and
MyB
configurer.configureEditorAreaDropListener(new
MyDropTargetAdapter(configurer.getWindow());
...
}
The editor area for each window can be individually configured and reconfigured at any time.