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

  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 Predicate<Object>`
  `createPatternMatcher(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 final org.eclipse.swt.widgets.Text`
  `getFilterText()`
  Returns the filter text control of this outline popup.
  `protected Object`
  `getFocalElement()`
  Returns the current focal element for this outline popup.
  `protected org.eclipse.swt.widgets.Control`
  `getFocusControl()`
  `protected final Predicate<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 final void`
  `updatePatternMatcher(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, 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 Details

  - ### FilteringOutlinePopup

    public FilteringOutlinePopup()

- ## Method Details

  - ### 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 Predicate<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(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 Predicate<Object> createPatternMatcher(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 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