Package org.eclipse.handly.ui.quickoutline

## Class FilteringOutlinePopup

- java.lang.Object
- - org.eclipse.jface.window.Window
  - - org.eclipse.jface.dialogs.PopupDialog
    - - org.eclipse.handly.ui.quickoutline.OutlinePopup
      - - org.eclipse.handly.ui.quickoutline.FilteringOutlinePopup

- All Implemented Interfaces:
    `org.eclipse.jface.window.IShellProvider`
  Direct Known Subclasses:
    `HandlyOutlinePopup`

      public abstract class FilteringOutlinePopup
      extends OutlinePopup

  An abstract implementation of an outline popup that supports filtering based on a pattern inputed by the user.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class | Description
    --- | --- | ---
    `protected class` | `FilteringOutlinePopup.ElementMatcher` | A pattern-based element matcher for the outline popup.
    `protected class` | `FilteringOutlinePopup.FilteringOutlineTreeViewer` | Extends `OutlinePopup.OutlineTreeViewer` to allow expanding any tree item when the pattern-based filter is active.
    `protected static class` | `FilteringOutlinePopup.StringMatcher` | A string pattern matcher that supports '*' and '?' wildcards.

    - ### Nested classes/interfaces inherited from class org.eclipse.handly.ui.quickoutline.OutlinePopup

      `OutlinePopup.OutlineTreeViewer`

    - ### Nested classes/interfaces inherited from class org.eclipse.jface.window.Window

      `org.eclipse.jface.window.Window.IExceptionHandler`

  - ### Field Summary

    - ### Fields inherited from class org.eclipse.jface.dialogs.PopupDialog

      `HOVER_SHELLSTYLE, INFOPOPUP_SHELLSTYLE, INFOPOPUPRESIZE_SHELLSTYLE, POPUP_HORIZONTALSPACING, POPUP_IMG_MENU, POPUP_IMG_MENU_DISABLED, POPUP_MARGINHEIGHT, POPUP_MARGINWIDTH, POPUP_VERTICALSPACING`

    - ### Fields inherited from class org.eclipse.jface.window.Window

      `CANCEL, OK, resizeHasOccurred`

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `FilteringOutlinePopup()` |

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `protected org.eclipse.swt.widgets.Text` | `createFilterText​(org.eclipse.swt.widgets.Composite parent)` | Creates the text control to be used for entering the filter pattern.
    `protected java.util.function.Predicate<java.lang.Object>` | `createPatternMatcher​(java.lang.String pattern)` | Returns a new pattern matcher based on the given pattern.
    `protected org.eclipse.swt.widgets.Control` | `createTitleControl​(org.eclipse.swt.widgets.Composite parent)`
    `protected org.eclipse.swt.widgets.Control` | `createTitleMenuArea​(org.eclipse.swt.widgets.Composite parent)` |
    `protected org.eclipse.jface.viewers.TreeViewer` | `createTreeViewer​(org.eclipse.swt.widgets.Composite parent)` | Creates a tree viewer for this outline popup.
    `protected org.eclipse.swt.widgets.Text` | `getFilterText()` | Returns the filter text control of this outline popup.
    `protected java.lang.Object` | `getFocalElement()` | Returns the current focal element for this outline popup.
    `protected org.eclipse.swt.widgets.Control` | `getFocusControl()` |
    `protected java.util.function.Predicate<java.lang.Object>` | `getPatternMatcher()` | Returns the current pattern matcher for this outline popup.
    `void` | `init​(IOutlinePopupHost host, org.eclipse.jface.bindings.keys.KeyStroke invokingKeyStroke)` | Initializes this outline popup with the given host and, optionally, invoking keystroke.
    `protected void` | `patternMatcherUpdated()` | Notifies that the pattern matcher has been updated.
    `protected void` | `selectFirstMatch()` | Selects the first element that matches the current filter pattern.
    `protected void` | `setTabOrder​(org.eclipse.swt.widgets.Composite composite)` |
    `protected void` | `updatePatternMatcher​(java.lang.String pattern)` | Updates the current pattern matcher to an instance `created` for the given pattern and `notifies` of the update.

    - ### Methods inherited from class org.eclipse.handly.ui.quickoutline.OutlinePopup

      `changeOutlineMode, computeInitialSelection, computeInput, createDialogArea, getContentProvider, getCorrespondingElement, getDefaultLocation, getDialogSettings, getHost, getInitialSelection, getInvokingKeyListener, getInvokingKeyStroke, getLabelProvider, getSelectedElement, getTreeViewer, gotoSelectedElement, initDecorationContext, isAutoExpandable, revealInHost, shouldUseHashlookup, updateInfoText`

    - ### Methods inherited from class org.eclipse.jface.dialogs.PopupDialog

      `adjustBounds, applyBackgroundColor, applyForegroundColor, close, configureShell, createContents, createInfoTextArea, fillDialogMenu, getBackground, getBackgroundColorExclusions, getDefaultSize, getForeground, getForegroundColorExclusions, getInitialLocation, getInitialSize, getPersistBounds, getPersistLocation, getPersistSize, hasInfoArea, hasTitleArea, open, saveDialogBounds, setInfoText, setTitleText, showDialogMenu`

    - ### Methods inherited from class org.eclipse.jface.window.Window

      `canHandleShellCloseEvent, constrainShellSize, create, createShell, getConstrainedShellBounds, getContents, getDefaultImage, getDefaultImages, getDefaultOrientation, getLayout, getParentShell, getReturnCode, getShell, getShellListener, getShellStyle, getWindowManager, handleFontChange, handleShellCloseEvent, initializeBounds, setBlockOnOpen, setDefaultImage, setDefaultImages, setDefaultModalParent, setDefaultOrientation, setExceptionHandler, setParentShell, setReturnCode, setShellStyle, setWindowManager`

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

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

- - ### Constructor Detail

    - #### FilteringOutlinePopup

          public FilteringOutlinePopup()

  - ### Method Detail

    - #### init

          public void init​(IOutlinePopupHost host,
                           org.eclipse.jface.bindings.keys.KeyStroke invokingKeyStroke)

      Initializes this outline popup with the given host and, optionally, invoking keystroke. This method must be called by clients before attempting to `open` the outline popup.

      This method may be extended by subclasses. Subclasses must call the superclass implementation.

      `OutlinePopup` implementation of this method sets the parent shell to the shell of the SWT control of the given host, creates all controls of the outline popup, including the `tree viewer`, initializes the tree viewer with the `content`- and `label` providers as well as the `input`, and sets the `initial selection` in the tree viewer and the `text` in the popup's info area.

      `FilteringOutlinePopup` extends this method to add a `pattern matcher` based filter to the outline popup's tree viewer.

      Overrides:
        `init` in class `OutlinePopup`
      Parameters:
        `host` - the host of this outline popup (not `null`)
        `invokingKeyStroke` - the keystroke for invoking this outline popup, or `null` if none

    - #### getFilterText

          protected final org.eclipse.swt.widgets.Text getFilterText()

      Returns the filter text control of this outline popup.
      Returns:
        the filter text control of this outline popup, or `null` if it has not been created yet

    - #### getPatternMatcher

          protected final java.util.function.Predicate<java.lang.Object> getPatternMatcher()

      Returns the current pattern matcher for this outline popup.
      Returns:
        the current pattern matcher for this outline popup, or `null` if none
      See Also:
        `updatePatternMatcher(String)`

    - #### getFocusControl

          protected org.eclipse.swt.widgets.Control getFocusControl()

      Overrides:
        `getFocusControl` in class `OutlinePopup`

    - #### setTabOrder

          protected void setTabOrder​(org.eclipse.swt.widgets.Composite composite)

      Overrides:
        `setTabOrder` in class `OutlinePopup`

    - #### createTreeViewer

          protected org.eclipse.jface.viewers.TreeViewer createTreeViewer​(org.eclipse.swt.widgets.Composite parent)

      Creates a tree viewer for this outline popup. The viewer has no input, no content provider, a default label provider, no sorter, and no filters. This method is called once, when the popup's control is created.

      This implementation returns a new instance of `FilteringOutlinePopup.FilteringOutlineTreeViewer`.

      Overrides:
        `createTreeViewer` in class `OutlinePopup`
      Parameters:
        `parent` - the parent composite (never `null`)
      Returns:
        the created tree viewer (not `null`)

    - #### createTitleMenuArea

          protected org.eclipse.swt.widgets.Control createTitleMenuArea​(org.eclipse.swt.widgets.Composite parent)

      Overrides:
        `createTitleMenuArea` in class `org.eclipse.jface.dialogs.PopupDialog`

    - #### createTitleControl

          protected org.eclipse.swt.widgets.Control createTitleControl​(org.eclipse.swt.widgets.Composite parent)

      This implementation creates the `filter text` control. It uses `createFilterText(Composite)` to create the control.

      Overrides:
        `createTitleControl` in class `org.eclipse.jface.dialogs.PopupDialog`

    - #### createFilterText

          protected org.eclipse.swt.widgets.Text createFilterText​(org.eclipse.swt.widgets.Composite parent)

      Creates the text control to be used for entering the filter pattern.

      This implementation creates a text control that:

      - Invokes `updatePatternMatcher(String)` when the text is modified.
      - Invokes `OutlinePopup.gotoSelectedElement()` when the ENTER key is pressed.
      - Sets the keyboard focus to the tree viewer when the DOWN ARROW or UP ARROW key is pressed.
      - Invokes `PopupDialog.close()` when the ESC key is pressed.

      If an `invoking key` is set, this implementation adds the `invoking key listener` to the created control.

      Parameters:
        `parent` - the parent composite (never `null`)
      Returns:
        the created filter text control (not `null`)

    - #### updatePatternMatcher

          protected final void updatePatternMatcher​(java.lang.String pattern)

      Updates the current pattern matcher to an instance `created` for the given pattern and `notifies` of the update.
      Parameters:
        `pattern` - the pattern string (not `null`)
      See Also:
        `getPatternMatcher()`

    - #### createPatternMatcher

          protected java.util.function.Predicate<java.lang.Object> createPatternMatcher​(java.lang.String pattern)

      Returns a new pattern matcher based on the given pattern. May return `null` if no filtering is required.

      This implementation returns `null` if the pattern is an empty string. Otherwise, it appends '*' to the pattern if the pattern does not already end with '*', and returns an `FilteringOutlinePopup.ElementMatcher` based on a `FilteringOutlinePopup.StringMatcher` for the pattern. Case-insensitive matching is enabled if, and only if, the pattern is all lower-case.

      Parameters:
        `pattern` - the pattern string (not `null`)
      Returns:
        the created pattern matcher, or `null` if no filtering is required

    - #### patternMatcherUpdated

          protected void patternMatcherUpdated()

      Notifies that the pattern matcher has been updated.

      This implementation refreshes the tree viewer, expands all nodes of the tree, and `selects` the first matching element.

    - #### selectFirstMatch

          protected void selectFirstMatch()

      Selects the first element that matches the current filter pattern.

      This implementation starts the search from the `focal element`. If there is no focal element, the search is started from the root of the tree.

    - #### getFocalElement

          protected java.lang.Object getFocalElement()

      Returns the current focal element for this outline popup.

      This implementation returns the `initially selected` element. Subclasses may override.

      Returns:
        the current focal element for this outline popup, or `null` if none