org.eclipse.nebula.widgets.nattable.edit.editor

Class AbstractCellEditor

java.lang.Object

org.eclipse.nebula.widgets.nattable.edit.editor.AbstractCellEditor

All Implemented Interfaces:

ICellEditor

Direct Known Subclasses:

CheckBoxCellEditor, ComboBoxCellEditor, TextCellEditor

public abstract class AbstractCellEditor
extends Object
implements ICellEditor

Abstract implementation of ICellEditor that wraps SWT controls to be NatTable editors. It is used to hide several default behaviour and styling from concrete editor implementations, so implementing an editor can focus on the editor specific handling instead of NatTable default behaviour.

Note that most of the member variables defined will be set on activating the editor. So you can not access those variables expecting reasonable values prior activation. This makes it possible to use the same editor instance for several cells instead of creating a new one for every cell.

Field Summary

Fields

Modifier and Type	Field and Description
protected IStyle	cellStyle The style that should be used for rendering within the editor control.
protected IConfigRegistry	configRegistry The IConfigRegistry containing the configuration of the current NatTable instance.
protected IEditErrorHandler	conversionEditErrorHandler The error handler that will be used to show conversion errors.
protected IDataValidator	dataValidator The IDataValidator that should be used to validate the input value prior committing.
protected IDisplayConverter	displayConverter The IDisplayConverter that should be used to convert the input value to the canonical value and vice versa.
protected EditModeEnum	editMode The EditModeEnum which is used to activate special behaviour and styling.
protected LabelStack	labelStack The LabelStack of the cell whose editor should be activated.
protected ILayerCell	layerCell The cell whose editor should be activated.
protected IEditErrorHandler	validationEditErrorHandler The error handler that will be used to show validation errors.

Constructor Summary

Constructors

Constructor and Description
AbstractCellEditor()

Method Summary

Methods

Modifier and Type	Method and Description
boolean	activateAtAnyPosition() This method is intended to be used by IMouseEventMatcher implementations that need to check for the editor and the click position to determine whether an editor should be activated or not.
protected abstract org.eclipse.swt.widgets.Control	activateCell(org.eclipse.swt.widgets.Composite parent, Object originalCanonicalValue) This method will be called by activateCell(Composite, Object, EditModeEnum, ICellEditHandler, ILayerCell, IConfigRegistry) after initializing the activation values and before adding the default listeners.
org.eclipse.swt.widgets.Control	activateCell(org.eclipse.swt.widgets.Composite parent, Object originalCanonicalValue, EditModeEnum editMode, ICellEditHandler editHandler, ILayerCell cell, IConfigRegistry configRegistry) This method will be called by the framework to activate this cell editor.
void	addEditorControlListeners() This method is intended to add listeners to the wrapped editor control to add context related behaviour.
void	close() Close/dispose the contained Control
boolean	commit(SelectionLayer.MoveDirectionEnum direction) Commits the current value of this editor.
boolean	commit(SelectionLayer.MoveDirectionEnum direction, boolean closeAfterCommit) Commits the current value of this editor.
boolean	commit(SelectionLayer.MoveDirectionEnum direction, boolean closeAfterCommit, boolean skipValidation) Commits the current value of this editor.
Object	getCanonicalValue() Converts the current value in this editor using the configured IDisplayConverter.
Object	getCanonicalValue(IEditErrorHandler conversionErrorHandler) Converts the current value in this editor using the configured IDisplayConverter.
int	getColumnIndex()
int	getColumnPosition()
int	getRowIndex()
int	getRowPosition()
protected Object	handleConversion(Object displayValue, IEditErrorHandler conversionErrorHandler) Converts the given display value using the configured IDisplayConverter.
boolean	isClosed()
boolean	openAdjacentEditor() Determines behaviour after committing the value of this editor in combination with selection movement.
boolean	openInline(IConfigRegistry configRegistry, List<String> configLabels) Determines whether the editor should be opened inline or using a dialog.
void	removeEditorControlListeners() This method is intended to remove listeners from the wrapped editor control that was added by ICellEditor.addEditorControlListeners() before to add context related behaviour.
void	setCanonicalValue(Object canonicalValue) Sets the given canonical value to the wrapped editor control.
void	setDataValidator(IDataValidator validator) This method can be used to set the IDataValidator to use.
boolean	supportMultiEdit(IConfigRegistry configRegistry, List<String> configLabels) Determines whether this editor supports multi edit behaviour or not.
boolean	validateCanonicalValue(Object canonicalValue) Validates the given value using the configured IDataValidator.
boolean	validateCanonicalValue(Object canonicalValue, IEditErrorHandler validationEditErrorHandler) Validates the current value in this editor using the configured IDataValidator.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface org.eclipse.nebula.widgets.nattable.edit.editor.ICellEditor

createEditorControl, getEditorControl, getEditorValue, setEditorValue

Field Detail

cellStyle

protected IStyle cellStyle

The style that should be used for rendering within the editor control. Mainly it will cover foreground color, background color and font. If the editor control supports further styles, this needs to be specified be the ICellEditor implementation itself.

displayConverter

protected IDisplayConverter displayConverter

The IDisplayConverter that should be used to convert the input value to the canonical value and vice versa.

dataValidator

protected IDataValidator dataValidator

The IDataValidator that should be used to validate the input value prior committing.

editMode

protected EditModeEnum editMode

The EditModeEnum which is used to activate special behaviour and styling. This is needed because activating an editor inline will have different behaviour (e.g. moving the selection after commit) and styling than rendering the editor on a subdialog.

layerCell

protected ILayerCell layerCell

The cell whose editor should be activated.

labelStack

protected LabelStack labelStack

The LabelStack of the cell whose editor should be activated.

conversionEditErrorHandler

protected IEditErrorHandler conversionEditErrorHandler

The error handler that will be used to show conversion errors.

validationEditErrorHandler

protected IEditErrorHandler validationEditErrorHandler

The error handler that will be used to show validation errors.

configRegistry

protected IConfigRegistry configRegistry

The IConfigRegistry containing the configuration of the current NatTable instance. This is necessary because the editors in the current architecture are not aware of the NatTable instance they are running in.

Constructor Detail

AbstractCellEditor

public AbstractCellEditor()

Method Detail

activateCell

public final org.eclipse.swt.widgets.Control activateCell(org.eclipse.swt.widgets.Composite parent,
                                           Object originalCanonicalValue,
                                           EditModeEnum editMode,
                                           ICellEditHandler editHandler,
                                           ILayerCell cell,
                                           IConfigRegistry configRegistry)

Description copied from interface: ICellEditor

This method will be called by the framework to activate this cell editor. It initializes the the values needed for further processing of the editor and will add listeners for general behaviour of the editor control.

Specified by:

activateCell in interface ICellEditor

Parameters:

parent - The parent Composite, needed for the creation of the editor control.

originalCanonicalValue - The value that should be put to the activated editor control.

editMode - The EditModeEnum which is used to activate special behaviour and styling. This is needed because activating an editor inline will have different behaviour (e.g. moving the selection after commit) and styling than rendering the editor on a subdialog.

editHandler - The ICellEditHandler that will be used on commit.

cell - The cell whose corresponding editor should be activated.

configRegistry - The IConfigRegistry containing the configuration of the current NatTable instance. This is necessary because the editors in the current architecture are not aware of the NatTable instance they are running in.

Returns:

The SWT Control to be used for capturing the new cell value.

activateCell

protected abstract org.eclipse.swt.widgets.Control activateCell(org.eclipse.swt.widgets.Composite parent,
                                           Object originalCanonicalValue)

This method will be called by activateCell(Composite, Object, EditModeEnum, ICellEditHandler, ILayerCell, IConfigRegistry) after initializing the activation values and before adding the default listeners. In this method the underlying editor control should be created and initialized, hiding default configuration from editor implementors.

Parameters:

parent - The parent Composite, needed for the creation of the editor control.

originalCanonicalValue - The value that should be put to the activated editor control.

Returns:

The SWT Control to be used for capturing the new cell value.

getColumnIndex

public int getColumnIndex()

Specified by:

getColumnIndex in interface ICellEditor

Returns:

The column index of the cell to which this editor is attached.

See Also:

ILayerCell.getColumnIndex()

getRowIndex

public int getRowIndex()

Specified by:

getRowIndex in interface ICellEditor

Returns:

The row index of the cell to which this editor is attached.

See Also:

ILayerCell.getRowIndex()

getColumnPosition

public int getColumnPosition()

Specified by:

getColumnPosition in interface ICellEditor

Returns:

The column position of the cell to which this editor is attached.

See Also:

ILayerCell.getColumnPosition()

getRowPosition

public int getRowPosition()

Specified by:

getRowPosition in interface ICellEditor

Returns:

The row position of the cell to which this editor is attached.

See Also:

ILayerCell.getRowPosition()

getCanonicalValue

public Object getCanonicalValue()

Converts the current value in this editor using the configured IDisplayConverter. If there is no IDisplayConverter registered for this editor, the value itself will be returned.

Specified by:

getCanonicalValue in interface ICellEditor

Returns:

The canonical value after converting the current value or the value itself if no IDisplayConverter is configured.

Throws:

RuntimeException - for conversion failures. As the IDisplayConverter interface does not specify throwing checked Exceptions on converting data, only unchecked Exceptions can occur. This is needed to stop further commit processing if the conversion failed.

See Also:

IDisplayConverter

getCanonicalValue

public Object getCanonicalValue(IEditErrorHandler conversionErrorHandler)

Converts the current value in this editor using the configured IDisplayConverter. If there is no IDisplayConverter registered for this editor, the value itself will be returned. Will use the specified IEditErrorHandler for handling conversion errors.

Specified by:

getCanonicalValue in interface ICellEditor

Parameters:

conversionErrorHandler - The error handler that will be activated in case of conversion errors.

Returns:

The canonical value after converting the current value or the value itself if no IDisplayConverter is configured.

Throws:

RuntimeException - for conversion failures. As the IDisplayConverter interface does not specify throwing checked Exceptions on converting data, only unchecked Exceptions can occur. This is needed to stop further commit processing if the conversion failed.

See Also:

IDisplayConverter

handleConversion

protected Object handleConversion(Object displayValue,
                      IEditErrorHandler conversionErrorHandler)

Converts the given display value using the configured IDisplayConverter. If there is no IDisplayConverter registered for this editor, the value itself will be returned. Will use the specified IEditErrorHandler for handling conversion errors.

Parameters:

displayValue - The display value that needs to be converted.

conversionErrorHandler - The error handler that will be activated in case of conversion errors.

Returns:

The canonical value after converting the current value or the value itself if no IDisplayConverter is configured.

Throws:

RuntimeException - for conversion failures. As the IDisplayConverter interface does not specify throwing checked Exceptions on converting data, only unchecked Exceptions can occur. This is needed to stop further commit processing if the conversion failed.

See Also:

IDisplayConverter

setCanonicalValue

public void setCanonicalValue(Object canonicalValue)

Description copied from interface: ICellEditor

Sets the given canonical value to the wrapped editor control. Prior to setting the value it needs to be converted to the display value, using the configured IDisplayConverter.

Specified by:

setCanonicalValue in interface ICellEditor

Parameters:

canonicalValue - The canonical value to be set to the wrapped editor control.

validateCanonicalValue

public boolean validateCanonicalValue(Object canonicalValue)

Description copied from interface: ICellEditor

Validates the given value using the configured IDataValidator. This method should be called with the value converted before by using ICellEditor.getCanonicalValue().

Specified by:

validateCanonicalValue in interface ICellEditor

Parameters:

canonicalValue - The canonical value to validate.

Returns:

true if the current value in this editor is valid or no IDataValidator is registered, false if the value is not valid.

validateCanonicalValue

public boolean validateCanonicalValue(Object canonicalValue,
                             IEditErrorHandler validationEditErrorHandler)

Description copied from interface: ICellEditor

Validates the current value in this editor using the configured IDataValidator. Validates the given value using the configured IDataValidator. This method should be called with the value converted before by using ICellEditor.getCanonicalValue(). Will use the specified IEditErrorHandler for handling validation errors.

Specified by:

validateCanonicalValue in interface ICellEditor

Parameters:

canonicalValue - The canonical value to validate.

validationEditErrorHandler - The error handler that will be activated in case of validation errors.

Returns:

true if the current value in this editor is valid or no IDataValidator is registered, false if the value is not valid.

commit

public boolean commit(SelectionLayer.MoveDirectionEnum direction)

Description copied from interface: ICellEditor

Commits the current value of this editor. Will first try to convert and validate the current value, and if that succeeds and the value can be committed to the data model, the editor will be closed afterwards.

Specified by:

commit in interface ICellEditor

Parameters:

direction - The direction the selection within the NatTable should move after commit has finished.

Returns:

true if the commit operation succeeded, false if the current value could not be committed. A value might not be committed for example if the conversion or the validation failed.

commit

public boolean commit(SelectionLayer.MoveDirectionEnum direction,
             boolean closeAfterCommit)

Description copied from interface: ICellEditor

Commits the current value of this editor. Will first try to convert the current value. Then it is checked if the validation should be executed which can be specified via parameter. If that succeeds and the value can be committed to the data model, the editor will be closed afterwards.

Specified by:

commit in interface ICellEditor

Parameters:

direction - The direction the selection within the NatTable should move after commit has finished.

closeAfterCommit - flag to tell whether this editor needs to closed after the commit or if it should stay open.

Returns:

true if the commit operation succeeded, false if the current value could not be committed. A value might not be committed for example if the conversion or the validation failed.

commit

public boolean commit(SelectionLayer.MoveDirectionEnum direction,
             boolean closeAfterCommit,
             boolean skipValidation)

Description copied from interface: ICellEditor

Commits the current value of this editor.

Specified by:

commit in interface ICellEditor

Parameters:

direction - The direction the selection within the NatTable should move after commit has finished.

closeAfterCommit - flag to tell whether this editor needs to closed after the commit or if it should stay open.

skipValidation - Flag to specify whether the current value in this editor should be validated or not.

Returns:

true if the commit operation succeeded, false if the current value could not be committed. A value might not be committed for example if the conversion or the validation failed.

close

public void close()

Description copied from interface: ICellEditor

Close/dispose the contained Control

Specified by:

close in interface ICellEditor

isClosed

public boolean isClosed()

Specified by:

isClosed in interface ICellEditor

Returns:

true if this editor has been closed already, false if it is still open

openInline

public boolean openInline(IConfigRegistry configRegistry,
                 List<String> configLabels)

Description copied from interface: ICellEditor

Determines whether the editor should be opened inline or using a dialog. By default it will check this by configuration attribute EditConfigAttributes.OPEN_IN_DIALOG. If there is no configuration found for this, true will be returned for backwards compatibility.

If this method returns true, the editor will be opened inline (default).

There might be editors that are only able to be opened in a dialog. These implementations need to override this method to always return false, so the editor never gets opened inline.

Specified by:

openInline in interface ICellEditor

Parameters:

configRegistry - The IConfigRegistry to retrieve the configuration for inline/dialog editing out of. Needed here because the instance IConfigRegistry might not be set on calling this method.

configLabels - The labels out of the LabelStack of the cell whose editor should be activated. Needed here because this method needs to be called prior to activation to determine where to activate it.

Returns:

true if the editor should opened inline, false if not.

See Also:

EditConfigAttributes.OPEN_IN_DIALOG

supportMultiEdit

public boolean supportMultiEdit(IConfigRegistry configRegistry,
                       List<String> configLabels)

Description copied from interface: ICellEditor

Determines whether this editor supports multi edit behaviour or not. If this method returns true, on selecting and pressing F2 on several cells that are editable, having the same editor type and converter registered, a multi edit dialog will open. By default this method will return true. You can change this behaviour by setting the configuration attribute EditConfigAttributes.SUPPORT_MULTI_EDIT.

You should consider returning false e.g. if the update operation is complex or you use conditional validation, where a value is validated against another value in the data model.

Specified by:

supportMultiEdit in interface ICellEditor

Parameters:

configRegistry - The IConfigRegistry to retrieve the configuration for multi edit support out of. Needed here because the instance IConfigRegistry might not be set on calling this method.

configLabels - The labels out of the LabelStack of the cell whose editor should be activated. Needed here because this method needs to be called prior to activation to determine where to activate it.

Returns:

true if this editor will open in a subdialog for multi editing, false if the multi editing of this kind of cell editor is not supported.

See Also:

EditConfigAttributes.SUPPORT_MULTI_EDIT

openAdjacentEditor

public boolean openAdjacentEditor()

Description copied from interface: ICellEditor

Determines behaviour after committing the value of this editor in combination with selection movement. If this method return true and the selection is moved after committing, the editor for the newly selected cell will be activated immediately. If this method returns false or the selection is not moved after commit, no action should be executed.

The behaviour previous to this configuration was to not open the adjacent editor. So if there is no configuration registered for this, false will be returned by default.

Note: It only makes sense to call this method if the editor is already activated. Calling this method on an editor that has not been activated already will lead to exceptions.

Specified by:

openAdjacentEditor in interface ICellEditor

Returns:

true if the adjacent editor should be opened if the selection moves after commit, false if not.

See Also:

EditConfigAttributes.OPEN_ADJACENT_EDITOR

activateAtAnyPosition

public boolean activateAtAnyPosition()

Description copied from interface: ICellEditor

This method is intended to be used by IMouseEventMatcher implementations that need to check for the editor and the click position to determine whether an editor should be activated or not. By default this method will return true. Special implementations that need a different behaviour need to return false instead. E.g. checkbox editors should only be activated in case the icon that represents the checkbox is clicked.

Specified by:

activateAtAnyPosition in interface ICellEditor

Returns:

true if this ICellEditor should be activated by clicking at any position in the corresponding cell, false if there need to be a special position clicked.

addEditorControlListeners

public void addEditorControlListeners()

Description copied from interface: ICellEditor

This method is intended to add listeners to the wrapped editor control to add context related behaviour. For example, in EditModeEnum.INLINE by default this should add a FocusListener that commits the current value if the editor control loses focus.

This method was introduced mainly because of two issues:

1. On Mac OS calling setBounds() on a Control will cause losing focus. So listeners need to be added after this method is called by the EditController, otherwise on activating the editor it will be closed immediately after the correct size is calculated.
2. The main concept for cell editor activation is, that the editor control is disposed on closing the editor. This way everytime the cell editor is activated, a new editor control will be created. If an editor is implemented that needs to keep the editor control after closing the editor, it needs to be ensured that the listeners are removed again. Otherwise the listeners would be added again everytime the editor is activated.

This method will be called automatically by EditController.editCell(ILayerCell, Composite, Object, IConfigRegistry).

Specified by:

addEditorControlListeners in interface ICellEditor

removeEditorControlListeners

public void removeEditorControlListeners()

Description copied from interface: ICellEditor

This method is intended to remove listeners from the wrapped editor control that was added by ICellEditor.addEditorControlListeners() before to add context related behaviour.

This method was introduced to add the possibilty to create an ICellEditor whose wrapped editor control should not be disposed on closing the editor.

The main concept for cell editor activation is, that the editor control is disposed on closing the editor. This way everytime the cell editor is activated, a new editor control will be created. If an editor is implemented that needs to keep the editor control after closing the editor, it needs to be ensured that the listeners are removed again. Otherwise the listeners would be added again everytime the editor is activated.

This method needs to be called on ICellEditor.close(). There is no automatical call by the framework if you are not using the abstract implementation of ICellEditor.

Specified by:

removeEditorControlListeners in interface ICellEditor

setDataValidator

public void setDataValidator(IDataValidator validator)

This method can be used to set the IDataValidator to use. This might be useful e.g. the configured validator needs to be wrapped to add special behaviour. Setting a validator prior to activating the editor will have no effect.

Note: It is not suggested to call this method in custom code. It is used e.g. by the TickUpdateCellEditDialog as dependent on the selected update type, the validator needs to be enabled or not.

Parameters:

validator - The IDataValidator to set.