eu.webtoolkit.jwt
Class WSortFilterProxyModel

java.lang.Object
  eu.webtoolkit.jwt.WObject
      eu.webtoolkit.jwt.WAbstractItemModel
          eu.webtoolkit.jwt.WAbstractProxyModel
              eu.webtoolkit.jwt.WSortFilterProxyModel

public class WSortFilterProxyModel
extends WAbstractProxyModel

A proxy model for Wt's item models that provides filtering and/or sorting.

This proxy model does not store data itself, but presents data from a source model, after filtering rows. It also allows sorting of the source model data, without actually altering the source model. This may be convenient when the source model does not support sorting (i.e. does not reimplement WAbstractItemModel#sort()), or you do not want to reorder the underlying model since that affects all views on the model.

To use the proxy model to filter data, you use the methods setFilterKeyColumn(), setFilterRegExp() and setFilterRole() to specify a filtering operation based on the values of a single column. If this filtering mechanism is too limiting, you can provide specialized filtering by reimplementing the filterAcceptRow() method.

Sorting is provided by reimplementing the standard WAbstractItemModel#sort() method. In this way, a view class such as WTreeView may resort the model as indicated by the user. Use setSortRole() to indicate on what data role sorting should be done, or reimplement the lessThan() method to provide a specialized sorting method.

By default, the proxy does not automatically refilter and resort when the original model changes. Data changes or row additions to the source model are not automatically reflected in the proxy model, but to maintain integrity, row removals in the source model are always reflected in the proxy model. You can enable the model to always refilter and resort when the underlying model changes using setDynamicSortFilter().

Usage example:

 // model is the source model
   WAbstractItemModel model = ...
  
  // we setup a proxy to filter the source model
  WSortFilterProxyModel proxy = new WSortFilterProxyModel(this);
  proxy.setSourceModel(model);
  proxy.setDynamicSortFilter(true);
  proxy.setFilterKeyColumn(0);
  proxy.setFilterRole(ItemDataRole.UserRole);
  proxy.setFilterRegExp(".*");
 		 
  // configure a view to use the proxy model instead of the source model
  WTreeView view = new WTreeView(this);
  view.setModel(proxy);
  ...
 
 

Nested Class Summary

Nested classes/interfaces inherited from class eu.webtoolkit.jwt.WAbstractProxyModel

WAbstractProxyModel.BaseItem

Constructor Summary

WSortFilterProxyModel()
Constructor.

WSortFilterProxyModel(WObject parent)
Constructor.

Method Summary

protected boolean	filterAcceptRow(int sourceRow, WModelIndex sourceParent) Returns whether a source row is accepted by the filter.
int	getColumnCount(WModelIndex parent) Returns the number of columns.
int	getFilterFlags() Returns the filter regular expression flags.
int	getFilterKeyColumn() Return the column on which the filtering is applied.
java.lang.String	getFilterRegExp() Return the regular expression used for filtering.
int	getFilterRole() Return the data role used for filtering.
java.lang.Object	getHeaderData(int section, Orientation orientation, int role) Returns the row or column header data.
java.util.EnumSet<HeaderFlag>	getHeaderFlags(int section, Orientation orientation) Returns the flags for a header.
WModelIndex	getIndex(int row, int column, WModelIndex parent) Returns the child index for the given row and column.
WModelIndex	getParent(WModelIndex index) Returns the parent for a model index.
int	getRowCount(WModelIndex parent) Returns the number of rows.
int	getSortColumn() Returns the current sort column.
SortOrder	getSortOrder() Returns the current sort order.
int	getSortRole() Return the data role used for sorting.
boolean	insertRows(int row, int count, WModelIndex parent) Inserts a number rows.
boolean	isDynamicSortFilter() Returns whether this proxy dynmically filters and sorts.
protected boolean	lessThan(WModelIndex lhs, WModelIndex rhs) Compares two indexes.
WModelIndex	mapFromSource(WModelIndex sourceIndex) Maps a source model index to the proxy model.
WModelIndex	mapToSource(WModelIndex proxyIndex) Maps a proxy model index to the source model.
boolean	removeRows(int row, int count, WModelIndex parent) Removes a number rows.
void	setDynamicSortFilter(boolean enable) Configure the proxy to dynamically track changes in the source model.
void	setFilterFlags(int flags) Sets the filter regular expression flags.
void	setFilterKeyColumn(int column) Specify the column on which the filtering is applied.
void	setFilterRegExp(java.lang.String pattern) Specify a regular expression for filtering.
void	setFilterRole(int role) Specify the data role used for filtering.
boolean	setHeaderData(int section, Orientation orientation, java.lang.Object value, int role) Sets header data for a column or row.
void	setSortRole(int role) Specify the data role used used for sorting.
void	setSourceModel(WAbstractItemModel model) Sets the source model.
void	sort(int column, SortOrder order) Sorts the model according to a particular column.

Methods inherited from class eu.webtoolkit.jwt.WAbstractProxyModel

createSourceIndex, dropEvent, fromRawIndex, getAcceptDropMimeTypes, getData, getFlags, getMimeType, getSourceModel, insertColumns, removeColumns, setData, shiftModelIndexes, toRawIndex

Methods inherited from class eu.webtoolkit.jwt.WAbstractItemModel

beginInsertColumns, beginInsertRows, beginRemoveColumns, beginRemoveRows, collapseColumn, columnsAboutToBeInserted, columnsAboutToBeRemoved, columnsInserted, columnsRemoved, createIndex, dataChanged, endInsertColumns, endInsertRows, endRemoveColumns, endRemoveRows, expandColumn, getColumnCount, getData, getData, getData, getData, getHeaderData, getHeaderData, getHeaderFlags, getIndex, getItemData, getRowCount, hasChildren, hasIndex, hasIndex, headerDataChanged, insertColumn, insertColumn, insertColumns, insertRow, insertRow, insertRows, layoutAboutToBeChanged, layoutChanged, match, modelReset, removeColumn, removeColumn, removeColumns, removeRow, removeRow, removeRows, reset, rowsAboutToBeInserted, rowsAboutToBeRemoved, rowsInserted, rowsRemoved, setData, setData, setData, setData, setHeaderData, setHeaderData, setItemData, sort

Methods inherited from class eu.webtoolkit.jwt.WObject

addChild, getId, getObjectName, remove, setObjectName, tr

Methods inherited from class java.lang.Object

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

Constructor Detail

WSortFilterProxyModel

public WSortFilterProxyModel(WObject parent)

Constructor.

WSortFilterProxyModel

public WSortFilterProxyModel()

Constructor.

Calls this((WObject)null)

Method Detail

mapFromSource

public WModelIndex mapFromSource(WModelIndex sourceIndex)

Description copied from class: WAbstractProxyModel

Maps a source model index to the proxy model.

This method returns a model index in the proxy model that corresponds to the model index sourceIndex in the source model. This method must only be implemented for source model indexes that are mapped and thus are the result of mapToSource().

Specified by:

mapFromSource in class WAbstractProxyModel

See Also:

WAbstractProxyModel.mapToSource(WModelIndex proxyIndex)

mapToSource

public WModelIndex mapToSource(WModelIndex proxyIndex)

Description copied from class: WAbstractProxyModel

Maps a proxy model index to the source model.

This method returns a model index in the source model that corresponds to the proxy model index proxyIndex.

Specified by:

mapToSource in class WAbstractProxyModel

See Also:

WAbstractProxyModel.mapFromSource(WModelIndex sourceIndex)

setSourceModel

public void setSourceModel(WAbstractItemModel model)

Description copied from class: WAbstractProxyModel

Sets the source model.

The source model provides the actual data for the proxy model.

Ownership of the source model is not transferred.

Overrides:

setSourceModel in class WAbstractProxyModel

setFilterKeyColumn

public void setFilterKeyColumn(int column)

Specify the column on which the filtering is applied.

This configures the column on which the getFilterRegExp() is applied.

The default value is 0.

See Also:

setFilterRegExp(String pattern), setFilterRole(int role)

getFilterKeyColumn

public int getFilterKeyColumn()

Return the column on which the filtering is applied.

See Also:

setFilterKeyColumn(int column)

setFilterRegExp

public void setFilterRegExp(java.lang.String pattern)

Specify a regular expression for filtering.

This configures the regular expression used for filtering on getFilterKeyColumn().

The default value is an empty expression, which disables filtering.

See Also:

setFilterKeyColumn(int column), setFilterRole(int role)

getFilterRegExp

public java.lang.String getFilterRegExp()

Return the regular expression used for filtering.

See Also:

setFilterRegExp(String pattern)

setFilterFlags

public void setFilterFlags(int flags)

Sets the filter regular expression flags.

getFilterFlags

public int getFilterFlags()

Returns the filter regular expression flags.

setFilterRole

public void setFilterRole(int role)

Specify the data role used for filtering.

This configures the data role used for filtering on getFilterKeyColumn().

The default value is DisplayRole.

See Also:

setFilterKeyColumn(int column), setFilterRegExp(String pattern)

getFilterRole

public int getFilterRole()

Return the data role used for filtering.

See Also:

setFilterRole(int role)

setSortRole

public void setSortRole(int role)

Specify the data role used used for sorting.

This configures the data role used for sorting.

The default value is DisplayRole.

See Also:

lessThan(WModelIndex lhs, WModelIndex rhs)

getSortRole

public int getSortRole()

Return the data role used for sorting.

See Also:

setSortRole(int role)

getSortColumn

public int getSortColumn()

Returns the current sort column.

When sort() has not been called, the model is unsorted, and this method returns -1.

See Also:

sort(int column, SortOrder order)

getSortOrder

public SortOrder getSortOrder()

Returns the current sort order.

See Also:

sort(int column, SortOrder order)

setDynamicSortFilter

public void setDynamicSortFilter(boolean enable)

Configure the proxy to dynamically track changes in the source model.

When enable is true, the proxy will re-filter and re-sort the model when changes happen to the source model.

Note: This may be ackward when editing through the proxy model, since changing some data may rearrange the model and thus invalidate model indexes. Therefore it is usually less complicated to manipulate directly the source model instead.

See Also:

lessThan(WModelIndex lhs, WModelIndex rhs)

isDynamicSortFilter

public boolean isDynamicSortFilter()

Returns whether this proxy dynmically filters and sorts.

See Also:

setDynamicSortFilter(boolean enable)

getColumnCount

public int getColumnCount(WModelIndex parent)

Description copied from class: WAbstractItemModel

Returns the number of columns.

This returns the number of columns at index parent.

Specified by:

getColumnCount in class WAbstractItemModel

See Also:

WAbstractItemModel.getRowCount(WModelIndex parent)

getRowCount

public int getRowCount(WModelIndex parent)

Description copied from class: WAbstractItemModel

Returns the number of rows.

This returns the number of rows at index parent.

Specified by:

getRowCount in class WAbstractItemModel

See Also:

WAbstractItemModel.getColumnCount(WModelIndex parent)

getParent

public WModelIndex getParent(WModelIndex index)

Description copied from class: WAbstractItemModel

Returns the parent for a model index.

An implementation should use createIndex() to create a model index that corresponds to the parent of a given index.

Note that the index itself may be stale (referencing a row/column within the parent that is outside the model geometry), but its parent (identified by the WModelIndex#getInternalPointer()) is referencing an existing parent. A stale index can only be used while the model geometry is being updated, i.e. during the emission of the corresponding [rows/columns](Being)[Removed/Inserted]() signals.

Specified by:

getParent in class WAbstractItemModel

See Also:

WAbstractItemModel.getIndex(int row, int column, WModelIndex parent)

getIndex

public WModelIndex getIndex(int row,
                            int column,
                            WModelIndex parent)

Description copied from class: WAbstractItemModel

Returns the child index for the given row and column.

When implementing this method, you can use createIndex() to create an index that corresponds to the item at row and column within parent.

If the location is invalid (out of bounds at the parent), then an invalid index must be returned.

Specified by:

getIndex in class WAbstractItemModel

See Also:

WAbstractItemModel.getParent(WModelIndex index)

setHeaderData

public boolean setHeaderData(int section,
                             Orientation orientation,
                             java.lang.Object value,
                             int role)

Description copied from class: WAbstractItemModel

Sets header data for a column or row.

Returns true if the operation was successful.

Overrides:

setHeaderData in class WAbstractItemModel

See Also:

WAbstractItemModel.getHeaderData(int section, Orientation orientation, int role)

getHeaderData

public java.lang.Object getHeaderData(int section,
                                      Orientation orientation,
                                      int role)

Description copied from class: WAbstractItemModel

Returns the row or column header data.

When orientation is Horizontal, section is a column number, when orientation is Vertical, section is a row number.

Overrides:

getHeaderData in class WAbstractItemModel

See Also:

WAbstractItemModel.getData(WModelIndex index, int role), WAbstractItemModel.setHeaderData(int section, Orientation orientation, Object value, int role)

getHeaderFlags

public java.util.EnumSet<HeaderFlag> getHeaderFlags(int section,
                                                    Orientation orientation)

Description copied from class: WAbstractItemModel

Returns the flags for a header.

The default implementation returns no flags set.

Overrides:

getHeaderFlags in class WAbstractItemModel

See Also:

HeaderFlag

insertRows

public boolean insertRows(int row,
                          int count,
                          WModelIndex parent)

Inserts a number rows.

The rows are inserted in the source model, and if successful, also in the proxy model regardless of whether they are matched by the current filter. They are inserted at the indicated row, regardless of whether this is the correct place according to the defined sorting.

As soon as you set data for the column on which the filtering is active, or which affects the sorting, the row may be filtered out or change position when dynamic sorting/filtering is enabled. Therefore, it is usually a good idea to temporarily disable the dynamic sort/filtering behaviour while inserting new row(s) of data.

Overrides:

insertRows in class WAbstractItemModel

See Also:

WAbstractItemModel.insertColumns(int column, int count, WModelIndex parent), WAbstractItemModel.removeRows(int row, int count, WModelIndex parent), WAbstractItemModel.beginInsertRows(WModelIndex parent, int first, int last), WAbstractItemModel.endInsertRows()

removeRows

public boolean removeRows(int row,
                          int count,
                          WModelIndex parent)

Removes a number rows.

The rows are removed from the source model.

Overrides:

removeRows in class WAbstractItemModel

See Also:

WAbstractItemModel.removeColumns(int column, int count, WModelIndex parent), WAbstractItemModel.insertRows(int row, int count, WModelIndex parent), WAbstractItemModel.beginRemoveRows(WModelIndex parent, int first, int last), WAbstractItemModel.endRemoveRows()

sort

public void sort(int column,
                 SortOrder order)

Description copied from class: WAbstractItemModel

Sorts the model according to a particular column.

If the model supports sorting, then it should emit the layoutAboutToBeChanged() signal, rearrange its items, and afterwards emit the layoutChanged() signal.

Overrides:

sort in class WAbstractItemModel

See Also:

WAbstractItemModel.layoutAboutToBeChanged(), WAbstractItemModel.layoutChanged()

filterAcceptRow

protected boolean filterAcceptRow(int sourceRow,
                                  WModelIndex sourceParent)

Returns whether a source row is accepted by the filter.

The default implementation uses getFilterKeyColumn(), getFilterRole() and getFilterRegExp().

You may want to reimplement this method to provide specialized filtering.

lessThan

protected boolean lessThan(WModelIndex lhs,
                           WModelIndex rhs)

Compares two indexes.

The default implementation uses getSortRole() and an ordering using the operator< when the data is of the same type or compares lexicographically otherwise.

You may want to reimplement this method to provide specialized sorting.