Class TableFormController


  • public class TableFormController
    extends Object

    A helper class for dealing with Form objects related to table components.

    The implementation of tables for different UI platforms in JGUIraffe requires some common functionality for dealing with the single properties of model beans. When defining a table Form instances are created allowing the manipulation of properties via the API provided by this class. This also includes support for data type transformation and validation. Nevertheless, there is still some boiler-plate code necessary to interact with these forms, e.g. to retrieve the values to be displayed in a table column or to write back data the user has changed.

    This class aims at providing this functionality in a central place so that platform-specific implementations of table components can be simplified. Before version 1.3 of this library this code was mainly contained in the Swing-specific table implementation. It is now refactored so that it can be reused by other implementations, too.

    This class uses a form-based approach for accessing the table model data of a specific row. This means that if a new row is selected for being rendered or edited, the data of the model is loaded into the row render and editor forms. From there it can be read (and even updated) using the typical API offered by the Form class.

    Since:
    1.3
    Version:
    $Id$
    Author:
    Oliver Heger
    • Constructor Detail

      • TableFormController

        public TableFormController​(TableTag tabTag)
        Creates a new instance of TableFormController and initializes it from the passed in TableTag.
        Parameters:
        tabTag - the TableTag (must not be null)
        Throws:
        IllegalArgumentException - if the passed in tag is null
    • Method Detail

      • getDataModel

        public List<Object> getDataModel()
        Returns the list serving as data model for the managed table. Note that the list is directly returned, no defensive copy is created. Callers are responsible for performing only valid modifications if any!
        Returns:
        the data model list
      • getRowCount

        public int getRowCount()
        Returns the number of rows in the data model of the managed table.
        Returns:
        the number of rows in the table
      • getColumnCount

        public int getColumnCount()
        Returns the number of columns of the managed table.
        Returns:
        the number of columns
      • getColumnName

        public String getColumnName​(int col)
        Returns the title of the column with the given index. This string can be placed in the column header.
        Parameters:
        col - the index of the column in question
        Returns:
        the title of this column
      • getColumnFieldName

        public String getColumnFieldName​(int col)
        Returns the field name of the specified column in the render or edit form. In the forms created for a table for each column per default a field is created. This method can be used to determine the field name of a column.
        Parameters:
        col - the index of the column in question
        Returns:
        the name of the field associated with this column in the table forms
      • getModelBean

        public Object getModelBean​(int row)
        A convenience method which returns the bean from the data model with the specified row index. Indices are 0-based.
        Parameters:
        row - the row index
        Returns:
        the data object at this row index in the table model
      • selectCurrentRow

        public void selectCurrentRow​(int row)
        Tells this controller that the specified row becomes the current row. This method causes some initializations to be made. Namely, the forms representing the content of the row are initialized.
        Parameters:
        row - the index of the new current row
      • resetCurrentRow

        public void resetCurrentRow()
        Resets the current row index. This is the opposite of the selectCurrentRow() method. It invalidates the index of the current row. Calling this method makes sense for instance if there have been changes on the underlying data model.
      • invalidateRange

        public void invalidateRange​(int fromIdx,
                                    int toIdx)
        Notifies this controller that a range of rows has changed in the underlying table model. If the current row is affected, it is reset.
        Parameters:
        fromIdx - the start row index of the affected range
        toIdx - the end row index of the affected change (including)
      • getColumnValue

        public Object getColumnValue​(int col)
        Returns the value from the given column in the current row. The value is obtained from the field associated with this column from the row rendering form. Note: Before this method can be used, selectCurrentRow() must have been called first.
        Parameters:
        col - the index of the column in question
        Returns:
        the value of this column for the current row
      • setColumnValue

        public void setColumnValue​(Object table,
                                   int col,
                                   Object value)
        Sets the value for the given column in the current row. This method can be used for modifying the value of a cell if no special edit form is specified for this column. (If there is an edit form, this method performs no action.) The value is written into the edit form, and validation is performed. The table's validation handler is invoked with the results of the validation. Depending on this, the table is updated or the changes are discarded. Note: Before this method can be used, selectCurrentRow() must have been called first.
        Parameters:
        table - the current table component
        col - the index of the column in question
        value - the value to be set for this cell
      • validateColumn

        public boolean validateColumn​(Object table,
                                      int col)
        Validates a column in the current row. This method can be called after the user has edited a cell in the table. It performs a validation on all fields displayed in this table. With the results of this validation the TableEditorValidationHandler is invoked. This object also determines how to handle validation errors. If everything goes well, the data from the edit form is copied into the model bean for the current row.
        Parameters:
        table - the current table component
        col - the index of the column in question
        Returns:
        a flag whether validation was successful
      • getColumnRenderer

        public Object getColumnRenderer​(int col)
        Returns the renderer component installed for the specified column. Result is null if no renderer was set for this column.
        Parameters:
        col - the column index
        Returns:
        the renderer component for this column or null
      • getColumnEditor

        public Object getColumnEditor​(int col)
        Returns the editor component installed for the specified column. Result is null if no editor was set for this column.
        Parameters:
        col - the column index
        Returns:
        the editor component for this column or null
      • hasEditor

        public boolean hasEditor​(int col)
        Checks whether for the specified column a custom editor is specified.
        Parameters:
        col - the column index
        Returns:
        a flag if this column has its own editor
      • hasRenderer

        public boolean hasRenderer​(int col)
        Checks whether for the specified column a custom renderer is specified.
        Parameters:
        col - the column index
        Returns:
        a flag if this column has its own renderer component
      • isColumnEditable

        public boolean isColumnEditable​(int col)
        Returns a flag whether the specified column is declared to be editable.
        Parameters:
        col - the column index
        Returns:
        true if this column should be editable, false otherwise
      • isTableEditable

        public boolean isTableEditable()
        Returns a flag whether the table is editable.
        Returns:
        the editable flag for the whole table
      • getLogicDataClass

        public ColumnClass getLogicDataClass​(int col)
        Returns the logic data class of the specified column. Result may be null if no logic column class was assigned. In this case, the Class object returned by getDataClass() may be used to determine the column type.
        Parameters:
        col - the column index
        Returns:
        the logic column class (may be null)
      • getDataClass

        public Class<?> getDataClass​(int col)
        Returns the data class for the specified column. Normally, it is preferred to use a logic column class. Applications can also specify a "real" class, but the platform in use must then support this class. This method never returns null; if no explicit data class was set, the generic Object class is returned.
        Parameters:
        col - the column index
        Returns:
        the data class of this column
      • getColumnRecalibrator

        public TableColumnRecalibrator getColumnRecalibrator()
                                                      throws FormBuilderException
        Convenience method for querying the TableColumnRecalibrator. This method returns the TableColumnWidthController which also implements this interface.
        Returns:
        the TableColumnRecalibrator
        Throws:
        FormBuilderException - if this object cannot be obtained
      • getColumnWidthCalculator

        public TableColumnWidthCalculator getColumnWidthCalculator()
                                                            throws FormBuilderException
        Convenience method for querying the TableColumnWidthCalculator. This method returns the TableColumnWidthController which also implements this interface.
        Returns:
        the TableColumnWidthCalculator
        Throws:
        FormBuilderException - if this object cannot be obtained
      • installTransformersForColumnType

        public boolean installTransformersForColumnType​(int col)
        Installs special transformers and validators for the field associated with the specified column based on its ColumnClass. This method checks whether a logic type is defined for this column, if it does not have a renderer, and if no transformers and validators are defined. If all these conditions are met, corresponding transformers and validators are created for the column's logic type and installed at the field handlers of the row forms.
        Parameters:
        col - the column index
        Returns:
        a flag whether transformers were installed
      • calculateFixedColumnWidths

        public int calculateFixedColumnWidths​(UnitSizeHandler sizeHandler,
                                              Object container)
                                       throws FormBuilderException
        Determines the fixed size columns of the represented table and initializes their widths in the TableColumnWidthController of the current table.
        Parameters:
        sizeHandler - the UnitSizeHandler
        container - the enclosing container object
        Returns:
        the total width of all columns with a fixed column width
        Throws:
        FormBuilderException - if an error occurs
      • isMultiSelection

        public boolean isMultiSelection()
        Returns a flag whether multi-selection mode is enabled for the associated table.
        Returns:
        a flag whether multi-selection mode is enabled
        Since:
        1.3.1