Class WStandardItemModel
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 (getInvisibleRootItem()
) 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()
to set the
initial table size, and use the getItem()
and setItem()
methods
to set data. You can change the geometry by inserting rows (insertRow()) or columns
(insertColumn()) or removing rows (WAbstractItemModel#removeRow()
) or columns (WAbstractItemModel#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 getInvisibleRootItem()
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 getItemFromIndex()
and indexFromItem()
models to translate between
model indexes (that are used by the view class) and standard items.
-
Nested Class Summary
Nested classes/interfaces inherited from class eu.webtoolkit.jwt.WObject
WObject.FormData
-
Constructor Summary
ConstructorDescriptionCreates a new standard item model.WStandardItemModel
(int rows, int columns) Creates a new standard item model with an initial geometry. -
Method Summary
Modifier and TypeMethodDescriptionvoid
appendColumn
(List<WStandardItem> items) Adds a single column of top level items.void
appendRow
(WStandardItem item) Appends a single row containing a single item.void
appendRow
(List<WStandardItem> items) Adds a single row of top level items.protected void
beginInsertColumns
(WModelIndex parent, int first, int last) Method to be called before inserting columns.protected void
beginInsertRows
(WModelIndex parent, int first, int last) Method to be called before inserting rows.protected void
beginRemoveColumns
(WModelIndex parent, int first, int last) Method to be called before removing columns.protected void
beginRemoveRows
(WModelIndex parent, int first, int last) Method to be called before removing rows.void
clear()
Erases all data in the model.protected void
copyData
(WModelIndex sIndex, WModelIndex dIndex) Copy data to an index in this model.void
dropEvent
(WDropEvent e, DropAction action, int row, int column, WModelIndex parent) Handles a drop event.fromRawIndex
(Object rawIndex) Converts a raw pointer to a model index.int
getColumnCount
(WModelIndex parent) Returns the number of columns.getData
(WModelIndex index, ItemDataRole role) Returns data at a specified model index for the given role.getFlags
(WModelIndex index) Returns the flags for an item.getHeaderData
(int section, Orientation orientation, ItemDataRole role) Returns the row or column header data.getHeaderFlags
(int section, Orientation orientation) Returns the flags for a header.getIndex
(int row, int column, WModelIndex parent) Returns the child index for the given row and column.Returns the invisible root item.final WStandardItem
getItem
(int row) Returns a toplevel item.getItem
(int row, int column) Returns a toplevel item.getItemFromIndex
(WModelIndex index) Returns the standard item that corresponds to a model index.Returns the item prototype.getParent
(WModelIndex index) Returns the parent for a model index.int
getRowCount
(WModelIndex parent) Returns the number of rows.Returns the role used to sort the model.indexFromItem
(WStandardItem item) Returns the model index for a particular item.void
insertColumn
(int column, List<WStandardItem> items) Inserts a single column of top level items.boolean
insertColumns
(int column, int count, WModelIndex parent) Inserts one or more columns.void
insertRow
(int row, WStandardItem item) Inserts a single row containing a single item.void
insertRow
(int row, List<WStandardItem> items) Inserts a single row of top level items.boolean
insertRows
(int row, int count, WModelIndex parent) Inserts one or more rows.Signal emitted when an item is changed.boolean
removeColumns
(int column, int count, WModelIndex parent) Removes columns.boolean
removeRows
(int row, int count, WModelIndex parent) Removes rows.boolean
setData
(WModelIndex index, Object value, ItemDataRole role) Sets data at the given model index.boolean
setHeaderData
(int section, Orientation orientation, Object value, ItemDataRole role) Sets header data for a column or row.final void
setHeaderFlags
(int section, Orientation orientation, HeaderFlag flag, HeaderFlag... flags) Sets header flags.void
setHeaderFlags
(int section, Orientation orientation, EnumSet<HeaderFlag> flags) Sets header flags.void
setItem
(int row, int column, WStandardItem item) Sets a toplevel item.void
Sets the item prototype.void
setSortRole
(ItemDataRole role) Set the role used to sort the model.void
Sorts the model according to a particular column.takeColumn
(int column) Takes a column out of the model.final WStandardItem
takeItem
(int row) Takes an item out of the model.takeItem
(int row, int column) Takes an item out of the model.takeRow
(int row) Takes a row out of the model.toRawIndex
(WModelIndex index) Converts a model index to a raw pointer that remains valid while the model's layout is changed.Methods inherited from class eu.webtoolkit.jwt.WAbstractItemModel
collapseColumn, columnsAboutToBeInserted, columnsAboutToBeRemoved, columnsInserted, columnsRemoved, createIndex, createIndex, dataChanged, dropEvent, endInsertColumns, endInsertRows, endRemoveColumns, endRemoveRows, expandColumn, getAcceptDropMimeTypes, getColumnCount, getData, getData, getData, getData, getHeaderData, getHeaderData, getHeaderFlags, getIndex, getItemData, getMimeType, 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
getId, getObjectName, remove, setFormData, setObjectName, tr
-
Constructor Details
-
WStandardItemModel
public WStandardItemModel()Creates a new standard item model. -
WStandardItemModel
public WStandardItemModel(int rows, int columns) 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 tonull
.
-
-
Method Details
-
clear
public void clear()Erases all data in the model.After clearing the model,
WAbstractItemModel#getRowCount()
andWAbstractItemModel#getColumnCount()
are 0. -
getInvisibleRootItem
Returns the invisible root item.The invisible root item is a special item that is not rendered itself, but holds the top level data.
-
indexFromItem
Returns the model index for a particular item.If the
item
is thegetInvisibleRootItem()
, then an invalid index is returned.- See Also:
-
getItemFromIndex
Returns the standard item that corresponds to a model index.If the index is an invalid index, then the
getInvisibleRootItem()
is returned.- See Also:
-
appendColumn
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(), std::move(items));
- See Also:
-
insertColumn
Inserts a single column of top level items.Inserts a single column of top level
items
at columncolumn
. If necessary, the row count is increased.Equivalent to:
invisibleRootItem().insertColumn(column, std::move(items));
-
appendRow
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(), std::move(items));
- See Also:
-
insertRow
Inserts a single row of top level items.Inserts a single row of top level
items
at rowrow
. If necessary, the column count is increased.Equivalent to:
invisibleRootItem().insertRow(row, std::move(items));
-
appendRow
Appends a single row containing a single item.Appends a single toplevel row, with a single item.
Equivalent to:
insertRow(rowCount(), std::move(item));
-
insertRow
Inserts a single row containing a single item.Inserts a single toplevel row, with a single item.
Equivalent to:
invisibleRootItem().insertRow(row, std::move(item));
-
getItem
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);
-
getItem
Returns a toplevel item.Returns
getItem(row, 0)
-
setItem
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, std::move(item));
-
getItemPrototype
Returns the item prototype.- See Also:
-
setItemPrototype
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:
-
takeColumn
Takes a column out of the model.Removes a column from the model, and returns the items that it contained.
Equivalent to:
invisibleRootItem().takeColumn(column);
-
takeRow
Takes a row out of the model.Removes a row from the model, and returns the items that it contained.
Equivalent to:
invisibleRootItem().takeRow(row);
-
takeItem
Takes an item out of the model.Removes an item from the model, and returns it.
Equivalent to:
invisibleRootItem().takeItem(row, column);
-
takeItem
Takes an item out of the model.Returns
takeItem(row, 0)
-
setHeaderFlags
Sets header flags.By default, no flags are set.
-
setHeaderFlags
public final void setHeaderFlags(int section, Orientation orientation, HeaderFlag flag, HeaderFlag... flags) Sets header flags.Calls
setHeaderFlags(section, orientation, EnumSet.of(flag, flags))
-
getHeaderFlags
Description copied from class:WAbstractItemModel
Returns the flags for a header.The default implementation returns no flags set.
- Overrides:
getHeaderFlags
in classWAbstractItemModel
- See Also:
-
getFlags
Description copied from class:WAbstractItemModel
Returns the flags for an item.The default implementation returns
ItemFlag.Selectable
.- Overrides:
getFlags
in classWAbstractItemModel
- See Also:
-
getParent
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 classWAbstractItemModel
- See Also:
-
getData
Description copied from class:WAbstractItemModel
Returns data at a specified model index for the given role.You should check the
role
to decide what data to return. Usually a View class will ask for data for several roles which affect not only the contents (ItemDataRole.Display
) but also icons (ItemDataRole.Decoration
), URLs (ItemDataRole.Link
), and other visual aspects. If your item does not specify data for a particular role, it should simply return a Wt::cpp17::any(). -
getHeaderData
Description copied from class:WAbstractItemModel
Returns the row or column header data.When
orientation
isOrientation.Horizontal
,section
is a column number, whenorientation
isOrientation.Vertical
,section
is a row number. -
getIndex
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 atrow
andcolumn
withinparent
.If the location is invalid (out of bounds at the parent), then an invalid index must be returned.
- Specified by:
getIndex
in classWAbstractItemModel
- See Also:
-
getColumnCount
Description copied from class:WAbstractItemModel
Returns the number of columns.This returns the number of columns at index
parent
.- Specified by:
getColumnCount
in classWAbstractItemModel
- See Also:
-
getRowCount
Description copied from class:WAbstractItemModel
Returns the number of rows.This returns the number of rows at index
parent
.- Specified by:
getRowCount
in classWAbstractItemModel
- See Also:
-
insertColumns
Description copied from class:WAbstractItemModel
Inserts one or more columns.In models that support column insertion, this inserts
count
columns, starting atcolumn
, and returnstrue
if the operation was successful. The new columns are inserted underparent
.The default implementation returns
false
.The model implementation must call
beginInsertColumns()
andendInsertColumns()
before and after the operation whenever its geometry is changed by inserting columns. This emits signals for views to properly react to these changes.- Overrides:
insertColumns
in classWAbstractItemModel
- See Also:
-
insertRows
Description copied from class:WAbstractItemModel
Inserts one or more rows.In models that support row insertion, this inserts
count
rows, starting atrow
, and returnstrue
if the operation was successful. The new rows are inserted underparent
.If parent had no children, then a single column is added with
count
rows.The default implementation returns
false
.The model implementation must call
beginInsertRows()
andendInsertRows()
before and after the operation whenever its geometry is changed by inserting rows. This emits signals for views to properly react to these changes.- Overrides:
insertRows
in classWAbstractItemModel
- See Also:
-
removeColumns
Description copied from class:WAbstractItemModel
Removes columns.Returns
true
if the operation was successful.The default implementation returns
false
.The model implementation must call
beginRemoveColumns()
andendRemoveColumns()
before and after the operation whenever its geometry is changed by removing columns. This emits signals for views to properly react to these changes.- Overrides:
removeColumns
in classWAbstractItemModel
- See Also:
-
removeRows
Description copied from class:WAbstractItemModel
Removes rows.Returns
true
if the operation was successful.The default implementation returns
false
.The model implementation must call
beginRemoveRows()
andendRemoveRows()
before and after the operation whenever its geometry is changed by removing rows. This emits signals for views to properly react to these changes.- Overrides:
removeRows
in classWAbstractItemModel
- See Also:
-
setData
Description copied from class:WAbstractItemModel
Sets data at the given model index.Returns
true
if the operation was successful.The default implementation returns
false
.The model implementation must emit the
dataChanged()
signal after data was changed.- Overrides:
setData
in classWAbstractItemModel
- See Also:
-
setHeaderData
Description copied from class:WAbstractItemModel
Sets header data for a column or row.Returns
true
if the operation was successful.- Overrides:
setHeaderData
in classWAbstractItemModel
- See Also:
-
toRawIndex
Description copied from class:WAbstractItemModel
Converts 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
null
, which indicates that the index cannot be converted to a raw pointer. If you reimplement this method, you also need to reimplemntfromRawIndex()
. -
fromRawIndex
Description copied from class:WAbstractItemModel
Converts 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.
- Overrides:
fromRawIndex
in classWAbstractItemModel
- See Also:
-
dropEvent
Description copied from class:WAbstractItemModel
Handles 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).
This method is overloaded for handling drop events on top of items or drop events between items (see
DropLocation
). This overload handles drops on top of items, but note that due to historical reasons it will also insert the items in between when called withDropAction.Move
.The location in the model is indicated by the
row
andcolumn
within theparent
index. Ifrow
is -1, then the item is appended to theparent
. Otherwise, the item is inserted at or copied over the indicated item (and subsequent rows). Whenaction
is aDropAction.Move
, 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.
Note: Currently, only row selections are handled by the default implementation.
- Overrides:
dropEvent
in classWAbstractItemModel
- See Also:
-
setSortRole
Set the role used to sort the model.The default role is
ItemDataRole.Display
.- See Also:
-
getSortRole
Returns the role used to sort the model.- See Also:
-
sort
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 thelayoutChanged()
signal.- Overrides:
sort
in classWAbstractItemModel
- See Also:
-
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.
-
beginInsertColumns
Description copied from class:WAbstractItemModel
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. -
beginInsertRows
Description copied from class:WAbstractItemModel
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. -
beginRemoveColumns
Description copied from class:WAbstractItemModel
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. -
beginRemoveRows
Description copied from class:WAbstractItemModel
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. -
copyData
Description copied from class:WAbstractItemModel
Copy data to an index in this model.The source index can be any valid index. The destination index must be part of this model.
- Overrides:
copyData
in classWAbstractItemModel
-