|
Eclipse Platform Release 3.0 |
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectorg.eclipse.jface.viewers.Viewer
org.eclipse.jface.viewers.ContentViewer
org.eclipse.jface.viewers.StructuredViewer
Abstract base implementation for structure-oriented viewers (trees, lists, tables). Supports custom sorting, filtering, and rendering.
Any number of viewer filters can be added to this viewer (using
addFilter
). When the viewer receives an update, it asks each
of its filters if it is out of date, and refilters elements as required.
ViewerFilter
,
ViewerSorter
Field Summary |
Fields inherited from class org.eclipse.jface.viewers.Viewer |
WIDGET_DATA_KEY |
Constructor Summary | |
protected |
StructuredViewer()
Creates a structured element viewer. |
Method Summary | |
void |
addDoubleClickListener(IDoubleClickListener listener)
Adds a listener for double-clicks in this viewer. |
void |
addDragSupport(int operations,
Transfer[] transferTypes,
DragSourceListener listener)
Adds support for dragging items out of this viewer via a user drag-and-drop operation. |
void |
addDropSupport(int operations,
Transfer[] transferTypes,
DropTargetListener listener)
Adds support for dropping items into this viewer via a user drag-and-drop operation. |
void |
addFilter(ViewerFilter filter)
Adds the given filter to this viewer, and triggers refiltering and resorting of the elements. |
void |
addOpenListener(IOpenListener listener)
Adds a listener for selection-open in this viewer. |
void |
addPostSelectionChangedListener(ISelectionChangedListener listener)
Adds a listener for post selection changes in this selection provider. |
protected void |
assertElementsNotNull(Object[] elements)
Asserts that the given array of elements is itself non- null
and contains no null elements. |
protected void |
associate(Object element,
Item item)
Associates the given element with the given widget. |
protected void |
disassociate(Item item)
Disassociates the given SWT item from its corresponding element. |
protected abstract Widget |
doFindInputItem(Object element)
Returns the widget in this viewer's control which represents the given element if it is the viewer's input. |
protected abstract Widget |
doFindItem(Object element)
Returns the widget in this viewer's control which represent the given element. |
protected abstract void |
doUpdateItem(Widget item,
Object element,
boolean fullMap)
Copies the attributes of the given element into the given SWT item. |
protected boolean |
equals(Object elementA,
Object elementB)
Compares two elements for equality. |
protected Object[] |
filter(Object[] elements)
Returns the result of running the given elements through the filters. |
protected Widget |
findItem(Object element)
Finds the widget which represents the given element. |
protected void |
fireDoubleClick(DoubleClickEvent event)
Notifies any double-click listeners that a double-click has been received. |
protected void |
fireOpen(OpenEvent event)
Notifies any open event listeners that a open event has been received. |
protected void |
firePostSelectionChanged(SelectionChangedEvent event)
Notifies any post selection listeners that a post selection event has been received. |
IElementComparer |
getComparer()
Returns the comparator to use for comparing elements, or null if none has been set. |
protected Object[] |
getFilteredChildren(Object parent)
Returns the filtered array of children of the given element. |
ViewerFilter[] |
getFilters()
Returns this viewer's filters. |
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 Object[] |
getRawChildren(Object parent)
Returns the children of the given parent without sorting and filtering them. |
protected Object |
getRoot()
Returns the root element. |
ISelection |
getSelection()
The StructuredViewer implementation of this method returns
the result as an IStructuredSelection .
|
protected abstract List |
getSelectionFromWidget()
Retrieves the selection, as a List , from the underlying
widget. |
protected Object[] |
getSortedChildren(Object parent)
Returns the sorted and filtered set of children of the given element. |
ViewerSorter |
getSorter()
Returns this viewer's sorter, or null if it does not have
one. |
protected void |
handleDoubleSelect(SelectionEvent event)
Handles a double-click select event from the widget. |
protected void |
handleInvalidSelection(ISelection invalidSelection,
ISelection newSelection)
Handles an invalid selection. |
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 boolean |
hasFilters()
Returns whether this viewer has any filters. |
protected void |
hookControl(Control control)
Adds event listener hooks to the given control. |
protected abstract void |
internalRefresh(Object element)
Refreshes this viewer starting at the given element. |
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. |
protected boolean |
needsRefilter(Object element,
String property)
Determines whether a change to the given property of the given element would require refiltering and/or resorting. |
protected void |
preservingSelection(Runnable updateCode)
Attempts to preserves the current selection across a run of the given code. |
void |
refresh()
Refreshes this viewer completely with information freshly obtained from this viewer's model. |
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. |
protected void |
refreshItem(Widget widget,
Object element)
Refreshes the given TableItem with the given element. |
void |
removeDoubleClickListener(IDoubleClickListener listener)
Removes the given double-click listener from this viewer. |
void |
removeFilter(ViewerFilter filter)
Removes the given filter from this viewer, and triggers refiltering and resorting of the elements if required. |
void |
removeOpenListener(IOpenListener listener)
Removes the given open listener from this viewer. |
void |
removePostSelectionChangedListener(ISelectionChangedListener listener)
Removes the given listener for post selection changes from this selection provider. |
void |
resetFilters()
Discards this viewer's filters and triggers refiltering and resorting of the elements. |
abstract void |
reveal(Object element)
Ensures that the given element is visible, scrolling the viewer if necessary. |
void |
setComparer(IElementComparer comparer)
Sets the comparator to use for comparing elements, or null
to use the default equals and hashCode
methods on the elements themselves. |
void |
setContentProvider(IContentProvider provider)
Sets the content provider used by this viewer. |
void |
setInput(Object input)
The ContentViewer implementation of this Viewer
method invokes inputChanged on the content provider and then the
inputChanged hook method. |
void |
setSelection(ISelection selection,
boolean reveal)
Sets a new selection for this viewer and optionally makes it visible. |
protected void |
setSelectionToWidget(ISelection selection,
boolean reveal)
Converts the selection to a List and calls
setSelectionToWidget(List, boolean) . |
protected abstract void |
setSelectionToWidget(List l,
boolean reveal)
Parlays the given list of selected elements into selections on this viewer's control. |
void |
setSorter(ViewerSorter sorter)
Sets this viewer's sorter and triggers refiltering and resorting of this viewer's element. |
void |
setUseHashlookup(boolean enable)
Configures whether this structured viewer uses an internal hash table to speeds up the mapping between elements and SWT items. |
Widget |
testFindItem(Object element)
Hook for testing. |
protected void |
unmapAllElements()
Removes all elements from the map. |
protected void |
unmapElement(Object element)
Removes the given element from the internal element to widget map. |
protected void |
unmapElement(Object element,
Widget item)
Removes the given association from the internal element to widget map. |
void |
update(Object[] elements,
String[] properties)
Updates the given elements' presentation when one or more of their properties change. |
void |
update(Object element,
String[] properties)
Updates the given element's presentation when one or more of its properties changes. |
protected void |
updateItem(Widget widget,
Object element)
Copies attributes of the given element into the given widget. |
protected void |
updateSelection(ISelection selection)
Updates the selection of this viewer. |
protected boolean |
usingElementMap()
Returns whether this structured viewer is configured to use an internal map to speed up the mapping between elements and SWT items. |
Methods inherited from class org.eclipse.jface.viewers.ContentViewer |
getContentProvider, getInput, getLabelProvider, handleDispose, labelProviderChanged, setLabelProvider |
Methods inherited from class org.eclipse.jface.viewers.Viewer |
addHelpListener, addSelectionChangedListener, fireHelpRequested, fireSelectionChanged, getControl, getData, handleHelpRequest, inputChanged, removeHelpListener, removeSelectionChangedListener, scrollDown, scrollUp, 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 |
protected StructuredViewer()
Method Detail |
public void addDoubleClickListener(IDoubleClickListener listener)
listener
- a double-click listenerpublic void addOpenListener(IOpenListener listener)
listener
- a double-click listenerpublic void addPostSelectionChangedListener(ISelectionChangedListener listener)
IPostSelectionProvider
addPostSelectionChangedListener
in interface IPostSelectionProvider
listener
- a selection changed listenerpublic void addDragSupport(int operations, Transfer[] transferTypes, DragSourceListener listener)
operations
- a bitwise OR of the supported drag and drop operation types (
DROP_COPY
,DROP_LINK
, and
DROP_MOVE
)transferTypes
- the transfer types that are supported by the drag operationlistener
- the callback that will be invoked to set the drag data and to
cleanup after the drag and drop operation finishesDND
public void addDropSupport(int operations, Transfer[] transferTypes, DropTargetListener listener)
operations
- a bitwise OR of the supported drag and drop operation types (
DROP_COPY
,DROP_LINK
, and
DROP_MOVE
)transferTypes
- the transfer types that are supported by the drop operationlistener
- the callback that will be invoked after the drag and drop
operation finishesDND
public void addFilter(ViewerFilter filter)
filter
- a viewer filterprotected void assertElementsNotNull(Object[] elements)
null
and contains no null
elements.
elements
- the array to checkprotected void associate(Object element, Item item)
element
- the elementitem
- the widgetprotected void disassociate(Item item)
null
and removes the element from the
element map (if enabled).
item
- the widgetprotected abstract Widget doFindInputItem(Object element)
This method is internal to the framework; subclassers should not call this method.
element
-
null
if noneprotected abstract Widget doFindItem(Object element)
This method is internal to the framework; subclassers should not call this method.
element
-
null
if noneprotected abstract void doUpdateItem(Widget item, Object element, boolean fullMap)
fullMap
.
If fullMap
is true
then the current mapping
from element to widgets is removed and the new mapping is added. If
fullmap is false
then only the new map gets installed.
Installing only the new map is necessary in cases where only the order of
elements changes but not the set of elements.
This method is internal to the framework; subclassers should not call this method.
item
- element
- elementfullMap
- true
if mappings are added and removed, and
false
if only the new map gets installedprotected boolean equals(Object elementA, Object elementB)
equals
method on the
elements themselves.
elementA
- the first elementelementB
- the second element
protected Object[] filter(Object[] elements)
elements
- the elements to filter
protected final Widget findItem(Object element)
The default implementation of this method tries first to find the widget
for the given element assuming that it is the viewer's input; this is
done by calling doFindInputItem
. If it is not found
there, it is looked up in the internal element map provided that this
feature has been enabled. If the element map is disabled, the widget is
found via doFindInputItem
.
element
- the element
null
if noneprotected void fireDoubleClick(DoubleClickEvent event)
event
- a double-click eventIDoubleClickListener.doubleClick(org.eclipse.jface.viewers.DoubleClickEvent)
protected void fireOpen(OpenEvent event)
event
- a double-click eventIOpenListener.open(OpenEvent)
protected void firePostSelectionChanged(SelectionChangedEvent event)
event
- a selection changed eventaddPostSelectionChangedListener(ISelectionChangedListener)
public IElementComparer getComparer()
null
if none has been set.
null
protected Object[] getFilteredChildren(Object parent)
parent
- the parent element
public ViewerFilter[] getFilters()
protected Item getItem(int x, int y)
null
if there is no item at that location.
The default implementation of this method returns null
.
x
- horizontal coordinatey
- vertical coordinate
null
if there is no item at the given
coordinatesprotected Object[] getRawChildren(Object parent)
Returns an empty array if the given parent is null
.
parent
- the parent element
protected Object getRoot()
The default implementation of this framework method forwards to
getInput
. Override if the root element is different from
the viewer's input element.
null
if nonepublic ISelection getSelection()
StructuredViewer
implementation of this method returns
the result as an IStructuredSelection
.
Subclasses do not typically override this method, but implement
getSelectionFromWidget(List)
instead.
getSelection
in interface ISelectionProvider
getSelection
in class Viewer
protected abstract List getSelectionFromWidget()
List
, from the underlying
widget.
protected Object[] getSortedChildren(Object parent)
parent
- the parent element
public ViewerSorter getSorter()
null
if it does not have
one.
null
if noneprotected void handleDoubleSelect(SelectionEvent event)
This method is internal to the framework; subclassers should not call this method.
event
- the SWT selection eventprotected void handleOpen(SelectionEvent event)
This method is internal to the framework; subclassers should not call this method.
event
- the SWT selection eventprotected void handleInvalidSelection(ISelection invalidSelection, ISelection newSelection)
This framework method is called if a model change picked up by a viewer
results in an invalid selection. For instance if an element contained in
the selection has been removed from the viewer, the viewer is free to
either remove the element from the selection or to pick another element
as its new selection. The default implementation of this method calls
updateSelection
. Subclasses may override it to implement
a different strategy for picking a new selection when the old selection
becomes invalid.
invalidSelection
- the selection before the viewer was updatednewSelection
- the selection after the update, or null
if noneprotected void handleLabelProviderChanged(LabelProviderChangedEvent event)
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.
handleLabelProviderChanged
in class ContentViewer
event
- the event that generated this updateprotected void handleSelect(SelectionEvent event)
This method is internal to the framework; subclassers should not call this method.
event
- the SWT selection eventprotected void handlePostSelect(SelectionEvent e)
This method is internal to the framework; subclassers should not call this method.
e
- the SWT selection eventprotected void hookControl(Control control)
ContentViewer
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.
hookControl
in class ContentViewer
control
- the controlprotected boolean hasFilters()
protected abstract void internalRefresh(Object element)
element
- the elementprotected void internalRefresh(Object element, boolean updateLabels)
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)
.
element
- the elementupdateLabels
- true
to update labels for existing elements,
false
to only update labels as needed, assuming
that labels for existing elements are unchanged.protected void mapElement(Object element, Widget item)
This method is internal to the framework; subclassers should not call this method.
element
- the elementitem
- the corresponding widgetprotected boolean needsRefilter(Object element, String property)
This method is internal to the framework; subclassers should not call this method.
element
- the elementproperty
- the property
true
if refiltering is required, and
false
otherwiseprotected void preservingSelection(Runnable updateCode)
The default implementation of this method:
getSelection
)setSelectionToWidget
getSelection
)
handleInvalidSelection
if the selection did not
takepostUpdateHook
updateCode
- the code to runpublic void refresh()
Viewer
refresh
in class Viewer
public void refresh(boolean updateLabels)
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.
updateLabels
- true
to update labels for existing elements,
false
to only update labels as needed, assuming
that labels for existing elements are unchanged.public void refresh(Object 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.
element
- the elementpublic void refresh(Object element, boolean updateLabels)
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.
element
- the elementupdateLabels
- true
to update labels for existing elements,
false
to only update labels as needed, assuming
that labels for existing elements are unchanged.protected final void refreshItem(Widget widget, Object element)
doUpdateItem(..., false)
.
This method is internal to the framework; subclassers should not call this method.
widget
- element
- public void removeOpenListener(IOpenListener listener)
listener
- a double-click listenerpublic void removePostSelectionChangedListener(ISelectionChangedListener listener)
IPostSelectionProvider
removePostSelectionChangedListener
in interface IPostSelectionProvider
listener
- a selection changed listenerpublic void removeDoubleClickListener(IDoubleClickListener listener)
listener
- a double-click listenerpublic void removeFilter(ViewerFilter filter)
filter
- a viewer filterpublic void resetFilters()
public abstract void reveal(Object element)
element
- the element to revealpublic void setContentProvider(IContentProvider provider)
ContentViewer
The ContentViewer
implementation of this method records the
content provider in an internal state variable.
Overriding this method is generally not required;
however, if overriding in a subclass,
super.setContentProvider
must be invoked.
setContentProvider
in class ContentViewer
provider
- the content providerContentViewer.getContentProvider()
public final void setInput(Object input)
ContentViewer
ContentViewer
implementation of this Viewer
method invokes inputChanged
on the content provider and then the
inputChanged
hook method. This method fails if this viewer does
not have a content provider. Subclassers are advised to override
inputChanged
rather than this method, but may extend this method
if required.
setInput
in class ContentViewer
public void setSelection(ISelection selection, boolean reveal)
Viewer
Subclasses must implement this method.
setSelection
in class Viewer
selection
- the new selectionreveal
- true
if the selection is to be made
visible, and false
otherwiseprotected abstract void setSelectionToWidget(List l, boolean reveal)
Subclasses should override to set their selection based on the given list of elements.
l
- list of selected elements (element type: Object
)
or null
if the selection is to be clearedreveal
- true
if the selection is to be made visible,
and false
otherwiseprotected void setSelectionToWidget(ISelection selection, boolean reveal)
List
and calls
setSelectionToWidget(List, boolean)
. The selection is
expected to be an IStructuredSelection
of elements. If
not, the selection is cleared.
Subclasses do not typically override this method, but implement
setSelectionToWidget(List, boolean)
instead.
selection
- an IStructuredSelection of elementsreveal
- true
to reveal the first element in the
selection, or false
otherwisepublic void setSorter(ViewerSorter sorter)
null
turns sorting off.
sorter
- a viewer sorter, or null
if nonepublic void setUseHashlookup(boolean enable)
setInput
).
enable
- true
to enable hash lookup, and
false
to disable itpublic void setComparer(IElementComparer comparer)
null
to use the default equals
and hashCode
methods on the elements themselves.
comparer
- the comparator to use for comparing elements or
null
public Widget testFindItem(Object element)
element
-
protected void unmapAllElements()
This method is internal to the framework; subclassers should not call this method.
protected void unmapElement(Object element)
This method is internal to the framework; subclassers should not call this method.
element
- the elementprotected void unmapElement(Object element, Widget item)
This method is internal to the framework; subclassers should not call this method.
element
- the elementitem
- the item to unmappublic void update(Object[] elements, String[] properties)
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 given elements.
If the viewer has a sorter which is affected by a change to one of the properties, the elements' positions are updated to maintain the sort order.
If the viewer has a filter which is affected by a change to one of the properties, elements may appear or disappear if the change affects whether or not they are filtered out.
elements
- the elementsproperties
- the properties that have changed, or null
to
indicate unknownpublic void update(Object element, String[] properties)
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.
element
- the elementproperties
- the properties that have changed, or null
to
indicate unknownprotected final void updateItem(Widget widget, Object element)
This method is internal to the framework; subclassers should not call
this method. Calls doUpdateItem(widget, element, true)
.
widget
- the widgetelement
- the elementprotected void updateSelection(ISelection selection)
This framework method should be called when the selection in the viewer widget changes.
The default implementation of this method notifies all selection change
listeners recorded in an internal state variable. Overriding this method
is generally not required; however, if overriding in a subclass,
super.updateSelection
must be invoked.
selection
- the selection, or null
if noneprotected boolean usingElementMap()
The default implementation of this framework method checks whether the internal map has been initialized.
true
if the element map is enabled, and
false
if disabled
|
Eclipse Platform Release 3.0 |
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
Guidelines for using Eclipse APIs.
Copyright (c) IBM Corp. and others 2000, 2004. All rights reserved.