Eclipse Platform
Release 3.1

org.eclipse.jface.viewers
Class TableViewer

java.lang.Object
  extended byorg.eclipse.jface.viewers.Viewer
      extended byorg.eclipse.jface.viewers.ContentViewer
          extended byorg.eclipse.jface.viewers.StructuredViewer
              extended byorg.eclipse.jface.viewers.TableViewer
All Implemented Interfaces:
IInputProvider, IInputSelectionProvider, IPostSelectionProvider, ISelectionProvider
Direct Known Subclasses:
CheckboxTableViewer

public class TableViewer
extends StructuredViewer

A concrete viewer based on a SWT Table control.

This class is not intended to be subclassed outside the viewer framework. It is designed to be instantiated with a pre-existing SWT table control and configured with a domain-specific content provider, table label provider, element filter (optional), and element sorter (optional).

Label providers for table viewers must implement either the ITableLabelProvider or the ILabelProvider interface (see TableViewer.setLabelProvider for more details).

As of 3.1 the TableViewer now supports the SWT.VIRTUAL flag. It is important to note that if SWT.VIRTUAL is in use that the Widget based APIs will return null in both the cases where either the element is not specified or not created yet.

Users of SWT.VIRTUAL should also avoid using getItems() from the Table within the TreeViewer as this does not necessarily generate a callback for the TreeViewer to populate the items. It also has the side effect of creating all of the items thereby eliminating the performance improvements of SWT.VIRTUAL.

See Also:
SWT.VIRTUAL, doFindItem(Object), internalRefresh(Object, boolean)

Nested Class Summary
 
Nested classes inherited from class org.eclipse.jface.viewers.StructuredViewer
StructuredViewer.ColorAndFontCollectorWithProviders
 
Field Summary
 
Fields inherited from class org.eclipse.jface.viewers.Viewer
WIDGET_DATA_KEY
 
Constructor Summary
TableViewer(Composite parent)
          Creates a table viewer on a newly-created table control under the given parent.
TableViewer(Composite parent, int style)
          Creates a table viewer on a newly-created table control under the given parent.
TableViewer(Table table)
          Creates a table viewer on the given table control.
 
Method Summary
 void add(Object element)
          Adds the given element to this table viewer.
 void add(Object[] elements)
          Adds the given elements to this table viewer.
protected  void assertContentProviderType(IContentProvider provider)
          Assert that the content provider is of one of the supported types.
 void cancelEditing()
          Cancels a currently active cell editor.
 void clear(int index)
          Clear the table item at the specified index
protected  Widget doFindInputItem(Object element)
          Returns the widget in this viewer's control which represents the given element if it is the viewer's input.
protected  Widget doFindItem(Object element)
          Returns the widget in this viewer's control which represent the given element.
protected  void doUpdateItem(Widget widget, Object element, boolean fullMap)
          Copies the attributes of the given element into the given SWT item.
 void editElement(Object element, int column)
          Starts editing the given element.
 CellEditor[] getCellEditors()
          Returns the cell editors of this table viewer.
 ICellModifier getCellModifier()
          Returns the cell modifier of this table viewer.
 Object[] getColumnProperties()
          Returns the column properties of this table viewer.
 Control getControl()
          Returns the primary control associated with this viewer.
 Object getElementAt(int index)
          Returns the element with the given index from this table viewer.
 IBaseLabelProvider getLabelProvider()
          The table viewer implementation of this Viewer framework method returns the label provider, which in the case of table viewers will be an instance of either ITableLabelProvider or ILabelProvider.
protected  Object[] getRawChildren(Object parent)
          Returns the children of the given parent without sorting and filtering them.
protected  List getSelectionFromWidget()
          Retrieves the selection, as a List, from the underlying widget.
 Table getTable()
          Returns this table viewer's table control.
protected  void hookControl(Control control)
          Adds event listener hooks to the given control.
protected  int indexForElement(Object element)
           
protected  void inputChanged(Object input, Object oldInput)
          Internal hook method called when the input to this viewer is initially set or subsequently changed.
 void insert(Object element, int position)
          Inserts the given element into this table viewer at the given position.
protected  void internalRefresh(Object element)
          Refreshes this viewer starting at the given element.
protected  void internalRefresh(Object element, boolean updateLabels)
          Refreshes this viewer starting at the given element.
 boolean isCellEditorActive()
          Returns whether there is an active cell editor.
 void remove(Object element)
          Removes the given element from this table viewer.
 void remove(Object[] elements)
          Removes the given elements from this table viewer.
 void replace(Object element, int index)
          Replace the entries starting at index with elements.
 void reveal(Object element)
          Ensures that the given element is visible, scrolling the viewer if necessary.
 void setCellEditors(CellEditor[] editors)
          Sets the cell editors of this table viewer.
 void setCellModifier(ICellModifier modifier)
          Sets the cell modifier of this table viewer.
 void setColumnProperties(String[] columnProperties)
          Sets the column properties of this table viewer.
 void setItemCount(int count)
          Set the item count of the receiver.
 void setLabelProvider(IBaseLabelProvider labelProvider)
          The table viewer implementation of this Viewer framework method ensures that the given label provider is an instance of either ITableLabelProvider or ILabelProvider.
protected  void setSelectionToWidget(List list, boolean reveal)
          Parlays the given list of selected elements into selections on this viewer's control.
 
Methods inherited from class org.eclipse.jface.viewers.StructuredViewer
addDoubleClickListener, addDragSupport, addDropSupport, addFilter, addOpenListener, addPostSelectionChangedListener, assertElementsNotNull, associate, buildLabel, disassociate, equals, filter, findItem, fireDoubleClick, fireOpen, firePostSelectionChanged, getColorAndFontCollector, getComparer, getFilteredChildren, getFilters, getItem, getRoot, getSelection, getSortedChildren, getSorter, handleDoubleSelect, handleInvalidSelection, handleLabelProviderChanged, handleOpen, handlePostSelect, handleSelect, hasFilters, internalUpdate, mapElement, needsRefilter, preservingSelection, refresh, refresh, refresh, refresh, refreshItem, removeDoubleClickListener, removeFilter, removeOpenListener, removePostSelectionChangedListener, resetFilters, setComparer, setContentProvider, setInput, setSelection, setSelectionToWidget, setSorter, setUseHashlookup, testFindItem, unmapAllElements, unmapElement, unmapElement, update, update, updateItem, updateSelection, usingElementMap
 
Methods inherited from class org.eclipse.jface.viewers.ContentViewer
getContentProvider, getInput, handleDispose, labelProviderChanged
 
Methods inherited from class org.eclipse.jface.viewers.Viewer
addHelpListener, addSelectionChangedListener, fireHelpRequested, fireSelectionChanged, getData, handleHelpRequest, 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

TableViewer

public TableViewer(Composite parent)
Creates a table viewer on a newly-created table control under the given parent. The table control is created using the SWT style bits MULTI, H_SCROLL, V_SCROLL, and BORDER. The viewer has no input, no content provider, a default label provider, no sorter, and no filters. The table has no columns.

Parameters:
parent - the parent control

TableViewer

public TableViewer(Composite parent,
                   int style)
Creates a table viewer on a newly-created table control under the given parent. The table control is created using the given style bits. The viewer has no input, no content provider, a default label provider, no sorter, and no filters. The table has no columns.

Parameters:
parent - the parent control
style - SWT style bits

TableViewer

public TableViewer(Table table)
Creates a table viewer on the given table control. The viewer has no input, no content provider, a default label provider, no sorter, and no filters.

Parameters:
table - the table control
Method Detail

add

public void add(Object[] elements)
Adds the given elements to this table viewer. If this viewer does not have a sorter, the elements are added at the end in the order given; otherwise the elements are inserted at appropriate positions.

This method should be called (by the content provider) when elements have been added to the model, in order to cause the viewer to accurately reflect the model. This method only affects the viewer, not the model.

Parameters:
elements - the elements to add

add

public void add(Object element)
Adds the given element to this table viewer. If this viewer does not have a sorter, the element is added at the end; otherwise the element is inserted at the appropriate position.

This method should be called (by the content provider) when a single element has been added to the model, in order to cause the viewer to accurately reflect the model. This method only affects the viewer, not the model. Note that there is another method for efficiently processing the simultaneous addition of multiple elements.

Parameters:
element - the element to add

cancelEditing

public void cancelEditing()
Cancels a currently active cell editor. All changes already done in the cell editor are lost.


doFindInputItem

protected Widget doFindInputItem(Object element)
Description copied from class: StructuredViewer
Returns the widget in this viewer's control which represents the given element if it is the viewer's input.

This method is internal to the framework; subclassers should not call this method.

Specified by:
doFindInputItem in class StructuredViewer
Parameters:
element -
Returns:
the corresponding widget, or null if none

doFindItem

protected Widget doFindItem(Object element)
Description copied from class: StructuredViewer
Returns the widget in this viewer's control which represent the given element. This method searchs all the children of the input element.

This method is internal to the framework; subclassers should not call this method.

Specified by:
doFindItem in class StructuredViewer
Parameters:
element -
Returns:
the corresponding widget, or null if none

doUpdateItem

protected void doUpdateItem(Widget widget,
                            Object element,
                            boolean fullMap)
Description copied from class: StructuredViewer
Copies the attributes of the given element into the given SWT item. The element map is updated according to the value of fullMap. If fullMap is true then the current mapping from element to widgets is removed and the new mapping is added. If fullmap is false then only the new map gets installed. Installing only the new map is necessary in cases where only the order of elements changes but not the set of elements.

This method is internal to the framework; subclassers should not call this method.

Specified by:
doUpdateItem in class StructuredViewer
Parameters:
widget -
element - element
fullMap - true if mappings are added and removed, and false if only the new map gets installed

editElement

public void editElement(Object element,
                        int column)
Starts editing the given element.

Parameters:
element - the element
column - the column number

getCellEditors

public CellEditor[] getCellEditors()
Returns the cell editors of this table viewer.

Returns:
the list of cell editors

getCellModifier

public ICellModifier getCellModifier()
Returns the cell modifier of this table viewer.

Returns:
the cell modifier

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.

Returns:
the list of column properties

getControl

public Control getControl()
Description copied from class: Viewer
Returns the primary control associated with this viewer.

Specified by:
getControl in class Viewer
Returns:
the SWT control which displays this viewer's content

getElementAt

public Object getElementAt(int index)
Returns the element with the given index from this table viewer. Returns null if the index is out of range.

This method is internal to the framework.

Parameters:
index - the zero-based index
Returns:
the element at the given index, or null if the index is out of range

getLabelProvider

public IBaseLabelProvider getLabelProvider()
The table viewer implementation of this Viewer framework method returns the label provider, which in the case of table viewers will be an instance of either ITableLabelProvider or ILabelProvider. If it is an ITableLabelProvider, then it provides a separate label text and image for each column. If it is an ILabelProvider, then it provides only the label text and image for the first column, and any remaining columns are blank.

Overrides:
getLabelProvider in class ContentViewer
Returns:
a label provider

getSelectionFromWidget

protected List getSelectionFromWidget()
Description copied from class: StructuredViewer
Retrieves the selection, as a List, from the underlying widget.

Specified by:
getSelectionFromWidget in class StructuredViewer
Returns:
the list of selected elements

getTable

public Table getTable()
Returns this table viewer's table control.

Returns:
the table control

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

indexForElement

protected int indexForElement(Object element)

inputChanged

protected void inputChanged(Object input,
                            Object oldInput)
Description copied from class: Viewer
Internal hook method called when the input to this viewer is initially set or subsequently changed.

The default implementation does nothing. Subclassers may override this method to do something when a viewer's input is set. A typical use is populate the viewer.

Overrides:
inputChanged in class Viewer
Parameters:
input - the new input of this viewer, or null if none
oldInput - the old input element or null if there was previously no input

insert

public void insert(Object element,
                   int position)
Inserts the given element into this table viewer at the given position. If this viewer has a sorter, the position is ignored and the element is inserted at the correct position in the sort order.

This method should be called (by the content provider) when elements have been added to the model, in order to cause the viewer to accurately reflect the model. This method only affects the viewer, not the model.

Parameters:
element - the element
position - a 0-based position relative to the model, or -1 to indicate the last position

internalRefresh

protected void internalRefresh(Object element)
Description copied from class: StructuredViewer
Refreshes this viewer starting at the given element.

Specified by:
internalRefresh in class StructuredViewer
Parameters:
element - the element

internalRefresh

protected void internalRefresh(Object element,
                               boolean updateLabels)
Description copied from class: StructuredViewer
Refreshes this viewer starting at the given element. Labels are updated as described in refresh(boolean updateLabels).

The default implementation simply calls internalRefresh(element), ignoring updateLabels.

If this method is overridden to do the actual refresh, then internalRefresh(Object element) should simply call internalRefresh(element, true).

Overrides:
internalRefresh 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.

isCellEditorActive

public boolean isCellEditorActive()
Returns whether there is an active cell editor.

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

remove

public void remove(Object[] elements)
Removes the given elements from this table viewer. The selection is updated if required.

This method should be called (by the content provider) when elements have been removed from the model, in order to cause the viewer to accurately reflect the model. This method only affects the viewer, not the model.

Parameters:
elements - the elements to remove

remove

public void remove(Object element)
Removes the given element from this table viewer. The selection is updated if necessary.

This method should be called (by the content provider) when a single element has been removed from the model, in order to cause the viewer to accurately reflect the model. This method only affects the viewer, not the model. Note that there is another method for efficiently processing the simultaneous removal of multiple elements.

Parameters:
element - the element

reveal

public void reveal(Object element)
Description copied from class: StructuredViewer
Ensures that the given element is visible, scrolling the viewer if necessary. The selection is unchanged.

Specified by:
reveal in class StructuredViewer
Parameters:
element - the element to reveal

setCellEditors

public void setCellEditors(CellEditor[] editors)
Sets the cell editors of this table viewer.

Parameters:
editors - the list of cell editors

setCellModifier

public void setCellModifier(ICellModifier modifier)
Sets the cell modifier of this table viewer.

Parameters:
modifier - the cell modifier

setColumnProperties

public void setColumnProperties(String[] columnProperties)
Sets 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.

Parameters:
columnProperties - the list of column properties

setLabelProvider

public void setLabelProvider(IBaseLabelProvider labelProvider)
The table viewer implementation of this Viewer framework method ensures that the given label provider is an instance of either ITableLabelProvider or ILabelProvider. If it is an ITableLabelProvider, then it provides a separate label text and image for each column. If it is an ILabelProvider, then it provides only the label text and image for the first column, and any remaining columns are blank.

Overrides:
setLabelProvider in class StructuredViewer

setSelectionToWidget

protected void setSelectionToWidget(List list,
                                    boolean reveal)
Description copied from class: StructuredViewer
Parlays the given list of selected elements into selections on this viewer's control.

Subclasses should override to set their selection based on the given list of elements.

Specified by:
setSelectionToWidget in class StructuredViewer
Parameters:
list - list of selected elements (element type: Object) or null if the selection is to be cleared
reveal - true if the selection is to be made visible, and false otherwise

setItemCount

public void setItemCount(int count)
Set the item count of the receiver.

Parameters:
count - the new table size.
Since:
3.1

replace

public void replace(Object element,
                    int index)
Replace the entries starting at index with elements. This method assumes all of these values are correct and will not call the content provider to verify. Note that this method will create a TableItem for all of the elements provided.

Parameters:
element -
index -
Since:
3.1
See Also:
ILazyContentProvider

clear

public void clear(int index)
Clear the table item at the specified index

Parameters:
index - the index of the table item to be cleared
Since:
3.1

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

assertContentProviderType

protected void assertContentProviderType(IContentProvider provider)
Description copied from class: StructuredViewer
Assert that the content provider is of one of the supported types.

Overrides:
assertContentProviderType in class StructuredViewer
Parameters:
provider -

Eclipse Platform
Release 3.1

Guidelines for using Eclipse APIs.

Copyright (c) IBM Corp. and others 2000, 2005. All rights reserved.