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

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

Eclipse Platform
Release 3.5

PREV CLASS NEXT CLASS

NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

org.eclipse.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
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).

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

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

Eclipse Platform
Release 3.5

PREV CLASS NEXT CLASS

NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

Guidelines for using Eclipse APIs.

org.eclipse.jface.viewers Class ColumnViewer

ColumnViewer

hookControl

hookEditingSupport

createViewerEditor

getCell

getViewerRow

getViewerRowFromItem

getColumnViewerOwner

getItemAt

getItem

setLabelProvider

cancelEditing

applyEditorValue

editElement

getCellEditors

getCellModifier

getColumnProperties

isCellEditorActive

refresh

refresh

update

setCellEditors

setCellModifier

setColumnProperties

doGetColumnCount

getLabelProvider

triggerEditorActivationEvent

setColumnViewerEditor

getColumnViewerEditor

getRawChildren

checkBusy

setBusy

isBusy

org.eclipse.jface.viewers
Class ColumnViewer