org.eclipse.jface.viewers

Class ColumnViewer

java.lang.Object

org.eclipse.jface.viewers.Viewer

org.eclipse.jface.viewers.ContentViewer

org.eclipse.jface.viewers.StructuredViewer

org.eclipse.jface.viewers.ColumnViewer

All Implemented Interfaces:

IInputProvider, IInputSelectionProvider, IPostSelectionProvider, ISelectionProvider

Direct Known Subclasses:

AbstractTableViewer, AbstractTreeViewer

public abstract class ColumnViewer
extends StructuredViewer

The ColumnViewer is the abstract superclass of viewers that have columns (e.g., AbstractTreeViewer and AbstractTableViewer). Concrete subclasses of ColumnViewer should implement a matching concrete subclass of ViewerColumn. This class is not intended to be subclassed outside of the JFace viewers framework.

Since:

3.3

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

WIDGET_DATA_KEY

Constructor Summary

Constructors

Constructor and Description
ColumnViewer() Create a new instance of the receiver.

Method Summary

Methods

Modifier and Type	Method and Description
protected void	applyEditorValue() Apply the value of the active cell editor if one is active.
void	cancelEditing() Cancels a currently active cell editor if one is active.
protected boolean	checkBusy() Checks if this viewer is currently busy, logging a warning and returning true if it is busy.
protected abstract ColumnViewerEditor	createViewerEditor() Creates the viewer editor used for editing cell contents.
protected abstract int	doGetColumnCount() Returns the number of columns contained in the receiver.
void	editElement(Object element, int column) Starts editing the given element at the given column index.
ViewerCell	getCell(Point point) Returns the viewer cell at the given widget-relative coordinates, or null if there is no cell at that location
CellEditor[]	getCellEditors() Return the CellEditors for the receiver, or null if no cell editors are set.
ICellModifier	getCellModifier() Returns the cell modifier of this viewer, or null if none has been set.
Object[]	getColumnProperties() Returns the column properties of this table viewer.
ColumnViewerEditor	getColumnViewerEditor()
protected abstract Widget	getColumnViewerOwner(int columnIndex) Returns the column widget at the given column index.
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 or the underlying SWT-Control is not made up of Item (e.g ListViewer) The default implementation of this method returns null.
protected abstract Item	getItemAt(Point point) Returns the Item at the given widget-relative coordinates, or null if there is no item at the given coordinates.
CellLabelProvider	getLabelProvider(int columnIndex) Returns the label provider associated with the column at the given index or null if no column with this index is known.
protected Object[]	getRawChildren(Object parent) Returns the children of the given parent without sorting and filtering them.
protected ViewerRow	getViewerRow(Point point) Returns the viewer row at the given widget-relative coordinates.
protected abstract ViewerRow	getViewerRowFromItem(Widget item) Returns a ViewerRow associated with the given row widget.
protected void	handleDispose(DisposeEvent event) Handles a dispose event on this viewer's control.
protected void	hookControl(Control control) Adds event listener hooks to the given control.
protected void	hookEditingSupport(Control control) Hook up the editing support.
boolean	isBusy() Returns true if this viewer is currently busy processing a refresh, add, remove, insert, replace, setItemCount, expandToLevel, update, setExpandedElements, or similar method that may make calls to client code.
boolean	isCellEditorActive() Returns whether there is an active cell editor.
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	setBusy(boolean busy) Sets the busy state of this viewer.
void	setCellEditors(CellEditor[] editors) Sets the cell editors of this column viewer.
void	setCellModifier(ICellModifier modifier) Sets the cell modifier for this column viewer.
void	setColumnProperties(String[] columnProperties) Sets the column properties of this column viewer.
void	setColumnViewerEditor(ColumnViewerEditor columnViewerEditor)
void	setLabelProvider(IBaseLabelProvider labelProvider) The column viewer implementation of this Viewer framework method ensures that the given label provider is an instance of ITableLabelProvider, ILabelProvider, or CellLabelProvider.
protected void	triggerEditorActivationEvent(ColumnViewerEditorActivationEvent event) Invoking this method fires an editor activation event which tries to enable the editor but before this event is passed to ColumnViewerEditorActivationStrategy to see if this event should really trigger editor activation
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.StructuredViewer

addDoubleClickListener, addDragSupport, addDropSupport, addFilter, addOpenListener, addPostSelectionChangedListener, assertContentProviderType, assertElementsNotNull, associate, buildLabel, disassociate, doFindInputItem, doFindItem, doUpdateItem, equals, filter, findItem, findItems, fireDoubleClick, fireOpen, firePostSelectionChanged, getColorAndFontCollector, getComparator, getComparer, getFilteredChildren, getFilters, getRoot, getSelection, getSelectionFromWidget, getSortedChildren, getSorter, handleDoubleSelect, handleInvalidSelection, handleLabelProviderChanged, handleOpen, handlePostSelect, handleSelect, hasFilters, internalRefresh, internalRefresh, internalUpdate, mapElement, needsRefilter, preservingSelection, refresh, refresh, refreshItem, removeDoubleClickListener, removeFilter, removeOpenListener, removePostSelectionChangedListener, resetFilters, reveal, setComparator, setComparer, setContentProvider, setFilters, setInput, setSelection, setSelectionToWidget, setSelectionToWidget, setSorter, setUseHashlookup, testFindItem, testFindItems, unmapAllElements, unmapElement, unmapElement, update, updateItem, updateSelection, usingElementMap

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

getContentProvider, getInput, getLabelProvider, labelProviderChanged

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

ColumnViewer

public ColumnViewer()

Create a new instance of the receiver.

Method Detail

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 StructuredViewer

Parameters:

control - the control

hookEditingSupport

protected void hookEditingSupport(Control control)

Hook up the editing support. Subclasses may override.

Parameters:

control - the control you want to hook on

createViewerEditor

protected abstract ColumnViewerEditor createViewerEditor()

Creates the viewer editor used for editing cell contents. To be implemented by subclasses.

Returns:

the editor, or null if this viewer does not support editing cell contents.

getCell

public ViewerCell getCell(Point point)

Returns the viewer cell at the given widget-relative coordinates, or null if there is no cell at that location

Parameters:

point - the widget-relative coordinates

Returns:

the cell or null if no cell is found at the given point

Since:

3.4

getViewerRow

protected ViewerRow getViewerRow(Point point)

Returns the viewer row at the given widget-relative coordinates.

Parameters:

point - the widget-relative coordinates of the viewer row

Returns:

ViewerRow the row or null if no row is found at the given coordinates

getViewerRowFromItem

protected abstract ViewerRow getViewerRowFromItem(Widget item)

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.

Parameters:

item - the row widget

Returns:

ViewerRow a viewer row object

getColumnViewerOwner

protected abstract Widget getColumnViewerOwner(int columnIndex)

Returns the column widget at the given column index.

Parameters:

columnIndex - the column index

Returns:

Widget the column widget

getItemAt

protected abstract Item getItemAt(Point point)

Returns the Item at the given widget-relative coordinates, or null if there is no item at the given coordinates.

Parameters:

point - the widget-relative coordinates

Returns:

the Item at the coordinates or null if there is no item at the given coordinates

getItem

protected Item getItem(int x,
           int y)

Description copied from class: StructuredViewer

Returns the item at the given display-relative coordinates, or null if there is no item at that location or the underlying SWT-Control is not made up of Item (e.g ListViewer)

The default implementation of this method returns null.

Overrides:

getItem in class StructuredViewer

Parameters:

x - horizontal coordinate

y - vertical coordinate

Returns:

the item, or null if there is no item at the given coordinates

setLabelProvider

public void setLabelProvider(IBaseLabelProvider labelProvider)

The column viewer implementation of this Viewer framework method ensures that the given label provider is an instance of ITableLabelProvider, ILabelProvider, or CellLabelProvider.

If the label provider is an ITableLabelProvider , then it provides a separate label text and image for each column. Implementers of ITableLabelProvider may also implement ITableColorProvider and/or ITableFontProvider to provide colors and/or fonts.

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

Overrides:

setLabelProvider in class StructuredViewer

Parameters:

labelProvider - the label provider, or null if none

cancelEditing

public void cancelEditing()

Cancels a currently active cell editor if one is active. All changes already done in the cell editor are lost.

Since:

3.1 (in subclasses, added in 3.3 to abstract class)

applyEditorValue

protected void applyEditorValue()

Apply the value of the active cell editor if one is active.

Since:

3.3

editElement

public void editElement(Object element,
               int column)

Starts editing the given element at the given column index.

Parameters:

element - the model element

column - the column index

Since:

3.1 (in subclasses, added in 3.3 to abstract class)

getCellEditors

public CellEditor[] getCellEditors()

Return the CellEditors for the receiver, or null if no cell editors are set.

Since 3.3, an alternative API is available, see ViewerColumn.setEditingSupport(EditingSupport) for a more flexible way of editing values in a column viewer.

Returns:

CellEditor[]

Since:

3.1 (in subclasses, added in 3.3 to abstract class)

See Also:

ViewerColumn.setEditingSupport(EditingSupport), EditingSupport

getCellModifier

public ICellModifier getCellModifier()

Returns the cell modifier of this viewer, or null if none has been set.

Since 3.3, an alternative API is available, see ViewerColumn.setEditingSupport(EditingSupport) for a more flexible way of editing values in a column viewer.

Returns:

the cell modifier, or null

Since:

3.1 (in subclasses, added in 3.3 to abstract class)

See Also:

ViewerColumn.setEditingSupport(EditingSupport), EditingSupport

getColumnProperties

public Object[] getColumnProperties()

Returns the column properties of this table viewer. The properties must correspond with the columns of the table control. They are used to identify the column in a cell modifier.

Since 3.3, an alternative API is available, see ViewerColumn.setEditingSupport(EditingSupport) for a more flexible way of editing values in a column viewer.

Returns:

the list of column properties

Since:

3.1 (in subclasses, added in 3.3 to abstract class)

See Also:

ViewerColumn.setEditingSupport(EditingSupport), EditingSupport

isCellEditorActive

public boolean isCellEditorActive()

Returns whether there is an active cell editor.

Since 3.3, an alternative API is available, see ViewerColumn.setEditingSupport(EditingSupport) for a more flexible way of editing values in a column viewer.

Returns:

true if there is an active cell editor, and false otherwise

Since:

3.1 (in subclasses, added in 3.3 to abstract class)

See Also:

ViewerColumn.setEditingSupport(EditingSupport), EditingSupport

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

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.

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 StructuredViewer

Parameters:

element - the element

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

setCellEditors

public void setCellEditors(CellEditor[] editors)

Sets the cell editors of this column viewer. If editing is not supported by this viewer the call simply has no effect.

Since 3.3, an alternative API is available, see ViewerColumn.setEditingSupport(EditingSupport) for a more flexible way of editing values in a column viewer.

Users setting up an editable TreeViewer or TableViewer with more than 1 column have to pass the SWT.FULL_SELECTION style bit

Parameters:

editors - the list of cell editors

Since:

3.1 (in subclasses, added in 3.3 to abstract class)

See Also:

ViewerColumn.setEditingSupport(EditingSupport), EditingSupport

setCellModifier

public void setCellModifier(ICellModifier modifier)

Sets the cell modifier for this column viewer. This method does nothing if editing is not supported by this viewer.

Since 3.3, an alternative API is available, see ViewerColumn.setEditingSupport(EditingSupport) for a more flexible way of editing values in a column viewer.

Users setting up an editable TreeViewer or TableViewer with more than 1 column have to pass the SWT.FULL_SELECTION style bit

Parameters:

modifier - the cell modifier

Since:

3.1 (in subclasses, added in 3.3 to abstract class)

See Also:

ViewerColumn.setEditingSupport(EditingSupport), EditingSupport

setColumnProperties

public void setColumnProperties(String[] columnProperties)

Sets the column properties of this column viewer. The properties must correspond with the columns of the control. They are used to identify the column in a cell modifier. If editing is not supported by this viewer the call simply has no effect.

Since 3.3, an alternative API is available, see ViewerColumn.setEditingSupport(EditingSupport) for a more flexible way of editing values in a column viewer.

Users setting up an editable TreeViewer or TableViewer with more than 1 column have to pass the SWT.FULL_SELECTION style bit

Parameters:

columnProperties - the list of column properties

Since:

3.1 (in subclasses, added in 3.3 to abstract class)

See Also:

ViewerColumn.setEditingSupport(EditingSupport), EditingSupport

doGetColumnCount

protected abstract int doGetColumnCount()

Returns the number of columns contained in the receiver. If no columns were created by the programmer, this value is zero, despite the fact that visually, one column of items may be visible. This occurs when the programmer uses the column viewer like a list, adding elements but never creating a column.

Returns:

the number of columns

Since:

3.3

getLabelProvider

public CellLabelProvider getLabelProvider(int columnIndex)

Returns the label provider associated with the column at the given index or null if no column with this index is known.

Parameters:

columnIndex - the column index

Returns:

the label provider associated with the column or null if no column with this index is known

Since:

3.3

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

triggerEditorActivationEvent

protected void triggerEditorActivationEvent(ColumnViewerEditorActivationEvent event)

Invoking this method fires an editor activation event which tries to enable the editor but before this event is passed to ColumnViewerEditorActivationStrategy to see if this event should really trigger editor activation

Parameters:

event - the activation event

setColumnViewerEditor

public void setColumnViewerEditor(ColumnViewerEditor columnViewerEditor)

Parameters:

columnViewerEditor - the new column viewer editor

getColumnViewerEditor

public ColumnViewerEditor getColumnViewerEditor()

Returns:

the currently attached viewer editor

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 StructuredViewer

Parameters:

parent - the parent element

Returns:

the child elements

checkBusy

protected boolean checkBusy()

Checks if this viewer is currently busy, logging a warning and returning true if it is busy. A column viewer is busy when it is processing a refresh, add, remove, insert, replace, setItemCount, expandToLevel, update, setExpandedElements, or similar method that may make calls to client code. Column viewers are not designed to handle reentrant calls while they are busy. The method returns true if the viewer is busy. It is recommended that this method be used by subclasses to determine whether the viewer is busy to return early from state-changing methods.

This method is not intended to be overridden by subclasses.

Returns:

true if the viewer is busy.

Since:

3.4

setBusy

protected void setBusy(boolean busy)

Sets the busy state of this viewer. Subclasses MUST use try ...finally as follows to ensure that the busy flag is reset to its original value:

 boolean oldBusy = isBusy();
 setBusy(true);
 try {
        // do work
 } finally {
        setBusy(oldBusy);
 }
 

This method is not intended to be overridden by subclasses.

Parameters:

busy - the new value of the busy flag

Since:

3.4

isBusy

public boolean isBusy()

Returns true if this viewer is currently busy processing a refresh, add, remove, insert, replace, setItemCount, expandToLevel, update, setExpandedElements, or similar method that may make calls to client code. Column viewers are not designed to handle reentrant calls while they are busy. It is recommended that clients avoid using this method if they can ensure by other means that they will not make reentrant calls to methods like the ones listed above. See bug 184991 for background discussion.

This method is not intended to be overridden by subclasses.

Returns:

Returns whether this viewer is busy.

Since:

3.4