Eclipse Platform
Release 3.2

org.eclipse.jface.viewers
Class TreeViewer

java.lang.Object
  extended byorg.eclipse.jface.viewers.Viewer
      extended byorg.eclipse.jface.viewers.ContentViewer
          extended byorg.eclipse.jface.viewers.StructuredViewer
              extended byorg.eclipse.jface.viewers.AbstractTreeViewer
                  extended byorg.eclipse.jface.viewers.TreeViewer
All Implemented Interfaces:
IInputProvider, IInputSelectionProvider, IPostSelectionProvider, ISelectionProvider
Direct Known Subclasses:
CheckboxTreeViewer, CommonViewer, DiffTreeViewer

public class TreeViewer
extends AbstractTreeViewer

A concrete viewer based on an SWT Tree control.

This class is not intended to be subclassed outside the viewer framework. It is designed to be instantiated with a pre-existing SWT tree control and configured with a domain-specific content provider, label provider, element filter (optional), and element sorter (optional).

Content providers for tree viewers must implement either the ITreeContentProvider interface or (as of 3.2) the ILazyTreeContentProvider interface. If the content provider is an ILazyTreeContentProvider, the underlying Tree must be created using the SWT.VIRTUAL style bit, and the tree viewer will not support sorting or filtering.


Nested Class Summary
 
Nested classes inherited from class org.eclipse.jface.viewers.StructuredViewer
StructuredViewer.ColorAndFontCollector, StructuredViewer.ColorAndFontCollectorWithProviders
 
Field Summary
 
Fields inherited from class org.eclipse.jface.viewers.AbstractTreeViewer
ALL_LEVELS
 
Fields inherited from class org.eclipse.jface.viewers.Viewer
WIDGET_DATA_KEY
 
Constructor Summary
TreeViewer(Composite parent)
          Creates a tree viewer on a newly-created tree control under the given parent.
TreeViewer(Composite parent, int style)
          Creates a tree viewer on a newly-created tree control under the given parent.
TreeViewer(Tree tree)
          Creates a tree viewer on the given tree control.
 
Method Summary
protected  void addTreeListener(Control c, TreeListener listener)
          Adds the given SWT tree listener to the given SWT control.
protected  void assertContentProviderType(IContentProvider provider)
          Assert that the content provider is of one of the supported types.
protected  void buildLabel(ViewerLabel updateLabel, Object elementOrPath)
          Override to handle tree paths.
 void cancelEditing()
          Cancels a currently active cell editor.
protected  void createChildren(Widget widget)
          Creates all children for the given widget.
protected  void doUpdateItem(Item item, Object element)
          Copies the attributes of the given element into the given SWT item.
 void editElement(Object element, int column)
          Starts editing the given element.
 CellEditor[] getCellEditors()
          Returns the cell editors of this tree viewer.
 ICellModifier getCellModifier()
          Returns the cell modifier of this tree viewer.
protected  Item getChild(Widget widget, int index)
          Get the child for the widget at index.
protected  Item[] getChildren(Widget o)
          Returns the SWT child items for the given SWT widget.
 Object[] getColumnProperties()
          Returns the column properties of this tree viewer.
 Control getControl()
          Returns the primary control associated with this viewer.
protected  boolean getExpanded(Item item)
          Returns whether the given SWT item is expanded or collapsed.
protected  Item getItem(int x, int y)
          Returns the item at the given display-relative coordinates, or null if there is no item at that location.
protected  int getItemCount(Control widget)
          Returns the number of child items of the given SWT control.
protected  int getItemCount(Item item)
          Returns the number of child items of the given SWT item.
protected  Item[] getItems(Item item)
          Returns the child items of the given SWT item.
 IBaseLabelProvider getLabelProvider()
          The tree viewer implementation of this Viewer framework method ensures that the given label provider is an instance of either ITableLabelProvider or ILabelProvider.
protected  Object getParentElement(Object element)
          This method takes a tree path or an element.
protected  Item getParentItem(Item item)
          Returns the parent item of the given item in the tree, or null if there is no parent item.
protected  Object[] getRawChildren(Object parent)
          Returns the children of the given parent without sorting and filtering them.
protected  Item[] getSelection(Control widget)
          Returns all selected items for the given SWT control.
 Tree getTree()
          Returns this tree viewer's tree control.
protected  void hookControl(Control control)
          Adds event listener hooks to the given control.
protected  void internalAdd(Widget widget, Object parentElement, Object[] childElements)
          Adds the given child elements to this viewer as children of the given parent element.
protected  void internalRefreshStruct(Widget widget, Object element, boolean updateLabels)
           
 boolean isCellEditorActive()
          Returns whether there is an active cell editor.
 boolean isExpandable(Object element)
          Return whether the tree node representing the given element or path can be expanded.
protected  boolean isSameSelection(List items, Item[] current)
          Returns true if the given list and array of items refer to the same model elements.
protected  void mapElement(Object element, Widget item)
          Adds the element item pair to the element map.
protected  Item newItem(Widget parent, int flags, int ix)
          Creates a new item.
protected  void removeAll(Control widget)
          Removes all items from the given control.
 void replace(Object parent, int index, Object element)
          For a TreeViewer with a tree with the VIRTUAL style bit set, replace the given parent's child at index with the given element.
 void setCellEditors(CellEditor[] editors)
          Sets the cell editors of this tree viewer.
 void setCellModifier(ICellModifier modifier)
          Sets the cell modifier of this tree viewer.
 void setChildCount(Object element, int count)
          For a TreeViewer with a tree with the VIRTUAL style bit set, set the number of children of the given element.
 void setColumnProperties(String[] columnProperties)
          Sets the column properties of this tree viewer.
protected  void setExpanded(Item node, boolean expand)
          Sets the expand state of the given item.
 void setLabelProvider(IBaseLabelProvider labelProvider)
          The tree viewer implementation of this Viewer framework method ensures that the given label provider is an instance of either ITableLabelProvider or ILabelProvider.
protected  void setSelection(List items)
          Sets the selection to the given list of items.
protected  void showItem(Item item)
          Shows the given item.
 
Methods inherited from class org.eclipse.jface.viewers.AbstractTreeViewer
add, add, addSelectionListener, addTreeListener, associate, collapseAll, collapseToLevel, createTreeItem, disassociate, doFindInputItem, doFindItem, doUpdateItem, expandAll, expandToLevel, expandToLevel, fireTreeCollapsed, fireTreeExpanded, getAutoExpandLevel, getExpandedElements, getExpandedState, getExpandedTreePaths, getFilteredChildren, getNextItem, getPreviousItem, getSelection, getSelectionFromWidget, getSortedChildren, getTreePathFromItem, getVisibleExpandedElements, handleDoubleSelect, handleTreeCollapse, handleTreeExpand, indexForElement, inputChanged, insert, internalCollapseToLevel, internalExpand, internalExpandToLevel, internalGetWidgetToSelect, internalRefresh, internalRefresh, internalRefresh, internalRemove, internalRemove, labelProviderChanged, remove, remove, remove, removeTreeListener, reveal, scrollDown, scrollUp, setAutoExpandLevel, setContentProvider, setExpandedElements, setExpandedState, setExpandedTreePaths, setSelectionToWidget, setSelectionToWidget, updateChildren, updatePlus
 
Methods inherited from class org.eclipse.jface.viewers.StructuredViewer
addDoubleClickListener, addDragSupport, addDropSupport, addFilter, addOpenListener, addPostSelectionChangedListener, assertElementsNotNull, equals, filter, findItem, findItems, fireDoubleClick, fireOpen, firePostSelectionChanged, getColorAndFontCollector, getComparator, getComparer, getFilters, getRoot, getSorter, handleInvalidSelection, handleLabelProviderChanged, handleOpen, handlePostSelect, handleSelect, hasFilters, internalUpdate, needsRefilter, preservingSelection, refresh, refresh, refresh, refresh, refreshItem, removeDoubleClickListener, removeFilter, removeOpenListener, removePostSelectionChangedListener, resetFilters, setComparator, setComparer, setInput, setSelection, setSorter, setUseHashlookup, testFindItem, testFindItems, unmapAllElements, unmapElement, unmapElement, update, update, updateItem, updateSelection, usingElementMap
 
Methods inherited from class org.eclipse.jface.viewers.ContentViewer
getContentProvider, getInput, handleDispose
 
Methods inherited from class org.eclipse.jface.viewers.Viewer
addHelpListener, addSelectionChangedListener, fireHelpRequested, fireSelectionChanged, getData, handleHelpRequest, removeHelpListener, removeSelectionChangedListener, setData, setSelection
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface org.eclipse.jface.viewers.ISelectionProvider
addSelectionChangedListener, removeSelectionChangedListener, setSelection
 

Constructor Detail

TreeViewer

public TreeViewer(Composite parent)
Creates a tree viewer on a newly-created tree control under the given parent. The tree control is created using the SWT style bits MULTI, H_SCROLL, V_SCROLL, and BORDER. The viewer has no input, no content provider, a default label provider, no sorter, and no filters.

Parameters:
parent - the parent control

TreeViewer

public TreeViewer(Composite parent,
                  int style)
Creates a tree viewer on a newly-created tree control under the given parent. The tree control is created using the given SWT style bits. The viewer has no input, no content provider, a default label provider, no sorter, and no filters.

Parameters:
parent - the parent control
style - the SWT style bits used to create the tree.

TreeViewer

public TreeViewer(Tree tree)
Creates a tree viewer on the given tree control. The viewer has no input, no content provider, a default label provider, no sorter, and no filters.

Parameters:
tree - the tree control
Method Detail

addTreeListener

protected void addTreeListener(Control c,
                               TreeListener listener)
Description copied from class: AbstractTreeViewer
Adds the given SWT tree listener to the given SWT control.

Specified by:
addTreeListener in class AbstractTreeViewer
Parameters:
c - the SWT control
listener - the SWT tree listener

cancelEditing

public void cancelEditing()
Cancels a currently active cell editor. All changes already done in the cell editor are lost.

Since:
3.1

doUpdateItem

protected void doUpdateItem(Item item,
                            Object element)
Description copied from class: AbstractTreeViewer
Copies the attributes of the given element into the given SWT item.

Specified by:
doUpdateItem in class AbstractTreeViewer
Parameters:
item - the SWT item
element - the element

buildLabel

protected void buildLabel(ViewerLabel updateLabel,
                          Object elementOrPath)
Override to handle tree paths.

Overrides:
buildLabel in class StructuredViewer
Parameters:
updateLabel - The ViewerLabel to collect the result in
elementOrPath - The element being decorated.
See Also:
StructuredViewer.buildLabel(org.eclipse.jface.viewers.ViewerLabel, java.lang.Object)

editElement

public void editElement(Object element,
                        int column)
Starts editing the given element.

Parameters:
element - the element
column - the column number
Since:
3.1

getCellEditors

public CellEditor[] getCellEditors()
Returns the cell editors of this tree viewer.

Returns:
the list of cell editors
Since:
3.1

getCellModifier

public ICellModifier getCellModifier()
Returns the cell modifier of this tree viewer.

Returns:
the cell modifier
Since:
3.1

getChildren

protected Item[] getChildren(Widget o)
Description copied from class: AbstractTreeViewer
Returns the SWT child items for the given SWT widget.

Specified by:
getChildren in class AbstractTreeViewer
Parameters:
o - the widget
Returns:
the child items

getColumnProperties

public Object[] getColumnProperties()
Returns the column properties of this tree viewer. The properties must correspond with the columns of the tree control. They are used to identify the column in a cell modifier.

Returns:
the list of column properties
Since:
3.1

getControl

public Control getControl()
Description copied from class: Viewer
Returns the primary control associated with this viewer.

Specified by:
getControl in class Viewer
Returns:
the SWT control which displays this viewer's content

getExpanded

protected boolean getExpanded(Item item)
Description copied from class: AbstractTreeViewer
Returns whether the given SWT item is expanded or collapsed.

Specified by:
getExpanded in class AbstractTreeViewer
Parameters:
item - the item
Returns:
true if the item is considered expanded and false if collapsed

getItem

protected Item getItem(int x,
                       int y)
Description copied from class: StructuredViewer
Returns the item at the given display-relative coordinates, or null if there is no item at that location.

The default implementation of this method returns null.

Overrides:
getItem in class StructuredViewer
Parameters:
x - horizontal coordinate
y - vertical coordinate
Returns:
the item, or null if there is no item at the given coordinates

getItemCount

protected int getItemCount(Control widget)
Description copied from class: AbstractTreeViewer
Returns the number of child items of the given SWT control.

Specified by:
getItemCount in class AbstractTreeViewer
Parameters:
widget - the control
Returns:
the number of children

getItemCount

protected int getItemCount(Item item)
Description copied from class: AbstractTreeViewer
Returns the number of child items of the given SWT item.

Specified by:
getItemCount in class AbstractTreeViewer
Parameters:
item - the item
Returns:
the number of children

getItems

protected Item[] getItems(Item item)
Description copied from class: AbstractTreeViewer
Returns the child items of the given SWT item.

Specified by:
getItems in class AbstractTreeViewer
Parameters:
item - the item
Returns:
the child items

getLabelProvider

public IBaseLabelProvider getLabelProvider()
The tree viewer implementation of this Viewer framework method ensures that the given label provider is an instance of either ITableLabelProvider or ILabelProvider. If it is an ITableLabelProvider, then it provides a separate label text and image for each column. If it is an ILabelProvider, then it provides only the label text and image for the first column, and any remaining columns are blank.

Overrides:
getLabelProvider in class ContentViewer
Returns:
a label provider

getParentItem

protected Item getParentItem(Item item)
Description copied from class: AbstractTreeViewer
Returns the parent item of the given item in the tree, or null if there is no parent item.

Specified by:
getParentItem in class AbstractTreeViewer
Parameters:
item - the item
Returns:
the parent item, or null if none

getSelection

protected Item[] getSelection(Control widget)
Description copied from class: AbstractTreeViewer
Returns all selected items for the given SWT control.

Specified by:
getSelection in class AbstractTreeViewer
Parameters:
widget - the control
Returns:
the list of selected items

getTree

public Tree getTree()
Returns this tree viewer's tree control.

Returns:
the tree control

hookControl

protected void hookControl(Control control)
Description copied from class: ContentViewer
Adds event listener hooks to the given control.

All subclasses must call this method when their control is first established.

The ContentViewer implementation of this method hooks dispose events for the given control. Subclasses may override if they need to add other control hooks; however, super.hookControl must be invoked.

Overrides:
hookControl in class AbstractTreeViewer

isCellEditorActive

public boolean isCellEditorActive()
Returns whether there is an active cell editor.

Returns:
true if there is an active cell editor, and false otherwise
Since:
3.1

newItem

protected Item newItem(Widget parent,
                       int flags,
                       int ix)
Description copied from class: AbstractTreeViewer
Creates a new item.

Specified by:
newItem in class AbstractTreeViewer
Parameters:
parent - the parent widget
flags - SWT style bits
ix - if non-negative, indicates the position to insert the item into its parent
Returns:
the newly-created item

removeAll

protected void removeAll(Control widget)
Description copied from class: AbstractTreeViewer
Removes all items from the given control.

Specified by:
removeAll in class AbstractTreeViewer
Parameters:
widget - the control

setCellEditors

public void setCellEditors(CellEditor[] editors)
Sets the cell editors of this tree viewer.

Parameters:
editors - the list of cell editors
Since:
3.1

setCellModifier

public void setCellModifier(ICellModifier modifier)
Sets the cell modifier of this tree viewer.

Parameters:
modifier - the cell modifier
Since:
3.1

setColumnProperties

public void setColumnProperties(String[] columnProperties)
Sets the column properties of this tree viewer. The properties must correspond with the columns of the tree control. They are used to identify the column in a cell modifier.

Parameters:
columnProperties - the list of column properties
Since:
3.1

setExpanded

protected void setExpanded(Item node,
                           boolean expand)
Description copied from class: AbstractTreeViewer
Sets the expand state of the given item.

Specified by:
setExpanded in class AbstractTreeViewer
Parameters:
node - the item
expand - the expand state of the item

setLabelProvider

public void setLabelProvider(IBaseLabelProvider labelProvider)
The tree viewer implementation of this Viewer framework method ensures that the given label provider is an instance of either ITableLabelProvider or ILabelProvider.

If the label provider is an ITableLabelProvider, then it provides a separate label text and image for each column. Implementers of ITableLabelProvider may also implement ITableColorProvider and/or ITableFontProvider to provide colors and/or fonts. Note that the underlying Tree must be configured with TreeColumn objects in this case.

If the label provider is an ILabelProvider, then it provides only the label text and image for the first column, and any remaining columns are blank. Implementers of ILabelProvider may also implement IColorProvider and/or IFontProvider to provide colors and/or fonts.

Overrides:
setLabelProvider in class StructuredViewer

setSelection

protected void setSelection(List items)
Description copied from class: AbstractTreeViewer
Sets the selection to the given list of items.

Specified by:
setSelection in class AbstractTreeViewer
Parameters:
items - list of items (element type: org.eclipse.swt.widgets.Item)

isSameSelection

protected boolean isSameSelection(List items,
                                  Item[] current)
Returns true if the given list and array of items refer to the same model elements. Order is unimportant.

Parameters:
items - the list of items
current - the array of items
Returns:
true if the refer to the same elements, false otherwise
Since:
3.1

showItem

protected void showItem(Item item)
Description copied from class: AbstractTreeViewer
Shows the given item.

Specified by:
showItem in class AbstractTreeViewer
Parameters:
item - the item

getChild

protected Item getChild(Widget widget,
                        int index)
Description copied from class: AbstractTreeViewer
Get the child for the widget at index. Note that the default implementation is not very effecient and should be overridden if this class is implemented.

Overrides:
getChild in class AbstractTreeViewer
Parameters:
widget - the widget to check
index - the index of the widget
Returns:
Item or null if widget is not a type that can contain items.

assertContentProviderType

protected void assertContentProviderType(IContentProvider provider)
Description copied from class: StructuredViewer
Assert that the content provider is of one of the supported types.

Overrides:
assertContentProviderType in class AbstractTreeViewer

getRawChildren

protected Object[] getRawChildren(Object parent)
Description copied from class: StructuredViewer
Returns the children of the given parent without sorting and filtering them. The resulting array must not be modified, as it may come directly from the model's internal state.

Returns an empty array if the given parent is null.

Overrides:
getRawChildren in class AbstractTreeViewer

setChildCount

public void setChildCount(Object element,
                          int count)
For a TreeViewer with a tree with the VIRTUAL style bit set, set the number of children of the given element. To set the number of children of the invisible root of the tree, the input object is passed as the element.

Parameters:
element -
count - EXPERIMENTAL. This class or interface has been added as part of a work in progress. There is no guarantee that this API will remain unchanged during the 3.2 release cycle. Please do not use this API without consulting with the Platform/UI team.

Since:
3.2

replace

public void replace(Object parent,
                    int index,
                    Object element)
For a TreeViewer with a tree with the VIRTUAL style bit set, replace the given parent's child at index with the given element. If the given parent is this viewer's input, this will replace the root element at the given index.

This method should be called by implementers of ILazyTreeContentProvider to populate this viewer.

Parameters:
parent - the parent of the element that should be updated
index - the index in the parent's children
element - the new element
Since:
3.2
See Also:
setChildCount(Object, int), EXPERIMENTAL. This class or interface has been added as part of a work in progress. There is no guarantee that this API will remain unchanged during the 3.2 release cycle. Please do not use this API without consulting with the Platform/UI team.


isExpandable

public boolean isExpandable(Object element)
Description copied from class: AbstractTreeViewer
Return whether the tree node representing the given element or path can be expanded. Clients should query expandablity by path if the viewer's content provider is an ITreePathContentProvider.

The default implementation of this framework method calls hasChildren on this viewer's content provider. It may be overridden if necessary.

Overrides:
isExpandable in class AbstractTreeViewer
Parameters:
element - the element or path
Returns:
true if the tree node representing the given element can be expanded, or false if not

getParentElement

protected Object getParentElement(Object element)
Description copied from class: AbstractTreeViewer
This method takes a tree path or an element. If the argument is not a tree path, returns the parent of the given element or null if the parent is not known. If the argument is a tree path with more than one segment, returns its parent tree path, otherwise returns null.

Overrides:
getParentElement in class AbstractTreeViewer
Parameters:
element -
Returns:
the parent element, or parent path, or null

createChildren

protected void createChildren(Widget widget)
Description copied from class: AbstractTreeViewer
Creates all children for the given widget.

The default implementation of this framework method assumes that widget.getData() returns the element corresponding to the node. Note: the node is not visually expanded! You may have to call parent.setExpanded(true).

Overrides:
createChildren in class AbstractTreeViewer
Parameters:
widget - the widget

internalAdd

protected void internalAdd(Widget widget,
                           Object parentElement,
                           Object[] childElements)
Description copied from class: AbstractTreeViewer
Adds the given child elements to this viewer as children of the given parent element.

EXPERIMENTAL. Not to be used except by JDT. This method was added to support JDT's explorations into grouping by working sets, which requires viewers to support multiple equal elements. See bug 76482 for more details. This support will likely be removed in Eclipse 3.2 in favour of proper support for multiple equal elements.

Overrides:
internalAdd in class AbstractTreeViewer
Parameters:
widget - the widget for the parent element
parentElement - the parent element
childElements - the child elements to add

internalRefreshStruct

protected void internalRefreshStruct(Widget widget,
                                     Object element,
                                     boolean updateLabels)
Parameters:
widget -
element -
updateLabels -

mapElement

protected void mapElement(Object element,
                          Widget item)
Description copied from class: StructuredViewer
Adds the element item pair to the element map.

This method is internal to the framework; subclassers should not call this method.

Overrides:
mapElement in class StructuredViewer
Parameters:
element - the element
item - the corresponding widget

Eclipse Platform
Release 3.2

Guidelines for using Eclipse APIs.

Copyright (c) IBM Corp. and others 2000, 2006. All rights reserved.