From 91e86688fc119e1bb67fd40ab30101015ddb638b Mon Sep 17 00:00:00 2001 From: Martin Smith Date: Mon, 5 Aug 2013 10:23:00 +0200 Subject: [PATCH] qdoc: Clarify documentation of member functions When implementing a custom subclass of QAbstractItemModel, if the custom model will use MIME types other than the default internal MIME type, the mimeTypes() member must be reimplemented to return the list of allowed MIME types. If mimeTypes() is reimplemented, mimeData(), canDropMimeData(), and dropMimeData() must also be reimplemented to use the allowed MIME types. Task-number: QTBUG-32362 Change-Id: Iee5cf5d2dbed8a6c1f7ab47a7a4b9b03e80e8e59 Reviewed-by: Venugopal Shivashankar Reviewed-by: Jerome Pasion --- src/corelib/itemmodels/qabstractitemmodel.cpp | 170 ++++++++++-------- 1 file 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 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 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