#include <Wt/WAbstractItemModel>
Public Member Functions | |
WAbstractItemModel (WObject *parent=0) | |
Create a new data model. | |
virtual | ~WAbstractItemModel () |
Destructor. | |
virtual int | columnCount (const WModelIndex &parent=WModelIndex()) const =0 |
Returns the number of columns. | |
virtual int | rowCount (const WModelIndex &parent=WModelIndex()) const =0 |
Returns the number of rows. | |
virtual int | flags (const WModelIndex &index) const |
Returns the flags for an item. | |
virtual bool | hasChildren (const WModelIndex &index) const |
Returns if there are children at an index. | |
virtual WModelIndex | parent (const WModelIndex &index) const =0 |
Returns the parent for a model index. | |
virtual boost::any | data (const WModelIndex &index, int role=DisplayRole) const =0 |
Returns data at a specific model index. | |
virtual std::map< int, boost::any > | itemData (const WModelIndex &index) const |
Returns all data at a specific index. | |
virtual boost::any | headerData (int section, Orientation orientation=Horizontal, int role=DisplayRole) const |
Returns the row or column header data. | |
virtual WModelIndex | index (int row, int column, const WModelIndex &parent=WModelIndex()) const =0 |
Returns the child index for the given row and column. | |
virtual WModelIndexList | match (const WModelIndex &start, int role, const boost::any &value, int hits=-1, MatchFlags flags=MatchFlags(MatchStartsWith|MatchWrap)) const |
Returns an index list for data items that match. | |
boost::any | data (int row, int column, int role=DisplayRole, const WModelIndex &parent=WModelIndex()) const |
Returns the data item at the given column and row. | |
virtual bool | hasIndex (int row, int column, const WModelIndex &parent=WModelIndex()) const |
Returns if an index at the given position is valid (i.e. falls within the column-row bounds). | |
virtual bool | insertColumns (int column, int count, const WModelIndex &parent=WModelIndex()) |
Insert one or more columns. | |
virtual bool | insertRows (int row, int count, const WModelIndex &parent=WModelIndex()) |
Insert one or more rows. | |
virtual bool | removeColumns (int column, int count, const WModelIndex &parent=WModelIndex()) |
Remove columns. | |
virtual bool | removeRows (int row, int count, const WModelIndex &parent=WModelIndex()) |
Remove rows. | |
virtual bool | setData (const WModelIndex &index, const boost::any &value, int role=EditRole) |
Set data at the given model index. | |
virtual bool | setItemData (const WModelIndex &index, const std::map< int, boost::any > &values) |
Set data at the given model index. | |
virtual bool | setHeaderData (int section, Orientation orientation, const boost::any &value, int role=EditRole) |
Set header data for a column or row. | |
bool | setHeaderData (int section, const boost::any &value) |
Set column header data (deprecated). | |
virtual void | sort (int column, SortOrder order=AscendingOrder) |
Sort the model according to a particular column. | |
virtual void * | toRawIndex (const WModelIndex &index) const |
Convert a model index to a raw pointer that remains valid while the model's layout is changed. | |
virtual WModelIndex | fromRawIndex (void *rawIndex) const |
Convert a raw pointer to a model index. | |
virtual std::string | mimeType () const |
Returns a mime-type for dragging a set of indexes. | |
virtual std::vector< std::string > | acceptDropMimeTypes () const |
Returns a list of mime-types that could be accepted for a drop event. | |
virtual void | dropEvent (const WDropEvent &e, DropAction action, int row, int column, const WModelIndex &parent) |
Handle a drop event. | |
bool | insertColumn (int column, const WModelIndex &parent=WModelIndex()) |
Insert one column. | |
bool | insertRow (int row, const WModelIndex &parent=WModelIndex()) |
Insert one row. | |
bool | removeColumn (int column, const WModelIndex &parent=WModelIndex()) |
Remove one column. | |
bool | removeRow (int row, const WModelIndex &parent=WModelIndex()) |
Remove one row. | |
bool | setData (int row, int column, const boost::any &value, int role=EditRole, const WModelIndex &parent=WModelIndex()) |
Set data at the given row and column. | |
Public Attributes | |
Signal< WModelIndex, int, int > | columnsAboutToBeInserted |
Signal emitted before a number of columns will be inserted. | |
Signal< WModelIndex, int, int > | columnsAboutToBeRemoved |
Signal emitted before a number of columns will be removed. | |
Signal< WModelIndex, int, int > | columnsInserted |
Signal emitted after a number of columns were inserted. | |
Signal< WModelIndex, int, int > | columnsRemoved |
Signal emitted after a number of columns were removed. | |
Signal< WModelIndex, int, int > | rowsAboutToBeInserted |
Signal emitted before a number of rows will be inserted. | |
Signal< WModelIndex, int, int > | rowsAboutToBeRemoved |
Signal emitted before a number of rows will be removed. | |
Signal< WModelIndex, int, int > | rowsInserted |
Signal emitted after a number of rows were inserted. | |
Signal< WModelIndex, int, int > | rowsRemoved |
Signal emitted after a number of rows were removed. | |
Signal< WModelIndex, WModelIndex > | dataChanged |
Signal emitted when some data was changed. | |
Signal< Orientation, int, int > | headerDataChanged |
Signal emitted when some header data was changed. | |
Signal | layoutAboutToBeChanged |
Signal emitted when the layout is about to be changed. | |
Signal | layoutChanged |
Signal emitted when the layout is changed. | |
Protected Member Functions | |
WModelIndex | createIndex (int row, int column, void *ptr) const |
Create a model index for the given row and column. | |
WModelIndex | createIndex (int row, int column, uint64_t id) const |
Create a model index for the given row and column. | |
WModelIndex | createIndex (int row, int column, const Sha1::Digest &hashId) const |
Create a model index for the given row and column. | |
void | beginInsertColumns (const WModelIndex &parent, int first, int last) |
Method to be called before inserting columns. | |
void | beginInsertRows (const WModelIndex &parent, int first, int last) |
Method to be called before inserting rows. | |
void | beginRemoveColumns (const WModelIndex &parent, int first, int last) |
Method to be called before removing columns. | |
void | beginRemoveRows (const WModelIndex &parent, int first, int last) |
Method to be called before removing rows. | |
void | endInsertColumns () |
Method to be called after inserting columns. | |
void | endInsertRows () |
Method to be called after inserting rows. | |
void | endRemoveColumns () |
Method to be called after removing columns. | |
void | endRemoveRows () |
Method to be called after removing rows. | |
Related Functions | |
(Note that these are not member functions.) | |
WT_API WString | asString (const boost::any &v, const WString &formatString=WString::emptyString) |
Interpret a boost::any as a string value. | |
WT_API double | asNumber (const boost::any &v) |
Interpret a boost::any as a number value. |
This abstract model is used by several Wt view widgets (WComboBox, WSelectionBox, WTreeView, Ext::ComboBox, and Ext::TableView) as data models.
In general, it organizes data in a hierarchical structure of tables, where every item stores data and optionally a nested table of data. Every data item is at a particular row and column of a parent item, and items may be referenced using the helper class WModelIndex. Top level data have an invalid parent WModelIndex.
Column header data may also be specified, for each top-level column.
The data itself is of type boost::any, which can either be empty, or hold any of the following type of data:
Conversion between native types and boost::any is done like this:
boost::any a = boost::any(v);For example:
WDate d(1976,6,14); model->setData(row, column, boost::any(d));
Type v = boost::any_cast<Type>(a);For example:
WDate d = boost::any_cast<WDate>(model->data(row, column));
if (!a.empty()) { ... }
if (a.type() == typeid(double)) { ... }
In addition, there are a number of utility functions that try to interpret a boost::any value as a string (asString()) or number (asNumber()).
To implement a custom model, you need to reimplement the following methods:
A crucial point in implementing a hierarchial model is to decide how to reference an index in terms of an internal pointer (WModelIndex::internalPointer()) or internal id (WModelIndex::internalId()). Other than the top-level index, which is special since it is referenced using an invalid index), every index with children must be identifiable using this number or pointer. For example, in the WStandardItemModel, the internal pointer points to the parent WStandardItem. For table models, the internal pointer plays no role, since only the toplevel index has children.
If you want to support editing of the model, then you also need to reimplement:
After data was modified, the model must emit the dataChanged signal.
Finally, if you want to support insertion of new data or removal of data (changing the geometry) by any of the view classes, then you need to reimplement the following methods:
Alternatively, you can provide your own API for changing the model. In either case it is important that you call the corresponding protected member functions which will emit the relevant signals so that views can adapt themselves to the new geometry.
virtual int Wt::WAbstractItemModel::columnCount | ( | const WModelIndex & | parent = WModelIndex() |
) | const [pure virtual] |
Returns the number of columns.
This returns the number of columns at index parent.
Implemented in Wt::WAbstractListModel, and Wt::WSortFilterProxyModel.
virtual int Wt::WAbstractItemModel::rowCount | ( | const WModelIndex & | parent = WModelIndex() |
) | const [pure virtual] |
Returns the number of rows.
This returns the number of rows at index parent.
Implemented in Wt::WSortFilterProxyModel, and Wt::WStringListModel.
int Wt::WAbstractItemModel::flags | ( | const WModelIndex & | index | ) | const [virtual] |
Returns the flags for an item.
The default implementation returns ItemIsSelectable.
Reimplemented in Wt::WAbstractProxyModel, and Wt::WStringListModel.
bool Wt::WAbstractItemModel::hasChildren | ( | const WModelIndex & | index | ) | const [virtual] |
Returns if there are children at an index.
Returns true when rowCount(index) > 0 and columnCount(index) > 0.
virtual WModelIndex Wt::WAbstractItemModel::parent | ( | const WModelIndex & | index | ) | const [pure virtual] |
Returns the parent for a model index.
You should use createIndex() to create a model index that corresponds to the parent of a given index.
Implemented in Wt::WAbstractListModel, and Wt::WSortFilterProxyModel.
virtual boost::any Wt::WAbstractItemModel::data | ( | const WModelIndex & | index, | |
int | role = DisplayRole | |||
) | const [pure virtual] |
Returns data at a specific model index.
Return data for a given role at a given index.
Implemented in Wt::WAbstractProxyModel, and Wt::WStringListModel.
std::map< int, boost::any > Wt::WAbstractItemModel::itemData | ( | const WModelIndex & | index | ) | const [virtual] |
Returns all data at a specific index.
This is a convenience function that returns a map with data corresponding to all standard roles.
boost::any Wt::WAbstractItemModel::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.
Reimplemented in Wt::WAbstractProxyModel.
virtual WModelIndex Wt::WAbstractItemModel::index | ( | int | row, | |
int | column, | |||
const WModelIndex & | parent = WModelIndex() | |||
) | const [pure 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.
Implemented in Wt::WAbstractListModel, and Wt::WSortFilterProxyModel.
WModelIndexList Wt::WAbstractItemModel::match | ( | const WModelIndex & | start, | |
int | role, | |||
const boost::any & | value, | |||
int | hits = -1 , |
|||
MatchFlags | flags = MatchFlags(MatchStartsWith | MatchWrap) | |||
) | const [virtual] |
Returns an index list for data items that match.
Returns an index list of data items that match, starting at start, and searching further in that column. If flags specifes MatchWrap then the search wraps around from the start. If hits is not -1, then at most that number of hits are returned.
boost::any Wt::WAbstractItemModel::data | ( | int | row, | |
int | column, | |||
int | role = DisplayRole , |
|||
const WModelIndex & | parent = WModelIndex() | |||
) | const |
bool Wt::WAbstractItemModel::hasIndex | ( | int | row, | |
int | column, | |||
const WModelIndex & | parent = WModelIndex() | |||
) | const [virtual] |
Returns if an index at the given position is valid (i.e. falls within the column-row bounds).
Equivalent to:
return row >= 0 && column >= 0 && row < rowCount(parent) && column < columnCount(parent);
bool Wt::WAbstractItemModel::insertColumns | ( | int | column, | |
int | count, | |||
const WModelIndex & | parent = WModelIndex() | |||
) | [virtual] |
Insert one or more columns.
Returns true if the operation was successful.
The default implementation returns false. If you reimplement this method, then you must call beginInsertColumns() and endInsertColumns() before and after the operation.
Reimplemented in Wt::WAbstractProxyModel.
bool Wt::WAbstractItemModel::insertRows | ( | int | row, | |
int | count, | |||
const WModelIndex & | parent = WModelIndex() | |||
) | [virtual] |
Insert one or more rows.
Returns true if the operation was successful. If you reimplement this method, then you must call beginInsertRows() and endInsertRows() before and after the operation.
The default implementation returns false.
Reimplemented in Wt::WAbstractProxyModel, and Wt::WStringListModel.
bool Wt::WAbstractItemModel::removeColumns | ( | int | column, | |
int | count, | |||
const WModelIndex & | parent = WModelIndex() | |||
) | [virtual] |
Remove columns.
Returns true if the operation was successful.
The default implementation returns false. If you reimplement this method, then you must call beginRemoveColumns() and endRemoveColumns() before and after the operation.
Reimplemented in Wt::WAbstractProxyModel.
bool Wt::WAbstractItemModel::removeRows | ( | int | row, | |
int | count, | |||
const WModelIndex & | parent = WModelIndex() | |||
) | [virtual] |
Remove rows.
Returns true if the operation was successful.
The default implementation returns false. If you reimplement this method, then you must call beginRemoveRows() and endRemoveRows() before and after the operation.
Reimplemented in Wt::WAbstractProxyModel, and Wt::WStringListModel.
bool Wt::WAbstractItemModel::setData | ( | const WModelIndex & | index, | |
const boost::any & | value, | |||
int | role = EditRole | |||
) | [virtual] |
Set data at the given model index.
Returns true if the operation was successful.
The default implementation returns false. If you reimplement this method, you must emit the the dataChanged signal after data was changed.
Reimplemented in Wt::WAbstractProxyModel, and Wt::WStringListModel.
bool Wt::WAbstractItemModel::setItemData | ( | const WModelIndex & | index, | |
const std::map< int, boost::any > & | values | |||
) | [virtual] |
Set data at the given model index.
This is a convenience function that sets data for all roles at once.
bool Wt::WAbstractItemModel::setHeaderData | ( | int | section, | |
Orientation | orientation, | |||
const boost::any & | value, | |||
int | role = EditRole | |||
) | [virtual] |
Set header data for a column or row.
Returns true if the operation was successful.
Reimplemented in Wt::WAbstractProxyModel.
bool Wt::WAbstractItemModel::setHeaderData | ( | int | section, | |
const boost::any & | value | |||
) |
Set column header data (deprecated).
Returns true if the operation was successful.
void Wt::WAbstractItemModel::sort | ( | int | column, | |
SortOrder | order = AscendingOrder | |||
) | [virtual] |
Sort 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.
Reimplemented in Wt::WSortFilterProxyModel, Wt::WStandardItemModel, and Wt::WStringListModel.
void * Wt::WAbstractItemModel::toRawIndex | ( | const WModelIndex & | index | ) | const [virtual] |
Convert a model index to a raw pointer that remains valid while the model's layout is changed.
Use this method to temporarily save model indexes while the model's layout is changed by for example a sorting operation.
The default implementation returns 0, which indicates that the index cannot be converted to a raw pointer. If you reimplement this method, you also need to reimplemnt fromRawIndex().
Reimplemented in Wt::WAbstractProxyModel.
WModelIndex Wt::WAbstractItemModel::fromRawIndex | ( | void * | rawIndex | ) | const [virtual] |
Convert a raw pointer to a model index.
Use this method to create model index from temporary raw pointers. It is the reciproce method of toRawIndex().
You can return an invalid modelindex if the rawIndex no longer points to a valid item because of the layout change.
Reimplemented in Wt::WAbstractProxyModel.
std::string Wt::WAbstractItemModel::mimeType | ( | ) | const [virtual] |
Returns a mime-type for dragging a set of indexes.
This method returns a mime-type that describes dragging of a selection of items.
The drop event will indicate a selection model for this abstract item model as source.
The default implementation returns a mime-type for generic drag&drop support between abstract item models.
Reimplemented in Wt::WAbstractProxyModel.
std::vector< std::string > Wt::WAbstractItemModel::acceptDropMimeTypes | ( | ) | const [virtual] |
Returns a list of mime-types that could be accepted for a drop event.
The default implementation only accepts drag&drop support between abstract item models.
Reimplemented in Wt::WAbstractProxyModel.
void Wt::WAbstractItemModel::dropEvent | ( | const WDropEvent & | e, | |
DropAction | action, | |||
int | row, | |||
int | column, | |||
const WModelIndex & | parent | |||
) | [virtual] |
Handle a drop event.
The default implementation only handles generic drag&drop between abstract item models. Source item data is copied (but not the source item's flags).
The location in the model is indicated by the row and column within the parent index. If row is -1, then the item is appended to the parent. Otherwise, the item is inserted at or copied over the indicated item (and subsequent rows). When action is a MoveAction, the original items are deleted from the source model.
You may want to reimplement this method if you want to handle other mime-type data, or if you want to refine how the drop event of an item selection must be interpreted.
Reimplemented in Wt::WAbstractProxyModel.
bool Wt::WAbstractItemModel::insertColumn | ( | int | column, | |
const WModelIndex & | parent = WModelIndex() | |||
) |
Insert one column.
This is a convenience method that adds a single column, and is equivalent to:
insertColumns(column, 1, parent);
Returns true if the operation was successful.
bool Wt::WAbstractItemModel::insertRow | ( | int | row, | |
const WModelIndex & | parent = WModelIndex() | |||
) |
Insert one row.
This is a convenience method that adds a single row, and is equivalent to:
insertRows(row, 1, parent);
Returns true if the operation was successful.
bool Wt::WAbstractItemModel::removeColumn | ( | int | column, | |
const WModelIndex & | parent = WModelIndex() | |||
) |
Remove one column.
This is a convenience method that removes a single column, and is equivalent to:
removeColumns(column, 1, parent);
Returns true if the operation was successful.
bool Wt::WAbstractItemModel::removeRow | ( | int | row, | |
const WModelIndex & | parent = WModelIndex() | |||
) |
Remove one row.
This is a convenience method that removes a single row, and is equivalent to:
removeRows(row, 1, parent);
Returns true if the operation was successful.
bool Wt::WAbstractItemModel::setData | ( | int | row, | |
int | column, | |||
const boost::any & | value, | |||
int | role = EditRole , |
|||
const WModelIndex & | parent = WModelIndex() | |||
) |
WModelIndex Wt::WAbstractItemModel::createIndex | ( | int | row, | |
int | column, | |||
void * | ptr | |||
) | const [protected] |
Create a model index for the given row and column.
Use this method to create a model index. ptr is an internal pointer that may be used to associate the index with particular model data.
WModelIndex Wt::WAbstractItemModel::createIndex | ( | int | row, | |
int | column, | |||
uint64_t | id | |||
) | const [protected] |
Create a model index for the given row and column.
Use this method to create a model index. id is an internal id that may be used to associate the index with particular model data.
WModelIndex Wt::WAbstractItemModel::createIndex | ( | int | row, | |
int | column, | |||
const Sha1::Digest & | hashId | |||
) | const [protected] |
Create a model index for the given row and column.
Use this method to create a model index. hashId is an internal id (of 20 bytes, long enough to hold a SHA-1 digest) that may be used to associate the index with particular model data.
Using a long internal id may be useful for models that wish to keep all of their data on disk or in a database (but not in memory).
void Wt::WAbstractItemModel::beginInsertColumns | ( | const WModelIndex & | parent, | |
int | first, | |||
int | last | |||
) | [protected] |
Method to be called before inserting columns.
If your model supports insertion of columns, then you should call this method before inserting one or more columns, and endInsertColumns() afterwards. These methods emit the necessary signals to allow view classes to update themselves.
void Wt::WAbstractItemModel::beginInsertRows | ( | const WModelIndex & | parent, | |
int | first, | |||
int | last | |||
) | [protected] |
Method to be called before inserting rows.
If your model supports insertion of rows, then you should call this method before inserting one or more rows, and endInsertRows() afterwards. These methods emit the necessary signals to allow view classes to update themselves.
void Wt::WAbstractItemModel::beginRemoveColumns | ( | const WModelIndex & | parent, | |
int | first, | |||
int | last | |||
) | [protected] |
Method to be called before removing columns.
If your model supports removal of columns, then you should call this method before removing one or more columns, and endRemoveColumns() afterwards. These methods emit the necessary signals to allow view classes to update themselves.
void Wt::WAbstractItemModel::beginRemoveRows | ( | const WModelIndex & | parent, | |
int | first, | |||
int | last | |||
) | [protected] |
Method to be called before removing rows.
If your model supports removal of rows, then you should call this method before removing one or more rows, and endRemoveRows() afterwards. These methods emit the necessary signals to allow view classes to update themselves.
void Wt::WAbstractItemModel::endInsertColumns | ( | ) | [protected] |
void Wt::WAbstractItemModel::endInsertRows | ( | ) | [protected] |
void Wt::WAbstractItemModel::endRemoveColumns | ( | ) | [protected] |
void Wt::WAbstractItemModel::endRemoveRows | ( | ) | [protected] |
WT_API WString asString | ( | const boost::any & | v, | |
const WString & | formatString = WString::emptyString | |||
) | [related] |
Interpret a boost::any as a string value.
The conversion works as follows:
WT_API double asNumber | ( | const boost::any & | v | ) | [related] |
Interpret a boost::any as a number value.
A boost::any without a value, or a string that does not represent a number, is converted to a "NaN". You can check for this value using the libc function isnan(). A WDate is converted to an integer number using the WDate::modifiedJulianDay() method.
Signal emitted before a number of columns will be inserted.
The first argument is the parent index. The two integer arguments are the column numbers that the first and last column will have when inserted.
Signal emitted before a number of columns will be removed.
The first argument is the parent index. The two integer arguments are the column numbers of the first and last column that will be removed.
Signal emitted after a number of columns were inserted.
The first argument is the parent index. The two integer arguments are the column numbers of the first and last column that were inserted.
Signal emitted after a number of columns were removed.
The first argument is the parent index. The two integer arguments are the column numbers of the first and last column that were removed.
Signal emitted before a number of rows will be inserted.
The first argument is the parent index. The two integer arguments are the row numbers that the first and last row will have when inserted.
Signal emitted before a number of rows will be removed.
The first argument is the parent index. The two integer arguments are the row numbers of the first and last row that will be removed.
Signal emitted after a number of rows were inserted.
The first argument is the parent index. The two integer arguments are the row numbers of the first and last row that were inserted.
Signal<WModelIndex, int, int> Wt::WAbstractItemModel::rowsRemoved |
Signal emitted after a number of rows were removed.
The first argument is the parent index. The two integer arguments are the row numbers of the first and last row that were removed.
Signal emitted when some data was changed.
The two arguments are the model indexes of the top-left and bottom-right data items that span the rectangle of changed data items.
Signal emitted when some header data was changed.
The first argument indicates the orientation of the header, and the two integer arguments are the row or column numbers of the first and last header item of which the value was changed.
Signal emitted when the layout is about to be changed.
A layout change reorders the data in the model, but no data is added or removed. Model indexes are invalidated by a layout change, but indexes may be ported across a layout change by using the toRawIndex() and fromRawIndex() methods.