Home | All Classes | Main Classes | Annotated | Grouped Classes | Functions

QAbstractItemModel Class Reference

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

#include <QAbstractItemModel>

Inherits QObject.

Inherited by QAbstractTableModel, QAbstractListModel, and QDirModel.

List of all members.

Public Types

Writable Properties

Public Functions

Public Slots

Signals

Static Public Members

Protected Functions


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.

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 has an index(), and possibly a sibling() index; child items have a parent() index. hasChildren() is true for items that have children. Each item has a number of data elements associated with them, each with a particular Role. Data elements are set individually with setData(), or for all roles with setItemData(). Data is retrieved from an item with data() (for a single role), or with itemData() (for every role). Items can be queried with isSelectable() and isEditable(). An item can be searched for using match().

The model has a rowCount() and a columnCount() for each level of the hierarchy. Rows and columns can be inserted and removed with insertRow(), insertColumn(), removeRow(), and removeColumn().

The model emits signals to indicate changes. For example, dataChanged() is emitted whenever the contents of the model are changed; rowsInserted(), columnsInserted(), rowsRemoved(), and columnsRemoved() are emitted when the model's dimensions are changed.

If the model isSortable(), it can be sorted with sort(). To customize sorting and searching, comparison functions can be reimplemented; for example, lessThan(), equal(), and greaterThan().

When subclassing QAbstractItemModel, at the very least you must implement index(), parent(), rowCount(), columnCount(), and data(). To enable editing in your model, you must also implement isEditable() and setData().

See also Model/View Programming, QModelIndex, and QAbstractItemView.


Member Type Documentation

enum QAbstractItemModel::MatchFlag
typedef QAbstractItemModel::MatchFlags

QAbstractItemModel::MatchContainsThe value is contained in the item.
QAbstractItemModel::MatchFromStartThe value matches the start of the item.
QAbstractItemModel::MatchFromEndThe value matches the end of the item.
QAbstractItemModel::MatchExactlyThe value matches the item exactly.
QAbstractItemModel::MatchCaseThe search is case sensitive.
QAbstractItemModel::MatchWrapThe search wraps around.
QAbstractItemModel::MatchDefaultThe default match, which is MatchFromStart|MatchWrap.

The MatchFlags typedef can store a combination of MatchFlag values.

enum QAbstractItemModel::Role

Each item in the model has a set of data elements associated with it, each with its own role. The roles are used when visualizing and editing the items in the views.

QAbstractItemModel::DisplayRoleThe data to be rendered as text.
QAbstractItemModel::DecorationRoleThe data to be rendered as an icon.
QAbstractItemModel::EditRoleThe data in a form suitable for editing in an editor.
QAbstractItemModel::ToolTipRoleThe data displayed in the item's tooltip.
QAbstractItemModel::StatusTipRoleThe data displayed in the status bar.
QAbstractItemModel::WhatsThisRoleThe data displayed for the item in "What's This?" mode.
QAbstractItemModel::UserRoleThe first role that can be used for application-specific purposes.

Member Function Documentation

QAbstractItemModel::QAbstractItemModel ( QObject * parent = 0 )

Constructs an abstract item model with parent parent.

QAbstractItemModel::~QAbstractItemModel ()   [virtual]

Destroys the abstract item model.

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

Returns the 'buddy' of the item represented by index. When the used wants to edit an item that is not editable, the delegate may ask for the item's buddy, and edit that item instead.

See also isEditable().

bool QAbstractItemModel::canDecode ( QMimeSource * src ) const   [virtual]

Returns true if decode() would be able to decode src; otherwise returns false.

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

Returns the number of columns for the given parent.

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

This signal is emitted after columns have been inserted into the model. The new items are those between start and end inclusive, under the given parent item.

See also insertColumns().

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

This signal is emitted just before columns are removed from the model. The removed items are those between start and end inclusive, under the given parent item.

See also removeRows().

QModelIndex QAbstractItemModel::createIndex ( int row = -1, int column = -1, void * data = 0, QModelIndex::Type type = QModelIndex::View ) const   [protected]

Creates a model index for the given row and column that points to the given data and is of the given type.

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

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

Returns the data of role role for the item at index.

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

This signal is emitted whenever the data in an existing item changes. The affected items are those between topLeft and bottomRight inclusive.

See also rowsInserted(), rowsRemoved(), columnsInserted(), columnsRemoved(), and setData().

bool QAbstractItemModel::decode ( QDropEvent * e, const QModelIndex & parent = QModelIndex() )   [virtual]

Decodes data from e, inserting the data under parent (if possible).

Returns true if the data was successfully decoded and inserted; otherwise returns false.

QDragObject * QAbstractItemModel::dragObject ( const QModelIndexList & indices, QWidget * dragSource )   [virtual]

Returns a pointer to a QDragObject object containing the data associated with the indices from the dragSource.

See also itemData().

bool QAbstractItemModel::equal ( const QModelIndex & left, const QModelIndex & right ) const   [virtual]

Returns true if the data at indexes left and right are equal; otherwise returns false.

See also greaterThan() and lessThan().

bool QAbstractItemModel::greaterThan ( const QModelIndex & left, const QModelIndex & right ) const

Returns true if the data at index left is greater than the data at index right; otherwise returns false.

See also equal() and lessThan().

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

Returns true if parent has any children; otherwise returns false.

See also parent() and index().

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

Returns the index of the item in the model specified by the given row, column, parent index, and type.

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

Inserts count new columns in the model before position column. If column is 0 the columns are prepended to the model, if column is columnCount() the columns are appended to the model. The column will be a child of parent. If parent has no children count columns with at least one row is inserted. Returns true if the columns were successfully inserted; otherwise returns false.

The base class implementation does nothing and returns false. If you want to be able to insert columns you must reimplement this function.

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

Inserts count rows in the model before position row. If row is 0 the rows are prepended to the model, if row is rowCount() the rows are appended to the model. The row will be a child of parent. If parent has no children count rows with at least one column is inserted. Returns true if the rows were successfully inserted; otherwise returns false.

The base class implementation does nothing and returns false. If you want to be able to insert rows you must reimplement this function.

bool QAbstractItemModel::isDragEnabled ( const QModelIndex & index ) const   [virtual]

Returns true if the item at index can be dragged; otherwise returns false.

The base class implementation returns false.

bool QAbstractItemModel::isDropEnabled ( const QModelIndex & index ) const   [virtual]

Returns true if other items can be dropped on the item at index; otherwise returns false.

The base class implementation returns false.

bool QAbstractItemModel::isEditable ( const QModelIndex & index ) const   [virtual]

Returns true if the item at index is editable; otherwise returns false.

The base class implementation returns false.

bool QAbstractItemModel::isSelectable ( const QModelIndex & index ) const   [virtual]

Returns true if the item at index is selectable; otherwise returns false.

The base class implementation returns true.

bool QAbstractItemModel::isSortable () const   [virtual]

Returns true if the items in the model can be sorted; otherwise returns false.

The base class implementation returns false.

See also sort().

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

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

This must be reimplemented if you want to extend the model with customized roles.

See also Role and data().

bool QAbstractItemModel::lessThan ( const QModelIndex & left, const QModelIndex & right ) const   [virtual]

Returns true if the data at index left is less than the data at index right; otherwise returns false.

See also equal() and greaterThan().

QModelIndexList QAbstractItemModel::match ( const QModelIndex & start, int role, const QVariant & value, int hits = 1, MatchFlags flags = MatchDefault ) const   [virtual]

Retuns a list of indexes for the items matching value in role role based on the flags. The list may be empty. The search starts from index start and continues until the number of matching data items equals hits or the search reaches the last row or start, depending on whether MatchWrap is specified in flags or not.

See also QAbstractItemModel::MatchFlag.

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

Returns the parent of the model item with the given index.

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

Removes count columns starting with column column under parent parent from the model. Returns true if the columns were successfully removed; otherwise returns false.

The base class implementation does nothing and returns false.

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

Removes count rows starting with row row under parent parent from the model. Returns true if the rows were successfully removed; otherwise returns false.

The base class implementation does nothing and returns false.

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

Returns the number of rows under the given parent.

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

This signal is emitted after rows have been inserted into the model. The new items are those between start and end inclusive, under the given parent item.

See also insertRows().

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

This signal is emitted just before rows are removed from the model. The removed items are those between start and end inclusive, under the given parent item.

See also removeRows().

bool QAbstractItemModel::setData ( const QModelIndex & index, int role, const QVariant & value )   [virtual]

Sets the role data for the item at index to value. Returns true if successful; otherwise returns false.

The base class implementation returns false. This function (and data()) must be reimplemented.

See also data() and itemData().

bool QAbstractItemModel::setData ( const QModelIndex & index, const QVariant & value )

This is an overloaded member function, provided for convenience. It behaves essentially like the above function.

Sets the EditRole role data for the item at index to value. Returns true if successful; otherwise returns false.

See also data() and itemData().

bool QAbstractItemModel::setItemData ( const QModelIndex & index, const QMap<int, QVariant> & roles )   [virtual]

For every Role in roles, sets the role data for the item at index to the associated value in roles. Returns true if successful; otherwise returns false.

See also setData(), data(), and itemData().

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

Returns the index of the sibling of the item at the given row, column, and index idx.

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

Sorts the model by column, if it is sortable, in the given order.

The base class implementation does nothing.

See also isSortable().


Copyright © 2004 Trolltech. Trademarks
Qt 4.0.0-tp1