Package docking.widgets.table

# Class AbstractSortedTableModel<T>

java.lang.Object
javax.swing.table.AbstractTableModel
docking.widgets.table.AbstractGTableModel<T>
docking.widgets.table.AbstractSortedTableModel<T>

Type Parameters:
  `T` - The row type upon which the table is based

All Implemented Interfaces:
  `RowObjectTableModel<T>`, `SelectionStorage<T>`, `SortedTableModel`, `Serializable`, `TableModel`

Direct Known Subclasses:
  `DynamicTableModel`, `GDynamicColumnTableModel`, `LanguageSortedTableModel`

public abstract class AbstractSortedTableModel<T> extends AbstractGTableModel<T> implements SortedTableModel
Table models should extends this model when they want sorting, potentially across multiple columns, but do not want Threading or do not work on Program-related data (Address, ProgramLocations, etc...).

In order to define custom comparators for a column, simply override `createSortComparator(int)`. Otherwise, a default comparator will be created for you.

Note on sorting: it is possible that the user can disable sorting by de-selecting all sorted columns. This can also be achieved programmatically by calling `setTableSortState(TableSortState)` with a value of `TableSortState.createUnsortedSortState()`.

See Also:
  - Serialized Form

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `protected boolean`
  `hasEverSorted`

  ### Fields inherited from class docking.widgets.table.AbstractGTableModel

  `isDisposed, WIDTH_UNDEFINED`

  ### Fields inherited from class javax.swing.table.AbstractTableModel

  `listenerList`

  ### Fields inherited from interface docking.widgets.table.SortedTableModel

  `ASCENDING_ORDER, DESCENDING_ORDER`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `AbstractSortedTableModel()`
  `AbstractSortedTableModel(int defaultSortColumn)`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `addSortListener(SortListener l)`
  Adds a listener to be notified when the sort state of this model changes.
  `protected TableSortState`
  `cleanupTableSortState(TableSortState state)`
  A convenience method that will take a given sort state and remove from it any columns that cannot be sorted.
  `protected Comparator<T>`
  `createSortComparator(int columnIndex)`
  An extension point for subclasses to insert their own comparator objects for their data.
  `protected TableSortingContext<T>`
  `createSortingContext(TableSortState newSortState)`
  `void`
  `fireTableChanged(TableModelEvent e)`
  `protected int`
  `getIndexForRowObject(T rowObject)`
  A convenience method for subclasses to quickly/efficiently search for the index of a given row object that is visible in the GUI.
  `protected int`
  `getIndexForRowObject(T rowObject, List<T> data)`
  Returns the index for the given object in the given list
  `TableSortState`
  `getPendingSortState()`
  `int`
  `getPrimarySortColumnIndex()`
  Returns the column index that is the primary sorted column; -1 if no column is sorted
  `int`
  `getRowIndex(T rowObject)`
  Returns the index of the given row object in this model; a negative value if the model does not contain the given object.
  `T`
  `getRowObject(int viewRow)`
  Returns the corresponding object for the given row.
  `TableSortState`
  `getTableSortState()`
  Gets the sort state of this sorted model
  `Object`
  `getValueAt(int rowIndex, int columnIndex)`
  The default implementation of `TableModel.getValueAt(int, int)` that calls the abstract `RowObjectTableModel.getColumnValueForRow(Object, int)`.
  `protected void`
  `initializeSorting()`
  This method is an attempt to help models that forget to call fireTableDataChanged().
  `boolean`
  `isSorted()`
  Returns true if this model has been sorted and does not have a new pending sort that will be applied
  `boolean`
  `isSortPending()`
  Returns true if there is a pending change to the current sort state (this includes a sort state that signals no sort will be applied)
  `protected void`
  `notifyModelSorted(boolean dataChanged)`
  Fires an event to let the listeners (like JTable) know that things have been changed.
  `protected void`
  `reSort()`
  `protected void`
  `setDefaultTableSortState(TableSortState defaultSortState)`
  `void`
  `setTableSortState(TableSortState newSortState)`
  Sets the sort state for this table model
  `protected void`
  `sort(List<T> data, TableSortingContext<T> sortingContext)`
  A default sort method that uses the `Collections.sort(List, Comparator)` method for sorting.
  `protected void`
  `sortCompleted(TableSortingContext<T> sortingContext)`

  ### Methods inherited from class docking.widgets.table.AbstractGTableModel

  `dispose, getLastSelectedObjects, getPreferredColumnWidth, getRowCount, isDisposed, refresh, setLastSelectedObjects`

  ### Methods inherited from class javax.swing.table.AbstractTableModel

  `addTableModelListener, findColumn, fireTableCellUpdated, fireTableDataChanged, fireTableRowsDeleted, fireTableRowsInserted, fireTableRowsUpdated, fireTableStructureChanged, getColumnClass, getColumnName, getListeners, getTableModelListeners, isCellEditable, removeTableModelListener, setValueAt`

  ### Methods inherited from class java.lang.Object

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

  ### Methods inherited from interface docking.widgets.table.RowObjectTableModel

  `fireTableDataChanged, getColumnValueForRow, getModelData, getName`

  ### Methods inherited from interface docking.widgets.table.SortedTableModel

  `isSortable`

  ### Methods inherited from interface javax.swing.table.TableModel

  `addTableModelListener, getColumnClass, getColumnCount, getColumnName, getRowCount, isCellEditable, removeTableModelListener, setValueAt`

- ## Field Details

  - ### hasEverSorted

    protected boolean hasEverSorted

- ## Constructor Details

  - ### AbstractSortedTableModel

    public AbstractSortedTableModel()

  - ### AbstractSortedTableModel

    public AbstractSortedTableModel(int defaultSortColumn)

- ## Method Details

  - ### setDefaultTableSortState

    protected void setDefaultTableSortState(TableSortState defaultSortState)

  - ### addSortListener

    public void addSortListener(SortListener l)
    Description copied from interface: `SortedTableModel`
    Adds a listener to be notified when the sort state of this model changes.
    Note: the listener may be stored in a weak collection, which means you have to maintain a handle to the listener so that it does not get garbage collected.
    Specified by:
      `addSortListener` in interface `SortedTableModel`
    Parameters:
      `l` - the listener

  - ### getRowObject

    public T getRowObject(int viewRow)
    Returns the corresponding object for the given row.
    Specified by:
      `getRowObject` in interface `RowObjectTableModel<T>`
    Overrides:
      `getRowObject` in class `AbstractGTableModel<T>`
    Parameters:
      `viewRow` - The row for which to get the row object.
    Returns:
      the row object.

  - ### getRowIndex

    public int getRowIndex(T rowObject)
    Returns the index of the given row object in this model; a negative value if the model does not contain the given object.

    Warning: if the this model has no sort applied, then performance will be O(n). If sorted, then performance is O(log n). You can call `isSorted()` to know when this will happen.

    Specified by:
      `getRowIndex` in interface `RowObjectTableModel<T>`
    Overrides:
      `getRowIndex` in class `AbstractGTableModel<T>`
    Parameters:
      `rowObject` - the object
    Returns:
      the row number

  - ### fireTableChanged

    public void fireTableChanged(TableModelEvent e)
    Overrides:
      `fireTableChanged` in class `AbstractTableModel`

  - ### reSort

    protected void reSort()

  - ### getTableSortState

    public TableSortState getTableSortState()
    Description copied from interface: `SortedTableModel`
    Gets the sort state of this sorted model
    Specified by:
      `getTableSortState` in interface `SortedTableModel`
    Returns:
      the current sort state

  - ### getPrimarySortColumnIndex

    public int getPrimarySortColumnIndex()
    Description copied from interface: `SortedTableModel`
    Returns the column index that is the primary sorted column; -1 if no column is sorted
    Specified by:
      `getPrimarySortColumnIndex` in interface `SortedTableModel`
    Returns:
      the index

  - ### setTableSortState

    public void setTableSortState(TableSortState newSortState)
    Description copied from interface: `SortedTableModel`
    Sets the sort state for this table model
    Specified by:
      `setTableSortState` in interface `SortedTableModel`
    Parameters:
      `newSortState` - the sort state

  - ### cleanupTableSortState

    protected TableSortState cleanupTableSortState(TableSortState state)
    A convenience method that will take a given sort state and remove from it any columns that cannot be sorted. This is useful if the client is restoring a sort state that contains columns that have been removed or are no longer sortable (such as during major table model rewrites).
    Parameters:
      `state` - the state
    Returns:
      the updated state

  - ### getPendingSortState

    public TableSortState getPendingSortState()

  - ### isSortPending

    public boolean isSortPending()
    Returns true if there is a pending change to the current sort state (this includes a sort state that signals no sort will be applied)
    Returns:
      true if there is a pending change to the current sort state

  - ### isSorted

    public boolean isSorted()
    Returns true if this model has been sorted and does not have a new pending sort that will be applied
    Returns:
      true if sorted
    See Also:
      - `isSortPending()`

  - ### createSortingContext

    protected TableSortingContext<T> createSortingContext(TableSortState newSortState)

  - ### getValueAt

    public Object getValueAt(int rowIndex, int columnIndex)
    The default implementation of `TableModel.getValueAt(int, int)` that calls the abstract `RowObjectTableModel.getColumnValueForRow(Object, int)`.
    Specified by:
      `getValueAt` in interface `TableModel`
    Overrides:
      `getValueAt` in class `AbstractGTableModel<T>`

  - ### initializeSorting

    protected void initializeSorting()
    This method is an attempt to help models that forget to call fireTableDataChanged(). It is expected that tables will fire the notification when they are ready to display data, even if they have that data at construction time. We put this call here so that the forgetful subclasses will have their data sorted for them the first time that this table tries to render itself.

  - ### getIndexForRowObject

    protected int getIndexForRowObject(T rowObject)
    A convenience method for subclasses to quickly/efficiently search for the index of a given row object that is visible in the GUI. The visible limitation is due to the fact that the data searched is retrieved from `RowObjectTableModel.getModelData()`, which may be filtered.
    Overrides:
      `getIndexForRowObject` in class `AbstractGTableModel<T>`
    Parameters:
      `rowObject` - The object for which to search.
    Returns:
      the index of the item in the data returned by

  - ### getIndexForRowObject

    protected int getIndexForRowObject(T rowObject, List<T> data)
    Returns the index for the given object in the given list
    Overrides:
      `getIndexForRowObject` in class `AbstractGTableModel<T>`
    Parameters:
      `rowObject` - the item
      `data` - the data
    Returns:
      the index

  - ### sort

    protected void sort(List<T> data, TableSortingContext<T> sortingContext)
    A default sort method that uses the `Collections.sort(List, Comparator)` method for sorting. Implementors with reasonably sized data sets can rely on this method. For data sets that can become large, the `ThreadedTableModel` is the recommended base class, as it handles loading/sorting/filtering in a threaded way.
    Parameters:
      `data` - The data to be sorted
      `sortingContext` - The context required to sort (it contains the sorting columns, a comparator for sorting, etc...).

  - ### sortCompleted

    protected void sortCompleted(TableSortingContext<T> sortingContext)

  - ### notifyModelSorted

    protected void notifyModelSorted(boolean dataChanged)
    Fires an event to let the listeners (like JTable) know that things have been changed. This method exists so that subclasses have a way to call the various `tableChanged()` methods without triggering this class's overridden version.
    Parameters:
      `dataChanged` - True signals that the actual data has changed; false signals that the data is the same, with exception that attributes of that data may be different.

  - ### createSortComparator

    protected Comparator<T> createSortComparator(int columnIndex)
    An extension point for subclasses to insert their own comparator objects for their data. Subclasses can create comparators for a single or multiple columns, as desired.
    Parameters:
      `columnIndex` - the column index
    Returns:
      the comparator