Wt: Wt::WSortFilterProxyModel Class Reference

Wt 3.3.0

- Main Page
- Related Pages
- Modules
- Namespaces
- Classes

- Class List
- Class Hierarchy
- Class Members

Public Member Functions | Protected Member Functions
Wt::WSortFilterProxyModel Class Reference
Model/view system

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

`#include <Wt/WSortFilterProxyModel>`

Inheritance diagram for Wt::WSortFilterProxyModel:
[legend]

List of all members.

## Public Member Functions
| WSortFilterProxyModel (WObject *parent=0)
| Constructor.
virtual | ~WSortFilterProxyModel ()
| Destructor.
virtual WModelIndex | mapFromSource (const WModelIndex &sourceIndex) const
| Maps a source model index to the proxy model.
virtual WModelIndex | mapToSource (const WModelIndex &proxyIndex) const
| Maps a proxy model index to the source model.
virtual void | setSourceModel (WAbstractItemModel *sourceModel)
| Sets the source model.
void | setFilterKeyColumn (int column)
| Specify the column on which the filtering is applied.
int | filterKeyColumn () const
| Return the column on which the filtering is applied.
void | setFilterRegExp (const WString &pattern)
| Specify a regular expression for filtering.
WString | filterRegExp () const
| Return the regular expression used for filtering.
void | setFilterFlags (WFlags< RegExpFlag > flags)
| Sets the filter regular expression flags.
WFlags< RegExpFlag > | filterFlags () const
| Returns the filter regular expression flags.
void | setFilterRole (int role)
| Specify the data role used for filtering.
int | filterRole () const
| Return the data role used for filtering.
void | setSortRole (int role)
| Specify the data role used used for sorting.
int | sortRole () const
| Return the data role used for sorting.
int | sortColumn () const
| Returns the current sort column.
SortOrder | sortOrder () const
| Returns the current sort order.
void | setDynamicSortFilter (bool enable)
| Configure the proxy to dynamically track changes in the source model.
bool | dynamicSortFilter () const
| Returns whether this proxy dynmically filters and sorts.
virtual int | columnCount (const WModelIndex &parent=WModelIndex()) const
| Returns the number of columns.
virtual int | rowCount (const WModelIndex &parent=WModelIndex()) const
| Returns the number of rows.
virtual WModelIndex | parent (const WModelIndex &index) const
| Returns the parent for a model index.
virtual WModelIndex | index (int row, int column, const WModelIndex &parent=WModelIndex()) const
| Returns the child index for the given row and column.
virtual bool | setHeaderData (int section, Orientation orientation, const boost::any &value, int role=EditRole)
| Sets header data for a column or row.
virtual boost::any | headerData (int section, Orientation orientation=Horizontal, int role=DisplayRole) const
| Returns the row or column header data.
virtual WFlags< HeaderFlag > | headerFlags (int section, Orientation orientation=Horizontal) const
| Returns the flags for a header.
virtual bool | insertRows (int row, int count, const WModelIndex &parent=WModelIndex())
| Inserts a number rows.
virtual bool | removeRows (int row, int count, const WModelIndex &parent=WModelIndex())
| Removes a number rows.
virtual void | sort (int column, SortOrder order=AscendingOrder)
| Sorts the model according to a particular column.
## Protected Member Functions
virtual bool | filterAcceptRow (int sourceRow, const WModelIndex &sourceParent) const
| Returns whether a source row is accepted by the filter.
virtual bool | lessThan (const WModelIndex &lhs, const WModelIndex &rhs) const
| Compares two indexes.

## Detailed Description

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 WAbstractProxyModel::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
     Wt::WAbstractItemModel *model = ...

     // we setup a proxy to filter the source model
     Wt::WSortFilterProxyModel *proxy = new Wt::WSortFilterProxyModel(this);
     proxy->setSourceModel(model);
     proxy->setDynamicSortFilter(true);
     proxy->setFilterKeyColumn(0);
     proxy->setFilterRole(Wt::UserRole);
     proxy->setFilterRegExp("Wt::.*");

     // configure a view to use the proxy model instead of the source model
     Wt::WTreeView *view = new Wt::WTreeView(this);
     view->setModel(proxy);
     ...

## Member Function Documentation

int Wt::WSortFilterProxyModel::columnCount | ( | const WModelIndex & | parent = `WModelIndex()` | ) | const`[virtual]`

Returns the number of columns.

This returns the number of columns at index `parent`.

See also:
  rowCount()

Implements Wt::WAbstractItemModel.

bool Wt::WSortFilterProxyModel::dynamicSortFilter | ( |  | ) | const

Returns whether this proxy dynmically filters and sorts.

See also:
  setDynamicSortFilter()

bool Wt::WSortFilterProxyModel::filterAcceptRow | ( | int | sourceRow,
|  | const WModelIndex & | sourceParent
| ) |  | const`[protected, virtual]`

Returns whether a source row is accepted by the filter.

The default implementation uses filterKeyColumn(), filterRole() and filterRegExp().

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

int Wt::WSortFilterProxyModel::filterKeyColumn | ( |  | ) | const

Return the column on which the filtering is applied.

See also:
  setFilterKeyColumn()

WString Wt::WSortFilterProxyModel::filterRegExp | ( |  | ) | const

Return the regular expression used for filtering.

See also:
  setFilterRegExp()

int Wt::WSortFilterProxyModel::filterRole | ( |  | ) | const

Return the data role used for filtering.

See also:
  setFilterRole()

boost::any Wt::WSortFilterProxyModel::headerData | ( | int | section,
|  | Orientation | orientation = `Horizontal`,
|  | int | role = `DisplayRole`
| ) |  | const`[virtual]`

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.

See also:
  data(), setHeaderData()

Reimplemented from Wt::WAbstractItemModel.

WFlags< HeaderFlag > Wt::WSortFilterProxyModel::headerFlags | ( | int | section,
|  | Orientation | orientation = `Horizontal`
| ) |  | const`[virtual]`

Returns the flags for a header.

The default implementation returns no flags set.

See also:
  Wt::HeaderFlag

Reimplemented from Wt::WAbstractItemModel.

WModelIndex Wt::WSortFilterProxyModel::index | ( | int | row,
|  | int | column,
|  | const WModelIndex & | parent = `WModelIndex()`
| ) |  | const`[virtual]`

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.

See also:
  parent()

Implements Wt::WAbstractItemModel.

bool Wt::WSortFilterProxyModel::insertRows | ( | int | row,
|  | int | count,
|  | const WModelIndex & | parent = `WModelIndex()`
| ) |  | `[virtual]`

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.

Reimplemented from Wt::WAbstractItemModel.

bool Wt::WSortFilterProxyModel::lessThan | ( | const WModelIndex & | lhs,
|  | const WModelIndex & | rhs
| ) |  | const`[protected, virtual]`

Compares two indexes.

The default implementation uses sortRole() 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.

WModelIndex Wt::WSortFilterProxyModel::mapFromSource | ( | const WModelIndex & | sourceIndex | ) | const`[virtual]`

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().

See also:
  mapToSource()

Implements Wt::WAbstractProxyModel.

WModelIndex Wt::WSortFilterProxyModel::mapToSource | ( | const WModelIndex & | proxyIndex | ) | const`[virtual]`

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`.

See also:
  mapFromSource()

Implements Wt::WAbstractProxyModel.

WModelIndex Wt::WSortFilterProxyModel::parent | ( | const WModelIndex & | index | ) | const`[virtual]`

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::internalPointer()) 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.

See also:
  index()

Implements Wt::WAbstractItemModel.

bool Wt::WSortFilterProxyModel::removeRows | ( | int | row,
|  | int | count,
|  | const WModelIndex & | parent = `WModelIndex()`
| ) |  | `[virtual]`

Removes a number rows.

The rows are removed from the source model.

Reimplemented from Wt::WAbstractItemModel.

int Wt::WSortFilterProxyModel::rowCount | ( | const WModelIndex & | parent = `WModelIndex()` | ) | const`[virtual]`

Returns the number of rows.

This returns the number of rows at index `parent`.

See also:
  columnCount()

Implements Wt::WAbstractItemModel.

void Wt::WSortFilterProxyModel::setDynamicSortFilter | ( | bool | 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()

void Wt::WSortFilterProxyModel::setFilterKeyColumn | ( | int | column | ) |

Specify the column on which the filtering is applied.

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

The default value is 0.

See also:
  setFilterRegExp(), setFilterRole()

void Wt::WSortFilterProxyModel::setFilterRegExp | ( | const WString & | pattern | ) |

Specify a regular expression for filtering.

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

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

See also:
  setFilterKeyColumn(), setFilterRole()

void Wt::WSortFilterProxyModel::setFilterRole | ( | int | role | ) |

Specify the data role used for filtering.

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

The default value is DisplayRole.

See also:
  setFilterKeyColumn(), setFilterRegExp()

bool Wt::WSortFilterProxyModel::setHeaderData | ( | int | section,
|  | Orientation | orientation,
|  | const boost::any & | value,
|  | int | role = `EditRole`
| ) |  | `[virtual]`

Sets header data for a column or row.

Returns `true` if the operation was successful.

See also:
  headerData()

Reimplemented from Wt::WAbstractItemModel.

void Wt::WSortFilterProxyModel::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()

void Wt::WSortFilterProxyModel::setSourceModel | ( | WAbstractItemModel * | sourceModel | ) | `[virtual]`

Sets the source model.

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

Ownership of the source model is not transferred.

Reimplemented from Wt::WAbstractProxyModel.

void Wt::WSortFilterProxyModel::sort | ( | int | column,
|  | SortOrder | order = `AscendingOrder`
| ) |  | `[virtual]`

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.

See also:
  layoutAboutToBeChanged(), layoutChanged()

Reimplemented from Wt::WAbstractItemModel.

int Wt::WSortFilterProxyModel::sortColumn | ( |  | ) | const

Returns the current sort column.

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

See also:
  sort()

SortOrder Wt::WSortFilterProxyModel::sortOrder | ( |  | ) | const

Returns the current sort order.

See also:
  sort()

int Wt::WSortFilterProxyModel::sortRole | ( |  | ) | const

Return the data role used for sorting.

See also:
  setSortRole()

All Classes Namespaces Functions Variables Typedefs Enumerations Enumerator