| <html> |
| <head> |
| <META http-equiv="Content-Type" content="text/html; charset=UTF-8"> |
| <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> |
| <link rel="stylesheet" href="../../../..//default_style.css" type="text/css"> |
| <link rel="stylesheet" href="../../../..//webtools/wtp.css" type="text/css"> |
| <title> |
| Structured Source Editing (SSE) Component Overview |
| </title> |
| </head> |
| <body> |
| <table width="100%" cellspacing="5" cellpadding="2" border="0"> |
| <tbody> |
| <tr> |
| <td width="60%" align="left"><font class="indextop">Structured Source Editing (SSE) Component</font> |
| <br> |
| <font class="indexsub"> |
| Structured Source Editing (SSE) Component Overview |
| </font></td><td width="40%"><img width="120" hspace="50" height="86" align="middle" src="../../../..//images/Idea.jpg"></td> |
| </tr> |
| </tbody> |
| </table> |
| <table width="100%" cellspacing="5" cellpadding="2" border="0"> |
| <col width="16"> |
| <col width="*"> |
| <tbody> |
| <tr> |
| <td valign="top" align="right"> </td><td valign="top"> |
| <p>Last modified September 20, 2005</p> |
| </td> |
| </tr> |
| <tr> |
| <td valign="top" align="right"> </td><td valign="top"> |
| <p> |
| |
| <i> |
| [This document is a work in progress. It is an attempt |
| to capture the key concepts of the WTP SSE Component. |
| Note that the concepts presented here may differ from |
| what is found in the currently released code. This |
| document describes the architecture, or "end goal", of |
| the SSE component. Once this document is finalized, the |
| intent is to bring the code and its specs into line with |
| this document.] |
| </i> |
| |
| </p> |
| </td> |
| </tr> |
| <tr> |
| <td valign="top" bgcolor="#0080c0" align="left" colspan="2"><b><font face="Arial,Helvetica" color="#ffffff">SSE UI</font></b></td> |
| </tr> |
| <tr> |
| <td valign="top" align="right"> </td><td valign="top"> |
| <p> |
| While there is a UI component to SSE, it has little API and |
| is intended to be a relatively thin layer on top of the base |
| Eclipse Text Editing API. SSE tries not to introduce UI API |
| unless we've found it necessary to go beyond functionality |
| provided by the Eclipse. |
| </p> |
| </td> |
| </tr> |
| <tr> |
| <td valign="top" align="right"> </td><td valign="top"> |
| <p> |
| The most important, probably long-term, difference from the |
| Eclipse text editing component that we attempt to make all |
| parts of the editor configurable according to the platform |
| content type of the input being edited, and in many cases, |
| based on the document partition types within the file. This |
| combination is the foundation of SSE's approach to handling |
| mixed content in a re-usable way. As such, one of the most |
| important areas to understand is the |
| <code>StructuredTextViewerConfiguration</code> |
| class and the Editor Configuration |
| <a href="designs/EditorConfiguration.html">extension point</a> |
| (<code>org.eclipse.wst.sse.ui.editorConfiguration</code>). |
| </p> |
| </td> |
| </tr> |
| <tr> |
| <td valign="top" align="right"> </td><td valign="top"> |
| <p> |
| I mention this as a "long term" difference, since the text |
| infrastructure allows editors to specify whole "processors" |
| (e.g. for content assist) whereas our philosophy is to |
| provide a processor that allows clients to participate in |
| creating the results. No implementation exists for Content |
| Assist at this time, but a working example of this pattern |
| can be found within SSE's "as you type" validation (see |
| <code> |
| org.eclipse.wst.sse.ui.extensions.sourcevalidation |
| </code> |
| extension point). |
| </p> |
| </td> |
| </tr> |
| <tr> |
| <td valign="top" align="right"> </td><td valign="top"> |
| <p> |
| Another area we differ from text infrastructure is in syntax |
| highlighting. We attempt to take direct advantage of |
| StyledText widget's callbacks to achieve greater efficiency |
| over preparing highlighting information in advance (this is |
| the theory, we still have some implementation work to do to |
| achieve in practice, in WTP Release 1.0). |
| </p> |
| </td> |
| </tr> |
| <tr> |
| <td valign="top" align="right"> </td><td valign="top"> |
| <p> |
| Another change is that while me make use of the platform's selection service to |
| <a href="designs/EditorSelection.html">communicate selection changes within our editor</a> |
| , we also provide <a href="designs/EditorSelection.html">more information</a> to listeners than most text editors. |
| </p> |
| </td> |
| </tr> |
| <tr> |
| <td valign="top" align="right"> </td><td valign="top"> |
| <p> |
| Issues we hope to remove as differences: there are currently |
| a number of overrides in SSE UI of Eclipse text |
| functionality that were originally made due to limitations |
| in Eclipse's text infrastructure (SSE dates back, in some |
| form, to before Eclipse 1.0). Many of those limitations have |
| since been improved upon or are improving in Eclipse's 3.1 |
| stream. We are currently investigating transitioning to the |
| provided infrastructure (some of which is new to Eclipse |
| 3.1) instead of providing an incompatible workalike. These |
| include: |
| <ul> |
| |
| <li> |
| An improved "undo" experience. SSE has a unified |
| Undo stack based on the resource being edited and |
| allowing participants to provide their own |
| operations on the stack for complex operations. It |
| seems "touch and go" if the base provided function |
| will suffice, but we are still early in our |
| investigation. |
| </li> |
| |
| <li> |
| validateEdit per resource, not per editor instance |
| </li> |
| |
| |
| <li> |
| Historically, several others which have a already |
| been migrated, such as "openOn" or hyperlink |
| navigation and context-sensitive preferences. |
| </li> |
| |
| </ul> |
| |
| </p> |
| </td> |
| </tr> |
| <tr> |
| <td valign="top" align="right"><img width="16" height="16" border="0" src="../../../..//images/Adarrow.gif"></td><td>Extension Points</td> |
| </tr> |
| <tr> |
| <td valign="top" align="right"> </td><td valign="top"><a href="designs/EditorConfiguration.html"> |
| <h4>Editor Configuration</h4> |
| </a></td> |
| </tr> |
| <tr> |
| <td valign="top" align="right"> </td><td valign="top"> |
| <p> |
| The Editor Configuration extension point takes the loose |
| coupling of the Eclipse SourceViewer and |
| SourceViewerConfiguration classes one step further by |
| allowing the viewer configuration itself to be dynamically |
| discovered and loaded instead of being statically specified |
| through code. The configuration class is most frequently |
| specified according to the platform content type being |
| edited. SSE also extends the viewer configuration pattern to its |
| outline and property sheet pages and also allows for certain |
| configurations to be specified according to document |
| partition type and editor IDs. |
| </p> |
| </td> |
| </tr> |
| <tr> |
| <td valign="top" align="right"> </td><td valign="top"> |
| <h4>Source Page Validation</h4> |
| </td> |
| </tr> |
| <tr> |
| <td valign="top" align="right"> </td><td valign="top"> |
| <p> |
| Allows participants to provide an |
| <code>org.eclipse.wst.validation.core.IValidator</code> |
| for source validation (as-you-type) via the |
| <code> |
| org.eclipse.wst.sse.ui.extensions.sourcevalidation |
| </code> |
| extension point. |
| </p> |
| </td> |
| </tr> |
| <tr> |
| <td valign="top" align="right"> </td><td valign="top"> |
| <p> |
| The enablement ("what" the validators can operate on) of the |
| source validators can be specified by content type ( |
| <code>org.eclipse.core.runtime.content.IContentType</code> |
| ) and partition types ( |
| <code>org.eclipse.jface.text.ITypedRegion.getType()</code> |
| ) within each content type. |
| </p> |
| </td> |
| </tr> |
| <tr> |
| <td valign="top" align="right"> </td><td valign="top"> |
| <br> |
| </td> |
| </tr> |
| <tr> |
| <td valign="top" align="right"> </td><td valign="top"> |
| <p> |
| This is likely the same |
| <code>org.eclipse.wst.validation.core.IValidator</code> |
| used for "batch" validation via the |
| <code>org.eclipse.wst.validation.validator</code> |
| extension. |
| </p> |
| </td> |
| </tr> |
| <tr> |
| <td valign="top" align="right"> </td><td valign="top"> |
| <p> |
| The validation messages are displayed to the user on the |
| source page as as "temporary" annotations. These show up in |
| the text as "squiggles" beneath the text and in the overview |
| ruler as rectangles. The validation message itself is |
| displayed by hovering the squiggle or rectangle. |
| </p> |
| </td> |
| </tr> |
| <tr> |
| <td valign="top" align="right"> </td><td valign="top"> |
| <h4>Line Style Participants</h4> |
| </td> |
| </tr> |
| <tr> |
| <td valign="top" align="right"> </td><td valign="top"> |
| <p> |
| [? to provide more] Line Style Participants are similar to |
| the Eclipse IPresentationRepairers, but are designed to |
| operate on structured documents. |
| </p> |
| </td> |
| </tr> |
| <tr> |
| <td valign="top" align="right"> </td><td valign="top"> |
| <h4>Content Assist Participants</h4> |
| </td> |
| </tr> |
| <tr> |
| <td valign="top" align="right"> </td><td valign="top"> |
| <p>[not committed -- ? to provide]</p> |
| </td> |
| </tr> |
| <tr> |
| <td valign="top" align="right"> </td><td valign="top"> |
| <h4>Editor related IDs</h4> |
| </td> |
| </tr> |
| <tr> |
| <td valign="top" align="right"> </td><td valign="top"> |
| <p> |
| Structured Text editor clients can contribute actions to the |
| editor as well as the help context id (infopop). Currently |
| this can be done through extension points offered by the |
| base (like org.eclipse.ui.editorActions, |
| org.eclipse.ui.popupMenus) Infopop can be contributed by the |
| standard infopop hooks (help context id points to actual |
| help) |
| |
| </p> |
| </td> |
| </tr> |
| <tr> |
| <td valign="top" align="right"> </td><td valign="top"> |
| <p> |
| To contribute, a "target id" of some kind is needed. For |
| Structured Text editors, the target id is generated based on |
| the content type in the editor, type of editor, place to |
| contribute. The target id looks like: >content |
| type<.>editor type keyword<.>place to contribute |
| keyword< |
| </p> |
| </td> |
| </tr> |
| <tr> |
| <td valign="top" align="right"> </td><td valign="top"> |
| <p> |
| This are the current editor types supported followed by |
| their keyword (the last in list are reserved for possible |
| future use): |
| <ul> |
| |
| <li>source page : source</li> |
| |
| <li>graph page : graph</li> |
| |
| <li>table page : table (reserved)</li> |
| |
| <li>design page : design (reserved)</li> |
| |
| <li>wysiwyg page : wysiwyg (reserved)</li> |
| |
| </ul> |
| |
| </p> |
| </td> |
| </tr> |
| <tr> |
| <td valign="top" align="right"> </td><td valign="top"> |
| <p> |
| These are the following places clients can contribute to |
| followed by their keyword: editor popup menu : EditorContext |
| editor vertical ruler popup menu : RulerContext outline view |
| popup menu : OutlineContext help context id : HelpId |
| </p> |
| </td> |
| </tr> |
| <tr> |
| <td valign="top" align="right"> </td><td valign="top"> |
| <p> |
| Here are some examples: To contribute to *xml source |
| editor's popup menu*, use target id |
| "org.eclipse.core.runtime.xml.source.EditorContext" |
| </p> |
| </td> |
| </tr> |
| <tr> |
| <td valign="top" align="right"> </td><td valign="top"> |
| <p> |
| To contribute to *xsd graph editor's outline view's popup |
| menu*, use target id |
| "org.eclipse.wst.xsd.contentmodel.xsdsource.graph.OutlineContext" |
| </p> |
| </td> |
| </tr> |
| <tr> |
| <td valign="top" align="right"> </td><td valign="top"> |
| <p> |
| To provide infopop for *html source page editor*, use help |
| context id |
| "org.eclipse.wst.html.core.htmlsource.source.HelpId" |
| </p> |
| </td> |
| </tr> |
| <tr> |
| <td valign="top" bgcolor="#0080c0" align="left" colspan="2"><b><font face="Arial,Helvetica" color="#ffffff">SSE Core</font></b></td> |
| </tr> |
| <tr> |
| <td valign="top" align="right"> </td><td valign="top"> |
| <p> |
| The more substantial contribution of SSE is its core APIs. |
| </p> |
| </td> |
| </tr> |
| <tr> |
| <td valign="top" align="right"><img width="16" height="16" border="0" src="../../../..//images/Adarrow.gif"></td><td>Structured Documents</td> |
| </tr> |
| <tr> |
| <td valign="top" align="right"> </td><td valign="top"> |
| <p> |
| Once central concept is the |
| <code>IStructuredDocument</code> |
| . It is intended to be similar to an IDocument, but with a |
| few significant differences. Some changes are aimed at |
| providing characteristics that document programmers expect |
| to see, such as encoding and end-of-lines information. In |
| addition: |
| |
| <ul> |
| |
| <li> |
| It has an associated parser and re-parser, which in |
| our experience is how most programmers think of text |
| models. |
| </li> |
| |
| <li> |
| It also does not depend on a "reconciler thread" to |
| reconcile the model. Instead, it notifies the model |
| immediate of changes. Our philosophy is that it is |
| the model itself that should decide if there would |
| be a delay or a separate thread required to |
| reconcile itself. For small and fast models, there |
| is no need to do this on a separate thread and the |
| user's experience will appear much more responsive. |
| For other cases a longer time may be required, but |
| when handled correctly, the model can still give |
| immediate feedback to the user that a longer |
| operation is in progress. |
| </li> |
| |
| <li> |
| A structured document implements the core runtime's |
| IAdaptable interface allowing clients to associate |
| their own data with the document, independent of the |
| implementation. |
| </li> |
| |
| <li> |
| A structured document allows regions of the text to |
| be set as "read-only" so that users can not simply |
| type over something that is intended to remain as |
| part of the document. |
| </li> |
| |
| </ul> |
| |
| </p> |
| </td> |
| </tr> |
| <tr> |
| <td valign="top" align="right"> </td><td valign="top"> |
| <p> |
| The IStructuredDocument is conceptually a stream of |
| characters made up of (divided into) |
| IStructuredDocumentRegions. The main constraint on what |
| types of languages are appropriate for structured documents |
| and structured regions is whether or not it has the concept |
| of having a syntactically determined end. This is used to |
| know how to correctly handle reparsing (deciding what is a |
| "safe start" and "safe end" for the reparse operation). |
| </p> |
| </td> |
| </tr> |
| <tr> |
| <td valign="top" align="right"><img width="16" height="16" border="0" src="../../../..//images/Adarrow.gif"></td><td>Parsers and re-parsers</td> |
| </tr> |
| <tr> |
| <td valign="top" align="right"> </td><td valign="top"> |
| <p> |
| The parser/reparser pair has a few conceptual requirements. |
| They must be able to handle any text (legal or not) and must |
| return regions that completely cover the input text (for |
| example, whitespace can not simply be ignored). More |
| difficult to implement, another constraint is that for any |
| (correctly specified) subset of text, the reparser must give |
| the same results that the parser would if parsed from top to |
| bottom. |
| |
| </p> |
| </td> |
| </tr> |
| <tr> |
| <td valign="top" align="right"> </td><td valign="top"> |
| <p> |
| It might be useful to note, for anyone looking at detail at |
| the parsers and re-parser implementations, for cases |
| involving "invalid input", heuristics are often used to make |
| these decisions so sometimes we can and do "guess right" |
| (based on what a user might be in the process of typing) and |
| sometimes not -- in other words, its not always easily |
| predictable as it is for "clean" text but is based on doing |
| a reasonable job which would not invalidate subsequent |
| reparsing. |
| </p> |
| </td> |
| </tr> |
| <tr> |
| <td valign="top" align="right"><img width="16" height="16" border="0" src="../../../..//images/Adarrow.gif"></td><td>Structured Document Events</td> |
| </tr> |
| <tr> |
| <td valign="top" align="right"> </td><td valign="top"> |
| <p> |
| The StructuredDocumentEvents are similar to IDocument's |
| DocumentEvents, but provide much more information about the |
| nature of the change in terms of IStructuredDocumentRegions |
| (and the ITextRegions of which they are composed). |
| Listeners, such as DOM parsers, can make use of this to |
| minimize the amount of reparsing/rebuilding they have to do. |
| </p> |
| </td> |
| </tr> |
| <tr> |
| <td valign="top" align="right"><img width="16" height="16" border="0" src="../../../..//images/Adarrow.gif"></td><td>Structured Models</td> |
| </tr> |
| <tr> |
| <td valign="top" align="right"> </td><td valign="top"> |
| <p> |
| Structured models are mostly interesting due to is extended |
| types and implementers and exists as an abstraction to |
| provide a consistent way to manage shared models and also to |
| access its underlying structured document. |
| </p> |
| </td> |
| </tr> |
| <tr> |
| <td valign="top" align="right"><img width="16" height="16" border="0" src="../../../..//images/Adarrow.gif"></td><td>Node Notification and Adaption</td> |
| </tr> |
| <tr> |
| <td valign="top" align="right"> </td><td valign="top"> |
| <p> |
| In addition to IAdaptable and whole model state listeners, |
| many "Node" structures in SSE related models make use of a |
| finer level of adaption and notification. This mechanism can |
| be used to have improved UI updates or can be used to keep |
| related models "in synch" (for example, a DOM model change |
| can cause a change in an EMF model, and vis versa). |
| </p> |
| </td> |
| </tr> |
| <tr> |
| <td valign="top" align="right"><img width="16" height="16" border="0" src="../../../..//images/Adarrow.gif"></td><td>Model Management</td> |
| </tr> |
| <tr> |
| <td valign="top" align="right"> </td><td valign="top"> |
| <p> |
| Another important contribution of sse.core is the |
| IModelManager. Its purpose is to provide a StructuredModel, |
| appropriate to contentType, that can be shared between many |
| clients at runtime. This increases efficiency since each |
| client doesn't have to (re)create their own, but just as |
| importantly, it is an easy way for clients to all stay "in |
| synch"--a change in the model made by one client will be |
| known by all others clients. The other motivation for this |
| is it allows looser coupling, since clients who may not even |
| know about each other can share the resource (model) without |
| passing it around to each other. |
| </p> |
| </td> |
| </tr> |
| </tbody> |
| </table> |
| </body> |
| </html> |
