2003 HEWLETT-PACKARD COMPANY

cr eat i ng a t ext - based

edi t or f or ecl i pse















By Elwin Ho
Contact author at: [email protected]
June 2003



2003 HEWLETT-PACKARD COMPANY 2
TABLE OF CONTENTS
Purpose...................................................................................................................................... 3
Overview of the Eclipse Workbench ......................................................................................... 4
Creating a Simple Text Editor................................................................................................... 5
Create a Plug-in Development Project in Eclipse ......................................................................................5
Import an Icon to Associate with Our Editors Files ................................................................................8
Register Our Editor Plug-in with Eclipse....................................................................................................9
Build, Run, and Test the Project .................................................................................................................10
Adding Syntax Coloring to the Text Editor ............................................................................ 12
Modify the Code ............................................................................................................................................13
Build, Run, and Test the Project .................................................................................................................15
Adding Content Assistance to the Text Editor ....................................................................... 16
Modify the Code ............................................................................................................................................16
Build, Run, and Test the Project .................................................................................................................18
Summary.................................................................................................................................. 18
Reference: ................................................................................................................................ 19


2003 HEWLETT-PACKARD COMPANY 3
creating a text-based editor for eclipse
pur pose
The purpose of this white paper is to show you how to create an Eclipse editor with syntax
coloring features and code completion functionality. Creating your own custom editor allows you to
support a new language that the default editor does not. Think of this article as the entry point for
creating such an editor. This white paper is intended for the intermediate Eclipse plug-in developer.
This paper does not go into details about the theory behind the Eclipse editor framework. For
more detailed information, refer to the Eclipse online help and source code. [Reference 1]
Throughout this paper, there are links to code samples. These samples are the finished product
for each section. These are provided so that you have working examples to build, run, and extend.

2003 HEWLETT-PACKARD COMPANY 4
over view of the ecl ipse workbench
Eclipse is an open source framework for building Integrated Development Environment using a
pre-built set of tools and GUI Components. It has generated interest from many developers since it
was first released.
The Eclipse Workbench consists of:
Editors specific editors are associated with various types of documents
Views views support editors
Perspectives a combination of specific views and editors

Figure 1. Eclipse Workbench

Below is a picture of the Eclipse Resource Perspective with a text document open in the Text
Editor. As you can see, the Resource Perspective contains:
Text Editor
Navigator View
Outline View
Task View

2003 HEWLETT-PACKARD COMPANY 5

Figure 2. Eclipse Resource Perspective

For additional information on the Eclipse Workbench, or any terminology used in this paper,
refer to the Workbench User Guide in the Eclipse online help (Help > Help Contents).
creati ng a si mpl e text editor
In this section, we describe how to create an Eclipse plug-in that provides basic text editor
features. We also show you how to associate a custom icon with files created using this editor. All
this functionality is a result of using Eclipse wizards. We dont have to write a single line of Java
code!
To begin, download the sample project by clicking the link MyEditor1 and then import this
project into your Eclipse workbench.
Create a Plug-in Development Project in Eclipse
To create a plug-in development project in Eclipse:
1) Select File > New > Project from the menu bar to open the New Project
Wizard.
2) Select Plug-in Development from the left pane and Plug-in Project from the
right pane. Click Next.

2003 HEWLETT-PACKARD COMPANY 6

3) Enter a Project name and click Next. For example, we named our project
MyEditor.

4) Select the Default Plug-In Structure and click Next.

2003 HEWLETT-PACKARD COMPANY 7

5) Choose Create a plug-in project using a code generation wizard and select the
Default Plug-In Structure code generation wizard. Click Next.
6) Accept the Simple Plug-in Content default settings and click Finish.

7) Our new editor plug-in project appears in the Package Explorer view.

2003 HEWLETT-PACKARD COMPANY 8


We have created a basic Eclipse plug-in development project. Now we can start customizing our
editor.
Import an Icon to Associate with Our Editors Files
Our next step is to import an icon for tagging the file type associated with our new editor. We
are going to import a sample icon from the Eclipse sample project into our plug-in.
To import an icon into our plug-in:
1) Create a directory for the icon: highlight our project and select File > New >
Folder from the menu bar.
2) Name our folder and click Finish. For example, we named our new folder icons.
3) Import the sample icon: highlight our new folder and select File > Import from
the menu bar.
4) Select File system and click Next.


2003 HEWLETT-PACKARD COMPANY 9
5) Browse to the
eclipse\plugins\org.eclipse.pde.ui_2.1.0\templates\edi
tor\bin\icons folder then,
a) Click OK.
b) Select sample.gif in the right pane.
c) Make sure the Into folder field has the correct path: MyEditor/icons.
d) Click Finish.
Now we are ready to create an extension point to register our plug-in with Eclipse.
Register Our Editor Plug-in with Eclipse
We must add an extension point to the plugin.xml file to register the editor plug-in with Eclipse.
To register your plug-in by adding an extension point the plugin.xml file:
1) Open the plugin.xml file: Right-click on the file in the Package Explorer, click
Open. To see the source code, click the Source tab in the bottom of the Plug-in
editor view.
2) Add the following extension point definition to the end of the plugin.xml file
right before </plugin>. See the table below for an explanation of each attribute
we are adding.


Attribute Description
point=org.eclipse.ui.editors Extension point for registering
our editor.
name=MyEditor Our editors name.
icon=icons/sample.gif Icon that is associated with files
created by our editor. If you
named your folder something
different than icons, make
sure to change this attribute to
specify the correct folder.
extensions=myfile Extension associated with files
created by our editor.
contributorClass=
org.eclipse.ui.editors.text.TextEditorActionContr
ibutor
Menu and toolbar action
definitions.

2003 HEWLETT-PACKARD COMPANY 10
class=org.eclipse.ui.editors.text.TextEditor Our editors main class. This is
the default text editor from the
Eclipse framework. This
provides basic text editing
features.
id=org.eclipse.ui.editors.text.texteditor Unique id for this contribution

Build, Run, and Test the Project
To build and run our project:
1) Build our plug-in project by selecting Project > Rebuild All from the menu bar.
2) Run our project by selecting Run > Run As > Run-time Workbench. This will
start a new instance of Eclipse that uses our new editor.
To test our editor:
1) Create a simple project by selecting File > New > Project from the menu bar.
2) Select Simple from the left pane and Project from the right pane. Click Next.
e) Enter a Project name and click Finish. For example, we called our project
TestEditor.



f) Select File > New > File from the menu bar to create a new file.
g) Name our file with the .myfile extension. For example, we named our file
test.myfile.


2003 HEWLETT-PACKARD COMPANY 11


h) Our new file with the sample icon appears in the Navigator view.



To view our editor file associations:
1) Select Window > Preferences from the menu bar.

2003 HEWLETT-PACKARD COMPANY 12
2) In the Preferences dialog box, expand the Workbench tree and highlight File
Associations. Notice that files with the .myfile extension is associated with
MyEditor.



adding syntax col oring to the text editor
We can extend our editor with different functionality. Lets add syntax coloring to our editor
that designates:
Red for <myTag> elements and content
Green for single-line comments (preceded by //)

2003 HEWLETT-PACKARD COMPANY 13

Eclipse contains APIs that help us add syntax coloring to our editor. Eclipse uses the damage,
repair, reconcile model. Every time the user changes the document, the presentation reconciler
determines which region of the visual presentation should be invalidated and how to repair it.
Damage is the text that must be redisplayed.
Repair is the method used for redisplaying the damaged area.
The process of maintaining the visual presentation of a document as changes
are made in the editor is known as reconciling.
To customize the damage/repair model to our editor, we extend the default TextEditor class
from Eclipse and then configure it to use our own SourceViewerConfiguration class. The
SourceViewer is the central class for configuring the editor with pluggable behavior such as
syntax coloring and code assistance. By default, the SourceViewer in the default text editor does
not support syntax coloring. We can create our own SourceViewer class by extending the
SourceViewerConfiguration class and overriding some of its methods to add the syntax-
highlighting feature to our editor. The following graphic shows the relationship of these basic classes
and the functions they provide.

TextEditor
Provide basic text editing
TextEditor
Provide basic text editing
SourceViewerConfiguration
The place to add syntax coloring
SourceViewerConfiguration
The place to add syntax coloring
RuleBasedScanner
Detect the token
Define text attribute
RuleBasedScanner
Detect the token
Define text attribute
Composition

Figure 3: Relationship of damage/repair relate classes
For more information on these classes, please refer to the Configuring a source viewer and
Syntax coloring topic in the Editors chapter of the Platform Plug-in Developer Guide in the Eclipse
online help.
Modify the Code

2003 HEWLETT-PACKARD COMPANY 14
To begin, download the sample project by clicking the link MyEditor2 and then import this
project into your Eclipse workbench. This sample project adds three classes to the default
MyEditorPlugin, MyEditor, MyRuleScanner, and MySourceViewerConfig. These
classes provide the following basic features:
MyEditorPlugin The standard class for plug-ins that integrate with the
Eclipse platform UI. It is created by the project wizard.
MyEditor extends the default TextEditor class in Eclipse. We change the
default SouceViewer in this class.
MyRuleScanner extends the RuleBasedScanner class in Eclipse and
actually sets the rules for our editor (makes specified tags red and single-line
comments green) that will be used in the damage/repair class.
MySourceViewerConfig extends the
SourceViewerConfiguration class in Eclipse, instantiates the rule
scanner, and defines the reconciler action.
The following steps detail the classes added for our new color syntax:
Define a new class that extends the Eclipse SourceViewerConfiguration class:

Listing 1 MyScouceViewConfig.java
Extend the basic TextEditor as our editor and configure MySourceViewerConfig as
our editor source viewer in the MyEditor class:

Listing 2. MyEditor.java
Now set up the damage/repair/reconcile model by overwriting the
SourceViewerConfiguration.getPresentationReconciler() method.
Configure the default DamagerRepairer as our damage/repair handler as shown in line 39 in
the text below. It uses MyRuleScanner as parameter (return by getTagScanner method in
line 23 to 31). The default DamagerRepairer takes the token that we define in
MyRuleScanner to repair the text that includes the text attribute, in this case the text color. (In
list 4, line 21 to 27)

2003 HEWLETT-PACKARD COMPANY 15

Listing 3 SourceViewerConfiguration.java
MyRuleScanner class builds rules for detecting different kinds of tokens such as single line
comments (//). It adds rules to detect the patterns we specify and associates the text attributes, that
is, the colors with these patterns. It then returns a token for the reconciler action. For example, in
line 17 and line 26 we associate the color green (RGB 0, 200, 0) with a comment line in listing 4.

Listing 4 MyRuleScanner.java

Build, Run, and Test the Project
Build and run our project the same way we did previously.
To test the syntax-highlighting feature:
1) Create a test file. For example, we named our file test.myfile.

2003 HEWLETT-PACKARD COMPANY 16
2) Type the following lines in the new file:
<myTag> red </myTag>
// green comment
The first line appears in red and the second line in green.

adding content assistance to the text editor
Content assistance is a feature that allows an editor to provide context-sensitive content
completion upon user request. To pop up a content assistance box, press CTRL-space or enter key
characters when editing a file. We can double-click a selection in the content assistance box to insert
that particular text into our file.
Now that we have added syntax coloring, we detail how to add a content assistance feature to
our editor. Our content assistance box contains the options myTag, html, and form.

Modify the Code
To begin, download the sample project by clicking the link MyEditor3 and then import this
project into your Eclipse workbench. This sample project adds one new class
(MyCompletionProcessor) to the three we added in the last section. The four classes are:
MyCompletionProcessor provides the text completion action (new
class)
MyEditor extends the TextEditor class in Eclipse

2003 HEWLETT-PACKARD COMPANY 17
MyRuleScanner extends the RuleBasedScanner class in Eclipse and
actually sets the rules for our editor
MySourceViewerConfig extends the
SourceViewerConfiguration class in Eclipse and instantiates the
content assistant.
As in syntax coloring, we need to customize content assistance object in the
MySourceViewerConfig class to implement the content assistance. In the
MySourceViewerConfig class, we use Eclipses ContentAssistant class to enable
content assistance as shown in line 48 below. The MyCompletionProcessor class provides the
completion action. We set the assistance properties (for example, orientation and delay time) in lines
53 to 56.

List 5 MySourceViewerConfig.java
Inside MyCompletionProcessor, we must define the trigger function. This function tells
the system that whenever the < is typed, code assistance should be invoked. We do this by
overriding getCompletionProposalAutoActivationCharacters() in the
MyCompletionProcessor class.

List 6 MyCompletionProcessor.java
We also implement the computeCompletionProposals method to return the
completion proposal for the content assistance. In this example, we simply return a list of hard-
coded text in line 25 to 27.

2003 HEWLETT-PACKARD COMPANY 18

List 7 MyCompletionProcessor.java
Build, Run, and Test the Project
Once again, build and run our project.
To test the content assistance feature:
1) Open test.myfile.
2) On a new line, type <. Double-click on one of the selections to add it to our file.



We can also get the content assistance box to pop up by simply:
Pressing CTRL+Space
Selecting Edit > Content Assist from the Eclipse menu bar
summar y
The editor is the most frequently used tool in an IDE. It has a major impact on the success of
any IDE. Any features we can add to help developers increase their accuracy and efficiency greatly
enhances the usefulness of our editor. The Eclipse platform provides a rich set of APIs and

2003 HEWLETT-PACKARD COMPANY 19
frameworks to allow different vendors to create their own unique development environments. Once
we have created our own editor, we can add many features besides the syntax coloring and content
assistance demonstrated in this white paper. Some of the possible features we can add include
content outlining, annotation, and text hovering. The Eclipse online help provides more information
about these features.

reference:
1. Eclipse on line help [http://dev.eclipse.org/help21/index.jsp ]
2. Eclipse news group [http://www.eclipse.org/newsgroups/index.html]
3. Wiki wiki [http://eclipsewiki.swiki.net]