Eclipse Plug-in Developer Guide (Galileo) - CommonViewer (Eclipse Platform API Specification)

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

Eclipse Platform
Release 3.5

PREV CLASS NEXT CLASS

NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

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.ColumnViewer
                  

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
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.

Note that as of 3.2.1 and 3.3, the common viewer caches its selection. Clients must not set the selection of the viewer's tree control directly.

Since:: 3.2

Nested Class Summary

Nested classes/interfaces 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

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 CommonDragAdapter createDragAdapter ()
          Creates the CommonDragAdapter, this is used to provide a subclass if desired.

protected CommonDropAdapter createDropAdapter ()
          Creates the CommonDropAdapter, this is used to provide a subclass if desired.

void createFrameList ()


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

void doUpdateItem ( Widget item)
          Update an item in the tree.

CommonNavigator getCommonNavigator ()


org.eclipse.ui.internal.navigator.framelist.FrameList getFrameList ()


ICommonViewerMapper getMapper ()
          Gets the ICommonViewerMapper assigned to this viewer.

INavigatorContentService getNavigatorContentService ()
           The INavigatorContentServiceprovides the hook into the framework to provide content from the various extensions.

ISelection getSelection ()
          Returns the current selection.

protected void handleDispose ( DisposeEvent event)
          Handles a dispose event on this viewer's control.

protected void handleDoubleSelect ( SelectionEvent event)
          Handles a double-click select event from the widget.

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 handleOpen ( SelectionEvent event)
          Handles an open event from the OpenStrategy.

protected void handlePostSelect ( SelectionEvent e)
          Handles a post select event from the widget.

protected void handleSelect ( SelectionEvent event)
          Handles a select event from the widget.

protected void hookControl ( Control control)
          Adds event listener hooks to the given control.

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 internalRefresh ( Object element, boolean updateLabels)
          Refreshes this viewer starting at the given element.

protected void mapElement ( Object element, Widget item)
          Adds the element item pair to the element map.

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)


void setMapper ( ICommonViewerMapper mapper)
          Sets the ICommonViewerMapper to work with this viewer.

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

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 ()


protected void unmapAllElements ()
          Removes all elements from the map.

protected void unmapElement ( Object element, Widget item)
          Removes the given association from the internal element to widget map.

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, createChildren, createViewerEditor, disassociate, doGetColumnCount, editElement, getChild, getChildren, getColumnViewerOwner, getControl, getExpanded, getItemAt, getItemCount, getItemCount, getItems, getLabelProvider, getParentElement, getParentItem, getRawChildren, getSelection, getTree, getViewerRowFromItem, handleTreeCollapse, handleTreeExpand, internalAdd, internalInitializeTree, internalRefreshStruct, isExpandable, newItem, remove, removeAll, replace, setChildCount, setContentProvider, setExpanded, setHasChildren, setSelection, showItem, updatePlus

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

add, addSelectionListener, addTreeListener, associate, buildLabel, collapseAll, collapseToLevel, createTreeItem, doFindInputItem, doFindItem, doUpdateItem, doUpdateItem, expandAll, expandToLevel, expandToLevel, fireTreeCollapsed, fireTreeExpanded, getAutoExpandLevel, getChildren, getExpandedElements, getExpandedState, getExpandedTreePaths, getFilteredChildren, getNextItem, getPreviousItem, getSelectionFromWidget, getSortedChildren, getTreePathFromItem, getVisibleExpandedElements, indexForElement, inputChanged, insert, internalCollapseToLevel, internalExpand, internalExpandToLevel, internalFindItems, internalGetWidgetToSelect, internalIsInputOrEmptyPath, internalRefresh, internalRefresh, internalRemove, internalRemove, isSameSelection, labelProviderChanged, remove, remove, removeTreeListener, reveal, scrollDown, scrollUp, setAutoExpandLevel, setExpandedElements, setExpandedState, setExpandedTreePaths, setSelectionToWidget, updateChildren

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

applyEditorValue, cancelEditing, checkBusy, getCell, getCellEditors, getCellModifier, getColumnProperties, getColumnViewerEditor, getItem, getLabelProvider, getViewerRow, hookEditingSupport, isBusy, isCellEditorActive, setBusy, setCellEditors, setCellModifier, setColumnProperties, setColumnViewerEditor, setLabelProvider, triggerEditorActivationEvent

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, hasFilters, internalUpdate, needsRefilter, preservingSelection, refresh, refresh, refreshItem, removeDoubleClickListener, removeFilter, removeOpenListener, removePostSelectionChangedListener, resetFilters, setComparator, setComparer, setFilters, setInput, setUseHashlookup, testFindItem, testFindItems, 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.

setMapper

public void setMapper(
ICommonViewerMapper mapper)

Sets the ICommonViewerMapper to work with this viewer.

Parameters:: mapper -
Since:: 3.4

getMapper

public 
ICommonViewerMapper getMapper()

Gets the ICommonViewerMapper assigned to this viewer.

Returns:: the mapper
Since:: 3.4

getCommonNavigator

public 
CommonNavigator getCommonNavigator()

Returns:: the CommonNavigator
Since:: 3.4

removeWithoutRefresh

protected void removeWithoutRefresh(
Object[] elements)

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()

See Also:: CommonDragAdapter, CommonDropAdapter

createDragAdapter

protected 
CommonDragAdapter createDragAdapter()

Creates the CommonDragAdapter, this is used to provide a subclass if desired.

Returns:: the CommonDragAdapter
Since:: 3.4

createDropAdapter

protected 
CommonDropAdapter createDropAdapter()

Creates the CommonDropAdapter, this is used to provide a subclass if desired.

Returns:: the CommonDropAdapter
Since:: 3.4

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 StructuredViewer

Parameters:: event - a dispose event

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(
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 ColumnViewer

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.

setSelection

public void setSelection(
ISelection selection,
                         boolean reveal)

Description copied from class: TreeViewer

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 TreeViewer

Parameters:: selection - the new selection; reveal - true if the selection is to be made visible, and false otherwise

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 TreeViewer

Parameters:: control - the control

doUpdateItem

public void doUpdateItem(
Widget item)

Update an item in the tree.

Parameters:: item - the item in the tree to update
Since:: 3.4

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 TreeViewer

Parameters:: element - the element; item - the corresponding widget

unmapElement

protected void unmapElement(
Object element,
                            
Widget item)

Description copied from class: StructuredViewer

Removes the given association from the internal element to widget map. Does nothing if mapping is disabled, or if the given element does not map to the given item.

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

Overrides:: unmapElement in class StructuredViewer

Parameters:: element - the element; item - the item to unmap

unmapAllElements

protected void unmapAllElements()

Description copied from class: StructuredViewer

Removes all elements from the map.

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

Overrides:: unmapAllElements in class StructuredViewer

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

Parameters:: v - list of selected elements (element type: Object) or null if the selection is to be cleared; reveal - true if the selection is to be made visible, and false otherwise

handleDoubleSelect

protected void handleDoubleSelect(
SelectionEvent event)

Description copied from class: StructuredViewer

Handles a double-click select event from the widget.

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

Overrides:: handleDoubleSelect in class AbstractTreeViewer

Parameters:: event - the SWT selection event

handleOpen

protected void handleOpen(
SelectionEvent event)

Description copied from class: StructuredViewer

Handles an open event from the OpenStrategy.

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

Overrides:: handleOpen in class StructuredViewer

Parameters:: event - the SWT selection event

handlePostSelect

protected void handlePostSelect(
SelectionEvent e)

Description copied from class: StructuredViewer

Handles a post select event from the widget.

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

Overrides:: handlePostSelect in class StructuredViewer

Parameters:: e - the SWT selection event

handleSelect

protected void handleSelect(
SelectionEvent event)

Description copied from class: StructuredViewer

Handles a select event from the widget.

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

Overrides:: handleSelect in class StructuredViewer

Parameters:: event - the SWT selection event

getSelection

public 
ISelection getSelection()

Returns the current selection.

Note that as of 3.2.1 and 3.3, the common viewer caches its selection. Clients must not set the selection of the viewer's tree control directly.

Specified by:: getSelection in interface ISelectionProvider
Overrides:: getSelection in class AbstractTreeViewer

Returns:: ISelection
See Also:: AbstractTreeViewer.getSelection()

refresh

public void refresh(
Object element)

Description copied from class: StructuredViewer

Refreshes this viewer starting with the given element.

Overrides:: refresh in class ColumnViewer

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. Specifying 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. Note that resorting may not happen if properties is null.

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. Note that filtering may not happen if properties is null.

Overrides:: update in class ColumnViewer

Parameters:: element - the element; properties - the properties that have changed, or null to indicate unknown

toString

public 
String toString()

Overrides:: toString in class Object

internalRefresh

protected void internalRefresh(
Object element,
                               boolean updateLabels)

Description copied from class: StructuredViewer

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

The default implementation simply calls internalRefresh(element), ignoring updateLabels.

If this method is overridden to do the actual refresh, then internalRefresh(Object element) should simply call internalRefresh(element, true).

Overrides:: internalRefresh in class AbstractTreeViewer

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.

createFrameList

public void createFrameList()

Since:: 3.4
Restriction:: This method is not intended to be referenced by clients.
Restriction:: This method is not intended to be re-implemented or extended by clients.

getFrameList

public org.eclipse.ui.internal.navigator.framelist.FrameList getFrameList()

Returns:: a FrameList
Since:: 3.4
Restriction:: This method is not intended to be referenced by clients.
Restriction:: This method is not intended to be re-implemented or extended by clients.

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

Eclipse Platform
Release 3.5

PREV CLASS NEXT CLASS

NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

Guidelines for using Eclipse APIs.

org.eclipse.ui.navigator Class CommonViewer

CommonViewer

init

setMapper

getMapper

getCommonNavigator

removeWithoutRefresh

initDragAndDrop

createDragAdapter

createDropAdapter

handleLabelProviderChanged

handleDispose

dispose

setSorter

getNavigatorContentService

add

remove

refresh

setSelection

hookControl

doUpdateItem

mapElement

unmapElement

unmapAllElements

setSelectionToWidget

handleDoubleSelect

handleOpen

handlePostSelect

handleSelect

getSelection

refresh

update

toString

internalRefresh

createFrameList

getFrameList

org.eclipse.ui.navigator
Class CommonViewer