Adding a new editor

Following the principle of "separation of concerns", editors should generally be developed in separate, dedicated bundles in the bundles directory of the project. Exceptions to this rule should be based on compelling reasons for including an editor in an existing bundle project. Reasons may include, for example, that the architectural overhead for creating a very simple editor may be too high. In cases of uncertainty, follow the rule that changes to software should keep the maintenance effort in proportion to the benefit of the change, and generally as small as possible.

In Eclipse 4, additions to the user interface are organized in so-called Parts. A part consists of two components:

  • a PartDescriptor entry in the fragment.e4xmi file of the bundle containing the new editor, and
  • the actual Java class implementing the behavior.

Adding a minimal Java class

Add a Java class to your bundle project. This class does not need to inherit any interface, but should have a method with the @PostConstruct annotation.

public class TextViewer {
	@PostConstruct
	public void postConstruct(Composite parent, MPart part, ProjectManager projectManager) { 
		// TODO: add actual editor implementation
	}
}

This example injects the SWT parent composite which can be used to construct user interface elements and the part parameter, which describes the application model for this part.

SWT ("Standard Widget Toolkit") is the default user interface widgets toolkit for Eclipse-based applications, such as Hexatomic, and is used in this example. For more information, see the Eclipse SWT project website. For information on the application model of Eclipse-based applications, see the Eclipse Wiki page on the UI model.

The projectManager is an Hexatomic specific service that provides access to the global Salt project which is currently loaded.

Note that you can directly add the SWT instructions to define your user interface in the code, or use the Eclipse Window Builder, which is a graphical editor for user interfaces based on SWT (and other technologies).

Adding a part to the application model

To add the newly created class to the Eclipse RCP 4 application model, open the fragment.e4xmi file of the existing bundle, or create a new one via the File -> New -> Other menu and choose "New Model Fragment".

Adding a new fragment model file

In the fragment editor, add a new model fragment by selecting "Model fragments" and clicking on the "Add" button.

Adding a new model fragment in the editor

Edit the model fragment properties by selecting the newly created entry. Make sure to set the extended element ID to xpath:/and the feature name to descriptors (1). This means that the model fragment extends the part descriptors of the application. Then, add a new part descriptor with the Add button (2).

Edit model fragment properties

Select the new part descriptor in the model fragment editor and you can edit several properties, such as the caption of the part, or an icon. Make sure to set the "Class URI" field to the newly created editor class. You can use the "Find" button to navigate the workspace and insert the proper value. Also, the "Category" must be set to org.corpus_tools.hexatomic.tag.editor to mark that this part is an Hexatomic editor. The Label field will be used as a name for the editor, for example in a menu from which the user will choose one of the editors available to open a document with.

Part descriptor general properties

Getting the associated Salt document to display

When an editor part is created, it is initialized with a state. This state can hold internal configurations, but also contains the ID of the associated Salt document that this editor should edit. The actual ID is set to the editor part's state in the class handling user actions to open a Salt document, org.corpus_tools.hexatomic.core.handlers.OpenSaltDocumentHandler.

It is stored in the part state in a setting with the name org.corpus_tools.hexatomic.document-id. The injected ProjectManager can then be used to get the actual document.

String documentID = part.getPersistedState()
	.get("org.corpus_tools.hexatomic.document-id");
Optional<SDocument> doc = projectManager.getDocument(documentID);