Contents

• Public Functions
• Public Slots
• Signals
• Protected Functions
• Protected Slots
• Detailed Description
• Subclassing

Detailed Description

TheQAbstractItemModel class provides the abstract interface for item model classes.

TheQAbstractItemModel class defines the standard interface that item models must use to be able to interoperate with other components in the model/view architecture. It is not supposed to be instantiated directly. Instead, you should subclass it to create new models.

TheQAbstractItemModel class is one of theModel/View Classes and is part of Qt'smodel/view framework.

If you need a model to use with aQListView or aQTableView, you should consider subclassingQAbstractListModel orQAbstractTableModel instead of this class.

The underlying data model is exposed to views and delegates as a hierarchy of tables. If you do not make use of the hierarchy, then the model is a simple table of rows and columns. Each item has a unique index specified by aQModelIndex.

Every item of data that can be accessed via a model has an associated model index. You can obtain this model index using theindex() function. Each index may have asibling() index; child items have aparent() index.

Each item has a number of data elements associated with it and they can be retrieved by specifying a role (seeQt::ItemDataRole) to the model'sdata() function. Data for all available roles can be obtained at the same time using theitemData() function.

Data for each role is set using a particularQt::ItemDataRole. Data for individual roles are set individually withsetData(), or they can be set for all roles withsetItemData().

Items can be queried withflags() (seeQt::ItemFlag) to see if they can be selected, dragged, or manipulated in other ways.

If an item has child objects,hasChildren() returns true for the corresponding index.

The model has arowCount() and acolumnCount() for each level of the hierarchy. Rows and columns can be inserted and removed withinsertRows(),insertColumns(),removeRows(), andremoveColumns().

The model emits signals to indicate changes. For example,dataChanged() is emitted whenever items of data made available by the model are changed. Changes to the headers supplied by the model causeheaderDataChanged() to be emitted. If the structure of the underlying data changes, the model can emitlayoutChanged() to indicate to any attached views that they should redisplay any items shown, taking the new structure into account.

The items available through the model can be searched for particular data using thematch() function.

To sort the model, you can usesort().

Subclassing

Note:Some general guidelines for subclassing models are available in theModel Subclassing Reference.

When subclassingQAbstractItemModel, at the very least you must implementindex(),parent(),rowCount(),columnCount(), anddata(). These functions are used in all read-only models, and form the basis of editable models.

You can also reimplementhasChildren() to provide special behavior for models where the implementation ofrowCount() is expensive. This makes it possible for models to restrict the amount of data requested by views, and can be used as a way to implement lazy population of model data.

To enable editing in your model, you must also implementsetData(), and reimplementflags() to ensure thatItemIsEditable is returned. You can also reimplementheaderData() andsetHeaderData() to control the way the headers for your model are presented.

ThedataChanged() andheaderDataChanged() signals must be emitted explicitly when reimplementing thesetData() andsetHeaderData() functions, respectively.

Custom models need to create model indexes for other components to use. To do this, callcreateIndex() with suitable row and column numbers for the item, and an identifier for it, either as a pointer or as an integer value. The combination of these values must be unique for each item. Custom models typically use these unique identifiers in other reimplemented functions to retrieve item data and access information about the item's parents and children. See theSimple Tree Model Example for more information about unique identifiers.

It is not necessary to support every role defined inQt::ItemDataRole. Depending on the type of data contained within a model, it may only be useful to implement thedata() function to return valid information for some of the more common roles. Most models provide at least a textual representation of item data for theQt::DisplayRole, and well-behaved models should also provide valid information for theQt::ToolTipRole andQt::WhatsThisRole. Supporting these roles enables models to be used with standard Qt views. However, for some models that handle highly-specialized data, it may be appropriate to provide data only for user-defined roles.

Models that provide interfaces to resizable data structures can provide implementations ofinsertRows(),removeRows(),insertColumns(),andremoveColumns(). When implementing these functions, it is important to notify any connected views about changes to the model's dimensions bothbefore andafter they occur:

• AninsertRows() implementation must callbeginInsertRows()before inserting new rows into the data structure, andendInsertRows()immediately afterwards.
• AninsertColumns() implementation must callbeginInsertColumns()before inserting new columns into the data structure, andendInsertColumns()immediately afterwards.
• AremoveRows() implementation must callbeginRemoveRows()before the rows are removed from the data structure, andendRemoveRows()immediately afterwards.
• AremoveColumns() implementation must callbeginRemoveColumns()before the columns are removed from the data structure, andendRemoveColumns()immediately afterwards.

Theprivate signals that these functions emit give attached components the chance to take action before any data becomes unavailable. The encapsulation of the insert and remove operations with these begin and end functions also enables the model to managepersistent model indexes correctly.If you want selections to be handled properly, you must ensure that you call these functions. If you insert or remove an item with children, you do not need to call these functions for the child items. In other words, the parent item will take care of its child items.

To create models that populate incrementally, you can reimplementfetchMore() andcanFetchMore(). If the reimplementation offetchMore() adds rows to the model,beginInsertRows() andendInsertRows() must be called.

Member Function Documentation

QAbstractItemModel::QAbstractItemModel(QObject * parent = 0)

Constructs an abstract item model with the givenparent.

[virtual]QAbstractItemModel::~QAbstractItemModel()

Destroys the abstract item model.

[protected]void QAbstractItemModel::beginInsertColumns(constQModelIndex & parent,int first,int last)

Begins a column insertion operation.

When reimplementinginsertColumns() in a subclass, you must call this functionbefore inserting data into the model's underlying data store.

Theparent index corresponds to the parent into which the new columns are inserted;first andlast are the column numbers of the new columns will have after they have been inserted.

	Specify the first and last column numbers for the span of columns you want to insert into an item in a model. For example, as shown in the diagram, we insert three columns before column 4, sofirst is 4 andlast is 6: beginInsertColumns(parent,4,6); This inserts the three new columns as columns 4, 5, and 6.
	To append columns, insert them after the last column. For example, as shown in the diagram, we append three columns to a collection of six existing columns (ending in column 5), sofirst is 6 andlast is 8: beginInsertColumns(parent,6,8); This appends the two new columns as columns 6, 7, and 8.

Note:This function emits thecolumnsAboutToBeInserted() signal which connected views (or proxies) must handle before the data is inserted. Otherwise, the views may end up in an invalid state.

See alsoendInsertColumns().

[protected]void QAbstractItemModel::beginInsertRows(constQModelIndex & parent,int first,int last)

Begins a row insertion operation.

When reimplementinginsertRows() in a subclass, you must call this functionbefore inserting data into the model's underlying data store.

Theparent index corresponds to the parent into which the new rows are inserted;first andlast are the row numbers that the new rows will have after they have been inserted.

	Specify the first and last row numbers for the span of rows you want to insert into an item in a model. For example, as shown in the diagram, we insert three rows before row 2, sofirst is 2 andlast is 4: beginInsertRows(parent,2,4); This inserts the three new rows as rows 2, 3, and 4.
	To append rows, insert them after the last row. For example, as shown in the diagram, we append two rows to a collection of 4 existing rows (ending in row 3), sofirst is 4 andlast is 5: beginInsertRows(parent,4,5); This appends the two new rows as rows 4 and 5.

Note:This function emits therowsAboutToBeInserted() signal which connected views (or proxies) must handle before the data is inserted. Otherwise, the views may end up in an invalid state.

See alsoendInsertRows().

[protected]bool QAbstractItemModel::beginMoveColumns(constQModelIndex & sourceParent,int sourceFirst,int sourceLast, constQModelIndex & destinationParent,int destinationChild)

Begins a column move operation.

When reimplementing a subclass, this method simplifies moving entities in your model. This method is responsible for moving persistent indexes in the model, which you would otherwise be required to do yourself. UsingbeginMoveRows andendMoveRows is an alternative to emittinglayoutAboutToBeChanged andlayoutChanged directly along with changePersistentIndexes.layoutAboutToBeChanged is emitted by this method for compatibility reasons.

ThesourceParent index corresponds to the parent from which the columns are moved;sourceFirst andsourceLast are the first and last column numbers of the columns to be moved. ThedestinationParent index corresponds to the parent into which those columns are moved. ThedestinationChild is the column to which the columns will be moved. That is, the index at columnsourceFirst insourceParent will become columndestinationChild indestinationParent, followed by all other columns up tosourceLast.

However, when moving columns down in the same parent (sourceParent anddestinationParent are equal), the columnss will be placed before thedestinationChild index. That is, if you wish to move columns 0 and 1 so they will become columns 1 and 2,destinationChild should be 3. In this case, the new index for the source columni (which is betweensourceFirst andsourceLast) is equal to(destinationChild-sourceLast-1+i).

Note that ifsourceParent anddestinationParent are the same, you must ensure that thedestinationChild is not within the range ofsourceFirst andsourceLast + 1. You must also ensure that you do not attempt to move a column to one of its own children or ancestors. This method returns false if either condition is true, in which case you should abort your move operation.

This function was introduced in Qt 4.6.

See alsoendMoveColumns().

[protected]bool QAbstractItemModel::beginMoveRows(constQModelIndex & sourceParent,int sourceFirst,int sourceLast, constQModelIndex & destinationParent,int destinationChild)

Begins a row move operation.

When reimplementing a subclass, this method simplifies moving entities in your model. This method is responsible for moving persistent indexes in the model, which you would otherwise be required to do yourself. Using beginMoveRows andendMoveRows is an alternative to emittinglayoutAboutToBeChanged andlayoutChanged directly along with changePersistentIndexes.layoutAboutToBeChanged is emitted by this method for compatibility reasons.

ThesourceParent index corresponds to the parent from which the rows are moved;sourceFirst andsourceLast are the first and last row numbers of the rows to be moved. ThedestinationParent index corresponds to the parent into which those rows are moved. ThedestinationChild is the row to which the rows will be moved. That is, the index at rowsourceFirst insourceParent will become rowdestinationChild indestinationParent, followed by all other rows up tosourceLast.

However, when moving rows down in the same parent (sourceParent anddestinationParent are equal), the rows will be placed before thedestinationChild index. That is, if you wish to move rows 0 and 1 so they will become rows 1 and 2,destinationChild should be 3. In this case, the new index for the source rowi (which is betweensourceFirst andsourceLast) is equal to(destinationChild-sourceLast-1+i).

Note that ifsourceParent anddestinationParent are the same, you must ensure that thedestinationChild is not within the range ofsourceFirst andsourceLast + 1. You must also ensure that you do not attempt to move a row to one of its own children or ancestors. This method returns false if either condition is true, in which case you should abort your move operation.

	Specify the first and last row numbers for the span of rows in the source parent you want to move in the model. Also specify the row in the destination parent to move the span to. For example, as shown in the diagram, we move three rows from row 2 to 4 in the source, sosourceFirst is 2 andsourceLast is 4. We move those items to above row 2 in the destination, sodestinationChild is 2. beginMoveRows(sourceParent,2,4, destinationParent,2); This moves the three rows rows 2, 3, and 4 in the source to become 2, 3 and 4 in the destination. Other affected siblings are displaced accordingly.
	To append rows to another parent, move them to after the last row. For example, as shown in the diagram, we move three rows to a collection of 6 existing rows (ending in row 5), sodestinationChild is 6: beginMoveRows(sourceParent,2,4, destinationParent,6); This moves the target rows to the end of the target parent as 6, 7 and 8.
	To move rows within the same parent, specify the row to move them to. For example, as shown in the diagram, we move one item from row 2 to row 0, sosourceFirst andsourceLast are 2 anddestinationChild is 0. beginMoveRows(parent,2,2, parent,0); Note that other rows may be displaced accordingly. Note also that when moving items within the same parent you should not attempt invalid or no-op moves. In the above example, item 2 is at row 2 before the move, so it can not be moved to row 2 (where it is already) or row 3 (no-op as row 3 means above row 3, where it is already)
	To move rows within the same parent, specify the row to move them to. For example, as shown in the diagram, we move one item from row 2 to row 4, sosourceFirst andsourceLast are 2 anddestinationChild is 4. beginMoveRows(parent,2,2, parent,4); Note that other rows may be displaced accordingly.

This function was introduced in Qt 4.6.

See alsoendMoveRows().

[protected]void QAbstractItemModel::beginRemoveColumns(constQModelIndex & parent,int first,int last)

Begins a column removal operation.

When reimplementingremoveColumns() in a subclass, you must call this functionbefore removing data from the model's underlying data store.

Theparent index corresponds to the parent from which the new columns are removed;first andlast are the column numbers of the first and last columns to be removed.

Specify the first and last column numbers for the span of columns you want to remove from an item in a model. For example, as shown in the diagram, we remove the three columns from column 4 to column 6, sofirst is 4 andlast is 6: beginRemoveColumns(parent,4,6);

Note:This function emits thecolumnsAboutToBeRemoved() signal which connected views (or proxies) must handle before the data is removed. Otherwise, the views may end up in an invalid state.

See alsoendRemoveColumns().

[protected]void QAbstractItemModel::beginRemoveRows(constQModelIndex & parent,int first,int last)

Begins a row removal operation.

When reimplementingremoveRows() in a subclass, you must call this functionbefore removing data from the model's underlying data store.

Theparent index corresponds to the parent from which the new rows are removed;first andlast are the row numbers of the rows to be removed.

Specify the first and last row numbers for the span of rows you want to remove from an item in a model. For example, as shown in the diagram, we remove the two rows from row 2 to row 3, sofirst is 2 andlast is 3: beginRemoveRows(parent,2,3);

Note:This function emits therowsAboutToBeRemoved() signal which connected views (or proxies) must handle before the data is removed. Otherwise, the views may end up in an invalid state.

See alsoendRemoveRows().

[protected]void QAbstractItemModel::beginResetModel()

Begins a model reset operation.

A reset operation resets the model to its current state in any attached views.

Note:Any views attached to this model will be reset as well.

When a model is reset it means that any previous data reported from the model is now invalid and has to be queried for again. This also means that the current item and any selected items will become invalid.

When a model radically changes its data it can sometimes be easier to just call this function rather than emitdataChanged() to inform other components when the underlying data source, or its structure, has changed.

You must call this function before resetting any internal data structures in your model or proxy model.

This function was introduced in Qt 4.6.

See alsomodelAboutToBeReset(),modelReset(), andendResetModel().

[virtual]QModelIndex QAbstractItemModel::buddy(constQModelIndex & index) const

Returns a model index for the buddy of the item represented byindex. When the user wants to edit an item, the view will call this function to check whether another item in the model should be edited instead. Then, the view will construct a delegate using the model index returned by the buddy item.

The default implementation of this function has each item as its own buddy.

[virtual]bool QAbstractItemModel::canFetchMore(constQModelIndex & parent) const

Returns true if there is more data available forparent; otherwise returns false.

The default implementation always returns false.

If canFetchMore() returns true,QAbstractItemView will callfetchMore(). However, thefetchMore() function is only called when the model is being populated incrementally.

See alsofetchMore().

[protected]void QAbstractItemModel::changePersistentIndex(constQModelIndex & from, constQModelIndex & to)

Changes theQPersistentModelIndex that is equal to the givenfrom model index to the givento model index.

If no persistent model index equal to the givenfrom model index was found, nothing is changed.

See alsopersistentIndexList() andchangePersistentIndexList().

[protected]void QAbstractItemModel::changePersistentIndexList(constQModelIndexList & from, constQModelIndexList & to)

Changes the QPersistentModelIndexes that is equal to the indexes in the givenfrom model index list to the givento model index list.

If no persistent model indexes equal to the indexes in the givenfrom model index list was found, nothing is changed.

This function was introduced in Qt 4.1.

See alsopersistentIndexList() andchangePersistentIndex().

[pure virtual]int QAbstractItemModel::columnCount(constQModelIndex & parent = QModelIndex()) const

Returns the number of columns for the children of the givenparent.

In most subclasses, the number of columns is independent of theparent.

For example:

int DomModel::columnCount(constQModelIndex&/*parent*/)const{return3;}

Note:When implementing a table based model, columnCount() should return 0 when the parent is valid.

See alsorowCount().

[signal]void QAbstractItemModel::columnsAboutToBeInserted(constQModelIndex & parent,int start,int end)

This signal is emitted just before columns are inserted into the model. The new items will be positioned betweenstart andend inclusive, under the givenparent item.

Note:Components connected to this signal use it to adapt to changes in the model's dimensions. It can only be emitted by theQAbstractItemModel implementation, and cannot be explicitly emitted in subclass code.

See alsoinsertColumns() andbeginInsertColumns().

[signal]void QAbstractItemModel::columnsAboutToBeMoved(constQModelIndex & sourceParent,int sourceStart,int sourceEnd, constQModelIndex & destinationParent,int destinationColumn)

This signal is emitted just before columns are moved within the model. The items that will be moved are those betweensourceStart andsourceEnd inclusive, under the givensourceParent item. They will be moved todestinationParent starting at the columndestinationColumn.

Note: Components connected to this signal use it to adapt to changes in the model's dimensions. It can only be emitted by theQAbstractItemModel implementation, and cannot be explicitly emitted in subclass code.

This function was introduced in Qt 4.6.

See alsobeginMoveRows().

[signal]void QAbstractItemModel::columnsAboutToBeRemoved(constQModelIndex & parent,int start,int end)

This signal is emitted just before columns are removed from the model. The items to be removed are those betweenstart andend inclusive, under the givenparent item.

Note:Components connected to this signal use it to adapt to changes in the model's dimensions. It can only be emitted by theQAbstractItemModel implementation, and cannot be explicitly emitted in subclass code.

See alsoremoveColumns() andbeginRemoveColumns().

[signal]void QAbstractItemModel::columnsInserted(constQModelIndex & parent,int start,int end)

This signal is emitted after columns have been inserted into the model. The new items are those betweenstart andend inclusive, under the givenparent item.

Note:Components connected to this signal use it to adapt to changes in the model's dimensions. It can only be emitted by theQAbstractItemModel implementation, and cannot be explicitly emitted in subclass code.

See alsoinsertColumns() andbeginInsertColumns().

[signal]void QAbstractItemModel::columnsMoved(constQModelIndex & sourceParent,int sourceStart,int sourceEnd, constQModelIndex & destinationParent,int destinationColumn)

This signal is emitted after columns have been moved within the model. The items betweensourceStart andsourceEnd inclusive, under the givensourceParent item have been moved todestinationParent starting at the columndestinationColumn.

Note: Components connected to this signal use it to adapt to changes in the model's dimensions. It can only be emitted by theQAbstractItemModel implementation, and cannot be explicitly emitted in subclass code.

This function was introduced in Qt 4.6.

See alsobeginMoveRows().

[signal]void QAbstractItemModel::columnsRemoved(constQModelIndex & parent,int start,int end)

This signal is emitted after columns have been removed from the model. The removed items are those betweenstart andend inclusive, under the givenparent item.

Note:Components connected to this signal use it to adapt to changes in the model's dimensions. It can only be emitted by theQAbstractItemModel implementation, and cannot be explicitly emitted in subclass code.

See alsoremoveColumns() andbeginRemoveColumns().

[protected]QModelIndex QAbstractItemModel::createIndex(int row,int column,void * ptr = 0) const

Creates a model index for the givenrow andcolumn with the internal pointerptr.

When using aQSortFilterProxyModel, its indexes have their own internal pointer. It is not advisable to access this internal pointer outside of the model. Use thedata() function instead.

This function provides a consistent interface that model subclasses must use to create model indexes.

[protected]QModelIndex QAbstractItemModel::createIndex(int row,int column,quint32 id) const

Creates a model index for the givenrow andcolumn with the internal identifier,id.

This function provides a consistent interface that model subclasses must use to create model indexes.

See alsoQModelIndex::internalId().

[pure virtual]QVariant QAbstractItemModel::data(constQModelIndex & index,int role = Qt::DisplayRole) const

Returns the data stored under the givenrole for the item referred to by theindex.

Note:If you do not have a value to return, return aninvalidQVariant instead of returning 0.

See alsoQt::ItemDataRole,setData(), andheaderData().

[signal]void QAbstractItemModel::dataChanged(constQModelIndex & topLeft, constQModelIndex & bottomRight)

This signal is emitted whenever the data in an existing item changes.

If the items are of the same parent, the affected ones are those betweentopLeft andbottomRight inclusive. If the items do not have the same parent, the behavior is undefined.

When reimplementing thesetData() function, this signal must be emitted explicitly.

See alsoheaderDataChanged(),setData(), andlayoutChanged().

[virtual]bool QAbstractItemModel::dropMimeData(constQMimeData * data,Qt::DropAction action,int row,int column, constQModelIndex & parent)

Handles thedata supplied by a drag and drop operation that ended with the givenaction.

Returns true if the data and action can be handled by the model; otherwise returns false.

The specifiedrow,column andparent indicate the location of an item in the model where the operation ended. It is the responsibility of the model to complete the action at the correct location.

For instance, a drop action on an item in aQTreeView can result in new items either being inserted as children of the item specified byrow,column, andparent, or as siblings of the item.

Whenrow andcolumn are -1 it means that the dropped data should be considered as dropped directly onparent. Usually this will mean appending the data as child items ofparent. Ifrow and column are greater than or equal zero, it means that the drop occurred just before the specifiedrow andcolumn in the specifiedparent.

See alsosupportedDropActions() andUsing drag and drop with item views.

[protected]void QAbstractItemModel::endInsertColumns()

Ends a column insertion operation.

When reimplementinginsertColumns() in a subclass, you must call this functionafter inserting data into the model's underlying data store.

See alsobeginInsertColumns().

[protected]void QAbstractItemModel::endInsertRows()

Ends a row insertion operation.

When reimplementinginsertRows() in a subclass, you must call this functionafter inserting data into the model's underlying data store.

See alsobeginInsertRows().

[protected]void QAbstractItemModel::endMoveColumns()

Ends a column move operation.

When implementing a subclass, you must call this functionafter moving data within the model's underlying data store.

layoutChanged is emitted by this method for compatibility reasons.

This function was introduced in Qt 4.6.

See alsobeginMoveColumns().

[protected]void QAbstractItemModel::endMoveRows()

Ends a row move operation.

When implementing a subclass, you must call this functionafter moving data within the model's underlying data store.

layoutChanged is emitted by this method for compatibility reasons.

This function was introduced in Qt 4.6.

See alsobeginMoveRows().

[protected]void QAbstractItemModel::endRemoveColumns()

Ends a column removal operation.

When reimplementingremoveColumns() in a subclass, you must call this functionafter removing data from the model's underlying data store.

See alsobeginRemoveColumns().

[protected]void QAbstractItemModel::endRemoveRows()

Ends a row removal operation.

When reimplementingremoveRows() in a subclass, you must call this functionafter removing data from the model's underlying data store.

See alsobeginRemoveRows().

[protected]void QAbstractItemModel::endResetModel()

Completes a model reset operation.

You must call this function after resetting any internal data structure in your model or proxy model.

This function was introduced in Qt 4.6.

See alsobeginResetModel().

[virtual]void QAbstractItemModel::fetchMore(constQModelIndex & parent)

Fetches any available data for the items with the parent specified by theparent index.

Reimplement this if you are populating your model incrementally.

The default implementation does nothing.

See alsocanFetchMore().

[virtual]Qt::ItemFlags QAbstractItemModel::flags(constQModelIndex & index) const

Returns the item flags for the givenindex.

The base class implementation returns a combination of flags that enables the item (ItemIsEnabled) and allows it to be selected (ItemIsSelectable).

See alsoQt::ItemFlags.

[virtual]bool QAbstractItemModel::hasChildren(constQModelIndex & parent = QModelIndex()) const

Returns true ifparent has any children; otherwise returns false.

UserowCount() on the parent to find out the number of children.

See alsoparent() andindex().

bool QAbstractItemModel::hasIndex(int row,int column, constQModelIndex & parent = QModelIndex()) const

Returns true if the model returns a validQModelIndex forrow andcolumn withparent, otherwise returns false.

[virtual]QVariant QAbstractItemModel::headerData(int section,Qt::Orientation orientation,int role = Qt::DisplayRole) const

Returns the data for the givenrole andsection in the header with the specifiedorientation.

For horizontal headers, the section number corresponds to the column number. Similarly, for vertical headers, the section number corresponds to the row number.

See alsoQt::ItemDataRole,setHeaderData(), andQHeaderView.

[signal]void QAbstractItemModel::headerDataChanged(Qt::Orientation orientation,int first,int last)

This signal is emitted whenever a header is changed. Theorientation indicates whether the horizontal or vertical header has changed. The sections in the header from thefirst to thelast need to be updated.

When reimplementing thesetHeaderData() function, this signal must be emitted explicitly.

If you are changing the number of columns or rows you do not need to emit this signal, but use the begin/end functions (refer to the section on subclassing in theQAbstractItemModel class description for details).

See alsoheaderData(),setHeaderData(), anddataChanged().

[pure virtual]QModelIndex QAbstractItemModel::index(int row,int column, constQModelIndex & parent = QModelIndex()) const

Returns the index of the item in the model specified by the givenrow,column andparent index.

When reimplementing this function in a subclass, callcreateIndex() to generate model indexes that other components can use to refer to items in your model.

See alsocreateIndex().

bool QAbstractItemModel::insertColumn(int column, constQModelIndex & parent = QModelIndex())

Inserts a single column before the givencolumn in the child items of theparent specified.

Returns true if the column is inserted; otherwise returns false.

See alsoinsertColumns(),insertRow(), andremoveColumn().

[virtual]bool QAbstractItemModel::insertColumns(int column,int count, constQModelIndex & parent = QModelIndex())

On models that support this, insertscount new columns into the model before the givencolumn. The items in each new column will be children of the item represented by theparent model index.

Ifcolumn is 0, the columns are prepended to any existing columns.

Ifcolumn iscolumnCount(), the columns are appended to any existing columns.

Ifparent has no children, a single row withcount columns is inserted.

Returns true if the columns were successfully inserted; otherwise returns false.

The base class implementation does nothing and returns false.

If you implement your own model, you can reimplement this function if you want to support insertions. Alternatively, you can provide your own API for altering the data.

See alsoinsertRows(),removeColumns(),beginInsertColumns(), andendInsertColumns().

bool QAbstractItemModel::insertRow(int row, constQModelIndex & parent = QModelIndex())

Note:The base class implementation of this function does nothing and returns false.

Inserts a single row before the givenrow in the child items of theparent specified.

Returns true if the row is inserted; otherwise returns false.

See alsoinsertRows(),insertColumn(), andremoveRow().

[virtual]bool QAbstractItemModel::insertRows(int row,int count, constQModelIndex & parent = QModelIndex())

Note:The base class implementation of this function does nothing and returns false.

On models that support this, insertscount rows into the model before the givenrow. Items in the new row will be children of the item represented by theparent model index.

Ifrow is 0, the rows are prepended to any existing rows in the parent.

Ifrow isrowCount(), the rows are appended to any existing rows in the parent.

Ifparent has no children, a single column withcount rows is inserted.

Returns true if the rows were successfully inserted; otherwise returns false.

If you implement your own model, you can reimplement this function if you want to support insertions. Alternatively, you can provide your own API for altering the data. In either case, you will need to callbeginInsertRows() andendInsertRows() to notify other components that the model has changed.

See alsoinsertColumns(),removeRows(),beginInsertRows(), andendInsertRows().

[virtual]QMap<int,QVariant> QAbstractItemModel::itemData(constQModelIndex & index) const

Returns a map with values for all predefined roles in the model for the item at the givenindex.

Reimplement this function if you want to extend the default behavior of this function to include custom roles in the map.

See alsosetItemData(),Qt::ItemDataRole, anddata().

[signal]void QAbstractItemModel::layoutAboutToBeChanged()

This signal is emitted just before the layout of a model is changed. Components connected to this signal use it to adapt to changes in the model's layout.

Subclasses should update any persistent model indexes after emitting layoutAboutToBeChanged().

This function was introduced in Qt 4.2.

See alsolayoutChanged() andchangePersistentIndex().

[signal]void QAbstractItemModel::layoutChanged()

This signal is emitted whenever the layout of items exposed by the model has changed; for example, when the model has been sorted. When this signal is received by a view, it should update the layout of items to reflect this change.

When subclassingQAbstractItemModel orQAbstractProxyModel, ensure that you emitlayoutAboutToBeChanged() before changing the order of items or altering the structure of the data you expose to views, and emit layoutChanged() after changing the layout.

Subclasses should update any persistent model indexes before emitting layoutChanged(). In other words, when the structure changes:

• emitlayoutAboutToBeChanged
• Remember theQModelIndex that will change
• Update your internal data
• CallchangePersistentIndex()
• emit layoutChanged

See alsolayoutAboutToBeChanged(),dataChanged(),headerDataChanged(),modelReset(), andchangePersistentIndex().

[virtual]QModelIndexList QAbstractItemModel::match(constQModelIndex & start,int role, constQVariant & value,int hits = 1,Qt::MatchFlags flags = Qt::MatchFlags( Qt::MatchStartsWith | Qt::MatchWrap )) const

Returns a list of indexes for the items in the column of thestart index where data stored under the givenrole matches the specifiedvalue. The way the search is performed is defined by theflags given. The list that is returned may be empty.

The search begins from thestart index, and continues until the number of matching data items equalshits, the search reaches the last row, or the search reachesstart again - depending on whetherMatchWrap is specified inflags. If you want to search for all matching items, usehits = -1.

By default, this function will perform a wrapping, string-based comparison on all items, searching for items that begin with the search term specified byvalue.

Note:The default implementation of this function only searches columns. Reimplement this function to include a different search behavior.

[virtual]QMimeData * QAbstractItemModel::mimeData(constQModelIndexList & indexes) const

Returns an object that contains serialized items of data corresponding to the list ofindexes specified. The formats used to describe the encoded data is obtained from themimeTypes() function.

If the list of indexes is empty, or there are no supported MIME types, 0 is returned rather than a serialized empty list.

See alsomimeTypes() anddropMimeData().

[virtual]QStringList QAbstractItemModel::mimeTypes() const

Returns a list of MIME types that can be used to describe a list of model indexes.

See alsomimeData().

[signal]void QAbstractItemModel::modelAboutToBeReset()

This signal is emitted whenreset() is called, before the model's internal state (e.g. persistent model indexes) has been invalidated.

This function was introduced in Qt 4.2.

See alsobeginResetModel() andmodelReset().

[signal]void QAbstractItemModel::modelReset()

This signal is emitted whenreset() is called, after the model's internal state (e.g. persistent model indexes) has been invalidated.

This function was introduced in Qt 4.1.

See alsoendResetModel() andmodelAboutToBeReset().

[pure virtual]QModelIndex QAbstractItemModel::parent(constQModelIndex & index) const

Returns the parent of the model item with the givenindex. If the item has no parent, an invalidQModelIndex is returned.

A common convention used in models that expose tree data structures is that only items in the first column have children. For that case, when reimplementing this function in a subclass the column of the returnedQModelIndex would be 0.

When reimplementing this function in a subclass, be careful to avoid callingQModelIndex member functions, such asQModelIndex::parent(), since indexes belonging to your model will simply call your implementation, leading to infinite recursion.

See alsocreateIndex().

[protected]QModelIndexList QAbstractItemModel::persistentIndexList() const

Returns the list of indexes stored as persistent indexes in the model.

This function was introduced in Qt 4.2.

bool QAbstractItemModel::removeColumn(int column, constQModelIndex & parent = QModelIndex())

Removes the givencolumn from the child items of theparent specified.

Returns true if the column is removed; otherwise returns false.

See alsoremoveColumns(),removeRow(), andinsertColumn().

[virtual]bool QAbstractItemModel::removeColumns(int column,int count, constQModelIndex & parent = QModelIndex())

On models that support this, removescount columns starting with the givencolumn under parentparent from the model.

Returns true if the columns were successfully removed; otherwise returns false.

The base class implementation does nothing and returns false.

If you implement your own model, you can reimplement this function if you want to support removing. Alternatively, you can provide your own API for altering the data.

See alsoremoveColumn(),removeRows(),insertColumns(),beginRemoveColumns(), andendRemoveColumns().

bool QAbstractItemModel::removeRow(int row, constQModelIndex & parent = QModelIndex())

Removes the givenrow from the child items of theparent specified.

Returns true if the row is removed; otherwise returns false.

This is a convenience function that callsremoveRows(). TheQAbstractItemModel implementation ofremoveRows() does nothing.

See alsoremoveRows(),removeColumn(), andinsertRow().

[virtual]bool QAbstractItemModel::removeRows(int row,int count, constQModelIndex & parent = QModelIndex())

On models that support this, removescount rows starting with the givenrow under parentparent from the model.

Returns true if the rows were successfully removed; otherwise returns false.

The base class implementation does nothing and returns false.

If you implement your own model, you can reimplement this function if you want to support removing. Alternatively, you can provide your own API for altering the data.

See alsoremoveRow(),removeColumns(),insertColumns(),beginRemoveRows(), andendRemoveRows().

[protected]void QAbstractItemModel::reset()

Resets the model to its original state in any attached views.

Note:UsebeginResetModel() andendResetModel() instead whenever possible. Use this method only if there is no way to callbeginResetModel() before invalidating the model. Otherwise it could lead to unexpected behaviour, especially when used with proxy models.

[protected slot]void QAbstractItemModel::resetInternalData()

This slot is called just after the internal data of a model is cleared while it is being reset.

This slot is provided the convenience of subclasses of concrete proxy models, such as subclasses ofQSortFilterProxyModel which maintain extra data.

class CustomDataProxy :publicQSortFilterProxyModel{    Q_OBJECTpublic:    CustomDataProxy(QObject*parent)      :QSortFilterProxyModel(parent)    {    }...QVariant data(constQModelIndex&index,int role)    {if (role!=Qt::BackgroundRole)returnQSortFilterProxyModel::data(index, role);if (m_customData.contains(index.row()))return m_customData.value(index.row());returnQSortFilterProxyModel::data(index, role);    }privateslots:void resetInternalData()    {        m_customData.clear();    }private:QHash<int,QVariant> m_customData;};

This function was introduced in Qt 4.8.

See alsomodelAboutToBeReset() andmodelReset().

[virtual slot]void QAbstractItemModel::revert()

Lets the model know that it should discard cached information. This function is typically used for row editing.

See alsosubmit().

constQHash<int,QByteArray> & QAbstractItemModel::roleNames() const

Returns the model's role names.

This function was introduced in Qt 4.6.

See alsosetRoleNames().

[pure virtual]int QAbstractItemModel::rowCount(constQModelIndex & parent = QModelIndex()) const

Returns the number of rows under the givenparent. When the parent is valid it means that rowCount is returning the number of children of parent.

Note:When implementing a table based model, rowCount() should return 0 when the parent is valid.

See alsocolumnCount().

[signal]void QAbstractItemModel::rowsAboutToBeInserted(constQModelIndex & parent,int start,int end)

This signal is emitted just before rows are inserted into the model. The new items will be positioned betweenstart andend inclusive, under the givenparent item.

Note:Components connected to this signal use it to adapt to changes in the model's dimensions. It can only be emitted by theQAbstractItemModel implementation, and cannot be explicitly emitted in subclass code.

See alsoinsertRows() andbeginInsertRows().

[signal]void QAbstractItemModel::rowsAboutToBeMoved(constQModelIndex & sourceParent,int sourceStart,int sourceEnd, constQModelIndex & destinationParent,int destinationRow)

This signal is emitted just before rows are moved within the model. The items that will be moved are those betweensourceStart andsourceEnd inclusive, under the givensourceParent item. They will be moved todestinationParent starting at the rowdestinationRow.

Note: Components connected to this signal use it to adapt to changes in the model's dimensions. It can only be emitted by theQAbstractItemModel implementation, and cannot be explicitly emitted in subclass code.

This function was introduced in Qt 4.6.

See alsobeginMoveRows().

[signal]void QAbstractItemModel::rowsAboutToBeRemoved(constQModelIndex & parent,int start,int end)

This signal is emitted just before rows are removed from the model. The items that will be removed are those betweenstart andend inclusive, under the givenparent item.

Note:Components connected to this signal use it to adapt to changes in the model's dimensions. It can only be emitted by theQAbstractItemModel implementation, and cannot be explicitly emitted in subclass code.

See alsoremoveRows() andbeginRemoveRows().

[signal]void QAbstractItemModel::rowsInserted(constQModelIndex & parent,int start,int end)

This signal is emitted after rows have been inserted into the model. The new items are those betweenstart andend inclusive, under the givenparent item.

Note:Components connected to this signal use it to adapt to changes in the model's dimensions. It can only be emitted by theQAbstractItemModel implementation, and cannot be explicitly emitted in subclass code.

See alsoinsertRows() andbeginInsertRows().

[signal]void QAbstractItemModel::rowsMoved(constQModelIndex & sourceParent,int sourceStart,int sourceEnd, constQModelIndex & destinationParent,int destinationRow)

This signal is emitted after rows have been moved within the model. The items betweensourceStart andsourceEnd inclusive, under the givensourceParent item have been moved todestinationParent starting at the rowdestinationRow.

Note: Components connected to this signal use it to adapt to changes in the model's dimensions. It can only be emitted by theQAbstractItemModel implementation, and cannot be explicitly emitted in subclass code.

This function was introduced in Qt 4.6.

See alsobeginMoveRows().

[signal]void QAbstractItemModel::rowsRemoved(constQModelIndex & parent,int start,int end)

This signal is emitted after rows have been removed from the model. The removed items are those betweenstart andend inclusive, under the givenparent item.

Note:Components connected to this signal use it to adapt to changes in the model's dimensions. It can only be emitted by theQAbstractItemModel implementation, and cannot be explicitly emitted in subclass code.

See alsoremoveRows() andbeginRemoveRows().

[virtual]bool QAbstractItemModel::setData(constQModelIndex & index, constQVariant & value,int role = Qt::EditRole)

Sets therole data for the item atindex tovalue.

Returns true if successful; otherwise returns false.

ThedataChanged() signal should be emitted if the data was successfully set.

The base class implementation returns false. This function anddata() must be reimplemented for editable models.

See alsoQt::ItemDataRole,data(), anditemData().

[virtual]bool QAbstractItemModel::setHeaderData(int section,Qt::Orientation orientation, constQVariant & value,int role = Qt::EditRole)

Sets the data for the givenrole andsection in the header with the specifiedorientation to thevalue supplied.

Returns true if the header's data was updated; otherwise returns false.

When reimplementing this function, theheaderDataChanged() signal must be emitted explicitly.

See alsoQt::ItemDataRole andheaderData().

[virtual]bool QAbstractItemModel::setItemData(constQModelIndex & index, constQMap<int,QVariant> & roles)

Sets the role data for the item atindex to the associated value inroles, for everyQt::ItemDataRole.

Returns true if successful; otherwise returns false.

Roles that are not inroles will not be modified.

See alsosetData(),data(), anditemData().

[protected]void QAbstractItemModel::setRoleNames(constQHash<int,QByteArray> & roleNames)

Sets the model's role names toroleNames.

This function allows mapping of role identifiers to role property names in Declarative UI. This function must be called before the model is used. Modifying the role names after the model has been set may result in undefined behaviour.

This function was introduced in Qt 4.6.

See alsoroleNames().

void QAbstractItemModel::setSupportedDragActions(Qt::DropActions actions)

Sets the supported dragactions for the items in the model.

This function was introduced in Qt 4.2.

See alsosupportedDragActions() andUsing drag and drop with item views.

QModelIndex QAbstractItemModel::sibling(int row,int column, constQModelIndex & index) const

Returns the sibling atrow andcolumn for the item atindex, or an invalidQModelIndex if there is no sibling at that location.

sibling() is just a convenience function that finds the item's parent, and uses it to retrieve the index of the child item in the specifiedrow andcolumn.

See alsoindex(),QModelIndex::row(), andQModelIndex::column().

[virtual]void QAbstractItemModel::sort(int column,Qt::SortOrder order = Qt::AscendingOrder)

Sorts the model bycolumn in the givenorder.

The base class implementation does nothing.

[virtual]QSize QAbstractItemModel::span(constQModelIndex & index) const

Returns the row and column span of the item represented byindex.

Note:Currently, span is not used.

[virtual slot]bool QAbstractItemModel::submit()

Lets the model know that it should submit cached information to permanent storage. This function is typically used for row editing.

Returns true if there is no error; otherwise returns false.

See alsorevert().

Qt::DropActions QAbstractItemModel::supportedDragActions() const

Returns the actions supported by the data in this model.

The default implementation returnssupportedDropActions() unless specific values have been set withsetSupportedDragActions().

supportedDragActions() is used byQAbstractItemView::startDrag() as the default values when a drag occurs.

See alsosetSupportedDragActions(),Qt::DropActions, andUsing drag and drop with item views.

[virtual]Qt::DropActions QAbstractItemModel::supportedDropActions() const

Returns the drop actions supported by this model.

The default implementation returnsQt::CopyAction. Reimplement this function if you wish to support additional actions. You must also reimplement thedropMimeData() function to handle the additional operations.

This function was introduced in Qt 4.2.

See alsodropMimeData(),Qt::DropActions, andUsing drag and drop with item views.