1 files changed, 236 insertions, 0 deletions
diff --git a/org.eclipse.ui.examples.javaeditor/doc-html/ui_javaeditor_ex.html b/org.eclipse.ui.examples.javaeditor/doc-html/ui_javaeditor_ex.html
new file mode 100644
index 00000000000..d81ed0b127f
--- /dev/null
+++ b/org.eclipse.ui.examples.javaeditor/doc-html/ui_javaeditor_ex.html
@@ -0,0 +1,236 @@
+<!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.51 [en] (WinNT; I) [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.&nbsp; It also shows how&nbsp; 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&nbsp; 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>
+&nbsp;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".&nbsp;
+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>&nbsp;
+<p><a href="hglegal.htm"><img SRC="ngibmcpy.gif" ALT="Copyright IBM Corp. 2000, 2001.  All Rights Reserved." BORDER=0 height=12 width=195></a>
+</body>
+</html>