| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" |
| "http://www.w3.org/TR/html4/loose.dtd"> |
| <html> |
| <head> |
| <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> |
| <link rel="stylesheet" href="../../../../../default_style.css" |
| type="text/css"> |
| <link rel="stylesheet" href="../../../../wtp.css" type="text/css"> |
| <title>Selection in StructuredTextEditor</title> |
| <style> |
| <!-- |
| dd { |
| padding-bottom: 1em; |
| } |
| dt { |
| text-decoration: underline; |
| } |
| --> |
| </style> |
| </head> |
| <body> |
| <table width="100%" cellspacing="5" cellpadding="2" border="0"> |
| <tbody> |
| <tr> |
| <td width="60%" align="left"><font class="indextop">Selection in |
| StructuredTextEditor</font> <br> |
| <font class="indexsub">structured source editing (sse) component</font></td> |
| <td width="40%"><img width="120" hspace="50" height="86" |
| align="right" src="http://eclipse.org//images/Idea.jpg"></td> |
| </tr> |
| </tbody> |
| </table> |
| <table border="1"> |
| <tr> |
| <th>Date</th> |
| <th>Revision info</th> |
| </tr> |
| <tr> |
| <td>9/20/2005</td> |
| <td>Initial contribution</td> |
| </tr> |
| <tr> |
| <td>9/28/2005</td> |
| <td>Added example usages</td> |
| </tr> |
| </table> |
| <br> |
| |
| <table width="96%" cellspacing="5" cellpadding="2" border="0"> |
| <col width="4%"> |
| <col width="*"> |
| <tbody> |
| <!-- |
| <tr> |
| <td valign="top" align="right"> </td> |
| <td valign="top"><a name="top"></a></td> |
| </tr> |
| <tr> |
| <td valign="top" bgcolor="#0080c0" align="left" colspan="2"><b><font |
| face="Arial,Helvetica" color="#ffffff">section header</font></b></td> |
| </tr> |
| <tr> |
| <td valign="top" align="right"> </td> |
| <td valign="top">section contents</td> |
| </tr> |
| --> |
| <tr id="main_content_top"> |
| <td valign="top" align="right"> </td> |
| <td valign="top"><a name="top"></a></td> |
| </tr> |
| <tr id="overview_header"> |
| <td valign="top" bgcolor="#0080c0" align="left" colspan="2"><b><font |
| face="Arial,Helvetica" color="#ffffff">Overview</font></b></td> |
| </tr> |
| <tr id="overview_content"> |
| <td valign="top" align="right"> </td> |
| <td valign="top">One of the most visible cues of good integration |
| between editors and views is synchronized selection: the selected |
| Java method in the Outline view should reflect the caret position in |
| the Java Editor, the Properties view should show properties for the |
| DOM Element selected in the Outline view, the selected objects on a |
| mutli-page editor's Design page should always be the same as on its |
| Source page, etc. Rather than introduce and maintain our own |
| mechanism for achieving this, the <code>StructuredTextEditor</code> |
| exposes its selection handling using standard Eclipse platform APIs. |
| <br> |
| <br> |
| <br> |
| </td> |
| </tr> |
| <tr id="notification_in_TE_content"> |
| <td valign="top" bgcolor="#0080c0" align="left" colspan="2"><b><font |
| face="Arial,Helvetica" color="#ffffff">Selection notification in |
| text editors</font></b></td> |
| </tr> |
| <tr></tr> |
| <tr id="notification_in_TE_content"> |
| <td valign="top" align="right"> </td> |
| <td valign="top"><img src="selection/single.jpg" |
| alt="block diagram of key selection objects for a text editor"><br> |
| In text editors, the editor sets a <code>ISelectionProvider</code> |
| into its <code>IEditorSite</code>. The <code>ISelectionProvider</code> |
| sends <code>ITextSelection</code> objects from the source viewer to |
| its listeners and knows how to accept an <code>ITextSelection</code> |
| and apply it to the <code>SourceViewer</code>. The workbench <code>ISelectionService</code> |
| becomes a listener of the <code>ISelectionProvider</code> and any |
| changes sent to the <code>ISelectionService</code> are forwarded to |
| everyone listening to the service--most views, for example. |
| <p>The flow of selection notification from the editor's source viewer |
| changes looks like this: <br> |
| <table> |
| <tr> |
| <td colspan="1"> </td> |
| <td colspan="4">selection changes in the source viewer</td> |
| </tr> |
| <tr> |
| <td colspan="1"> </td> |
| <td colspan="1"> </td> |
| <td colspan="3">-> editor's <code>ISelectionProvider</code> |
| receives selection changed and notifies its listeners</td> |
| </tr> |
| <tr> |
| <td colspan="1"> </td> |
| <td colspan="1"> </td> |
| <td colspan="1"> </td> |
| <td colspan="2">-> <code>ISelectionService</code> receives |
| selection changed and notifies its listeners</td> |
| </tr> |
| <tr> |
| <td colspan="1"> </td> |
| <td colspan="1"> </td> |
| <td colspan="1"> </td> |
| <td colspan="1"> </td> |
| <td colspan="1">-> listeners react (views update)</td> |
| </tr> |
| </table> |
| <br> |
| The flow of setting selection into the editor looks like this:<br> |
| <table> |
| <tr> |
| <td colspan="1"> </td> |
| <td colspan="2">selection created</td> |
| </tr> |
| <tr> |
| <td colspan="1"> </td> |
| <td colspan="1"> </td> |
| <td colspan="1">-> editor's <code>ISelectionProvider</code> |
| receives <code>setSelection()</code> message and updates the source |
| viewer's selected text</td> |
| </tr> |
| </table> |
| <br> |
| <br> |
| <br> |
| </td> |
| </tr> |
| <tr id="notification_in_STE_header"> |
| <td valign="top" bgcolor="#0080c0" align="left" colspan="2"><b><font |
| face="Arial,Helvetica" color="#ffffff">How this applies to SSE and |
| its StructuredTextEditor</font></b></td> |
| </tr> |
| <tr id="notification_in_STE_content"> |
| <td valign="top" align="right"> </td> |
| <td valign="top">In the past, the <code>StructuredTextEditor</code> |
| didn't affect any of this. As part of the changes for bug <a |
| href="http://bugs.eclipse.org/bugs/show_bug.cgi?id=109441">109441</a> |
| , <code>StructuredTextEditor</code> provides an <code>ISelectionProvider</code> |
| that creates a single selection object implementing both <code>ITextSelection</code> |
| and <code>IStructuredSelection</code> . Listeners that can only |
| handle one of those types of selection can still function because |
| this unified selection is provided in every selection changed event |
| and as the result of <code>ISelectionProvider.getSelection()</code> . |
| The <code>ISelectionProvider</code> also accepts both kinds of |
| selection for <code>ISelectionProvider.setSelection(ISelection)</code>, |
| passing text selections straight through to the source viewer. The |
| actual <code>ISelectionProvider</code> implementation being used is <code>org.eclipse.wst.sse.ui.StructuredTextEditor.StructuredSelectionProvider</code> |
| .<br> |
| <br> |
| <br> |
| </td> |
| </tr> |
| <tr id="notification_in_MPE_header"> |
| <td valign="top" bgcolor="#0080c0" align="left" colspan="2"><b><font |
| face="Arial,Helvetica" color="#ffffff">Selection notification when |
| embedded in Multi-page Editors</font></b></td> |
| </tr> |
| <tr id="notification_in_MPE_content"> |
| <td valign="top" align="right"> </td> |
| <td valign="top"><img src="selection/multipage.jpg" |
| alt="block diagram of key selection objects for a text editor in a multi-page editor part"> |
| The <code>MultiPageEditorPart</code> connects its own selection |
| provider (2) to the selection service. That selection provider (2) is |
| notified of selection changes by the selection providers (1) of all |
| of its connected pages and forwards any notifications to the |
| selection service. In Eclipse 3.1, this is done for plain selection |
| notification only, not for post selection. Source viewers send cursor |
| movements using post selection notification, and when using the base |
| selection APIs, updating selection in views like the outline will |
| rely on post selection notification coming from the source viewer |
| through the <code>MultiPageEditorPart</code> and the selection |
| service. Eclipse bug <a |
| href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=108324">108324</a> |
| has been opened to address this for Eclipse 3.2. <code>org.eclipse.wst.common.ui.provisional.editors.PostSelectionMultiPageEditorPart</code> |
| has been provided as a temporary workaround.<br> |
| <br> |
| <br> |
| </td> |
| </tr> |
| <tr id="usage_header"> |
| <td valign="top" bgcolor="#0080c0" align="left" colspan="2"><b><font |
| face="Arial,Helvetica" color="#ffffff">Guidelines for usage</font></b></td> |
| </tr> |
| <tr id="usage_content"> |
| <td valign="top" align="right"> </td> |
| <td valign="top"> |
| <dl> |
| <dt>Synchronizing selection from an editor to a view:</dt> |
| <dd>To synchronize selection from an editor to a view, the view |
| should register itself as a listener of the ISelectionService when |
| it is initialized. It will then automatically recieve notification |
| about selection changes and the workbench part that originated them. |
| Pages in a <code>PageBookView</code> should check their visibility |
| before handling any selection change notifications as they'll |
| receive notification from every workbench part. The <code>PageBook</code> |
| will ensure that the page is only visible when the correct workbench |
| part is active.</dd> |
| |
| <dt>Synchronizing selection from a view to an editor:</dt> |
| <dd>It's rare for an editor to want just any view to control it, so |
| this is also left as a task for the editor part itself. SSE's <code>ConfigurableContentOutlinePage</code> |
| allows anyone to add an <code>IDoubleClickListener</code> to it, and |
| multi-page editors built around the <code>StructuredTextEditors</code> |
| would be expected to do so (<code>StructuredTextEditor</code> |
| already does this if it creates the page) to respond to double-click |
| events within the outline.</dd> |
| |
| <dt>How to synchronize selection from one view to another view:</dt> |
| <dd>The first view is set up to provide selection notification to |
| the selection service. The second view can then be driven from the |
| first view's selection just as it would by an editor's selection. |
| For a concrete example, when editing HTML, the <code>StructuredTextEditor</code> |
| will provide its <code>IStructuredSelection</code> using DOM nodes. |
| It's Outline provides <code>IStructuredSelection</code> using the |
| same DOM nodes. The SSE Property Sheet can't tell the difference, |
| and since it's only ever showing the properties of nodes supplied |
| through the selection (which is now always an <code>IStructuredSelection</code>), |
| it doesn't even need an <code>IStructuredModel</code> to be set on |
| it--the node is supplied by the active part, whether it's the |
| editor, outline, or otherwise.</dd> |
| |
| <dt>Synchronizing selection within a Multi-Page Editor:</dt> |
| <dd>Currently, the main multi-page editor class must synchronize the |
| selection between its pages by itself. For reference, <code>ITextEditor</code> |
| returns an <code>ISelectionProvider</code> as part of its interface |
| and the SSE <code>IDesignViewer</code> has been changed to do so as |
| well. The provided <code>XMLMultiPageEditorPart</code> synchronizes |
| using these interfaces and relies on the source viewer to notify the |
| selection service.</dd> |
| |
| <dt>Avoiding selection notification loops:</dt> |
| <dd>Setting the selection into a viewer causes it to also fire |
| selection notifications, so if two viewers are synchronizing |
| selection based on post selection notification, they might end up |
| looping endlessly notifying each other when selection is applied to |
| their Controls. The selection objects themselves will be different |
| as each viewer will be generating a fresh selection event and |
| selection from the underlying <code>Control</code>. The recommended |
| solution for this problem is to make sure that a part never updates |
| its selection from outside notification when it is the active part, |
| nor when it is sending selection (or post selection) notification |
| itself.</dd> |
| |
| <dt>Listening to the selection service</dt> |
| <dd>Editors should not just be a listener of the selection service |
| since selection changes in every part (including some listening for |
| changes in that same editor) would be received.</dd> |
| |
| <dt>How to get selected "nodes" and text from a |
| StructuredTextEditor:</dt> |
| <dd>The <code>StructuredTextEditor</code>'s selection provider |
| returns an <code>ITextSelection & IStructuredSelection</code> |
| combination when <code>ISelectionProvider.getSelection()</code> is |
| called. Casting to an <code>IStructuredSelection</code> will give |
| you the selected <code>IndexedNodes</code> for the current text |
| selection. Casting to an <code>ITextSelection</code> will give the |
| current text selection, just as you would receive from other text |
| editors.<br> |
| Caution: <code>IStructuredSelection</code> does not provide explicit |
| typing for its selected objects (<code>NodeSelectionChangedEvent</code> |
| didn't, either).</dd> |
| |
| <dt>How to manage double-click:</dt> |
| <dd>As of now, we haven't provided a unified way to do this, and |
| we're currently not planning to. Like selection, double-click does |
| different things in different places. The <code>XMLMultiPageEditorPart</code> |
| won't handle double-click from its design page to its source page |
| properly in 1.0M8, that will be released early in 1.0M9 development.</dd> |
| </dl> |
| </td> |
| </tr> |
| <tr id="references_header"> |
| <td valign="top" bgcolor="#0080c0" align="left" colspan="2"><b><font |
| face="Arial,Helvetica" color="#ffffff">API references</font></b></td> |
| </tr> |
| <tr id="references_content"> |
| <td valign="top" align="right"> </td> |
| <td valign="top"><a |
| href="http://help.eclipse.org/help31/topic/org.eclipse.platform.doc.isv/reference/api/org/eclipse/jface/text/ITextSelection.html">org.eclipse.jface.text.ITextSelection</a><br> |
| <a |
| href="http://help.eclipse.org/help31/topic/org.eclipse.platform.doc.isv/reference/api/org/eclipse/jface/viewers/IPostSelectionProvider.html">org.eclipse.jface.viewers.IPostSelectionProvider</a><br> |
| <a |
| href="http://help.eclipse.org/help31/topic/org.eclipse.platform.doc.isv/reference/api/org/eclipse/jface/viewers/ISelection.html">org.eclipse.jface.viewers.ISelection</a><br> |
| <a |
| href="http://help.eclipse.org/help31/topic/org.eclipse.platform.doc.isv/reference/api/org/eclipse/jface/viewers/ISelectionChangedListener.html">org.eclipse.jface.viewers.ISelectionChangedListener</a><br> |
| <a |
| href="http://help.eclipse.org/help31/topic/org.eclipse.platform.doc.isv/reference/api/org/eclipse/jface/viewers/ISelectionProvider.html">org.eclipse.jface.viewers.ISelectionProvider</a><br> |
| <a |
| href="http://help.eclipse.org/help31/topic/org.eclipse.platform.doc.isv/reference/api/org/eclipse/jface/viewers/IStructuredSelection.html">org.eclipse.jface.viewers.IStructuredSelection</a><br> |
| <a |
| href="http://help.eclipse.org/help31/topic/org.eclipse.platform.doc.isv/reference/api/org/eclipse/ui/ISelectionService.html">org.eclipse.ui.ISelectionService</a> |
| <br> |
| <br> |
| <br> |
| </td> |
| </tr> |
| <tr id="misc_header"> |
| <td valign="top" bgcolor="#0080c0" align="left" colspan="2"><b><font |
| face="Arial,Helvetica" color="#ffffff">Other changes of interest:</font></b></td> |
| </tr> |
| <tr id="misc_content"> |
| <td valign="top" align="right"> </td> |
| <td valign="top"> |
| <ul> |
| <li><code>org.eclipse.wst.sse.ui.internal.ViewerSelectionManager</code> |
| - deprecated |
| <li><code>org.eclipse.wst.sse.ui.internal.CaretMediator</code> - |
| deprecated |
| <li><code>org.eclipse.wst.sse.ui.internal.view.events</code> - |
| entire package deprecated |
| <li>The selection range shown on the left of the source editor are |
| not the same for XML languages as they were before. Code in |
| org.eclipse.wst.sse.ui used to take advantage of the <code>org.w3c.Node</code> |
| interfaces being in the JRE to base the selection range on a parent |
| <code>Element</code> if a <code>Text</code> node was the selected |
| node. This made assumptions about the nature of the <code>IndexedNodes</code> |
| of an <code>IStructuredModel</code> that shouldn't be known in the |
| core SSE UI plugin. When the caret is within a <code>Text</code> |
| node you will now see a selection range reflecting the <code>Text |
| Node</code> itself. |
| </ul> |
| </td> |
| </tr> |
| </tbody> |
| </table> |
| <hr> |
| |
| |
| |
| </body> |
| </html> |
