org.itsnat.comp.table

Interface ItsNatTable

All Superinterfaces:

ItsNatComponent, ItsNatElementComponent, ItsNatUserData

All Known Subinterfaces:

ItsNatFreeTable, ItsNatHTMLTable

public interface ItsNatTable
extends ItsNatElementComponent

Is the base interface of table based components.

A table component manages a javax.swing.table.TableModel data model, table cell values are rendered as markup using a special object, the renderer, and may be optionally edited "in place" using a user defined editor.

Any change to the data model is notified to the component and the markup is rendered again. The data model ever mandates over the markup, any initial markup content (initial rows) is removed.

Almost a row with a cell must be present in the markup, this row and cell are used as patterns to create new table rows/cells, and is removed because by default the data model is empty.

This component family uses two javax.swing.ListSelectionModel selection models, one for columns, another for rows, to keep track of selection states. When a cell is selected (usually by clicking it) the selection state is updated accordingly using both selection models (notifying to registered listeners).

ItsNat tables support all selection modes that Swing JTable supports, as in JTable setRowSelectionAllowed(boolean) and setColumnSelectionAllowed(boolean) control whether the complete row and column are selected when a cell is selected.

There is no default decoration of table cell selection, selection model listeners may be used to decorate the table markup when its selection state changes.

By default this component uses the default renderer and editor and a javax.swing.table.DefaultTableModel data model.

Row and column indexes start in 0.

This component family is the "componentized" version of ElementTable and follows a similar philosophy (note the component version provides table header support).

Author:

Jose Maria Arranz Santamaria

Method Summary

Methods

Modifier and Type	Method and Description
void	changeSelection(int rowIndex, int columnIndex, boolean toggle, boolean extend) Updates the selection models of the table, depending on the state of the two flags: toggle and extend.
void	clearSelection() Clears any row or column selection.
javax.swing.table.TableModel	createDefaultTableModel() Creates a data model instance appropriated to this component.
javax.swing.ListSelectionModel	getColumnSelectionModel() Returns the current column selection model.
int	getEditingColumn() Returns the column of the cell being edited.
int	getEditingRow() Returns the row of the cell being edited.
java.lang.String	getEditorActivatorEvent() Returns the event type used to activate the table cell edition process by the user.
ItsNatTableCellEditor	getItsNatTableCellEditor() Returns the current table cell editor.
ItsNatTableCellRenderer	getItsNatTableCellRenderer() Returns the current component renderer.
ItsNatTableHeader	getItsNatTableHeader() Returns the table header sub-component.
ItsNatTableStructure	getItsNatTableStructure() Returns the component structure.
ItsNatTableUI	getItsNatTableUI() Returns the user interface manager of this component.
javax.swing.ListSelectionModel	getRowSelectionModel() Returns the current row selection model.
int	getSelectedColumn() Returns the index of the first selected column.
int[]	getSelectedColumns() Returns an array with indices of the current selected columns.
int	getSelectedRow() Returns the index of the first selected row.
int[]	getSelectedRows() Returns an array with indices of the current selected rows.
javax.swing.table.TableModel	getTableModel() Returns the current data model of this component.
boolean	isCellSelected(int row, int column) Informs whether the specified cell is selected.
boolean	isCellSelectionEnabled() Informs whether cell selection is enabled.
boolean	isColumnSelected(int column) Informs whether the specified column contains almost a cell selected.
boolean	isColumnSelectionAllowed() Informs whether column selection is allowed.
boolean	isEditing() Informs whether a table cell value is being edited.
boolean	isEditingEnabled() Informs whether the in place edition is enabled.
boolean	isJoystickMode() Informs whether a joystick is enough to control the component (some kind of mouse, pointer or stylus not present or not necessary).
boolean	isRowSelected(int row) Informs whether the specified row contains almost a cell selected.
boolean	isRowSelectionAllowed() Informs whether row selection is allowed.
boolean	isSelectionUsesKeyboard() Returns if the keyboard is used to select items.
void	selectAll() Selects all cells in the table.
void	setCellSelectionEnabled(boolean cellSelectionEnabled) Enables/disables cell selection.
void	setColumnSelectionAllowed(boolean columnSelectionAllowed) Sets whether column selection is allowed.
void	setColumnSelectionInterval(int index0, int index1) Sets a new column selection interval specifying an index range.
void	setColumnSelectionModel(javax.swing.ListSelectionModel selectionModel) Sets the new column selection model.
void	setEditingEnabled(boolean value) Enables or disables temporally the in place edition.
void	setEditorActivatorEvent(java.lang.String eventType) Sets the event type used to activate the table cell edition process by the user.
void	setItsNatTableCellEditor(ItsNatTableCellEditor editor) Sets the table cell editor.
void	setItsNatTableCellRenderer(ItsNatTableCellRenderer renderer) Sets the component renderer.
void	setJoystickMode(boolean value) Informs whether a joystick is enough to control the component (some kind of mouse, pointer or stylus not present or not necessary).
void	setRowSelectionAllowed(boolean rowSelectionAllowed) Sets whether row selection is allowed.
void	setRowSelectionInterval(int index0, int index1) Sets a new row selection interval specifying an index range.
void	setRowSelectionModel(javax.swing.ListSelectionModel selectionModel) Sets the new row selection model.
void	setSelectedColumns(int[] indices) Sets the current selected columns.
void	setSelectedRows(int[] indices) Sets the current selected rows.
void	setSelectionMode(int selectionMode) Sets a new selection mode to the row and column selection models.
void	setSelectionUsesKeyboard(boolean value) Sets if the keyboard is used to select items.
void	setTableModel(javax.swing.table.TableModel dataModel) Changes the data model of this component.
void	startEditingAt(int row, int column) Used to start programmatically a table cell edition process "in place".

Methods inherited from interface org.itsnat.comp.ItsNatElementComponent

getElement, getItsNatElementComponentUI

Methods inherited from interface org.itsnat.comp.ItsNatComponent

addEventListener, addEventListener, addEventListener, addEventListener, addPropertyChangeListener, addPropertyChangeListener, addVetoableChangeListener, disableEventListener, disableEventListener, dispose, enableEventListener, enableEventListener, getArtifact, getArtifact, getItsNatComponentManager, getItsNatComponentUI, getItsNatDocument, getNode, getPropertyChangeListeners, getPropertyChangeListeners, getVetoableChangeListeners, isDisposed, isEnabled, registerArtifact, removeArtifact, removeEventListener, removeEventListener, removeEventListener, removeEventListener, removePropertyChangeListener, removePropertyChangeListener, removeVetoableChangeListener, setEnabled, setEventListenerParams, setEventListenerParams, setNode

Methods inherited from interface org.itsnat.core.ItsNatUserData

containsUserValueName, getUserValue, getUserValueNames, removeUserValue, setUserValue

Method Detail

getTableModel

javax.swing.table.TableModel getTableModel()

Returns the current data model of this component.

Returns:

the current data model

See Also:

setTableModel(javax.swing.table.TableModel)

setTableModel

void setTableModel(javax.swing.table.TableModel dataModel)

Changes the data model of this component.

Current data model is disconnected from this component, and the new data model is bound to this component, every change is tracked and updates the user interfaces accordingly.

If the specified data model is the same instance as the current data model, then is reset, component listener is removed and added again. Use this technique if you want to add a data model listener to be executed before the default component listener.

Parameters:

dataModel - the new data model.

getItsNatTableHeader

ItsNatTableHeader getItsNatTableHeader()

Returns the table header sub-component.

Returns:

the table header. Null if this table does not have a header.

getItsNatTableUI

ItsNatTableUI getItsNatTableUI()

Returns the user interface manager of this component.

Returns:

the user interface manager.

createDefaultTableModel

javax.swing.table.TableModel createDefaultTableModel()

Creates a data model instance appropriated to this component. This instance is not bound to the component.

Returns:

a new data model instance.

getRowSelectionModel

javax.swing.ListSelectionModel getRowSelectionModel()

Returns the current row selection model.

Returns:

the current row selection model. By default a javax.swing.DefaultListSelectionModel instance.

See Also:

setRowSelectionModel(javax.swing.ListSelectionModel)

setRowSelectionModel

void setRowSelectionModel(javax.swing.ListSelectionModel selectionModel)

Sets the new row selection model.

If the new selection model is the current defined then is "reset", component listener is removed and added again. Use this technique if you want to add a listener to be executed before the default component listener.

Parameters:

selectionModel - the new row selection model.

See Also:

getRowSelectionModel()

getColumnSelectionModel

javax.swing.ListSelectionModel getColumnSelectionModel()

Returns the current column selection model.

Returns:

the current column selection model. By default a javax.swing.DefaultListSelectionModel instance.

See Also:

setColumnSelectionModel(javax.swing.ListSelectionModel)

setColumnSelectionModel

void setColumnSelectionModel(javax.swing.ListSelectionModel selectionModel)

Sets the new column selection model.

If the new selection model is the current defined then is "reset", component listener is removed and added again. Use this technique if you want to add a listener to be executed before the default component listener.

Parameters:

selectionModel - the new column selection model.

See Also:

getColumnSelectionModel()

clearSelection

void clearSelection()

Clears any row or column selection.

Calls ListSelectionModel.clearSelection() method of both, row and column, selection models.

setSelectionMode

void setSelectionMode(int selectionMode)

Sets a new selection mode to the row and column selection models.

Calls ListSelectionModel.setSelectionMode() method of both, row and column, selection models.

Parameters:

selectionMode - new selection mode value.

isRowSelectionAllowed

boolean isRowSelectionAllowed()

Informs whether row selection is allowed.

Returns:

if row selection is allowed, true by default.

See Also:

setRowSelectionAllowed(boolean)

setRowSelectionAllowed

void setRowSelectionAllowed(boolean rowSelectionAllowed)

Sets whether row selection is allowed.

Parameters:

rowSelectionAllowed - true if row selection is allowed.

See Also:

isRowSelectionAllowed(), isCellSelected(int,int)

isColumnSelectionAllowed

boolean isColumnSelectionAllowed()

Informs whether column selection is allowed.

Returns:

if column selection is allowed, true by default.

See Also:

setColumnSelectionAllowed(boolean)

setColumnSelectionAllowed

void setColumnSelectionAllowed(boolean columnSelectionAllowed)

Sets whether column selection is allowed.

Parameters:

columnSelectionAllowed - true if column selection is allowed.

See Also:

isColumnSelectionAllowed(), isCellSelected(int,int)

isCellSelectionEnabled

boolean isCellSelectionEnabled()

Informs whether cell selection is enabled. A cell may be selected if row or column (or both) selection is enabled.

Returns:

if cell selection is enabled. By default is true.

See Also:

setCellSelectionEnabled(boolean)

setCellSelectionEnabled

void setCellSelectionEnabled(boolean cellSelectionEnabled)

Enables/disables cell selection. If cell selection is enabled row and column selection are enabled too (if disabled are disabled too).

Parameters:

cellSelectionEnabled - true if cell selection is enabled.

See Also:

isCellSelectionEnabled()

isCellSelected

boolean isCellSelected(int row,
                     int column)

Informs whether the specified cell is selected.

A cell is selected if cell selection is enabled (isCellSelectionEnabled() returns true) and row selection OR column selection is enabled (not both) and the cell is part of a selected row or column. If row selection AND column selection are enabled the cell is selected only if cell row AND column are selected, this mode (row and column selection enabled) allows selecting individual cells.

Summary:

• To select complete rows: row selection enabled and column disabled. A single cell selection selects all remaining cells in the row
• To select complete columns: column selection enabled and row disabled.
A single cell selection selects all remaining cells in the column
• To select individual cells: column and row selection enabled.

Parameters:

row - row position of the cell.

column - column position of the cell.

Returns:

true if the specified cell is selected.

See Also:

isCellSelectionEnabled()

isRowSelected

boolean isRowSelected(int row)

Informs whether the specified row contains almost a cell selected.

This method simply delegates to getRowSelectionModel().isSelectedIndex(row).

Parameters:

row - the row index.

Returns:

true if the specified row is selected.

isColumnSelected

boolean isColumnSelected(int column)

Informs whether the specified column contains almost a cell selected.

This method simply delegates to getColumnSelectionModel().isSelectedIndex(column).

Parameters:

column - the column index.

Returns:

true if the specified column is selected.

setRowSelectionInterval

void setRowSelectionInterval(int index0,
                           int index1)

Sets a new row selection interval specifying an index range.

This method simply delegates to getRowSelectionModel().setSelectionInterval(index0,index1).

Parameters:

index0 - one end of the interval.

index1 - other end of the interval

setColumnSelectionInterval

void setColumnSelectionInterval(int index0,
                              int index1)

Sets a new column selection interval specifying an index range.

This method simply delegates to getColumnSelectionModel().setSelectionInterval(index0,index1).

Parameters:

index0 - one end of the interval.

index1 - other end of the interval

getSelectedRows

int[] getSelectedRows()

Returns an array with indices of the current selected rows.

Returns:

an array with the current selected rows.

See Also:

setSelectedRows(int[])

setSelectedRows

void setSelectedRows(int[] indices)

Sets the current selected rows.

Parameters:

indices - index array of the new selected rows.

See Also:

getSelectedRows()

getSelectedColumns

int[] getSelectedColumns()

Returns an array with indices of the current selected columns.

Returns:

an array with the current selected columns.

See Also:

setSelectedColumns(int[])

setSelectedColumns

void setSelectedColumns(int[] indices)

Sets the current selected columns.

Parameters:

indices - index array of the new selected columns.

See Also:

getSelectedColumns()

getSelectedRow

int getSelectedRow()

Returns the index of the first selected row. If several rows are selected returns the first one.

Returns:

index of the first selected row. -1 if none is selected.

getSelectedColumn

int getSelectedColumn()

Returns the index of the first selected column. If several columns are selected returns the first one.

Returns:

index of the first selected column. -1 if none is selected.

changeSelection

void changeSelection(int rowIndex,
                   int columnIndex,
                   boolean toggle,
                   boolean extend)

Updates the selection models of the table, depending on the state of the two flags: toggle and extend. Most changes to the selection are the result of mouse events received by the UI are channeled through this method.

This implementation uses the following conventions:

• toggle: false, extend: false. Clear the previous selection and ensure the new cell is selected. This state is used to change the selection by clicking a cell (no shift and ctrl keys held)
• toggle: false, extend: true. Extend the previous selection from the anchor to the specified cell, clearing all other selections. This state is used to change the selection by clicking a cell with shift key held.
• toggle: true, extend: false. If the specified cell is selected, deselect it. If it is not selected, select it. This state is used to change the selection by clicking a cell with ctrl key held.
• toggle: true, extend: true. Leave the selection state as it is, but move the anchor index to the specified location. This state is used to change the selection by clicking a cell with shift and ctrl keys held.

Note: original documentation (modified) obtained from JTable.changeSelection (Oracle JDK 1.5).

Parameters:

rowIndex - affects the selection at row

columnIndex - affects the selection at column

toggle - see description above

extend - if true, extend the current selection

selectAll

void selectAll()

Selects all cells in the table.

getItsNatTableStructure

ItsNatTableStructure getItsNatTableStructure()

Returns the component structure.

Returns:

the component structure.

getItsNatTableCellRenderer

ItsNatTableCellRenderer getItsNatTableCellRenderer()

Returns the current component renderer. This renderer converts a table cell value to markup.

Returns:

the current renderer. By default uses the default renderer (ItsNatComponentManager.createDefaultItsNatTableCellRenderer())

See Also:

setItsNatTableCellRenderer(ItsNatTableCellRenderer)

setItsNatTableCellRenderer

void setItsNatTableCellRenderer(ItsNatTableCellRenderer renderer)

Sets the component renderer.

Parameters:

renderer - the new renderer.

See Also:

getItsNatTableCellRenderer()

getItsNatTableCellEditor

ItsNatTableCellEditor getItsNatTableCellEditor()

Returns the current table cell editor. This object is used to edit in place a table cell value.

Returns:

the current editor. By default uses the default editor calling (ItsNatComponentManager.createDefaultItsNatTableCellEditor(ItsNatComponent)) with a null parameter.

See Also:

setItsNatTableCellEditor(ItsNatTableCellEditor)

setItsNatTableCellEditor

void setItsNatTableCellEditor(ItsNatTableCellEditor editor)

Sets the table cell editor.

Table cell edition works very much the same as label edition (see ItsNatLabel.setItsNatLabelEditor(ItsNatLabelEditor)).

Some differences:

The edition process starts programmatically by calling startEditingAt(int,int).

The edition takes place inside the cell content element as returned by ItsNatTableStructure.getCellContentElement(ItsNatTable,int,int,org.w3c.dom.Element).

The new cell value is set to the data model calling javax.swing.table.TableModel.setValueAt(Object,int,int).

Parameters:

editor - the new editor. May be null (edition disabled).

See Also:

getItsNatTableCellEditor()

startEditingAt

void startEditingAt(int row,
                  int column)

Used to start programmatically a table cell edition process "in place".

See Also:

isEditing()

isEditing

boolean isEditing()

Informs whether a table cell value is being edited.

Returns:

true if a table cell value is being edited.

See Also:

startEditingAt(int,int)

getEditingRow

int getEditingRow()

Returns the row of the cell being edited.

Returns:

the row of the cell being edited. -1 if none is being edited.

getEditingColumn

int getEditingColumn()

Returns the column of the cell being edited.

Returns:

the column of the cell being edited. -1 if none is being edited.

getEditorActivatorEvent

java.lang.String getEditorActivatorEvent()

Returns the event type used to activate the table cell edition process by the user.

If returns null edition activated by events is disabled .

Returns:

the event type used to activate the edition. By default is "dblclick".

See Also:

setEditorActivatorEvent(String)

setEditorActivatorEvent

void setEditorActivatorEvent(java.lang.String eventType)

Sets the event type used to activate the table cell edition process by the user.

Parameters:

eventType - the event type used to activate the edition.

See Also:

getEditorActivatorEvent()

isEditingEnabled

boolean isEditingEnabled()

Informs whether the in place edition is enabled.

Returns:

false if the editing in place is temporally disabled. True by default.

See Also:

setEditingEnabled(boolean)

setEditingEnabled

void setEditingEnabled(boolean value)

Enables or disables temporally the in place edition.

Parameters:

value - true to enable in place edition.

See Also:

isEditingEnabled()

isSelectionUsesKeyboard

boolean isSelectionUsesKeyboard()

Returns if the keyboard is used to select items.

If false ItsNat simulates the CTRL key is ever pressed when an item is selected.

This feature is useful for mobile devices without keyboard and tactile screens to select multiple items (if set to false).

Default value is defined by ItsNatComponentManager.isSelectionOnComponentsUsesKeyboard()

Returns:

the current state.

See Also:

setSelectionUsesKeyboard(boolean)

setSelectionUsesKeyboard

void setSelectionUsesKeyboard(boolean value)

Sets if the keyboard is used to select items.

Parameters:

value - the new state.

See Also:

isSelectionUsesKeyboard()

isJoystickMode

boolean isJoystickMode()

Informs whether a joystick is enough to control the component (some kind of mouse, pointer or stylus not present or not necessary).

If the component is in joystick mode, the "content element" of every table cell has an event listener associated. By this way table cells are "live" elements and can traversed using a joystick in mobile devices without a mouse, pointer or stylus.

Default value is defined by ItsNatDocument.isJoystickMode()

Returns:

true if joystick mode is on.

See Also:

setJoystickMode(boolean), ItsNatTableStructure.getCellContentElement(ItsNatTable, int, int, org.w3c.dom.Element)

setJoystickMode

void setJoystickMode(boolean value)

Informs whether a joystick is enough to control the component (some kind of mouse, pointer or stylus not present or not necessary).

Parameters:

value - true to enable joystick mode.

See Also:

isJoystickMode()