|  | Home · Overviews · Examples |

# QAbstractItemModel Class Reference
[com.trolltech.qt.core module]

The `QAbstractItemModel` class provides the abstract interface for item model classes. More...

Inherits `QObject`.

Inherited by `QAbstractListModel`, `QAbstractProxyModel`, `QAbstractTableModel`, `QDirModel`, `QProxyModel`, `QStandardItemModel`, and `QTreeModel`.

## Detailed Description

The `QAbstractItemModel` class provides the abstract interface for item model classes.

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

The `QAbstractItemModel` class is one of the Model/View Classes and is part of Qt's model/view framework.

If you need a model to use with a `QListView` or a `QTableView`, you should consider subclassing `QAbstractListModel` or `QAbstractTableModel` instead of this class.

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

Every item of data that can be accessed via a model has an associated model index that is obtained using the `index` function. Each index may have a `sibling` index; child items have a `parent` index.

Each item has a number of data elements associated with it, and each of these can be retrieved by specifying a role (see `Qt::ItemDataRole`) to the model's `data` function. Data for all available roles can be obtained at the same time using the `itemData` function.

Data for each role is set using a particular `Qt::ItemDataRole`. Data for individual roles are set individually with `setData`, or they can be set for all roles with `setItemData`.

Items can be queried with `flags` (see `Qt::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 a `rowCount` and a `columnCount` for each level of the hierarchy. Rows and columns can be inserted and removed with `insertRows`, `insertColumns`, `removeRows`, and `removeColumns`.

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 cause `headerDataChanged` to be emitted. If the structure of the underlying data changes, the model can emit `layoutChanged` 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 the `match` function.

If the model is sortable, it can be sorted with `sort`.

### Subclassing

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

When subclassing `QAbstractItemModel`, at the very least you must implement `index`, `parent`, `rowCount`, `columnCount`, and `data`. These functions are used in all read-only models, and form the basis of editable models.

You can also reimplement `hasChildren` to provide special behavior for models where the implementation of `rowCount` 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 implement `setData`, and reimplement `flags` to ensure that `ItemIsEditable` is returned. You can also reimplement `headerData` and `setHeaderData` to control the way the headers for your model are presented.

Note that the `dataChanged` and `headerDataChanged` signals must be emitted explicitly when reimplementing the `setData` and `setHeaderData` functions, respectively.

Custom models need to create model indexes for other components to use. To do this, call `createIndex` 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 the Simple Tree Model example for more information about unique identifiers.

It is not necessary to support every role defined in Qt::ItemDataRole. Depending on the type of data contained within a model, it may only be useful to implement the `data` function to return valid information for some of the more common roles. Most models provide at least a textual representation of item data for the Qt::DisplayRole, and well-behaved models should also provide valid information for the Qt::ToolTipRole and Qt::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 of `insertRows`, `removeRows`, `insertColumns`, and `removeColumns`. When implementing these functions, it is important to notify any connected views about changes to the model's dimensions both before and after they occur:

- An `insertRows` implementation must call `beginInsertRows` before inserting new rows into the data structure, and it must call `endInsertRows` immediately afterwards.
- An `insertColumns` implementation must call `beginInsertColumns` before inserting new columns into the data structure, and it must call `endInsertColumns` immediately afterwards.
- A `removeRows` implementation must call `beginRemoveRows` before the rows are removed from the data structure, and it must call `endRemoveRows` immediately afterwards.
- A `removeColumns` implementation must call `beginRemoveColumns` before the columns are removed from the data structure, and it must call `endRemoveColumns` immediately afterwards.

The private 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 manage persistent model indexes correctly. If you want selections to be handled properly, you must ensure that you call these functions.

See also Model Classes, Model Subclassing Reference, `QModelIndex`, `QAbstractItemView`, Using Drag and Drop with Item Views, Simple DOM Model Example, and Simple Tree Model Example.