org.eclipse.ui.dialogs

## Class FilteredItemsSelectionDialog

- java.lang.Object
- - org.eclipse.jface.window.Window
  - - org.eclipse.jface.dialogs.Dialog
    - - org.eclipse.jface.dialogs.TrayDialog
      - - org.eclipse.ui.dialogs.SelectionDialog
        - - org.eclipse.ui.dialogs.SelectionStatusDialog
          - - org.eclipse.ui.dialogs.FilteredItemsSelectionDialog

All Implemented Interfaces:
  IShellProvider

Direct Known Subclasses:
  FilteredResourcesSelectionDialog

    public abstract class FilteredItemsSelectionDialog
    extends SelectionStatusDialog

Shows a list of items to the user with a text entry field for a string pattern used to filter the list of items.

Since:
  3.3

### Nested Class Summary

Nested Classes
`protected class` `FilteredItemsSelectionDialog.AbstractContentProvider` An interface to content providers for `FilterItemsSelectionDialog`.
`protected class` `FilteredItemsSelectionDialog.ItemsFilter` Filters elements using SearchPattern by comparing the names of items with the filter pattern.
`protected static class` `FilteredItemsSelectionDialog.SelectionHistory` History stores a list of key, object pairs.

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

`Window.IExceptionHandler`

### Field Summary

Fields
`static int` `CARET_BEGINNING` Pattern input field selection where caret is at the beginning (used only for initial pattern).
`static int` `FULL_SELECTION` Represents a full selection in the pattern input field (used only for initial pattern).
`static int` `NONE` Represents an empty selection in the pattern input field (used only for initial pattern).

### Fields inherited from class org.eclipse.jface.dialogs.Dialog

`blockedHandler, buttonBar, DIALOG_DEFAULT_BOUNDS, DIALOG_PERSISTLOCATION, DIALOG_PERSISTSIZE, dialogArea, DLG_IMG_ERROR, DLG_IMG_HELP, DLG_IMG_INFO, DLG_IMG_MESSAGE_ERROR, DLG_IMG_MESSAGE_INFO, DLG_IMG_MESSAGE_WARNING, DLG_IMG_QUESTION, DLG_IMG_WARNING, ELLIPSIS`

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

`CANCEL, OK, resizeHasOccurred`

### Constructor Summary

Constructors
Constructor and Description
`FilteredItemsSelectionDialog(Shell shell)` Creates a new instance of the class.
`FilteredItemsSelectionDialog(Shell shell, boolean multi)` Creates a new instance of the class.

### Method Summary

All Methods Instance Methods Abstract Methods Concrete Methods Deprecated Methods
`protected void` `accessedHistoryItem(Object item)` Adds item to history.
`protected void` `addListFilter(ViewerFilter filter)` Adds viewer filter to the dialog items list.
`protected void` `applyFilter()` Applies the filter created by `createFilter()` method to the items list.
`boolean` `close()` Closes this window, disposes its shell, and removes this window from its window manager (if it has one).
`protected void` `computeResult()` Compute the result and return it.
`void` `create()` Creates this window's widgetry in a new top-level shell.
`protected Control` `createDialogArea(Composite parent)` Creates and returns the contents of the upper part of this dialog (above the button bar).
`protected abstract Control` `createExtendedContentArea(Composite parent)` Creates an extra content area, which will be located above the details.
`protected abstract FilteredItemsSelectionDialog.ItemsFilter` `createFilter()` Creates an instance of a filter.
`protected abstract void` `fillContentProvider(FilteredItemsSelectionDialog.AbstractContentProvider contentProvider, FilteredItemsSelectionDialog.ItemsFilter itemsFilter, IProgressMonitor progressMonitor)` Fills the content provider with matching items.
`protected void` `fillContextMenu(IMenuManager menuManager)` Hook that allows to add actions to the context menu.
`protected void` `fillViewMenu(IMenuManager menuManager)` Fills the menu of the dialog.
`protected IDialogSettings` `getDialogBoundsSettings()` Gets the dialog settings that should be used for remembering the bounds of the dialog, according to the dialog bounds strategy.
`protected abstract IDialogSettings` `getDialogSettings()` Returns the dialog settings.
`abstract String` `getElementName(Object item)` Returns name for then given object.
`protected String` `getInitialPattern()` Gets initial pattern.
`protected abstract Comparator` `getItemsComparator()` Returns comparator to sort items inside content provider.
`Control` `getPatternControl()` Get the control where the search pattern is entered.
`protected StructuredSelection` `getSelectedItems()` Returns the current selection.
`protected FilteredItemsSelectionDialog.SelectionHistory` `getSelectionHistory()` Returns the history of selected elements.
`protected void` `handleDoubleClick()` This method is a hook for subclasses to override default dialog behavior.
`protected void` `handleSelected(StructuredSelection selection)` Handle selection in the items list by updating labels of selected and unselected items and refresh the details field using the selection.
`boolean` `isDuplicateElement(Object item)` Indicates whether the given item is a duplicate.
`boolean` `isHistoryElement(Object item)` Indicates whether the given item is a history item.
`protected void` `okPressed()` Notifies that the ok button of this dialog has been pressed.
`void` `refresh()` Refreshes the dialog - has to be called in UI thread.
`void` `reloadCache(boolean checkDuplicates, IProgressMonitor monitor)` Notifies the content provider - fires filtering of content provider elements.
`protected Object` `removeHistoryItem(Object item)` Removes an item from history.
`protected void` `restoreDialog(IDialogSettings settings)` Restores dialog using persisted settings.
`void` `scheduleProgressMessageRefresh()` Schedules progress message refresh.
`void` `scheduleRefresh()` Schedule refresh job.
`void` `setDetailsLabelProvider(ILabelProvider detailsLabelProvider)` Sets label provider for the details field.
`void` `setInitialPattern(String text)` Sets the initial pattern used by the filter.
`void` `setInitialPattern(String text, int selectionMode)` Sets the initial pattern used by the filter.
`void` `setListLabelProvider(ILabelProvider listLabelProvider)` Sets a new label provider for items in the list.
`void` `setListSelectionLabelDecorator(ILabelDecorator listSelectionLabelDecorator)` Sets the label decorator for selected items in the list.
`protected void` `setSelectionHistory(FilteredItemsSelectionDialog.SelectionHistory selectionHistory)` Sets new history.
`void` `setSeparatorLabel(String separatorLabel)` Sets separator label
`protected void` `storeDialog(IDialogSettings settings)` Stores dialog settings.
`void` `updateProgressLabel()` Deprecated.
`protected void` `updateStatus(IStatus status)` Update the dialog's status line to reflect the given status.
`protected abstract IStatus` `validateItem(Object item)` Validates the item.

### Methods inherited from class org.eclipse.ui.dialogs.SelectionStatusDialog

`configureShell, createButtonBar, getFirstResult, setImage, setResult, setStatusLineAboveButtons, updateButtonsEnableState`

### Methods inherited from class org.eclipse.ui.dialogs.SelectionDialog

`createButtonsForButtonBar, createMessageArea, getDialogBoundsStrategy, getInitialElementSelections, getInitialSelections, getMessage, getOkButton, getResult, isResizable, setDialogBoundsSettings, setInitialElementSelections, setInitialSelections, setMessage, setResult, setSelectionResult, setTitle`

### Methods inherited from class org.eclipse.jface.dialogs.TrayDialog

`closeTray, createHelpControl, getLayout, getTray, handleShellCloseEvent, isDialogHelpAvailable, isHelpAvailable, openTray, setDialogHelpAvailable, setHelpAvailable`

### Methods inherited from class org.eclipse.jface.dialogs.Dialog

`applyDialogFont, buttonPressed, cancelPressed, convertHeightInCharsToPixels, convertHeightInCharsToPixels, convertHorizontalDLUsToPixels, convertHorizontalDLUsToPixels, convertVerticalDLUsToPixels, convertVerticalDLUsToPixels, convertWidthInCharsToPixels, convertWidthInCharsToPixels, createButton, createContents, dialogFontIsDefault, getBlockedHandler, getButton, getButtonBar, getCancelButton, getDialogArea, getImage, getInitialLocation, getInitialSize, getOKButton, initializeBounds, initializeDialogUnits, setBlockedHandler, setButtonLayoutData, setButtonLayoutFormData, shortenText`

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

`canHandleShellCloseEvent, constrainShellSize, createShell, getConstrainedShellBounds, getContents, getDefaultImage, getDefaultImages, getDefaultOrientation, getParentShell, getReturnCode, getShell, getShellListener, getShellStyle, getWindowManager, handleFontChange, open, 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`

### Field Detail

#### NONE

    public static final int NONE

Represents an empty selection in the pattern input field (used only for initial pattern).

See Also:
  Constant Field Values

#### CARET_BEGINNING

    public static final int CARET_BEGINNING

Pattern input field selection where caret is at the beginning (used only for initial pattern).

See Also:
  Constant Field Values

#### FULL_SELECTION

    public static final int FULL_SELECTION

Represents a full selection in the pattern input field (used only for initial pattern).

See Also:
  Constant Field Values

### Constructor Detail

#### FilteredItemsSelectionDialog

    public FilteredItemsSelectionDialog(Shell shell,
                                        boolean multi)

Creates a new instance of the class.

Parameters:
  `shell` - shell to parent the dialog on
  `multi` - indicates whether dialog allows to select more than one position in its list of items

#### FilteredItemsSelectionDialog

    public FilteredItemsSelectionDialog(Shell shell)

Creates a new instance of the class. Created dialog won't allow to select more than one item.

Parameters:
  `shell` - shell to parent the dialog on

### Method Detail

#### addListFilter

    protected void addListFilter(ViewerFilter filter)

Adds viewer filter to the dialog items list.

Parameters:
  `filter` - the new filter

#### setListLabelProvider

    public void setListLabelProvider(ILabelProvider listLabelProvider)

Sets a new label provider for items in the list. If the label provider also implements `.IStyledLabelProvider`, the style text labels provided by it will be used provided that the corresponding preference is set.

Parameters:
  `listLabelProvider` - the label provider for items in the list
See Also:
  `IWorkbenchPreferenceConstants.USE_COLORED_LABELS`

#### setListSelectionLabelDecorator

    public void setListSelectionLabelDecorator(ILabelDecorator listSelectionLabelDecorator)

Sets the label decorator for selected items in the list.

Parameters:
  `listSelectionLabelDecorator` - the label decorator for selected items in the list

#### setDetailsLabelProvider

    public void setDetailsLabelProvider(ILabelProvider detailsLabelProvider)

Sets label provider for the details field. For a single selection, the element sent to `ILabelProvider.getImage(Object)` and `ILabelProvider.getText(Object)` is the selected object, for multiple selection a `String` with amount of selected items is the element.

Parameters:
  `detailsLabelProvider` - the label provider for the details field
See Also:
  `getSelectedItems() can be used to retrieve selected items and get the items count.`

#### create

    public void create()

Description copied from class: `Window`
Creates this window's widgetry in a new top-level shell.

The default implementation of this framework method creates this window's shell (by calling `createShell`), and its controls (by calling `createContents`), then initializes this window's shell bounds (by calling `initializeBounds`).

Overrides:
  `create` in class `SelectionStatusDialog`

#### restoreDialog

    protected void restoreDialog(IDialogSettings settings)

Restores dialog using persisted settings. The default implementation restores the status of the details line and the selection history.

Parameters:
  `settings` - settings used to restore dialog

#### close

    public boolean close()

Description copied from class: `Window`
Closes this window, disposes its shell, and removes this window from its window manager (if it has one).

This framework method may be extended (`super.close` must be called).

Note that in order to prevent recursive calls to this method it does not call `Shell#close()`. As a result `ShellListener`s will not receive a `shellClosed` event.

Overrides:
  `close` in class `Dialog`
Returns:
  `true` if the window is (or was already) closed, and `false` if it is still open
See Also:
  `Window.close()`

#### storeDialog

    protected void storeDialog(IDialogSettings settings)

Stores dialog settings.

Parameters:
  `settings` - settings used to store dialog

#### fillViewMenu

    protected void fillViewMenu(IMenuManager menuManager)

Fills the menu of the dialog.

Parameters:
  `menuManager` - the menu manager

#### fillContextMenu

    protected void fillContextMenu(IMenuManager menuManager)

Hook that allows to add actions to the context menu.

Subclasses may extend in order to add other actions.

Parameters:
  `menuManager` - the context menu manager
Since:
  3.5

#### createExtendedContentArea

    protected abstract Control createExtendedContentArea(Composite parent)

Creates an extra content area, which will be located above the details.

Parameters:
  `parent` - parent to create the dialog widgets in
Returns:
  an extra content area

#### createDialogArea

    protected Control createDialogArea(Composite parent)

Description copied from class: `Dialog`
Creates and returns the contents of the upper part of this dialog (above the button bar).

The `Dialog` implementation of this framework method creates and returns a new `Composite` with standard margins and spacing.

The returned control's layout data must be an instance of `GridData`. This method must not modify the parent's layout.

Subclasses must override this method but may call `super` as in the following example:

     Composite composite = (Composite) super.createDialogArea(parent);
     //add controls to composite as necessary
     return composite;

Overrides:
  `createDialogArea` in class `Dialog`
Parameters:
  `parent` - the parent composite to contain the dialog area
Returns:
  the dialog area control

#### handleDoubleClick

    protected void handleDoubleClick()

This method is a hook for subclasses to override default dialog behavior. The `handleDoubleClick()` method handles double clicks on the list of filtered elements.

Current implementation makes double-clicking on the list do the same as pressing `OK` button on the dialog.

#### handleSelected

    protected void handleSelected(StructuredSelection selection)

Handle selection in the items list by updating labels of selected and unselected items and refresh the details field using the selection.

Parameters:
  `selection` - the new selection

#### getDialogBoundsSettings

    protected IDialogSettings getDialogBoundsSettings()

Description copied from class: `SelectionDialog`
Gets the dialog settings that should be used for remembering the bounds of the dialog, according to the dialog bounds strategy. Overridden to provide the dialog settings that were set using `SelectionDialog.setDialogBoundsSettings(IDialogSettings, int)`.

Overrides:
  `getDialogBoundsSettings` in class `SelectionDialog`
Returns:
  the dialog settings used to store the dialog's location and/or size, or `null` if the dialog's bounds should not be stored.
See Also:
  `Dialog.getDialogBoundsStrategy()`, `SelectionDialog.setDialogBoundsSettings(IDialogSettings, int)`

#### getDialogSettings

    protected abstract IDialogSettings getDialogSettings()

Returns the dialog settings. Returned object can't be null.

Returns:
  return dialog settings for this dialog

#### refresh

    public void refresh()

Refreshes the dialog - has to be called in UI thread.

#### updateProgressLabel

    @Deprecated
    public void updateProgressLabel()

Deprecated.
Updates the progress label.

#### reloadCache

    public void reloadCache(boolean checkDuplicates,
                            IProgressMonitor monitor)

Notifies the content provider - fires filtering of content provider elements. During the filtering, a separator between history and workspace matches is added.

This is a long running operation and should be called in a job.

Parameters:
  `checkDuplicates` - `true` if data concerning elements duplication should be computed - it takes much more time than the standard filtering
  `monitor` - a progress monitor or `null` if no monitor is available

#### scheduleRefresh

    public void scheduleRefresh()

Schedule refresh job.

#### scheduleProgressMessageRefresh

    public void scheduleProgressMessageRefresh()

Schedules progress message refresh.

#### computeResult

    protected void computeResult()

Description copied from class: `SelectionStatusDialog`
Compute the result and return it.

Specified by:
  `computeResult` in class `SelectionStatusDialog`

#### updateStatus

    protected void updateStatus(IStatus status)

Description copied from class: `SelectionStatusDialog`
Update the dialog's status line to reflect the given status. It is safe to call this method before the dialog has been opened.

Overrides:
  `updateStatus` in class `SelectionStatusDialog`

#### okPressed

    protected void okPressed()

Description copied from class: `Dialog`
Notifies that the ok button of this dialog has been pressed.

The `Dialog` implementation of this framework method sets this dialog's return code to `Window.OK` and closes the dialog. Subclasses may override.

Overrides:
  `okPressed` in class `SelectionStatusDialog`

#### setInitialPattern

    public void setInitialPattern(String text)

Sets the initial pattern used by the filter. This text is copied into the selection input on the dialog. A full selection is used in the pattern input field.

Parameters:
  `text` - initial pattern for the filter
See Also:
  `FULL_SELECTION`

#### setInitialPattern

    public void setInitialPattern(String text,
                                  int selectionMode)

Sets the initial pattern used by the filter. This text is copied into the selection input on the dialog. The `selectionMode` is used to choose selection type for the input field.

Parameters:
  `text` - initial pattern for the filter
  `selectionMode` - one of: `NONE`, `CARET_BEGINNING`, `FULL_SELECTION`

#### getInitialPattern

    protected String getInitialPattern()

Gets initial pattern.

Returns:
  initial pattern, or `null` if initial pattern is not set

#### getSelectedItems

    protected StructuredSelection getSelectedItems()

Returns the current selection.

Returns:
  the current selection

#### validateItem

    protected abstract IStatus validateItem(Object item)

Validates the item. When items on the items list are selected or deselected, it validates each item in the selection and the dialog status depends on all validations.

Parameters:
  `item` - an item to be checked
Returns:
  status of the dialog to be set

#### createFilter

    protected abstract FilteredItemsSelectionDialog.ItemsFilter createFilter()

Creates an instance of a filter.

Returns:
  a filter for items on the items list. Can be `null`, no filtering will be applied then, causing no item to be shown in the list.

#### applyFilter

    protected void applyFilter()

Applies the filter created by `createFilter()` method to the items list. When new filter is different than previous one it will cause refiltering.

#### getItemsComparator

    protected abstract Comparator getItemsComparator()

Returns comparator to sort items inside content provider. Returned object will be probably created as an anonymous class. Parameters passed to the `compare(java.lang.Object, java.lang.Object)` are going to be the same type as the one used in the content provider.

Returns:
  comparator to sort items content provider

#### fillContentProvider

    protected abstract void fillContentProvider(FilteredItemsSelectionDialog.AbstractContentProvider contentProvider,
                                                FilteredItemsSelectionDialog.ItemsFilter itemsFilter,
                                                IProgressMonitor progressMonitor)
                                         throws CoreException

Fills the content provider with matching items.

Parameters:
  `contentProvider` - collector to add items to. `FilteredItemsSelectionDialog.AbstractContentProvider.add(Object, FilteredItemsSelectionDialog.ItemsFilter)` only adds items that pass the given `itemsFilter`.
  `itemsFilter` - the items filter
  `progressMonitor` - must be used to report search progress. The state of this progress monitor reflects the state of the filtering process.
Throws:
  `CoreException`

#### removeHistoryItem

    protected Object removeHistoryItem(Object item)

Removes an item from history.

Parameters:
  `item` - an item to remove
Returns:
  removed item

#### accessedHistoryItem

    protected void accessedHistoryItem(Object item)

Adds item to history.

Parameters:
  `item` - the item to be added

#### getSelectionHistory

    protected FilteredItemsSelectionDialog.SelectionHistory getSelectionHistory()

Returns the history of selected elements.

Returns:
  history of selected elements, or `null` if it is not set

#### setSelectionHistory

    protected void setSelectionHistory(FilteredItemsSelectionDialog.SelectionHistory selectionHistory)

Sets new history.

Parameters:
  `selectionHistory` - the history

#### isHistoryElement

    public boolean isHistoryElement(Object item)

Indicates whether the given item is a history item.

Parameters:
  `item` - the item to be investigated
Returns:
  `true` if the given item exists in history, `false` otherwise

#### isDuplicateElement

    public boolean isDuplicateElement(Object item)

Indicates whether the given item is a duplicate.

Parameters:
  `item` - the item to be investigated
Returns:
  `true` if the item is duplicate, `false` otherwise

#### setSeparatorLabel

    public void setSeparatorLabel(String separatorLabel)

Sets separator label

Parameters:
  `separatorLabel` - the label showed on separator

#### getElementName

    public abstract String getElementName(Object item)

Returns name for then given object.

Parameters:
  `item` - an object from the content provider. Subclasses should pay attention to the passed argument. They should either only pass objects of a known type (one used in content provider) or make sure that passed parameter is the expected one (by type checking like `instanceof` inside the method).
Returns:
  name of the given item

#### getPatternControl

    public Control getPatternControl()

Get the control where the search pattern is entered. Any filtering should be done using an `FilteredItemsSelectionDialog.ItemsFilter`. This control should only be accessed for listeners that wish to handle events that do not affect filtering such as custom traversal.

Returns:
  Control or `null` if the pattern control has not been created.