org.eclipse.handly.ui.outline

## Class SourceElementLinkingHelper

- java.lang.Object
- - org.eclipse.ui.OpenAndLinkWithEditorHelper
  - - org.eclipse.handly.ui.outline.OutlineLinkingHelper
    - - org.eclipse.handly.ui.outline.SourceElementLinkingHelper

-     public class SourceElementLinkingHelper
      extends OutlineLinkingHelper

  Implements linking logic for outlines of `ISourceElement`s.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected IInputElementProvider` | `inputElementProvider` The input element provider for this linking helper.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `SourceElementLinkingHelper(ICommonOutlinePage outlinePage, IInputElementProvider inputElementProvider)` Creates a new source element linking helper for the given outline page with the given input element provider.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `dispose()`
    `protected IContentAdapter` | `getContentAdapter()` Returns the installed content adapter, or a `NullContentAdapter` if none.
    `protected org.eclipse.jface.viewers.IStructuredSelection` | `getLinkedSelection(org.eclipse.jface.viewers.ISelection selection, org.eclipse.core.runtime.IProgressMonitor monitor)` Returns the outline selection corresponding to the given selection in the editor.
    `protected org.eclipse.jface.viewers.IStructuredSelection` | `getLinkedSelection(org.eclipse.jface.text.ITextSelection selection, org.eclipse.core.runtime.IProgressMonitor monitor)` Returns the outline selection corresponding to the given text selection in the editor.
    `protected org.eclipse.ui.IEditorPart` | `getTargetEditor()` Returns the editor the outline should be linked to.
    `protected boolean` | `isInEditor(IElement element, org.eclipse.ui.IEditorPart editor)` Returns whether the given element is contained in the given editor.
    `protected void` | `linkToEditor(org.eclipse.jface.viewers.ISelection selection)` Tells to link the given outline selection to the editor.
    `protected void` | `linkToEditor(org.eclipse.ui.texteditor.ITextEditor editor, org.eclipse.jface.viewers.IStructuredSelection selection)` Tells to link the given outline selection to the given text editor.
    `protected void` | `linkToOutline(org.eclipse.jface.viewers.ISelection selection)` Tells to link the given editor selection to the outline.

    - ### Methods inherited from class org.eclipse.handly.ui.outline.OutlineLinkingHelper

      `activate, getOutlinePage, open, setLinkWithEditor`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### inputElementProvider

          protected final IInputElementProvider inputElementProvider

      The input element provider for this linking helper.

  - ### Constructor Detail

    - #### SourceElementLinkingHelper

          public SourceElementLinkingHelper(ICommonOutlinePage outlinePage,
                                            IInputElementProvider inputElementProvider)

      Creates a new source element linking helper for the given outline page with the given input element provider.
      Parameters:
        `outlinePage` - not `null`
        `inputElementProvider` - an input element provider

  - ### Method Detail

    - #### dispose

          public void dispose()

      Overrides:
        `dispose` in class `OutlineLinkingHelper`

    - #### linkToOutline

          protected final void linkToOutline(org.eclipse.jface.viewers.ISelection selection)

      Tells to link the given editor selection to the outline.

      This implementation does nothing if the given selection is `null` or empty. Otherwise, it schedules a background job to compute and set the new outline selection. The selection is computed using `getLinkedSelection(ISelection, IProgressMonitor)`.

      Specified by:
        `linkToOutline` in class `OutlineLinkingHelper`
      Parameters:
        `selection` - the editor selection (may be `null` or empty)

    - #### linkToEditor

          protected void linkToEditor(org.eclipse.jface.viewers.ISelection selection)

      Tells to link the given outline selection to the editor.

      This implementation does nothing if the given selection is `null` or empty. Otherwise, it calls `getTargetEditor()` to determine the editor that the outline should be linked to. It then delegates to `linkToEditor(ITextEditor, IStructuredSelection)` if the target editor is a text editor. Otherwise, it simply passes the given selection to the editor's selection provider.

      Specified by:
        `linkToEditor` in class `OutlineLinkingHelper`
      Parameters:
        `selection` - the outline selection (may be `null` or empty)

    - #### linkToEditor

          protected void linkToEditor(org.eclipse.ui.texteditor.ITextEditor editor,
                                      org.eclipse.jface.viewers.IStructuredSelection selection)

      Tells to link the given outline selection to the given text editor.

      This implementation attempts to adapt the selection's first element to an `IElement` through the `content adapter`. If the adapter element is an `ISourceElement` and is contained in the given editor as computed by `isInEditor(IElement, IEditorPart)`, the identifying range of the source element is selected and revealed in the text editor.

      Parameters:
        `editor` - the text editor (never `null`)
        `selection` - the outline selection (never `null`, never empty)

    - #### getLinkedSelection

          protected org.eclipse.jface.viewers.IStructuredSelection getLinkedSelection(org.eclipse.jface.viewers.ISelection selection,
                                                                                      org.eclipse.core.runtime.IProgressMonitor monitor)

      Returns the outline selection corresponding to the given selection in the editor.

      This implementation delegates to `getLinkedSelection(ITextSelection, IProgressMonitor)` if the given selection is a text selection. If the given selection is a structured selection, it is returned unchanged. Otherwise, `null` is returned.

      Parameters:
        `selection` - the selection in the editor (never `null`, never empty)
        `monitor` - a progress monitor (never `null`). The caller must not rely on `IProgressMonitor.done()` having been called by the receiver
      Returns:
        the outline selection corresponding to the given selection in the editor, or `null`
      Throws:
        `org.eclipse.core.runtime.OperationCanceledException` - if this method is canceled

    - #### getLinkedSelection

          protected org.eclipse.jface.viewers.IStructuredSelection getLinkedSelection(org.eclipse.jface.text.ITextSelection selection,
                                                                                      org.eclipse.core.runtime.IProgressMonitor monitor)

      Returns the outline selection corresponding to the given text selection in the editor.

      This implementation finds the smallest `ISourceElement` that includes the offset of the given selection and returns a selection containing a single outline element corresponding to the found source element, as determined by the `content adapter`.

      Parameters:
        `selection` - the text selection in the editor (never `null`, never empty)
        `monitor` - a progress monitor (never `null`). The caller must not rely on `IProgressMonitor.done()` having been called by the receiver
      Returns:
        the outline selection corresponding to the given selection in the editor, or `null`
      Throws:
        `org.eclipse.core.runtime.OperationCanceledException` - if this method is canceled

    - #### getTargetEditor

          protected org.eclipse.ui.IEditorPart getTargetEditor()

      Returns the editor the outline should be linked to.

      This implementation returns the editor that created the outline page or, if that editor is a multi-page editor, the currently selected editor page.

      Returns:
        the editor the outline should be linked to, or `null`

    - #### isInEditor

          protected boolean isInEditor(IElement element,
                                       org.eclipse.ui.IEditorPart editor)

      Returns whether the given element is contained in the given editor.

      This implementation uses the `input element provider` to obtain an `IElement` corresponding to the editor input. It then checks whether the `IElement` `contains` the given element and returns the result.

      Parameters:
        `element` - may be `null`
        `editor` - not `null`
      Returns:
        `true` if the element is contained in the editor, and `false` otherwise

    - #### getContentAdapter

          protected IContentAdapter getContentAdapter()

      Returns the installed content adapter, or a `NullContentAdapter` if none.

      This implementation returns the content adapter provided by the outline page, if the outline page is an `IContentAdapterProvider`.

      Returns:
        an `IContentAdapter` (never `null`)

Copyright (c) 2014, 2020 1C-Soft LLC and others. Made available under the Eclipse Public License 2.0