Document QAbstractItemModels::roleNames() better.

List all of the default role names, and mention that the function
must be overridden if the model is used within QML.

Change-Id: I6ced5ac74143dcb97c527da2a6a23aa9d21f70e5
Reviewed-by: J-P Nurmi <jpnurmi@digia.com>
Reviewed-by: Stephen Kelly <stephen.kelly@kdab.com>

1 files changed, 28 insertions, 0 deletions

diff --git a/src/corelib/itemmodels/qabstractitemmodel.cpp b/src/corelib/itemmodels/qabstractitemmodel.cpp
index ab257a996d..4241fe08ca 100644
--- a/src/corelib/itemmodels/qabstractitemmodel.cpp
+++ b/src/corelib/itemmodels/qabstractitemmodel.cpp
@@ -2334,6 +2334,31 @@ void QAbstractItemModel::doSetRoleNames(const QHash<int,QByteArray> &roleNames)
 
     Returns the model's role names.
 
+    The default role names set by Qt are:
+
+    \table
+    \header
+    \li Qt Role
+    \li QML Role Name
+    \row
+    \li Qt::DisplayRole
+    \li display
+    \row
+    \li Qt::DecorationRole
+    \li decoration
+    \row
+    \li Qt::EditRole
+    \li edit
+    \row
+    \li Qt::ToolTipRole
+    \li toolTip
+    \row
+    \li Qt::StatusTipRole
+    \li statusTip
+    \row
+    \li Qt::WhatsThisRole
+    \li whatsThis
+    \endtable
 */
 QHash<int,QByteArray> QAbstractItemModel::roleNames() const
 {
@@ -3378,6 +3403,9 @@ Qt::ItemFlags QAbstractTableModel::flags(const QModelIndex &index) const
     of the rowCount() and data() functions. Well behaved models also provide
     a headerData() implementation.
 
+    If your model is used within QML and requires roles other than the
+    default ones provided by the roleNames() function, you must override it.
+
     For editable list models, you must also provide an implementation of
     setData(), implement the flags() function so that it returns a value
     containing \l{Qt::ItemFlags}{Qt::ItemIsEditable}.