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

  • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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

    • updateSelection

      protected void updateSelection(ISelection selection)
      Description copied from class: StructuredViewer
      Updates the selection of this viewer.

      This framework method should be called when the selection in the viewer widget changes.

      The default implementation of this method notifies all selection change listeners recorded in an internal state variable. Overriding this method is generally not required; however, if overriding in a subclass, super.updateSelection must be invoked.

      Overrides:
      updateSelection in class StructuredViewer
      Parameters:
      selection - the selection, or null if none

    • firePostSelectionChanged

      protected void firePostSelectionChanged(SelectionChangedEvent event)
      Description copied from class: StructuredViewer
      Notifies any post selection listeners that a post selection event has been received. Only listeners registered at the time this method is called are notified.
      Overrides:
      firePostSelectionChanged in class StructuredViewer
      Parameters:
      event - a selection changed event
      See Also:

    • unmapAllElements

      protected void unmapAllElements()
      Description copied from class: StructuredViewer
      Removes all elements from the map.

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

      Overrides:
      unmapAllElements in class StructuredViewer