org.eclipse.ui.navigator
Class CommonViewer

java.lang.Object
  org.eclipse.jface.viewers.Viewer
      org.eclipse.jface.viewers.ContentViewer
          org.eclipse.jface.viewers.StructuredViewer
              org.eclipse.jface.viewers.AbstractTreeViewer
                  org.eclipse.jface.viewers.TreeViewer
                      org.eclipse.ui.navigator.CommonViewer

All Implemented Interfaces:

IInputProvider, IInputSelectionProvider, IPostSelectionProvider, ISelectionProvider

public class CommonViewer

extends TreeViewer

Provides the Tree Viewer for the Common Navigator. Content and labels are provided by an instance of INavigatorContentService which uses the ID supplied in the constructor CommonViewer(String, Composite, int) or through NavigatorContentServiceFactory.createContentService(String, org.eclipse.jface.viewers.StructuredViewer).

Clients may extend this class.

EXPERIMENTAL. This class or interface has been added as part of a work in progress. There is a guarantee neither that this API will work nor that it will remain the same. Please do not use this API without consulting with the Platform/UI team.

Since:

3.2

Nested Class Summary

Nested classes inherited from class org.eclipse.jface.viewers.StructuredViewer

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

CommonViewer(String aViewerId, Composite aParent, int aStyle)
Constructs the Tree Viewer for the Common Navigator and the corresponding NavigatorContentService.

Method Summary

void	add(Object parentElement, Object[] childElements) Adds the given child elements to this viewer as children of the given parent element.
protected void	createTreeItem(Widget parent, Object element, int index) Creates a single item for the given parent and synchronizes it with the given element.
void	dispose() Disposes of the NavigatorContentService, which will dispose the Content and Label providers.
INavigatorContentService	getNavigatorContentService() The INavigatorContentServiceprovides the hook into the framework to provide content from the various extensions.
protected Object[]	getSortedChildren(Object parent) Returns the sorted and filtered set of children of the given element.
protected void	handleDispose(DisposeEvent event) Handles a dispose event on this viewer's control.
protected void	handleLabelProviderChanged(LabelProviderChangedEvent event) The StructuredViewer implementation of this ContentViewer method calls update if the event specifies that the label of a given element has changed, otherwise it calls super.
protected void	init() Initializes the content provider, label provider, and drag and drop support.
protected void	initDragAndDrop() Adds DND support to the Navigator.
protected void	internalAdd(Widget widget, Object parentElement, Object[] childElements) Adds the given child elements to this viewer as children of the given parent element.
boolean	isExpandable(Object element) Return whether the tree node representing the given element or path can be expanded.
void	refresh(boolean updateLabels) Refreshes this viewer with information freshly obtained from this viewer's model.
void	refresh(Object element) Refreshes this viewer starting with the given element.
void	refresh(Object element, boolean updateLabels) Refreshes this viewer starting with the given element.
void	remove(Object[] elements) Removals are handled by refreshing the parents of each of the given elements.
protected void	removeWithoutRefresh(Object[] elements)
protected void	setSelectionToWidget(List v, boolean reveal) This implementation of setSelectionToWidget accepts a list of elements or a list of tree paths.
void	setSorter(ViewerSorter sorter) Sets this viewer's sorter and triggers refiltering and resorting of this viewer's element.
String	toString()
void	update(Object element, String[] properties) Updates the given element's presentation when one or more of its properties changes.

Methods inherited from class org.eclipse.jface.viewers.TreeViewer

addTreeListener, assertContentProviderType, buildLabel, cancelEditing, createChildren, doUpdateItem, editElement, getCellEditors, getCellModifier, getChild, getChildren, getColumnProperties, getControl, getExpanded, getItem, getItemCount, getItemCount, getItems, getLabelProvider, getParentElement, getParentItem, getRawChildren, getSelection, getTree, hookControl, internalRefreshStruct, isCellEditorActive, isSameSelection, mapElement, newItem, removeAll, replace, setCellEditors, setCellModifier, setChildCount, setColumnProperties, setExpanded, setLabelProvider, setSelection, showItem, virtualMaterializeItem

Methods inherited from class org.eclipse.jface.viewers.AbstractTreeViewer

add, addSelectionListener, addTreeListener, associate, collapseAll, collapseToLevel, disassociate, doFindInputItem, doFindItem, doUpdateItem, expandAll, expandToLevel, expandToLevel, fireTreeCollapsed, fireTreeExpanded, getAutoExpandLevel, getExpandedElements, getExpandedState, getExpandedTreePaths, getFilteredChildren, getNextItem, getPreviousItem, getSelection, getSelectionFromWidget, getTreePathFromItem, getVisibleExpandedElements, handleTreeCollapse, handleTreeExpand, indexForElement, inputChanged, internalCollapseToLevel, internalExpand, internalExpandToLevel, internalGetWidgetToSelect, internalRefresh, internalRefresh, internalRefresh, internalRemove, internalRemove, labelProviderChanged, remove, remove, removeTreeListener, reveal, scrollDown, scrollUp, setAutoExpandLevel, setContentProvider, setExpandedElements, setExpandedState, setExpandedTreePaths, 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, getComparer, getFilters, getRoot, getSorter, handleDoubleSelect, handleInvalidSelection, handleOpen, handlePostSelect, handleSelect, hasFilters, internalUpdate, needsRefilter, preservingSelection, refresh, refreshItem, removeDoubleClickListener, removeFilter, removeOpenListener, removePostSelectionChangedListener, resetFilters, setComparer, setInput, setSelection, 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, wait, wait, wait

Methods inherited from interface org.eclipse.jface.viewers.ISelectionProvider

addSelectionChangedListener, removeSelectionChangedListener, setSelection

Constructor Detail

CommonViewer

public CommonViewer(String aViewerId,
                    Composite aParent,
                    int aStyle)

Constructs the Tree Viewer for the Common Navigator and the corresponding NavigatorContentService. The NavigatorContentService will provide the Content Provider and Label Provider -- these need not be supplied by clients.

For the valid bits to supply in the style mask (aStyle), see documentation provided by TreeViewer.

Parameters:

aViewerId - An id tied to the extensions that is used to focus specific content to a particular instance of the Common Navigator

aParent - A Composite parent to contain the actual SWT widget

aStyle - A style mask that will be used to create the TreeViewer Composite.

Method Detail

init

protected void init()

Initializes the content provider, label provider, and drag and drop support. Should not be called by clients -- this method is invoked when the constructor is invoked.

removeWithoutRefresh

protected void removeWithoutRefresh(Object[] elements)

getSortedChildren

protected Object[] getSortedChildren(Object parent)

Returns the sorted and filtered set of children of the given element. The resulting array must not be modified, as it may come directly from the model's internal state.

Overrides:

getSortedChildren in class AbstractTreeViewer

Parameters:

parent - the parent element

Returns:

a sorted and filtered array of child elements

internalAdd

protected void internalAdd(Widget widget,
                           Object parentElement,
                           Object[] childElements)

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 TreeViewer

Parameters:

widget - the widget for the parent element

parentElement - the parent element

childElements - the child elements to add

Since:

3.1

initDragAndDrop

protected void initDragAndDrop()

Adds DND support to the Navigator. Uses hooks into the extensible framework for DND.

By default, the following Transfer types are supported:

• LocalSelectionTransfer.getInstance(),
• PluginTransfer.getInstance(),
• FileTransfer.getInstance(), and
• ResourceTransfer.getInstance()

See Also:

CommonNavigatorDragAdapter, CommonNavigatorDropAdapter

createTreeItem

protected void createTreeItem(Widget parent,
                              Object element,
                              int index)

Description copied from class: AbstractTreeViewer

Creates a single item for the given parent and synchronizes it with the given element.

Overrides:

createTreeItem in class AbstractTreeViewer

Parameters:

parent - the parent widget

element - the element

index - if non-negative, indicates the position to insert the item into its parent

handleLabelProviderChanged

protected void handleLabelProviderChanged(LabelProviderChangedEvent event)

Description copied from class: StructuredViewer

The StructuredViewer implementation of this ContentViewer method calls update if the event specifies that the label of a given element has changed, otherwise it calls super. Subclasses may reimplement or extend.

Overrides:

handleLabelProviderChanged in class StructuredViewer

Parameters:

event - the event that generated this update

handleDispose

protected void handleDispose(DisposeEvent event)

Description copied from class: ContentViewer

Handles a dispose event on this viewer's control.

The ContentViewer implementation of this method disposes of this viewer's label provider and content provider (if it has one). Subclasses should override this method to perform any additional cleanup of resources; however, overriding methods must invoke super.handleDispose.

Overrides:

handleDispose in class ContentViewer

Parameters:

event - a dispose event

setSelectionToWidget

protected void setSelectionToWidget(List v,
                                    boolean reveal)

Description copied from class: AbstractTreeViewer

This implementation of setSelectionToWidget accepts a list of elements or a list of tree paths.

Overrides:

setSelectionToWidget in class AbstractTreeViewer

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 TreeViewer

dispose

public void dispose()

Disposes of the NavigatorContentService, which will dispose the Content and Label providers.

setSorter

public void setSorter(ViewerSorter sorter)

Sets this viewer's sorter and triggers refiltering and resorting of this viewer's element. Passing null turns sorting off.

Overrides:

setSorter in class StructuredViewer

Parameters:

sorter - a viewer sorter, or null if none

getNavigatorContentService

public INavigatorContentService getNavigatorContentService()

The INavigatorContentServiceprovides the hook into the framework to provide content from the various extensions.

Returns:

The INavigatorContentServicethat was created when the viewer was created.

add

public void add(Object parentElement,
                Object[] childElements)

Description copied from class: AbstractTreeViewer

Adds the given child elements to this viewer as children of the given parent element. If this viewer does not have a sorter, the elements are added at the end of the parent's list of children in the order given; otherwise, the elements are inserted at the appropriate positions.

This method should be called (by the content provider) when elements have been added to the model, in order to cause the viewer to accurately reflect the model. This method only affects the viewer, not the model.

Overrides:

add in class AbstractTreeViewer

Parameters:

parentElement - the parent element

childElements - the child elements to add

remove

public void remove(Object[] elements)

Removals are handled by refreshing the parents of each of the given elements. The parents are determined via calls ot the contentProvider.

Overrides:

remove in class AbstractTreeViewer

Parameters:

elements - the elements to remove

See Also:

AbstractTreeViewer.remove(java.lang.Object[])

refresh

public void refresh(boolean updateLabels)

Description copied from class: StructuredViewer

Refreshes this viewer with information freshly obtained from this viewer's model. If updateLabels is true then labels for otherwise unaffected elements are updated as well. Otherwise, it assumes labels for existing elements are unchanged, and labels are only obtained as needed (for example, for new elements).

Calling refresh(true) has the same effect as refresh().

Note that the implementation may still obtain labels for existing elements even if updateLabels is false. The intent is simply to allow optimization where possible.

Overrides:

refresh in class StructuredViewer

Parameters:

updateLabels - true to update labels for existing elements, false to only update labels as needed, assuming that labels for existing elements are unchanged.

refresh

public void refresh(Object element,
                    boolean updateLabels)

Description copied from class: StructuredViewer

Refreshes this viewer starting with the given element. Labels are updated as described in refresh(boolean updateLabels).

Unlike the update methods, this handles structural changes to the given element (e.g. addition or removal of children). If only the given element needs updating, it is more efficient to use the update methods.

Overrides:

refresh in class StructuredViewer

Parameters:

element - the element

updateLabels - true to update labels for existing elements, false to only update labels as needed, assuming that labels for existing elements are unchanged.

refresh

public void refresh(Object element)

Description copied from class: StructuredViewer

Refreshes this viewer starting with the given element.

Unlike the update methods, this handles structural changes to the given element (e.g. addition or removal of children). If only the given element needs updating, it is more efficient to use the update methods.

Overrides:

refresh in class StructuredViewer

Parameters:

element - the element

update

public void update(Object element,
                   String[] properties)

Description copied from class: StructuredViewer

Updates the given element's presentation when one or more of its properties changes. Only the given element is updated.

This does not handle structural changes (e.g. addition or removal of elements), and does not update any other related elements (e.g. child elements). To handle structural changes, use the refresh methods instead.

This should be called when an element has changed in the model, in order to have the viewer accurately reflect the model. This method only affects the viewer, not the model.

Specifying which properties are affected may allow the viewer to optimize the update. For example, if the label provider is not affected by changes to any of these properties, an update may not actually be required. Specifing properties as null forces a full update of the element.

If the viewer has a sorter which is affected by a change to one of the properties, the element's position is updated to maintain the sort order.

If the viewer has a filter which is affected by a change to one of the properties, the element may appear or disappear if the change affects whether or not the element is filtered out.

Overrides:

update in class StructuredViewer

Parameters:

element - the element

properties - the properties that have changed, or null to indicate unknown

toString

public String toString()