Desktop - Java Editor Example

## Example - Java Editor

### Introduction

The Java Editor example demonstrates the standard features available for custom text editors. It also shows how to register an editor for a file extension (in this case .jav) and how to define a custom Document provider for use by that editor. This example is only for demonstration purposes. Java editing support is provided by the Eclipse Java Tooling.

The code for this example is in the `org.eclipse.ui.examples.javaeditor` plug-in. To explore the code it is recommended to import that plug-in into your workspace.

### Features demonstrated in the example editor

- syntax highlighting
- content type sensitive content assist (Javadoc and Java code)
- communication between content outliner and editor, i.e. content outliner selection feeds the highlight range of the editor
- two different presentation modes

- marking the highlight range using a visual range indicator
- confining the editor to show only text within the highlight range (e.g. show a single method of a Java class)

- marker handling
- document sharing

### Features not demonstrated

- content formatting
- dynamic reconciling of content outline page

### Running the example Java editor

1. Create a project
2. Create a file with the file extension ".jav" in the newly created project. The Java example editor opens automatically.
3. Insert Java code. The Java code is dynamically colored. The example editor presents the following language elements in different colors: multi-line comments, single line comments, Java language reserved words, string and character constants, regular Java code, as well as multi-line comments following the Javadoc guidelines. Inside those Javadoc comments, Javadoc keywords (green) and HTML tags (gray) are differently colored.
4. Open a new Java multi-line comment by inserting "/*" outside a Java comment. All the text between the inserted "/*" and the first occurrence of "*/" or the end of the text changes its color to red. Append another "*". The red range changes color to black as the regular multi-line comment now is considered containing Javadoc. Invoke code assist using CTRL-SPACE. The function of content assist is to support the user in writing code. So on invocation, content assist should list all possible valid completions at the invocation location. Inside Javadoc, the example editor always proposes all Javadoc keywords.
5. Outside a Java comment invoke content tip using CTRL+SHIFT+SPACE. Five proposals are listed. Select one and press ENTER. A small floating red window appears above the current line displaying the selected proposal. Content tips are used to let the user express her intention (e.g. entering a method call), and then to present contextual information which guides the user in doing so. In the example editor, the proposal is considered valid five characters around the initial invocation location. While the content tip is visible, invoke content assist using CTRL+SPACE. Content assist invoked in this situation should help the user to accomplish her stated intention, which is still visible in the content tip. Inside regular Java code, the example editor always proposes all Java keywords.
6. Save the Java code. Saving updates the content outliner. The content outliner contains ten entries each of them representing one of ten equally sized segments of the Java code in the editor. This style of content outline has been chosen to show that the semantics of highlight ranges can arbitrarily be defined. (See next steps.)
7. Select one of the entries in the content outliner. The corresponding lines are marked with a blue bar in the editor's left vertical ruler.
8. Now switch to the segmented presentation mode of the Java editor. For that make sure that the editor has the focus and press that button in the desktop's toolbar whose hover help says "Enable/Disable segmented source viewer". This functionality is used for single method views and similar functionality.
9. Select a different entry in the content outliner. Now the editor only shows the selected segment. By deselecting the entry in the content outliner, the complete Java code is shown again.
10. Select an entry in the content outliner, select a fraction of the visible text, and add a task for the selection. The task shows up in the task list. Modify the visible code. In the task list, select the previously created task and press the "Go to file" button. The task is selected in the visible area, correctly taking the previously applied modifications into account.
11. Select another entry in the content outliner. Reveal the previously added task from the task list. The editor's highlight range is automatically enlarged to enclose the range of the revealed task.
12. Open a new workspace. In the new workspace, open a Java editor for the same file as in the original workspace. Modify the editor content. Switch back to the original workspace. The editor shows the changes made in the other workspace. The two editors showing the same file are linked.

### Principles for creating custom text editors

The following steps are usually necessary do develop a custom text editor.

1. Create a document provider. A document provider (see IDocumentProvider) produces and manages documents (see IDocument) containing a textual representation of editor input elements. It is important to decide how the translation between element and textual representation should be performed and whether the document provider should be shared between multiple editors or not. See the class FileDocumentProvider in the Java example editor.
2. Create a document partitioner. A document partitioner (see IDocumentPartitioner) divides a document into disjoint regions. The partitioner assigns each region one content type out of a set of content types predefined by the partitioner. On each document change the document's partitioning must be updated. See the class JavaPartitioner in the Java example editor. The JavaPartitioner determines regions of types "multi-line comments", "Javadoc comments", and "everything else". It must be ensured that the document provider is set on each document produced by the document provider.
3. Determine which of the source viewer plug-ins should be provided. Among other supported plug-ins are auto indent strategies, double click strategies, content formatter, and text presentation reconciler. The subsequent description will be restricted to the text presentation reconciler (see IPresentationReconciler). In the Java example editor, the text presentation reconciler is utilized to implement syntax highlighting.
4. Create for all source viewer plug-ins the appropriate extensions for each supported content type. As seen above, the document partitioner defines the supported content types. The default implementation of IPresentationReconciler supports IPresentationDamagers and IPresentationRepairers as extensions. Those extensions are considered to be specific for a particular content type. Thus, for a custom editor, the user must first select a subset of the supported content types. Regions of a type in the selected subset will, e.g., be syntax highlighted. For each of those types the extensions must be implemented. See JavaDamagerRepairer and JavaDocDamagerRepairer in the example editor.
5. Build a source viewer configuration using the previously created plug-ins and extensions. See JavaSourceViewerConfiguration in the example editor.
6. Customize the class TextEditor or AbstractTextEditor with the developed document partitioner and source viewer configuration. Add or replace actions and adapt the construction of the editor's context menu. In the actual version, this customization must be done in a subclass. See JavaEditor in the example editor.
7. Set up an appropriate action bar contributor who contributes editor-related actions to the desktop's toolbar and menus. See JavaActionContributor in the example editor.
8. Extend the XML configuration file of the editor's plug-in, so that the editor registers at the predefined editor extension point for a specific set of file extensions. Also set up the action bar contributor in the XML file. See plugin.xml of this example.

### Code organization of the example

The Java editor example code is organized in four packages:

- `org.eclipse.ui.examples.javaeditor` contains all the editor specific classes.
- `org.eclipse.ui.examples.javaeditor.java` contains all Java specific source viewer plug-ins such as the JavaDamagerRepairer as well as the Java specific document partitioner.
- `org.eclipse.ui.examples.javaeditor.javadoc` contains all Javadoc specific source viewer plug-ins such as the JavaDocDamagerRepairer.
`org.eclipse.ui.examples.javaeditor.util` contains convenience classes shared by the three other packages.