doc: document the proxy role types

proxyrole.cpp

@@ -9,10 +9,25 @@
 
 namespace qqsfpm {
 
+/*!
+    \qmltype ProxyRole
+    \inqmlmodule SortFilterProxyModel
+    \brief Base type for the \l SortFilterProxyModel proxy roles
+
+    The ProxyRole type cannot be used directly in a QML file.
+    It exists to provide a set of common properties and methods,
+    available across all the other proxy role types that inherit from it.
+    Attempting to use the ProxyRole type directly will result in an error.
+*/
 ProxyRole::ProxyRole(QObject *parent) : QObject(parent)
 {
 }
 
+/*!
+    \qmlproperty string ProxyRole::name
+
+    This property holds the role name of the proxy role.
+*/
 const QString& ProxyRole::name() const
 {
     return m_name;
@@ -49,6 +64,32 @@ void ProxyRole::invalidate()
     Q_EMIT invalidated();
 }
 
+/*!
+    \qmltype JoinRole
+    \inherits ProxyRole
+    \inqmlmodule SortFilterProxyModel
+    \brief a role made from concatenating other roles
+
+    A JoinRole is a simple \l ProxyRole that concatenates other roles.
+
+    In the following example, the \c fullName role is computed by the concatenation of the \c firstName role and the \c lastName role separated by a space :
+    \code
+    SortFilterProxyModel {
+       sourceModel: contactModel
+       proxyRoles: JoinRole {
+           name: "fullName"
+           roleNames: ["firstName", "lastName"]
+      }
+    }
+    \endcode
+
+*/
+
+/*!
+    \qmlproperty list<string> JoinRole::roleNames
+
+    This property holds the role names that are joined by this role.
+*/
 QStringList JoinRole::roleNames() const
 {
     return m_roleNames;
@@ -64,6 +105,13 @@ void JoinRole::setRoleNames(const QStringList& roleNames)
     invalidate();
 }
 
+/*!
+    \qmlproperty string JoinRole::separator
+
+    This property holds the separator that is used to join the roles specified in \l roleNames.
+
+    By default, it's a space.
+*/
 QString JoinRole::separator() const
 {
     return m_separator;
@@ -92,12 +140,44 @@ QVariant JoinRole::data(const QModelIndex &sourceIndex, const QQmlSortFilterProx
     return result;
 }
 
+/*!
+    \qmltype SwitchRole
+    \inherits ProxyRole
+    \inqmlmodule SortFilterProxyModel
+    \brief a role using \l Filter to conditionnaly compute its data
+
+    A SwitchRole is a \l ProxyRole that computes its data with the help of \l Filter.
+    Each top level filters specified in the \l SwitchRole is evaluated on the rows of the model, if a \l Filter evaluates to true, the data of the \l SwitchRole for this row will be the one of the attached \l {value} {SwitchRole.value} property.
+    If no top level filters evaluate to true, the data will default to the one of the \l defaultRoleName (or the \l defaultValue if no \l defaultRoleName is specified).
+
+    In the following example, the \c favoriteOrFirstNameSection role is equal to \c * if the \c favorite role of a row is true, otherwise it's the same as the \c firstName role :
+    \code
+    SortFilterProxyModel {
+       sourceModel: contactModel
+       proxyRoles: SwitchRole {
+           name: "favoriteOrFirstNameSection"
+           filters: ValueFilter {
+               roleName: "favorite"
+               value: true
+               SwitchRole.value: "*"
+           }
+           defaultRoleName: "firstName"
+        }
+    }
+    \endcode
+
+*/
 SwitchRoleAttached::SwitchRoleAttached(QObject* parent) : QObject (parent)
 {
     if (!qobject_cast<Filter*>(parent))
         qmlInfo(parent) << "SwitchRole must be attached to a Filter";
 }
 
+/*!
+    \qmlattachedproperty var SwitchRole::value
+
+    This property attaches a value to a \l Filter.
+*/
 QVariant SwitchRoleAttached::value() const
 {
     return m_value;
@@ -112,6 +192,12 @@ void SwitchRoleAttached::setValue(QVariant value)
     Q_EMIT valueChanged();
 }
 
+/*!
+    \qmlproperty string SwitchRole::defaultRoleName
+
+    This property holds the default role name of the role.
+    If no filter match a row, the data of this role will be the data of the role whose name is \c defaultRoleName.
+*/
 QString SwitchRole::defaultRoleName() const
 {
     return m_defaultRoleName;
@@ -127,6 +213,12 @@ void SwitchRole::setDefaultRoleName(const QString& defaultRoleName)
     invalidate();
 }
 
+/*!
+    \qmlproperty var SwitchRole::defaultValue
+
+    This property holds the default value of the role.
+    If no filter match a row, and no \l defaultRoleName is set, the data of this role will be \c defaultValue.
+*/
 QVariant SwitchRole::defaultValue() const
 {
     return m_defaultValue;
@@ -142,6 +234,14 @@ void SwitchRole::setDefaultValue(const QVariant& defaultValue)
     invalidate();
 }
 
+/*!
+    \qmlproperty list<Filter> SwitchRole::filters
+
+    This property holds the list of filters for this proxy role.
+    The data of this role will be equal to the attached \l {value} {SwitchRole.value} property of the first filter that matches the model row.
+
+    \sa Filter
+*/
 QQmlListProperty<Filter> SwitchRole::filters()
 {
     return QQmlListProperty<Filter>(this, &m_filters,
@@ -218,6 +318,41 @@ void SwitchRole::clear_filters(QQmlListProperty<Filter> *list)
     that->invalidate();
 }
 
+/*!
+    \qmltype ExpressionRole
+    \inherits ProxyRole
+    \inqmlmodule SortFilterProxyModel
+    \brief A custom role computed from a javascrip expression
+
+    An ExpressionRole is a \l ProxyRole allowing to implement a custom role based on a javascript expression.
+
+    In the following example, the \c c role is computed by adding the \c a role and \c b role of the model :
+    \code
+    SortFilterProxyModel {
+       sourceModel: numberModel
+       proxyRoles: ExpressionRole {
+           name: "c"
+           expression: model.a + model.b
+      }
+    }
+    \endcode
+*/
+
+/*!
+    \qmlproperty expression ExpressionRole::expression
+
+    An expression to implement a custom role.
+    It has the same syntax has a \l {http://doc.qt.io/qt-5/qtqml-syntax-propertybinding.html} {Property Binding} except it will be evaluated for each of the source model's rows.
+    The data for this role will be the retuned valued of the expression.
+    Data for each row is exposed like for a delegate of a QML View.
+
+    This expression is reevaluated for a row every time its model data changes.
+    When an external property (not \c index or in \c model) the expression depends on changes, the expression is reevaluated for every row of the source model.
+    To capture the properties the expression depends on, the expression is first executed with invalid data and each property access is detected by the QML engine.
+    This means that if a property is not accessed because of a conditional, it won't be captured and the expression won't be reevaluted when this property changes.
+
+    A workaround to this problem is to access all the properties the expressions depends unconditionally at the beggining of the expression.
+*/
 const QQmlScriptString& ExpressionRole::expression() const
 {
     return m_scriptString;

qqmlsortfilterproxymodel.cpp

@@ -188,6 +188,13 @@ QQmlListProperty<Sorter> QQmlSortFilterProxyModel::sorters()
                                     &QQmlSortFilterProxyModel::clear_sorters);
 }
 
+/*!
+    \qmlproperty list<ProxyRole> SortFilterProxyModel::proxyRoles
+
+    This property holds the list of proxy roles for this proxy model. Each proxy role adds a new custom role to the model.
+
+    \sa ProxyRole
+*/
 QQmlListProperty<ProxyRole> QQmlSortFilterProxyModel::proxyRoles()
 {
     return QQmlListProperty<ProxyRole>(this, &m_proxyRoles,