Eclipse Platform
Release 3.6

org.eclipse.jface.viewers
Class ColumnViewer

java.lang.Object
  extended by org.eclipse.jface.viewers.Viewer
      extended by org.eclipse.jface.viewers.ContentViewer
          extended by org.eclipse.jface.viewers.StructuredViewer
              extended by 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
ColumnViewer()
          Create a new instance of the receiver.
 
Method Summary
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 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, handleDispose, 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

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

Eclipse Platform
Release 3.6

Guidelines for using Eclipse APIs.

Copyright (c) Eclipse contributors and others 2000, 2010. All rights reserved.