Package 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
Description
`ColumnViewer()`
Create a new instance of the receiver.

## Method Summary

Modifier and Type
Method
Description
`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 void`
`disassociate(Item item)`
Disassociates the given SWT item from its corresponding element.
`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`)
`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 Object[]`
`getSortedChildren(Object parent)`
Returns the sorted and filtered set of children of the given element.
`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`
`handleDoubleSelect(SelectionEvent event)`
Handles a double-click select event from the 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.
`final boolean`
`isExpandableNode(Object element)`
EXPERIMENTAL.
`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`
`setDisplayIncrementally(int incrementSize)`
EXPERIMENTAL.
`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, doFindInputItem, doFindItem, doUpdateItem, equals, filter, findItem, findItems, fireDoubleClick, fireOpen, firePostSelectionChanged, getColorAndFontCollector, getComparator, getComparer, getFilteredChildren, getFilters, getRoot, getSelection, getSelectionFromWidget, getSorter, getStructuredSelection, 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 Details

### ColumnViewer

public ColumnViewer()
Create a new instance of the receiver.

## Method Details

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

public void applyEditorValue()
Apply the value of the active cell editor if one is active.

Since:
  3.11 (public - protected 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

### getSortedChildren

protected Object[] getSortedChildren(Object parent)
Description copied from class: `StructuredViewer`
Returns the sorted and filtered set of children of the given element. The resulting array must not be modified, as it may come directly from the model's internal state.

Overrides:
  `getSortedChildren` in class `StructuredViewer`
Parameters:
  `parent` - the parent element
Returns:
  a sorted and filtered array of child elements

### setDisplayIncrementally

public void setDisplayIncrementally(int incrementSize)

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

Sets the viewers items limit on direct children at one level.

If the number of direct children will exceed this limit, the viewer will only show a subset of children up to the limit and add an `ExpandableNode` element after last shown item.

This method must be called before `StructuredViewer.setInput(Object)`. A parameter less than or equal to zero has no effect on the viewer.

This API does not guaranteed to work with `SWT.VIRTUAL` viewers.

Parameters:
  `incrementSize` - A non-negative integer greater than 0 to enable items limit
Since:
  3.31

### disassociate

protected void disassociate(Item item)
Description copied from class: `StructuredViewer`
Disassociates the given SWT item from its corresponding element. Sets the item's data to `null` and removes the element from the element map (if enabled).

Overrides:
  `disassociate` in class `StructuredViewer`
Parameters:
  `item` - the widget

### 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 `StructuredViewer`
Parameters:
  `event` - the SWT selection event

### isExpandableNode

public final boolean isExpandableNode(Object element)

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

Parameters:
  `element` - model object representing a special "expandable" node
Returns:
  return if it is an instance of ExpandableNode
Since:
  3.31