Eclipse Platform
Release 3.3

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.ColumnViewer
                  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, (as of 3.2) the ILazyTreeContentProvider interface, or (as of 3.3) the ILazyTreePathContentProvider. If the content provider is an ILazyTreeContentProvider or an ILazyTreePathContentProvider, 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 createChildren(Widget widget)
          Creates all children for the given widget.
protected  ColumnViewerEditor createViewerEditor()
          This implementation of createViewerEditor() returns null to ensure API backwards compatibility.
protected  void disassociate(Item item)
          The AbstractTreeViewer implementation of this method also recurses over children of the corresponding element.
protected  int doGetColumnCount()
          Returns the number of columns of this viewer.
 void editElement(Object element, int column)
          Starts editing the given element at the given column index.
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.
protected  Widget getColumnViewerOwner(int columnIndex)
          Returns the column widget at the given column index.
 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 getItemAt(Point p)
          This implementation of getItemAt(Point) returns null to ensure API backwards compatibility.
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  ViewerRow getViewerRowFromItem(Widget item)
          Returns a ViewerRow associated with the given row widget.
protected  void handleTreeExpand(TreeEvent event)
          Handles a tree expand event from the SWT widget.
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 internalInitializeTree(Control widget)
          Initializes the tree with root items, expanding to the appropriate level if necessary.
protected  void internalRefreshStruct(Widget widget, Object element, boolean updateLabels)
           
 boolean isExpandable(Object element)
          Return whether the tree node representing the given element or path can be expanded.
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.
 void remove(Object parentOrTreePath, int index)
          Removes the element at the specified index of the parent.
protected  void removeAll(Control widget)
          Removes all items from the given control.
 void replace(Object parentElementOrTreePath, 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 setChildCount(Object elementOrTreePath, int count)
          For a TreeViewer with a tree with the VIRTUAL style bit set, set the number of children of the given element or tree path.
 void setContentProvider(IContentProvider provider)
          The AbstractTreeViewer implementation of this method checks to ensure that the content provider is an ITreeContentProvider.
protected  void setExpanded(Item node, boolean expand)
          Sets the expand state of the given item.
 void setHasChildren(Object elementOrTreePath, boolean hasChildren)
          For a TreeViewer with a tree with the VIRTUAL style bit set, inform the viewer about whether the given element or tree path has children.
 void setSelection(ISelection selection, boolean reveal)
          Sets a new selection for this viewer and optionally makes it visible.
protected  void setSelection(List items)
          Sets the selection to the given list of items.
protected  void showItem(Item item)
          Shows the given item.
protected  void updatePlus(Item item, Object element)
          Updates the "+"/"-" icon of the tree node from the given element.
 
Methods inherited from class org.eclipse.jface.viewers.AbstractTreeViewer
add, add, addSelectionListener, addTreeListener, associate, buildLabel, collapseAll, collapseToLevel, createTreeItem, doFindInputItem, doFindItem, doUpdateItem, doUpdateItem, expandAll, expandToLevel, expandToLevel, fireTreeCollapsed, fireTreeExpanded, getAutoExpandLevel, getExpandedElements, getExpandedState, getExpandedTreePaths, getFilteredChildren, getNextItem, getPreviousItem, getSelection, getSelectionFromWidget, getSortedChildren, getTreePathFromItem, getVisibleExpandedElements, handleDoubleSelect, handleTreeCollapse, indexForElement, inputChanged, insert, internalCollapseToLevel, internalExpand, internalExpandToLevel, internalFindItems, internalGetWidgetToSelect, internalIsInputOrEmptyPath, internalRefresh, internalRefresh, internalRefresh, internalRemove, internalRemove, isSameSelection, labelProviderChanged, remove, remove, remove, removeTreeListener, reveal, scrollDown, scrollUp, setAutoExpandLevel, setExpandedElements, setExpandedState, setExpandedTreePaths, setSelectionToWidget, setSelectionToWidget, updateChildren
 
Methods inherited from class org.eclipse.jface.viewers.ColumnViewer
applyEditorValue, cancelEditing, getCellEditors, getCellModifier, getColumnProperties, getColumnViewerEditor, getItem, getLabelProvider, getViewerRow, hookEditingSupport, isCellEditorActive, refresh, refresh, setCellEditors, setCellModifier, setColumnProperties, setColumnViewerEditor, setLabelProvider, triggerEditorActivationEvent, update
 
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, handleDispose, handleInvalidSelection, handleLabelProviderChanged, handleOpen, handlePostSelect, handleSelect, hasFilters, internalUpdate, needsRefilter, preservingSelection, refresh, refresh, refreshItem, removeDoubleClickListener, removeFilter, removeOpenListener, removePostSelectionChangedListener, resetFilters, setComparator, setComparer, setFilters, setInput, setSorter, setUseHashlookup, testFindItem, testFindItems, unmapAllElements, unmapElement, unmapElement, update, updateItem, updateSelection, usingElementMap
 
Methods inherited from class org.eclipse.jface.viewers.ContentViewer
getContentProvider, getInput
 
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

getColumnViewerOwner

protected Widget getColumnViewerOwner(int columnIndex)
Description copied from class: ColumnViewer
Returns the column widget at the given column index.

Overrides:
getColumnViewerOwner in class AbstractTreeViewer

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

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

getItemAt

protected Item getItemAt(Point p)
Description copied from class: AbstractTreeViewer
This implementation of AbstractTreeViewer.getItemAt(Point) returns null to ensure API backwards compatibility. Subclasses should override.

Overrides:
getItemAt in class AbstractTreeViewer

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

createViewerEditor

protected ColumnViewerEditor createViewerEditor()
Description copied from class: AbstractTreeViewer
This implementation of AbstractTreeViewer.createViewerEditor() returns null to ensure API backwards compatibility. Subclasses should override.

Overrides:
createViewerEditor in class AbstractTreeViewer

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

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

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)

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 efficient 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 elementOrTreePath,
                          int count)
For a TreeViewer with a tree with the VIRTUAL style bit set, set the number of children of the given element or tree path. To set the number of children of the invisible root of the tree, you can pass the input object or an empty tree path.

Parameters:
elementOrTreePath - the element, or tree path
count -
Since:
3.2

replace

public void replace(Object parentElementOrTreePath,
                    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 or an empty tree path, this will replace the root element at the given index.

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

Parameters:
parentElementOrTreePath - the parent of the element that should be updated, or the tree path to that parent
index - the index in the parent's children
element - the new element
Since:
3.2
See Also:
setChildCount(Object, int), ILazyTreeContentProvider, ILazyTreePathContentProvider

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 expandability 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 favor 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

getViewerRowFromItem

protected ViewerRow getViewerRowFromItem(Widget item)
Description copied from class: ColumnViewer
Returns a ViewerRow associated with the given row widget. Implementations may re-use the same instance for different row widgets; callers can only use the viewer row locally and until the next call to this method.

Overrides:
getViewerRowFromItem in class AbstractTreeViewer

internalInitializeTree

protected void internalInitializeTree(Control widget)
Description copied from class: AbstractTreeViewer
Initializes the tree with root items, expanding to the appropriate level if necessary.

Overrides:
internalInitializeTree in class AbstractTreeViewer
Parameters:
widget - the tree control

updatePlus

protected void updatePlus(Item item,
                          Object element)
Description copied from class: AbstractTreeViewer
Updates the "+"/"-" icon of the tree node from the given element. It calls isExpandable to determine whether an element is expandable.

Overrides:
updatePlus in class AbstractTreeViewer
Parameters:
item - the item
element - the element

remove

public void remove(Object parentOrTreePath,
                   int index)
Removes the element at the specified index of the parent. The selection is updated if required.

Parameters:
parentOrTreePath - the parent element, the input element, or a tree path to the parent element
index - child index
Since:
3.3

handleTreeExpand

protected void handleTreeExpand(TreeEvent event)
Description copied from class: AbstractTreeViewer
Handles a tree expand event from the SWT widget.

Overrides:
handleTreeExpand in class AbstractTreeViewer
Parameters:
event - the SWT tree event

setContentProvider

public void setContentProvider(IContentProvider provider)
Description copied from class: AbstractTreeViewer
The AbstractTreeViewer implementation of this method checks to ensure that the content provider is an ITreeContentProvider.

Overrides:
setContentProvider in class AbstractTreeViewer

setHasChildren

public void setHasChildren(Object elementOrTreePath,
                           boolean hasChildren)
For a TreeViewer with a tree with the VIRTUAL style bit set, inform the viewer about whether the given element or tree path has children. Avoid calling this method if the number of children has already been set.

Parameters:
elementOrTreePath - the element, or tree path
hasChildren -
Since:
3.3

disassociate

protected void disassociate(Item item)
Description copied from class: AbstractTreeViewer
The AbstractTreeViewer implementation of this method also recurses over children of the corresponding element.

Overrides:
disassociate in class AbstractTreeViewer

doGetColumnCount

protected int doGetColumnCount()
Description copied from class: AbstractTreeViewer
Returns the number of columns of this viewer.

Subclasses should overwrite this method, which has a default implementation (returning 0) for API backwards compatility reasons

Overrides:
doGetColumnCount in class AbstractTreeViewer
Returns:
the number of columns

setSelection

public void setSelection(ISelection selection,
                         boolean reveal)
Sets a new selection for this viewer and optionally makes it visible.

Currently the reveal parameter is not honored because Tree does not provide an API to only select an item without scrolling it into view

Overrides:
setSelection in class StructuredViewer
Parameters:
selection - the new selection
reveal - true if the selection is to be made visible, and false otherwise

editElement

public void editElement(Object element,
                        int column)
Description copied from class: ColumnViewer
Starts editing the given element at the given column index.

Overrides:
editElement in class ColumnViewer
Parameters:
element - the model element
column - the column index

Eclipse Platform
Release 3.3

Guidelines for using Eclipse APIs.

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