Wt: Wt::WStandardItemModel Class Reference

Wt 3.3.0

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

- Class List
- Class Hierarchy
- Class Members

Public Member Functions
Wt::WStandardItemModel Class Reference
Model/view system

A standard data model, which stores its data in memory. More...

`#include <Wt/WStandardItemModel>`

Inheritance diagram for Wt::WStandardItemModel:
[legend]

List of all members.

## Public Member Functions
| WStandardItemModel (WObject *parent=0)
| Creates a new standard item model.
| WStandardItemModel (int rows, int columns, WObject *parent=0)
| Creates a new standard item model with an initial geometry.
| ~WStandardItemModel ()
| Destructor.
void | clear ()
| Erases all data in the model.
WStandardItem * | invisibleRootItem () const
| Returns the invisible root item.
WModelIndex | indexFromItem (const WStandardItem *item) const
| Returns the model index for a particular item.
WStandardItem * | itemFromIndex (const WModelIndex &index) const
| Returns the standard item that corresponds to a model index.
void | appendColumn (const std::vector< WStandardItem * > &items)
| Adds a single column of top level items.
void | insertColumn (int column, const std::vector< WStandardItem * > &items)
| Inserts a single column of top level items.
void | appendRow (const std::vector< WStandardItem * > &items)
| Adds a single row of top level items.
void | insertRow (int row, const std::vector< WStandardItem * > &items)
| Inserts a single row of top level items.
void | appendRow (WStandardItem *item)
| Appends a single row containing a single item.
void | insertRow (int row, WStandardItem *item)
| Inserts a single row containing a single item.
WStandardItem * | item (int row, int column=0) const
| Returns a toplevel item.
void | setItem (int row, int column, WStandardItem *item)
| Sets a toplevel item.
WStandardItem * | itemPrototype () const
| Returns the item prototype.
void | setItemPrototype (WStandardItem *item)
| Sets the item prototype.
std::vector< WStandardItem * > | takeColumn (int column)
| Takes a column out of the model.
std::vector< WStandardItem * > | takeRow (int row)
| Takes a row out of the model.
WStandardItem * | takeItem (int row, int column=0)
| Takes an item out of the model.
void | setHeaderFlags (int section, Orientation orientation, WFlags< HeaderFlag > flags)
| Sets header flags.
void | setSortRole (int role)
| Set the role used to sort the model.
int | sortRole () const
| Returns the role used to sort the model.
virtual void | sort (int column, SortOrder order=AscendingOrder)
| Sorts the model according to a particular column.
Signal< WStandardItem * > & | itemChanged ()
| Signal emitted when an item is changed.

## Detailed Description

A standard data model, which stores its data in memory.

The standard item model supports all features of WAbstractItemModel, and can thus be used to represent tables, trees and tree tables.

The data itself are organized in WStandardItem objects. There is one invisible root object (invisibleRootItem()) that holds the toplevel data. Most methods in this class that access or manipulate data internally operate on this root item.

If you want to use the model as a table, then you can use WStandardItemModel(int, int, WObject *) to set the initial table size, and use the item() and setItem() methods to set data. You can change the geometry by inserting rows (insertRow()) or columns (insertColumn()) or removing rows (removeRow()) or columns (removeColumn()).

If you want to use the model as a tree (or tree table), then you can use the default constructor to start with an empty tree, and use the WStandardItem API on invisibleRootItem() to manipulate the tree root. When you are building a tree, the column count at each node is 1. When you are building a tree table, you can add additional columns of data for each internal node. Only the items in the first column have children that result in a hierarchical tree structure.

When using the model with a view class, you can use the itemFromIndex() and indexFromItem() models to translate between model indexes (that are used by the view class) and standard items.

Usage example for tabular data:

     int rows = 5;
     int columns = 4;

     Wt::WStandardItemModel *model = new Wt::WStandardItemModel(rows, columns, this);

     for (int row = 0; row < rows; ++row) {
       for (int column = 0; column < columns; ++column) {
         Wt::WStandardItem *item = new Wt::WStandardItem();
         item->setText("Item " + boost::lexical_cast<std::string>(row)
                       + ", " + boost::lexical_cast<std::string>(column));
         model->setItem(row, column, item);
       }
     }

Usage example for tree-like data:

     int topLevelRows = 5;
     int secondLevelRows = 7;

     Wt::WStandardItemModel *model = new Wt::WStandardItemModel();
     Wt::WStandardItem *root = model->invisibleRootItem();

     for (int row = 0; row < topLevelRows; ++row) {
       Wt::WStandardItem *topLevel = new Wt::WStandardItem();
       topLevel->setText("Item " + boost::lexical_cast<std::string>(row));
       for (int row2 = 0; row2 < secondLevelRows; ++row2) {
         Wt::WStandardItem *item = new Wt::WStandardItem();
         item->setText("Item " + boost::lexical_cast<std::string>(row)
                       + ": " + boost::lexical_cast<std::string>(row2));
         topLevel->appendRow(item);
       }
       root->appendRow(topLevel);
     }

## Constructor & Destructor Documentation

Wt::WStandardItemModel::WStandardItemModel | ( | int | rows,
|  | int | columns,
|  | WObject * | parent = `0`
| ) |  |

Creates a new standard item model with an initial geometry.

Creates a standard item model with a geometry of rows x `columns`. All items are set to `0`.

## Member Function Documentation

void Wt::WStandardItemModel::appendColumn | ( | const std::vector< WStandardItem * > & | items | ) |

Adds a single column of top level items.

Appends a single column of top level `items`. If necessary, the row count is increased.

Equivalent to:

     insertColumn(columnCount(), items);

See also:
  insertColumn(), appendRow()

void Wt::WStandardItemModel::appendRow | ( | const std::vector< WStandardItem * > & | items | ) |

Adds a single row of top level items.

Appends a single row of top level `items`. If necessary, the column count is increased.

Equivalent to:

     insertRow(rowCount(), items);

See also:
  insertRow(), appendColumn()

void Wt::WStandardItemModel::appendRow | ( | WStandardItem * | item | ) |

Appends a single row containing a single item.

Appends a single toplevel row, with a single item.

Equivalent to:

     insertRow(rowCount(), item);

See also:
  WStandardItem::insertRow(int, WStandardItem *)

void Wt::WStandardItemModel::clear | ( |  | ) |

Erases all data in the model.

After clearing the model, rowCount() and columnCount() are 0.

WModelIndex Wt::WStandardItemModel::indexFromItem | ( | const WStandardItem * | item | ) | const

Returns the model index for a particular item.

If the `item` is the invisibleRootItem(), then an invalid index is returned.

See also:
  itemFromIndex()

void Wt::WStandardItemModel::insertColumn | ( | int | column,
|  | const std::vector< WStandardItem * > & | items
| ) |  |

Inserts a single column of top level items.

Inserts a single column of top level `items` at column `column`. If necessary, the row count is increased.

Equivalent to:

     invisibleRootItem()->insertColumn(column, items);

See also:
  WStandardItem::insertColumn()

void Wt::WStandardItemModel::insertRow | ( | int | row,
|  | const std::vector< WStandardItem * > & | items
| ) |  |

Inserts a single row of top level items.

Inserts a single row of top level `items` at row `row`. If necessary, the column count is increased.

Equivalent to:

     invisibleRootItem()->insertRow(row, items);

See also:
  WStandardItem::insertRow()

void Wt::WStandardItemModel::insertRow | ( | int | row,
|  | WStandardItem * | item
| ) |  |

Inserts a single row containing a single item.

Inserts a single toplevel row, with a single item.

Equivalent to:

     invisibleRootItem()->insertRow(row, item);

See also:
  WStandardItem::insertRow(int, WStandardItem *)

WStandardItem* Wt::WStandardItemModel::invisibleRootItem | ( |  | ) | const

Returns the invisible root item.

The invisible root item is a special item that is not rendered itself, but holds the top level data.

WStandardItem* Wt::WStandardItemModel::item | ( | int | row,
|  | int | column = `0`
| ) |  | const

Returns a toplevel item.

Returns the top level at at (row, `column`). This may be 0 if no item was set previously at that position, or if the indicated position is out of bounds.

Equivalent to:

     invisibleRootItem()->child(row, column);

See also:
  WStandardItem::child()

Signal<WStandardItem *>& Wt::WStandardItemModel::itemChanged | ( |  | ) |

Signal emitted when an item is changed.

This signal is emitted whenever data for an item has changed. The item that has changed is passed as the first parameter.

See also:
  WStandardItem::setData()

WStandardItem* Wt::WStandardItemModel::itemFromIndex | ( | const WModelIndex & | index | ) | const

Returns the standard item that corresponds to a model index.

If the index is an invalid index, then the invisibleRootItem() is returned.

See also:
  indexFromItem()

WStandardItem* Wt::WStandardItemModel::itemPrototype | ( |  | ) | const

Returns the item prototype.

See also:
  setItemPrototype()

void Wt::WStandardItemModel::setHeaderFlags | ( | int | section,
|  | Orientation | orientation,
|  | WFlags< HeaderFlag > | flags
| ) |  |

Sets header flags.

By default, no flags are set.

void Wt::WStandardItemModel::setItem | ( | int | row,
|  | int | column,
|  | WStandardItem * | item
| ) |  |

Sets a toplevel item.

Sets the top level at at (row, `column`). If necessary, the number of rows or columns is increased.

If an item was previously set for that position, it is deleted first.

Equivalent to:

     invisibleRootItem()->setChild(row, column, item);

See also:
  WStandardItem::setChild(int, int, WStandardItem *item)

void Wt::WStandardItemModel::setItemPrototype | ( | WStandardItem * | item | ) |

Sets the item prototype.

Set the item that is cloned when an item needs to be created because the model is manipulated through its WAbstractItemModel API. For example, this may be needed when a view sets data at a position for which no item was previously set and thus created.

The new item is created based on this prototype by using WStandardItem::clone().

The default prototype is WStandardItem().

See also:
  setItemPrototype()

void Wt::WStandardItemModel::setSortRole | ( | int | role | ) |

Set the role used to sort the model.

The default role is DisplayRole.

See also:
  sort().

virtual void Wt::WStandardItemModel::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::WStandardItemModel::sortRole | ( |  | ) | const

Returns the role used to sort the model.

See also:
  setSortRole()

std::vector<WStandardItem *> Wt::WStandardItemModel::takeColumn | ( | int | column | ) |

Takes a column out of the model.

Removes a column from the model, and returns the items that it contained. Ownership of the items is transferred out of the model.

Equivalent to:

     invisibleRootItem()->takeColumn(column);

See also:
  WStandardItem::takeColumn(), WStandardItem::takeRow()

WStandardItem* Wt::WStandardItemModel::takeItem | ( | int | row,
|  | int | column = `0`
| ) |  |

Takes an item out of the model.

Removes an item from the model, and returns it. Ownership of the item is transferred out of the model.

Equivalent to:

     invisibleRootItem()->takeItem(row, column);

See also:
  takeItem(), WStandardItem::takeRow(), WStandardItem::takeColumn()

std::vector<WStandardItem *> Wt::WStandardItemModel::takeRow | ( | int | row | ) |

Takes a row out of the model.

Removes a row from the model, and returns the items that it contained. Ownership of the items is transferred out of the model.

Equivalent to:

     invisibleRootItem()->takeRow(row);

See also:
  WStandardItem::takeRow(), takeColumn()

All Classes Namespaces Functions Variables Typedefs Enumerations Enumerator