diff options
| -rw-r--r-- | src/corelib/itemmodels/qabstractitemmodel.cpp | 170 |
1 files changed, 94 insertions, 76 deletions
diff --git a/src/corelib/itemmodels/qabstractitemmodel.cpp b/src/corelib/itemmodels/qabstractitemmodel.cpp index 4162e843a7..9791a02723 100644 --- a/src/corelib/itemmodels/qabstractitemmodel.cpp +++ b/src/corelib/itemmodels/qabstractitemmodel.cpp @@ -160,8 +160,8 @@ QPersistentModelIndex::~QPersistentModelIndex() } /*! - Returns true if this persistent model index is equal to the \a other - persistent model index; otherwise returns false. + Returns \c{true} if this persistent model index is equal to the \a other + persistent model index; otherwise returns \c{false}. All values in the persistent model index are used when comparing with another persistent model index. @@ -177,8 +177,8 @@ bool QPersistentModelIndex::operator==(const QPersistentModelIndex &other) const /*! \since 4.1 - Returns true if this persistent model index is smaller than the \a other - persistent model index; otherwise returns false. + Returns \c{true} if this persistent model index is smaller than the \a other + persistent model index; otherwise returns \c{false}. All values in the persistent model index are used when comparing with another persistent model index. @@ -196,8 +196,8 @@ bool QPersistentModelIndex::operator<(const QPersistentModelIndex &other) const \fn bool QPersistentModelIndex::operator!=(const QPersistentModelIndex &other) const \since 4.2 - Returns true if this persistent model index is not equal to the \a - other persistent model index; otherwise returns false. + Returns \c{true} if this persistent model index is not equal to the \a + other persistent model index; otherwise returns \c{false}. */ /*! @@ -258,8 +258,8 @@ QPersistentModelIndex::operator const QModelIndex&() const /*! \fn bool QPersistentModelIndex::operator==(const QModelIndex &other) const - Returns true if this persistent model index refers to the same location as - the \a other model index; otherwise returns false. + Returns \c{true} if this persistent model index refers to the same location as + the \a other model index; otherwise returns \c{false}. All values in the persistent model index are used when comparing with another model index. @@ -275,8 +275,8 @@ bool QPersistentModelIndex::operator==(const QModelIndex &other) const /*! \fn bool QPersistentModelIndex::operator!=(const QModelIndex &other) const - Returns true if this persistent model index does not refer to the same - location as the \a other model index; otherwise returns false. + Returns \c{true} if this persistent model index does not refer to the same + location as the \a other model index; otherwise returns \c{false}. */ bool QPersistentModelIndex::operator!=(const QModelIndex &other) const @@ -423,8 +423,8 @@ const QAbstractItemModel *QPersistentModelIndex::model() const /*! \fn bool QPersistentModelIndex::isValid() const - Returns true if this persistent model index is valid; otherwise returns - false. + Returns \c{true} if this persistent model index is valid; otherwise returns + \c{false}. A valid index belongs to a model, and has non-negative row and column numbers. @@ -522,7 +522,7 @@ static uint typeOfVariant(const QVariant &value) /*! \internal - return true if \a value contains a numerical type + Return \c{true} if \a value contains a numerical type. This function is used by our Q{Tree,Widget,Table}WidgetModel classes to sort. */ @@ -984,7 +984,7 @@ void QAbstractItemModel::resetInternalData() /*! \fn bool QModelIndex::isValid() const - Returns true if this model index is valid; otherwise returns false. + Returns \c{true} if this model index is valid; otherwise returns \c{false}. A valid index belongs to a model, and has non-negative row and column numbers. @@ -1041,8 +1041,8 @@ void QAbstractItemModel::resetInternalData() /*! \fn bool QModelIndex::operator==(const QModelIndex &other) const - Returns true if this model index refers to the same location as the - \a other model index; otherwise returns false. + Returns \c{true} if this model index refers to the same location as the + \a other model index; otherwise returns \c{false}. All values in the model index are used when comparing with another model index. @@ -1052,8 +1052,8 @@ void QAbstractItemModel::resetInternalData() /*! \fn bool QModelIndex::operator!=(const QModelIndex &other) const - Returns true if this model index does not refer to the same location as - the \a other model index; otherwise returns false. + Returns \c{true} if this model index does not refer to the same location as + the \a other model index; otherwise returns \c{false}. */ @@ -1113,7 +1113,7 @@ void QAbstractItemModel::resetInternalData() Items can be queried with flags() (see \l 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 + If an item has child objects, hasChildren() returns \c{true} for the corresponding index. The model has a rowCount() and a columnCount() for each level of the @@ -1236,7 +1236,7 @@ void QAbstractItemModel::resetInternalData() Inserts a single column before the given \a column in the child items of the \a parent specified. - Returns true if the column is inserted; otherwise returns false. + Returns \c{true} if the column is inserted; otherwise returns \c{false}. \sa insertColumns(), insertRow(), removeColumn() */ @@ -1249,7 +1249,7 @@ void QAbstractItemModel::resetInternalData() \note This function calls the virtual method insertRows. - Returns true if the row is inserted; otherwise returns false. + Returns \c{true} if the row is inserted; otherwise returns \c{false}. \sa insertRows(), insertColumn(), removeRow() */ @@ -1284,7 +1284,7 @@ void QAbstractItemModel::resetInternalData() Removes the given \a column from the child items of the \a parent specified. - Returns true if the column is removed; otherwise returns false. + Returns \c{true} if the column is removed; otherwise returns \c{false}. \sa removeColumns(), removeRow(), insertColumn() */ @@ -1294,7 +1294,7 @@ void QAbstractItemModel::resetInternalData() Removes the given \a row from the child items of the \a parent specified. - Returns true if the row is removed; otherwise returns false. + Returns \c{true} if the row is removed; otherwise returns \c{false}. This is a convenience function that calls removeRows(). The QAbstractItemModel implementation of removeRows() does nothing. @@ -1308,8 +1308,8 @@ void QAbstractItemModel::resetInternalData() On models that support this, moves \a sourceColumn from \a sourceParent to \a destinationChild under \a destinationParent. - Returns true if the columns were successfully moved; otherwise returns - false. + Returns \c{true} if the columns were successfully moved; otherwise returns + \c{false}. \sa moveRows(), moveColumn() */ @@ -1320,8 +1320,8 @@ void QAbstractItemModel::resetInternalData() On models that support this, moves \a sourceColumn from \a sourceParent to \a destinationChild under \a destinationParent. - Returns true if the columns were successfully moved; otherwise returns - false. + Returns \c{true} if the columns were successfully moved; otherwise returns + \c{false}. \sa moveColumns(), moveRow() */ @@ -1663,8 +1663,8 @@ QAbstractItemModel::~QAbstractItemModel() */ /*! - Returns true if the model returns a valid QModelIndex for \a row and - \a column with \a parent, otherwise returns false. + Returns \c{true} if the model returns a valid QModelIndex for \a row and + \a column with \a parent, otherwise returns \c{false}. */ bool QAbstractItemModel::hasIndex(int row, int column, const QModelIndex &parent) const { @@ -1675,7 +1675,7 @@ bool QAbstractItemModel::hasIndex(int row, int column, const QModelIndex &parent /*! - Returns true if \a parent has any children; otherwise returns false. + Returns \c{true} if \a parent has any children; otherwise returns \c{false}. Use rowCount() on the parent to find out the number of children. @@ -1732,12 +1732,12 @@ QMap<int, QVariant> QAbstractItemModel::itemData(const QModelIndex &index) const /*! Sets the \a role data for the item at \a index to \a value. - Returns true if successful; otherwise returns false. + Returns \c{true} if successful; otherwise returns \c{false}. The dataChanged() signal should be emitted if the data was successfully set. - The base class implementation returns false. This function and data() must + The base class implementation returns \c{false}. This function and data() must be reimplemented for editable models. \sa Qt::ItemDataRole, data(), itemData() @@ -1766,7 +1766,7 @@ bool QAbstractItemModel::setData(const QModelIndex &index, const QVariant &value Sets the role data for the item at \a index to the associated value in \a roles, for every Qt::ItemDataRole. - Returns true if successful; otherwise returns false. + Returns \c{true} if successful; otherwise returns \c{false}. Roles that are not in \a roles will not be modified. @@ -1781,10 +1781,19 @@ bool QAbstractItemModel::setItemData(const QModelIndex &index, const QMap<int, Q } /*! - Returns a list of MIME types that can be used to describe a list of model - indexes. + Returns the list of allowed MIME types. By default, the built-in + models and views use an internal MIME type: + \c{application/x-qabstractitemmodeldatalist}. - \sa mimeData() + When implementing drag and drop support in a custom model, if you + will return data in formats other than the default internal MIME + type, reimplement this function to return your list of MIME types. + + If you reimplement this function in your custom model, you must + also reimplement the member functions that call it: mimeData() and + dropMimeData(). + + \sa mimeData(), dropMimeData() */ QStringList QAbstractItemModel::mimeTypes() const { @@ -1795,11 +1804,14 @@ QStringList QAbstractItemModel::mimeTypes() const /*! Returns an object that contains serialized items of data corresponding to - the list of \a indexes specified. The formats used to describe the encoded - data is obtained from the mimeTypes() function. + the list of \a indexes specified. The format used to describe the encoded + data is obtained from the mimeTypes() function. This default implementation + uses the default MIME type returned by the default implementation of + mimeTypes(). If you reimplement mimeTypes() in your custom model to return + more MIME types, reimplement this function to make use of them. - If the list of indexes is empty, or there are no supported MIME types, 0 is - returned rather than a serialized empty list. + If the list of \a indexes is empty, or there are no supported MIME types, 0 + is returned rather than a serialized empty list. \sa mimeTypes(), dropMimeData() */ @@ -1820,13 +1832,13 @@ QMimeData *QAbstractItemModel::mimeData(const QModelIndexList &indexes) const } /*! - Returns whether a model can accept a drop of data. + Returns \c{true} if a model can accept a drop of the \a data. This + default implementation always returns \c{true}. - This can be used to indicate whether a drop of certain data is allowed, for example - by using a 'forbidden' emblem on a mouse cursor during a drag operation. - - This method returns true by default. Reimplementations can return whether the - \a data can be dropped at \a row, \a column, \a parent with \a action. + Reimplement this function in your custom model, if you want to + test whether the \a data can be dropped at \a row, \a column, + \a parent with \a action. If you don't need that test, it is not + necessary to reimplement this function. \sa dropMimeData(), {Using drag and drop with item views} */ @@ -1846,8 +1858,8 @@ bool QAbstractItemModel::canDropMimeData(const QMimeData *data, Qt::DropAction a Handles the \a data supplied by a drag and drop operation that ended with the given \a action. - Returns true if the data and action can be handled by the model; otherwise - returns false. + Returns \c{true} if the data and action were handled by the model; otherwise + returns \c{false}. The specified \a row, \a column and \a parent indicate the location of an item in the model where the operation ended. It is the responsibility of @@ -1859,10 +1871,16 @@ bool QAbstractItemModel::canDropMimeData(const QMimeData *data, Qt::DropAction a When \a row and \a column are -1 it means that the dropped data should be considered as dropped directly on \a parent. Usually this will mean - appending the data as child items of \a parent. If \a row and column are + appending the data as child items of \a parent. If \a row and \a column are greater than or equal zero, it means that the drop occurred just before the specified \a row and \a column in the specified \a parent. + The mimeTypes() member is called to get the list of acceptable MIME types. + This default implementation assumes the default implementation of mimeTypes(), + which returns a single default MIME type. If you reimplement mimeTypes() in + your custom model to return multiple MIME types, you must reimplement this + function to make use of them. + \sa supportedDropActions(), canDropMimeData(), {Using drag and drop with item views} */ bool QAbstractItemModel::dropMimeData(const QMimeData *data, Qt::DropAction action, @@ -1950,7 +1968,7 @@ void QAbstractItemModel::doSetSupportedDragActions(Qt::DropActions actions) /*! \note The base class implementation of this function does nothing and - returns false. + returns \c{false}. On models that support this, inserts \a count rows into the model before the given \a row. Items in the new row will be children of the item @@ -1964,8 +1982,8 @@ void QAbstractItemModel::doSetSupportedDragActions(Qt::DropActions actions) If \a parent has no children, a single column with \a count rows is inserted. - Returns true if the rows were successfully inserted; otherwise returns - false. + Returns \c{true} if the rows were successfully inserted; otherwise returns + \c{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 @@ -1993,10 +2011,10 @@ bool QAbstractItemModel::insertRows(int, int, const QModelIndex &) If \a parent has no children, a single row with \a count columns is inserted. - Returns true if the columns were successfully inserted; otherwise returns - false. + Returns \c{true} if the columns were successfully inserted; otherwise returns + \c{false}. - The base class implementation does nothing and returns false. + The base class implementation does nothing and returns \c{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 @@ -2013,10 +2031,10 @@ bool QAbstractItemModel::insertColumns(int, int, const QModelIndex &) On models that support this, removes \a count rows starting with the given \a row under parent \a parent from the model. - Returns true if the rows were successfully removed; otherwise returns - false. + Returns \c{true} if the rows were successfully removed; otherwise returns + \c{false}. - The base class implementation does nothing and returns false. + The base class implementation does nothing and returns \c{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 @@ -2034,10 +2052,10 @@ bool QAbstractItemModel::removeRows(int, int, const QModelIndex &) On models that support this, removes \a count columns starting with the given \a column under parent \a parent from the model. - Returns true if the columns were successfully removed; otherwise returns - false. + Returns \c{true} if the columns were successfully removed; otherwise returns + \c{false}. - The base class implementation does nothing and returns false. + The base class implementation does nothing and returns \c{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 @@ -2056,10 +2074,10 @@ bool QAbstractItemModel::removeColumns(int, int, const QModelIndex &) \a sourceRow under parent \a sourceParent to row \a destinationChild under parent \a destinationParent. - Returns true if the rows were successfully moved; otherwise returns - false. + Returns \c{true} if the rows were successfully moved; otherwise returns + \c{false}. - The base class implementation does nothing and returns false. + The base class implementation does nothing and returns \c{false}. If you implement your own model, you can reimplement this function if you want to support moving. Alternatively, you can provide your own API for @@ -2077,10 +2095,10 @@ bool QAbstractItemModel::moveRows(const QModelIndex &, int , int , const QModelI \a sourceColumn under parent \a sourceParent to column \a destinationChild under parent \a destinationParent. - Returns true if the columns were successfully moved; otherwise returns - false. + Returns \c{true} if the columns were successfully moved; otherwise returns + \c{false}. - The base class implementation does nothing and returns false. + The base class implementation does nothing and returns \c{false}. If you implement your own model, you can reimplement this function if you want to support moving. Alternatively, you can provide your own API for @@ -2109,10 +2127,10 @@ void QAbstractItemModel::fetchMore(const QModelIndex &) } /*! - Returns true if there is more data available for \a parent; otherwise - returns false. + Returns \c{true} if there is more data available for \a parent; otherwise + returns \c{false}. - The default implementation always returns false. + The default implementation always returns \c{false}. If canFetchMore() returns true, the fetchMore() function should be called. This is the behavior of QAbstractItemView, for example. @@ -2310,7 +2328,7 @@ QHash<int,QByteArray> QAbstractItemModel::roleNames() const 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. + Returns \c{true} if there is no error; otherwise returns \c{false}. \sa revert() */ @@ -2355,7 +2373,7 @@ QVariant QAbstractItemModel::headerData(int section, Qt::Orientation orientation Sets the data for the given \a role and \a section in the header with the specified \a orientation to the \a value supplied. - Returns true if the header's data was updated; otherwise returns false. + Returns \c{true} if the header's data was updated; otherwise returns \c{false}. When reimplementing this function, the headerDataChanged() signal must be emitted explicitly. @@ -2682,7 +2700,7 @@ bool QAbstractItemModelPrivate::allowMove(const QModelIndex &srcParent, int star you must ensure that the \a destinationChild is not within the range of \a sourceFirst and \a sourceLast + 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 + This method returns \c{false} if either condition is true, in which case you should abort your move operation. \table 80% @@ -2949,7 +2967,7 @@ void QAbstractItemModel::endRemoveColumns() you must ensure that the \a destinationChild is not within the range of \a sourceFirst and \a sourceLast + 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 + This method returns \c{false} if either condition is true, in which case you should abort your move operation. \sa endMoveColumns() @@ -3596,8 +3614,8 @@ bool QAbstractListModel::dropMimeData(const QMimeData *data, Qt::DropAction acti \fn bool QModelIndex::operator<(const QModelIndex &other) const \since 4.1 - Returns true if this model index is smaller than the \a other - model index; otherwise returns false. + Returns \c{true} if this model index is smaller than the \a other + model index; otherwise returns \c{false}. The less than calculation is not directly useful to developers - the way that indexes with different parents compare is not defined. This operator only exists so that the |