| <!doctype html public "-//w3c//dtd html 4.0 transitional//en"> |
| <html> |
| <head> |
| <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> |
| <meta name="GENERATOR" content="Mozilla/4.76 [en] (Windows NT 5.0; U) [Netscape]"> |
| <title>Desktop - Java Editor Example</title> |
| </head> |
| <body> |
| |
| <h2> |
| <b>Example - Java Editor</b></h2> |
| |
| <h3> |
| Introduction</h3> |
| 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. |
| <h3> |
| <b>Features demonstrated in the example editor</b></h3> |
| |
| <ul> |
| <li> |
| syntax highlighting</li> |
| |
| <li> |
| content type sensitive content assist (JavaDoc and Java code)</li> |
| |
| <li> |
| communication between content outliner and editor, i.e. content outliner |
| selection feeds the highlight range of the editor</li> |
| |
| <li> |
| two different presentation modes</li> |
| |
| <ul> |
| <li> |
| marking the highlight range using a visual range indicator</li> |
| |
| <li> |
| confining the editor to show only text within the highlight range (e.g. |
| show a single method of a Java class)</li> |
| </ul> |
| |
| <li> |
| marker handling</li> |
| |
| <li> |
| document sharing</li> |
| </ul> |
| |
| <h3> |
| Features not demonstrated</h3> |
| |
| <ul> |
| <li> |
| content formatting</li> |
| |
| <li> |
| dynamic reconciling of content outline page</li> |
| </ul> |
| |
| <h3> |
| Running the example editor</h3> |
| |
| <ol> |
| <li> |
| Create a project</li> |
| |
| <li> |
| Create a file with the file extension ".jav" in the newly created project. |
| The Java example editor opens automatically.</li> |
| |
| <li> |
| 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 and tags are differently colored.</li> |
| |
| <li> |
| 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 green 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.</li> |
| |
| <li> |
| 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. |
| The anticipated use of content tips is to let the user express her intention, |
| e.g. to enter a method call and to present contextual information which |
| guides the user by 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 visible in the content tip. Inside regular Java code, |
| the example editor always proposes all Java keywords.</li> |
| |
| <li> |
| 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.)</li> |
| |
| <li> |
| 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.</li> |
| |
| <li> |
| 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 anticipated to be used, e.g., for single method views.</li> |
| |
| <li> |
| 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.</li> |
| |
| <li> |
| 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.</li> |
| |
| <li> |
| 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.</li> |
| |
| <li> |
| 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 lively linked.</li> |
| </ol> |
| |
| <h3> |
| Principles for creating custom text editors</h3> |
| The following steps are usually necessary do develop a custom text editor. |
| <ol> |
| <li> |
| 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 looks like and whether the document |
| provider should be shared between multiple editors or not. See the class |
| FileDocumentProvider in the Java example editor.</li> |
| |
| <li> |
| 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 the 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.</li> |
| |
| <li> |
| Determine which of the source viewer plugins should be provided. Among |
| other supported plugins 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.</li> |
| |
| <li> |
| Create for all source viewer plugins 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 being 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 being a member of 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.</li> |
| |
| <li> |
| Build a source viewer configuration using the previously created plugins |
| and extensions. See JavaSourceViewerConfiguration in the example editor.</li> |
| |
| <li> |
| 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.</li> |
| |
| <li> |
| 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.</li> |
| |
| <li> |
| Extend the XML configuration file of the editor's plugin, 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.</li> |
| </ol> |
| |
| <h3> |
| Code organization of the example</h3> |
| The example code is organized in four packages: |
| <ul> |
| <li> |
| <tt>org.eclipse.ui.examples.javaeditor </tt>contains all the editor specific |
| classes.</li> |
| |
| <li> |
| <tt>org.eclipse.ui.examples.javaeditor.java</tt> contains all Java specific |
| source viewer plugins such as the JavaDamagerRepairer as well as the Java |
| specific document partitioner.</li> |
| |
| <li> |
| <tt>org.eclipse.ui.examples.javaeditor.javadoc </tt>contains all JavaDoc |
| specific source viewer plugins such as the JavaDocDamagerRepairer.</li> |
| |
| <br><tt>org.eclipse.ui.examples.javaeditor.util</tt> contains convenience |
| classes shared by the three other packages.</ul> |
| |
| <br> |
| <p><a href="hglegal2003.htm"><img src="ngibmcpy2003.gif" alt="Copyright IBM Corporation and others 2000, 2003" border="0" width="324" height="14"></a> |
| </p> |
| </body> |
| </html> |
