Package org.eclipse.ui.dialogs

Class FilteredTree

java.lang.Object

org.eclipse.swt.widgets.Widget

org.eclipse.swt.widgets.Control

org.eclipse.swt.widgets.Scrollable

org.eclipse.swt.widgets.Composite

org.eclipse.ui.dialogs.FilteredTree

All Implemented Interfaces:

Drawable

public class FilteredTree
extends Composite

A simple control that provides a text widget and a tree viewer. The contents of the text widget are used to drive a PatternFilter that is on the viewer.

Since:

3.2

See Also:

• PatternFilter

Field Summary

Fields

Modifier and Type	Field	Description
protected Control	clearButtonControl	Note: As of 4.13 not used anymore
protected Composite	filterComposite	The Composite on which the filter controls are created.
protected Text	filterText	The filter text widget to be used by this tree.
protected ToolBarManager	filterToolBar	Note: As of 4.13 not used anymore
protected String	initialText	The text to initially show in the filter text control.
protected Composite	parent	The parent composite of the filtered tree.
protected boolean	showFilterControls	Whether or not to show the filter controls (text and clear button).
protected Composite	treeComposite
protected TreeViewer	treeViewer	The viewer for the filtered tree.

Fields inherited from class org.eclipse.swt.widgets.Control

handle

Fields inherited from class org.eclipse.swt.widgets.Widget

nativeZoom

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	FilteredTree(Composite parent)	Deprecated. As of 3.116, replaced by FilteredTree(Composite, boolean, boolean)
protected	FilteredTree(Composite parent, boolean useNewLook)	Deprecated. As of 3.116, replaced by FilteredTree(Composite, int, PatternFilter, boolean, boolean)
	FilteredTree(Composite parent, boolean useNewLook, boolean useFastHashLookup)	Create a new instance of the receiver.
	FilteredTree(Composite parent, int treeStyle, PatternFilter filter)	Deprecated. As of 3.116, replaced by FilteredTree(Composite, int, PatternFilter, boolean, boolean)
	FilteredTree(Composite parent, int treeStyle, PatternFilter filter, boolean useNewLook)	Deprecated. As of 3.116, replaced by FilteredTree(Composite, int, PatternFilter, boolean, boolean)
	FilteredTree(Composite parent, int treeStyle, PatternFilter filter, boolean useNewLook, boolean useFastHashLookup)	Calls FilteredTree(Composite, int, PatternFilter, boolean, boolean, long) with a default refresh time
	FilteredTree(Composite parent, int treeStyle, PatternFilter filter, boolean useNewLook, boolean useFastHashLookup, long refreshJobDelayInMillis)	Create a new instance of the receiver.

Method Summary

Modifier and Type	Method	Description
protected void	clearText()	Clears the text in the filter text widget.
protected void	createControl(Composite parent, int treeStyle)	Create the filtered tree's controls.
protected Composite	createFilterControls(Composite parent)	Create the filter controls.
protected void	createFilterText(Composite parent)	Creates the filter text and adds listeners.
protected Control	createTreeControl(Composite parent, int style)	Creates and set up the tree and tree viewer.
protected Text	doCreateFilterText(Composite parent)	Creates the text control for entering the filter text.
protected WorkbenchJob	doCreateRefreshJob()	Creates a workbench job that will refresh the tree based on the current filter text.
protected TreeViewer	doCreateTreeViewer(Composite parent, int style)	Creates the tree viewer.
static Font	getBoldFont(Object element, FilteredTree tree, PatternFilter filter)	Return a bold font if the given element matches the given pattern.
Text	getFilterControl()	Get the filter text for the receiver, if it was created.
protected String	getFilterString()	Convenience method to return the text of the filter control.
protected String	getInitialText()	Get the initial text for the receiver.
final PatternFilter	getPatternFilter()	Returns the pattern filter used by this tree.
protected long	getRefreshJobDelay()	Return the time delay that should be used when scheduling the filter refresh job.
TreeViewer	getViewer()	Get the tree viewer of the receiver.
protected void	init(int treeStyle, PatternFilter filter)	Create the filtered tree.
protected void	selectAll()	Select all text in the filter text field.
void	setBackground(Color background)	Set the background for the widgets that support the filter text area.
protected void	setFilterText(String filterText)	Set the text in the filter control.
void	setInitialText(String text)	Set the text that will be shown until the first focus.
void	setQuickSelectionMode(boolean enabled)	Sets whether this filtered tree is used to make quick selections.
protected void	textChanged()	Update the receiver after the text has changed.
protected void	updateToolbar(boolean visible)	Updates the toolbar.
protected void	updateTreeSelection(boolean setFocus)	Updates the selection in the tree, based on the filter text.

Methods inherited from class org.eclipse.swt.widgets.Composite

changed, checkSubclass, drawBackground, getBackgroundMode, getChildren, getLayout, getLayoutDeferred, getTabList, isLayoutDeferred, layout, layout, layout, layout, layout, setBackgroundMode, setFocus, setLayout, setLayoutDeferred, setTabList, toString

Methods inherited from class org.eclipse.swt.widgets.Scrollable

computeTrim, getClientArea, getHorizontalBar, getScrollbarsMode, getVerticalBar, setScrollbarsMode

Methods inherited from class org.eclipse.swt.widgets.Control

addControlListener, addDragDetectListener, addFocusListener, addGestureListener, addHelpListener, addKeyListener, addMenuDetectListener, addMouseListener, addMouseMoveListener, addMouseTrackListener, addMouseWheelListener, addPaintListener, addTouchListener, addTraverseListener, computeSize, computeSize, dragDetect, dragDetect, forceFocus, getAccessible, getBackground, getBackgroundImage, getBorderWidth, getBounds, getCursor, getDragDetect, getEnabled, getFont, getForeground, getLayoutData, getLocation, getMenu, getMonitor, getOrientation, getParent, getRegion, getShell, getSize, getTextDirection, getToolTipText, getTouchEnabled, getVisible, internal_dispose_GC, internal_new_GC, isEnabled, isFocusControl, isReparentable, isVisible, moveAbove, moveBelow, pack, pack, print, redraw, redraw, removeControlListener, removeDragDetectListener, removeFocusListener, removeGestureListener, removeHelpListener, removeKeyListener, removeMenuDetectListener, removeMouseListener, removeMouseMoveListener, removeMouseTrackListener, removeMouseWheelListener, removePaintListener, removeTouchListener, removeTraverseListener, requestLayout, setBackgroundImage, setBounds, setBounds, setCapture, setCursor, setDragDetect, setEnabled, setFont, setForeground, setLayoutData, setLocation, setLocation, setMenu, setOrientation, setParent, setRedraw, setRegion, setSize, setSize, setTextDirection, setToolTipText, setTouchEnabled, setVisible, toControl, toControl, toDisplay, toDisplay, traverse, traverse, traverse, update

Methods inherited from class org.eclipse.swt.widgets.Widget

addDisposeListener, addListener, addTypedListener, checkWidget, dispose, getData, getData, getDisplay, getListeners, getStyle, getTypedListeners, isAutoDirection, isDisposed, isListening, notifyListeners, removeDisposeListener, removeListener, removeListener, removeTypedListener, reskin, setData, setData

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.eclipse.swt.graphics.Drawable

isAutoScalable

Field Details

filterText

protected Text filterText

The filter text widget to be used by this tree. This value may be null if there is no filter widget, or if the controls have not yet been created.

filterToolBar

protected ToolBarManager filterToolBar

Note: As of 4.13 not used anymore

clearButtonControl

protected Control clearButtonControl

Note: As of 4.13 not used anymore

Since:

3.5

treeViewer

protected TreeViewer treeViewer

The viewer for the filtered tree. This value should never be null after the widget creation methods are complete.

filterComposite

protected Composite filterComposite

The Composite on which the filter controls are created. This is used to set the background color of the filter controls to match the surrounding controls.

initialText

protected String initialText

The text to initially show in the filter text control.

parent

protected Composite parent

The parent composite of the filtered tree.

Since:

3.3

showFilterControls

protected boolean showFilterControls

Whether or not to show the filter controls (text and clear button). The default is to show these controls. This can be overridden by providing a setting in the product configuration file. The setting to add to not show these controls is: org.eclipse.ui/SHOW_FILTERED_TEXTS=false

treeComposite

protected Composite treeComposite

Since:

3.3

Constructor Details

FilteredTree

public FilteredTree(Composite parent,
 boolean useNewLook,
 boolean useFastHashLookup)

Create a new instance of the receiver. Subclasses that wish to override the default creation behavior may use this constructor, but must ensure that the init(composite, int, PatternFilter) method is called in the overriding constructor. *

WARNING: Passing false as parameter for useFastHashLookup results in a slow performing tree and should not be used if the underlying data model uses a stable and correct hashCode and equals implementation.

Parameters:

parent - the parent Composite

useNewLook - ignored, keep for API compliance

useFastHashLookup - true, if tree should use fast hashlookup, false, if the tree should be slow but working for data with mutable or broken hashcode implementation. Only used if treeViewer is already initialized

Since:

3.116

FilteredTree

public FilteredTree(Composite parent,
 int treeStyle,
 PatternFilter filter,
 boolean useNewLook,
 boolean useFastHashLookup)

Calls FilteredTree(Composite, int, PatternFilter, boolean, boolean, long) with a default refresh time

Since:

3.116

FilteredTree

public FilteredTree(Composite parent,
 int treeStyle,
 PatternFilter filter,
 boolean useNewLook,
 boolean useFastHashLookup,
 long refreshJobDelayInMillis)

Create a new instance of the receiver.

WARNING: Passing false as parameter for useFastHashLookup results in a slow performing tree and should not be used if the underlying data model uses a stable and correct hashCode and equals implementation.

Parameters:

parent - the parent Composite

treeStyle - the style bits for the Tree

filter - the filter to be used

useNewLook - ignored, keep for API compliance

useFastHashLookup - true, if tree should use fast hash lookup, false, if the tree should be slow but working for data with mutable or broken hashcode implementation. Only used if treeViewer is already initialized

refreshJobDelayInMillis - refresh delay in ms, the time to expand the tree after debounce

Since:

3.132

FilteredTree

@Deprecated
protected FilteredTree(Composite parent)

Deprecated.

As of 3.116, replaced by FilteredTree(Composite, boolean, boolean)

Create a new instance of the receiver. Subclasses that wish to override the default creation behavior may use this constructor, but must ensure that the init(composite, int, PatternFilter) method is called in the overriding constructor.

WARNING: Using this constructor results in a slow performing tree and should not be used if the underlying data model uses a stable and correct hashCode and equals implementation. Prefer the usage of FilteredTree(Composite, boolean, boolean) if possible.

Parameters:

parent - the parent Composite

Since:

3.3

See Also:

• init(int, PatternFilter)

FilteredTree

@Deprecated
protected FilteredTree(Composite parent,
 boolean useNewLook)

Deprecated.

As of 3.116, replaced by FilteredTree(Composite, int, PatternFilter, boolean, boolean)

Create a new instance of the receiver. Subclasses that wish to override the default creation behavior may use this constructor, but must ensure that the init(composite, int, PatternFilter) method is called in the overriding constructor. *

WARNING: Using this constructor results in a slow performing tree and should not be used if the underlying data model uses a stable and correct hashCode and equals implementation. Prefer the usage of FilteredTree(Composite, int, PatternFilter, boolean, boolean) if possible.

Parameters:

parent - the parent Composite

useNewLook - ignored, look introduced in 3.5 is always used

Since:

3.5

See Also:

• init(int, PatternFilter)

FilteredTree

@Deprecated
public FilteredTree(Composite parent,
 int treeStyle,
 PatternFilter filter)

Deprecated.

As of 3.116, replaced by FilteredTree(Composite, int, PatternFilter, boolean, boolean)

Create a new instance of the receiver.

WARNING: Using this constructor results in a slow performing tree and should not be used if the underlying data model uses a stable and correct hashCode and equals implementation. Prefer the usage of FilteredTree(Composite, int, PatternFilter, boolean, boolean) if possible.

Parameters:

parent - the parent Composite

treeStyle - the style bits for the Tree

filter - the filter to be used

FilteredTree

@Deprecated
public FilteredTree(Composite parent,
 int treeStyle,
 PatternFilter filter,
 boolean useNewLook)

Deprecated.

As of 3.116, replaced by FilteredTree(Composite, int, PatternFilter, boolean, boolean)

Create a new instance of the receiver.

WARNING: Using this constructor results in a slow performing tree and should not be used if the underlying data model uses a stable and correct hashCode and equals implementation. Prefer the usage of FilteredTree(Composite, int, PatternFilter, boolean, boolean) if possible

Parameters:

parent - the parent Composite

treeStyle - the style bits for the Tree

filter - the filter to be used

useNewLook - ignored, look introduced in 3.5 is always used

Since:

3.5

Method Details

init

protected void init(int treeStyle,
 PatternFilter filter)

Create the filtered tree.

Parameters:

treeStyle - the style bits for the Tree

filter - the filter to be used

Since:

3.3

createControl

protected void createControl(Composite parent,
 int treeStyle)

Create the filtered tree's controls. Subclasses should override.

Parameters:

parent - the parent

treeStyle - SWT style bits used to create the tree

createFilterControls

protected Composite createFilterControls(Composite parent)

Create the filter controls. By default, a text and corresponding tool bar button that clears the contents of the text is created. Subclasses may override.

Parameters:

parent - parent Composite of the filter controls

Returns:

the Composite that contains the filter controls

createTreeControl

protected Control createTreeControl(Composite parent,
 int style)

Creates and set up the tree and tree viewer. This method calls doCreateTreeViewer(Composite, int) to create the tree viewer. Subclasses should override doCreateTreeViewer(Composite, int) instead of overriding this method.

Parameters:

parent - parent Composite

style - SWT style bits used to create the tree

Returns:

the tree

doCreateTreeViewer

protected TreeViewer doCreateTreeViewer(Composite parent,
 int style)

Creates the tree viewer. Subclasses may override.

Parameters:

parent - the parent composite

style - SWT style bits used to create the tree viewer

Returns:

the tree viewer

Since:

3.3

doCreateRefreshJob

protected WorkbenchJob doCreateRefreshJob()

Creates a workbench job that will refresh the tree based on the current filter text. Subclasses may override.

Returns:

a workbench job that can be scheduled to refresh the tree

Since:

3.4

updateToolbar

protected void updateToolbar(boolean visible)

Updates the toolbar. The default implementation does nothing. Subclasses may override.

Parameters:

visible - boolean

createFilterText

protected void createFilterText(Composite parent)

Creates the filter text and adds listeners. This method calls doCreateFilterText(Composite) to create the text control. Subclasses should override doCreateFilterText(Composite) instead of overriding this method.

Parameters:

parent - Composite of the filter text

updateTreeSelection

protected void updateTreeSelection(boolean setFocus)

Updates the selection in the tree, based on the filter text.

Parameters:

setFocus - true if the focus should be set on the tree, false otherwise

Since:

3.105

doCreateFilterText

protected Text doCreateFilterText(Composite parent)

Creates the text control for entering the filter text. Subclasses may override.

Parameters:

parent - the parent composite

Returns:

the text widget

Since:

3.3

textChanged

protected void textChanged()

Update the receiver after the text has changed.

getRefreshJobDelay

protected long getRefreshJobDelay()

Return the time delay that should be used when scheduling the filter refresh job. Subclasses may override.

Returns:

a time delay in milliseconds before the job should run

Since:

3.5

setBackground

public void setBackground(Color background)

Set the background for the widgets that support the filter text area.

Overrides:

setBackground in class Control

Parameters:

background - background Color to set

clearText

protected void clearText()

Clears the text in the filter text widget.

setFilterText

protected void setFilterText(String filterText)

Set the text in the filter control.

Parameters:

filterText - the text to set.

getPatternFilter

public final PatternFilter getPatternFilter()

Returns the pattern filter used by this tree.

Returns:

The pattern filter; never null.

getViewer

public TreeViewer getViewer()

Get the tree viewer of the receiver.

Returns:

the tree viewer

getFilterControl

public Text getFilterControl()

Get the filter text for the receiver, if it was created. Otherwise return null.

Returns:

the filter Text, or null if it was not created

getFilterString

protected String getFilterString()

Convenience method to return the text of the filter control. If the text widget is not created, then null is returned.

Returns:

String in the text, or null if the text does not exist

setInitialText

public void setInitialText(String text)

Set the text that will be shown until the first focus. A default value is provided, so this method only need be called if overriding the default initial text is desired.

Parameters:

text - initial text to appear in text field

setQuickSelectionMode

public void setQuickSelectionMode(boolean enabled)

Sets whether this filtered tree is used to make quick selections. In this mode the first match in the tree is automatically selected while filtering and the 'Enter' key is not used to move the focus to the tree.

By default, this is set to false.

Parameters:

enabled - true if this filtered tree is used to make quick selections, false otherwise

Since:

3.105

selectAll

protected void selectAll()

Select all text in the filter text field.

getInitialText

protected String getInitialText()

Get the initial text for the receiver.

Returns:

String

getBoldFont

public static Font getBoldFont(Object element,
 FilteredTree tree,
 PatternFilter filter)

Return a bold font if the given element matches the given pattern. Clients can opt to call this method from a Viewer's label provider to get a bold font for which to highlight the given element in the tree.

Parameters:

element - element for which a match should be determined

tree - FilteredTree in which the element resides

filter - PatternFilter which determines a match

Returns:

bold font