org.eclipse.handly.ui

## Class EditorUtility

- java.lang.Object
- - org.eclipse.handly.ui.EditorUtility

- Direct Known Subclasses:
    DefaultEditorUtility

      public class EditorUtility
      extends java.lang.Object

  Provides common methods for working with model elements in editors (such as finding an editor reference for an element and revealing an element in an editor).

  The implementations of the methods in this class strive to provide a reasonable default behavior and work fine for most cases. Clients can use the `default` instance of the editor utility or may subclass this class if they need to specialize the default behavior.

  Restriction:
    This class is not intended to be instantiated by clients.

- - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `EditorUtility()` Prevents direct instantiation by clients.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `org.eclipse.ui.IEditorReference` | `findEditor(org.eclipse.ui.IWorkbenchPage page, java.lang.Object element)` Given a workbench page, finds and returns the reference for an editor that matches the given element.
    `protected IBuffer` | `getBuffer(ISourceElement element)` Returns the buffer for the given source element, or `null` if the element has no corresponding buffer or if an exception occurs while obtaining the buffer.
    `org.eclipse.ui.IEditorInput` | `getEditorInput(java.lang.Object element)` Returns the editor input for the given element, or `null` if no editor input corresponds to the element.
    `void` | `revealElement(org.eclipse.ui.IEditorPart editor, java.lang.Object element)` Reveals the given element in the given editor on a best effort basis.
    `void` | `revealTextRange(org.eclipse.ui.IEditorPart editor, int offset, int length, ISnapshot snapshot)` Reveals the given text range in the given editor on a best effort basis.

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

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

- - ### Constructor Detail

    - #### EditorUtility

          protected EditorUtility()

      Prevents direct instantiation by clients. Use `DefaultEditorUtility.INSTANCE` if you need an instance of the editor utility with the default behavior.

  - ### Method Detail

    - #### getEditorInput

          public org.eclipse.ui.IEditorInput getEditorInput(java.lang.Object element)

      Returns the editor input for the given element, or `null` if no editor input corresponds to the element.

      If the given element is an editor input, this implementation returns the element itself. Otherwise, it attempts to find a resource that corresponds to the given element and, if the corresponding resource is a file, returns a `FileEditorInput` based on the resource. The corresponding resource is determined as follows:

      - If the input element is an `IResource`, the corresponding resource is the element itself.
      - Otherwise, if the given element could be adapted to an `IElement`, the corresponding resource is obtained via `Elements.getResource(IElement)`.
      - Otherwise, the given element is adapted to an `IResource` via `ResourceUtil.getResource(Object)`.
      Parameters:
        `element` - may be `null`
      Returns:
        the corresponding editor input, or `null` if none

    - #### findEditor

          public org.eclipse.ui.IEditorReference findEditor(org.eclipse.ui.IWorkbenchPage page,
                                                            java.lang.Object element)

      Given a workbench page, finds and returns the reference for an editor that matches the given element. If several matching editors are found within the page, returns the reference for the 'most specific' editor, which would typically be the most recently used matching editor. Returns `null` if there are no matching editors.

      This implementation asks the workbench page to find editor references that match the editor input provided for the given element by `getEditorInput(Object)` and returns the reference for the most recently used matching editor. If the given element could be adapted to an `IElement` and the adapter element is an `ISourceElement`, it is additionally required for matching editors which could be adapted to an `ITextEditor` that the text editor's document equals the document of the source element's `buffer`.

      Parameters:
        `page` - not `null`
        `element` - not `null`
      Returns:
        the matching editor reference, or `null` if none

    - #### revealElement

          public void revealElement(org.eclipse.ui.IEditorPart editor,
                                    java.lang.Object element)

      Reveals the given element in the given editor on a best effort basis.

      If the given element could be adapted to an `IElement` and the adapter element is an `ISourceElement`, and if the given editor could be adapted to an `ITextEditor`, this implementation attempts to select and reveal the source element's identifying range in the text editor, provided that the text editor's document equals the document of the source element's `buffer`. If all else fails, a structured selection containing a single object, the given element, is passed to the selection provider of the given editor.

      Parameters:
        `editor` - not `null`
        `element` - not `null`

    - #### revealTextRange

          public void revealTextRange(org.eclipse.ui.IEditorPart editor,
                                      int offset,
                                      int length,
                                      ISnapshot snapshot)

      Reveals the given text range in the given editor on a best effort basis.

      If the given editor could be adapted to an `ITextEditor`, this implementation calls `ITextEditor.selectAndReveal(int, int)`. Otherwise, if the given editor could be adapted to an `IGotoMarker`, this implementation creates a temporary text marker on the `IFile` corresponding to the editor input (if such a file exists) and calls `IGotoMarker.gotoMarker(IMarker)`. As a fallback, a text selection for the given range is passed to the selection provider of the given editor.

      Parameters:
        `editor` - not `null`
        `offset` - the offset of the text range (not negative)
        `length` - the length of the text range (not negative)
        `snapshot` - a snapshot on which the given text range is based, or `null` if the snapshot is unknown or does not matter
      Throws:
        `StaleSnapshotException` - if the given snapshot could be detected to be stale

    - #### getBuffer

          protected IBuffer getBuffer(ISourceElement element)

      Returns the buffer for the given source element, or `null` if the element has no corresponding buffer or if an exception occurs while obtaining the buffer.

      If the given element is contained in a source file, this implementation delegates to `Elements.getBuffer(ISourceFile)`, suppressing and logging a `CoreException` if necessary.

      Parameters:
        `element` - not `null`
      Returns:
        the corresponding buffer, or `null` if none

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