Editors - Example

In Chapter 19, Editors, you learned how to create a new editor in order to extend the capabilities of Eclipse. The example presents a simple but functionally complete editor, a "mini-spreadsheet." It demonstrates how you can implement an editor that supports basic functionality, contributes actions, works with the standard Outline view, and allows others to extend its capabilities. (Note that this topic assumes you have read Chapter 18, Views, and are familiar with its examples.)

Running the Example

This example demonstrates an editor in the Eclipse IDE and the same editor in the Eclipse RCP. To run the IDE-based example, import the following projects:

com.ibm.jdg2e.msseditor.ide (the "main" plug-in of the IDE-based example)
com.ibm.jdg2e.msseditor.common
com.ibm.jdg2e.msseditor.extras

Verify that the RCP-based version of this example, com.ibm.jdg2e.msseditor.miniwp is not open in the workspace; the plug-ins com.ibm.jdg2e.msseditor.ide and com.ibm.jdg2e.msseditor.miniwp define an editor with the same id, so loading them into the same runtime Workbench causes a conflict.

To begin, launch the runtime instance of Eclipse (Run > Run As > Eclipse Application). Create a new mini-spreadsheet from File > New > Other > JDG2E > Mini-Spreadsheet. The editor will be opened automatically. To run the RCP-based example, use the launch configuration JDG2E Mini-Workplace supplied in the com.ibm.jdg2e.miniwp project (see Running the Example in Chapter 10 for more details).

The example begins with a File > New > Other... > JDG2E > Mini-Spreadsheet wizard:

Mini-spreadsheet wizard

This allows the user to create the resource that the mini-spreadsheet editor will display and modify.

Opening a mini-spreadsheet file (.mss) displays it in its associated editor.

Notice that the editor has added some new toolbar buttons (left, center, right alignment and clear all ), pulldown menu choices, and a pop-up menu for selected rows. These choices are the "base choices" supplied by the com.ibm.jdg2e.msseditor.common plug-in. Other plug-ins may extend the editor, as shown in the next step.
The ability to extend existing components is important to users wanting to seamlessly integrate new capabilities into their existing environment.

Mini-spreadsheet with extensions

The menu choices shown with an asterisk were contributed by another plug-in, defined in the project com.ibm.jdg2e.msseditor.extras, as well as a toolbar button contribution .

Reuse in an RCP-based application. The majority of the code for the editor is the same whether the target environment is the Eclipse IDE or its Rich Client Platform.

Mini-spreadsheet in the Mini-Workplace

See Chapter 10, Creating Applications Using the Rich Client Platform, and the com.ibm.jdg2e.msseditor.miniwp and com.ibm.jdg2e.miniwp projects for more information.

Note: Since the mini-spreadsheet is for demonstration purposes, its calculations make some simplifying assumptions. For example, an entry vaguely resembling an integer is accepted as valid input (e.g., "JDG2E" = 2 for calculations), although the output won't preserve all of the original input (e.g., doubling "JDG2E" with the button produces 4, not "JDG4E").

Roadmap of the Example

As described above, this example is partitioned into several plug-ins. The com.ibm.jdg2e.msseditor.common plug-in defines the base functionality. The com.ibm.jdg2e.msseditor.extras plug-in contributes actions to the editor's pulldown menu, toolbar, and pop-up menu. Since there are a fair amount of classes involved, they are arranged in different packages to make it clearer what roles the classes fulfill.

Note: Unlike the other examples, the Mini-Spreadsheet package names do not always correspond to the plug-in id. For example, the package com.ibm.jdg2e.msseditor.ui has more than one plug-in contributing classes to it, such as com.ibm.jdg2e.msseditor.ide, com.ibm.jdg2e.msseditor.miniwp, and com.ibm.jdg2e.msseditor.common.

Model

Located in the com.ibm.jdg2e.msseditor.core package in the com.ibm.jdg2e.msseditor.common plug-in, these represent the model (non-UI) classes.

Class (All) Description

MiniSS Model of a spreadsheet, containing 0...n rows.

IMiniSSRow Model of a spreadsheet row. It is convenient to have a separate model for the rows, since JFace viewers, such as TableViewer, are row-oriented.

IMiniSSListener Change notification interface.

User Interface

Located in the com.ibm.jdg2e.msseditor.ui package, these represent the base user interface classes expected by JFace.

Class (All)	Description
`MiniSSContentProvider`	Mediator between the model, `MiniSS`, and structured content viewers like `TableViewer`.
`MiniSSResourceEditor` and `MiniSSFileEditor`	The spreadsheet editor which provides a simple interface to modifying spreadsheet files (`.mss`). These two classes handle the IDE and RCP specific issues while their superclass, `AbstractMiniSSEditor`, handles their common implementation concerns. The RCP-oriented `MiniSSFileEditor` works directly with files in the file system, not those in the workspace like the `MiniSSResourceEditor` does. The RCP rendition of the mini-spreadsheet editor accepts instances of `MiniSSEditorInput` as input.
`MiniSSImages`	Convenience class defining all the image descriptors that the editor user interface requires.
`MiniSSLabelProvider`	Mediator between the spreadsheet's underlying elements, instances of `MiniSSRow`, and the viewer.
`MiniSSPlugin`	Singleton representing the plug-in itself.

Actions

Located in the com.ibm.jdg2e.msseditor.ui.actions package, these represent the base user interface actions, that is, those actions that are defined by the editor itself, not contributed.

Class (All)	Description
`AppendRowAction`	Action to add a row to the end of the spreadsheet.
`ChangeAlignmentAction`	Action that changes the alignment of the table columns. For this implementation, the column alignment isn't saved. In a more complete implementation, this would be saved as spreadsheet metadata.
`ClearAllAction`	Action to set all cells to an empty string.
`MiniSSEditorAction`	Superclass to all the editor actions.
`MiniSSEditorActionBarContributor`	Responsible for adding the editor's menu choices and toolbar buttons. This class is a singleton, i.e., it is shared by all active instances of this editor (keyed by editor id).
`MiniSSRowActionFilter`	Defines an example action filter, used to query state information from `MiniSSRow` instances using `<objectState>` tags. See the `com.ibm.jdg2e.msseditor.extras` project for an example of its use.
`MiniSSAdapterFactory`	Manages the creation of instances of `MiniSSRowActionFilter` and `MiniSSContentOutlinePage`.
`RemoveRowAction`	Action to remove the selected rows.
`SelectAllAction`	Action to select all rows.
`ShowTotalAction`	Action to display the total of all selected integer rows.

Wizard

Located in the com.ibm.jdg2e.msseditor.ui.wizards package, defines the wizard necessary to create a new mini-spreadsheet in the Eclipse IDE.

Class (All) Description

MiniSSWizardNewFileCreationPage An extension of the standard file creation wizard for the Eclipse IDE, it adds fields for the spreadsheet dimensions. Note that in this implementation, the user can add and delete rows, but cannot change the number of columns after the spreadsheet is created.

NewMiniSSWizard Wizard for the Eclipse IDE to handle creation of a spreadsheet resource (.mss).

Outline

Located in the com.ibm.jdg2e.msseditor.ui.outline package, defines the helper classes to enable the standard Outline view for the mini-spreadsheet. The need for an outline is contrived, but the code demonstrates the mechanics of enabling it for editors in general.

Class (All) Description

MiniSSContentOutlinePage An instance is provided to the Workbench when the editor is activated thanks to the MiniSSAdapterFactory, which handles mapping from the editor to the desired implementor of IContentOutlinePage. This adapter is declared by the org.eclipse.core.runtime.adapters extension in the com.ibm.jdg2e.msseditor.common plug-in.

MiniSSOutlineContentProvider and MiniSSOutlineLabelProvider These classes have the fairly mundane task of interpreting instances of MiniSS on the behalf of the outline's viewer.

Extended Actions

These classes are defined in a new plug-in, contained in the project com.ibm.jdg2e.msseditor.extras. The steps for contributing actions is different than the steps that an editor follows to define its own actions. The purpose of this plug-in is to clearly demonstrate this difference.

Class (All) Description

IncrementRowValuesObjectActionDelegate Action to increment the integer values in the selected row(s). It performs an operation similar to those in the base context menu actions, but this action is contributed via an extension.

ShowMaxEditorActionDelegate Action to show the maximum of the integers in the table. It performs an operation similar to those in the base window pulldown menu actions, but this action is contributed via an extension.

DoubleActionDelegate Action to double integer values in the selected row(s). It performs an operation similar to those in the base toolbar button actions, but this action is contributed via an extension.

Notice that all the actions are subtypes of IActionDelegate. This extra level of indirection between an action contribution and the action itself allows the Workbench to defer loading the plug-in that is contributing the actions.

Class (All)	Description
`MiniSS`	Model of a spreadsheet, containing 0...n rows.
`IMiniSSRow`	Model of a spreadsheet row. It is convenient to have a separate model for the rows, since JFace viewers, such as `TableViewer`, are row-oriented.
`IMiniSSListener`	Change notification interface.

Class (All)	Description
`MiniSSWizardNewFileCreationPage`	An extension of the standard file creation wizard for the Eclipse IDE, it adds fields for the spreadsheet dimensions. Note that in this implementation, the user can add and delete rows, but cannot change the number of columns after the spreadsheet is created.
`NewMiniSSWizard`	Wizard for the Eclipse IDE to handle creation of a spreadsheet resource (`.mss`).

Class (All)	Description
`MiniSSContentOutlinePage`	An instance is provided to the Workbench when the editor is activated thanks to the `MiniSSAdapterFactory`, which handles mapping from the editor to the desired implementor of `IContentOutlinePage`. This adapter is declared by the `org.eclipse.core.runtime.adapters` extension in the `com.ibm.jdg2e.msseditor.common` plug-in.
`MiniSSOutlineContentProvider` and `MiniSSOutlineLabelProvider`	These classes have the fairly mundane task of interpreting instances of `MiniSS` on the behalf of the outline's viewer.

Class (All)	Description
`IncrementRowValuesObjectActionDelegate`	Action to increment the integer values in the selected row(s). It performs an operation similar to those in the base context menu actions, but this action is contributed via an extension.
`ShowMaxEditorActionDelegate`	Action to show the maximum of the integers in the table. It performs an operation similar to those in the base window pulldown menu actions, but this action is contributed via an extension.
`DoubleActionDelegate`	Action to double integer values in the selected row(s). It performs an operation similar to those in the base toolbar button actions, but this action is contributed via an extension.