QIfFilterAndBrowseModelInterface Class
The QIfFilterAndBrowseModelInterface defines the interface for backends to the QIfFilterAndBrowseModel feature class. More...
| Header: | #include <QIfFilterAndBrowseModelInterface> |
| qmake: | QT += interfaceframework |
| Inherits: | QIfPagingModelInterface |
Public Functions
| virtual QIfPendingReply<QString> | goBack(const QUuid &identifier) = 0 |
| virtual QIfPendingReply<QString> | goForward(const QUuid &identifier, int index) = 0 |
| virtual QIfPendingReply<int> | indexOf(const QUuid &identifier, const QVariant &item) = 0 |
| virtual QIfPendingReply<void> | insert(const QUuid &identifier, int index, const QVariant &item) = 0 |
| virtual QIfPendingReply<void> | move(const QUuid &identifier, int currentIndex, int newIndex) = 0 |
| virtual QIfPendingReply<void> | remove(const QUuid &identifier, int index) = 0 |
| virtual void | setContentType(const QUuid &identifier, const QString &contentType) = 0 |
| virtual void | setupFilter(const QUuid &identifier, QIfAbstractQueryTerm *term, const QList<QIfOrderTerm> &orderTerms) = 0 |
Signals
| void | availableContentTypesChanged(const QStringList &availableContentTypes) |
| void | canGoBackChanged(const QUuid &identifier, bool canGoBack) |
| void | canGoForwardChanged(const QUuid &identifier, const QVector<bool> &indexes, int start) |
| void | contentTypeChanged(const QUuid &identifier, const QString &contentType) |
| void | queryIdentifiersChanged(const QUuid &identifier, const QSet<QString> &queryIdentifiers) |
Protected Functions
| QSet<QString> | identifiersFromItem() |
Detailed Description
The QIfFilterAndBrowseModelInterface is the interface used by QIfFilterAndBrowseModel
The interface is discovered by a QIfFilterAndBrowseModel object, which connects to it and sets it up.
Implementing QIfFilterAndBrowseModelInterface follows the same pattern as described in QIfPagingModelInterface. In addition, the following features can be used by setting the respective capability.
Navigation
When implementing something like a Media Library, it is useful to support navigating through multiple hierarchies, for example: show all artists, select one and show all albums of that artist. See also the Browsing section of the QIfFilterAndBrowseModel.
The canGoForwardChanged() and the canGoBackChanged() signals let the QIfFilterAndBrowseModel know how it can navigate. The actual request to navigate forward or backward is done using the goForward() and goBack() functions.
The availableContentTypesChanged() signal needs to be emitted to define which types can be browsed in this backend and let the user select the starting point to browse from.
Once the user selected a content type, the setContentType function is called and the backend needs to inform about the new contentType using the contentTypeChanged signal.
If the backend supports navigating without saving the state of a model instance locally, the SupportsStatelessNavigation capability can be set.
Filtering and Sorting
To support sorting and filtering of the model content on the backend side, the respective capabilities need to be set: SupportsFiltering and SupportsSorting To also allow complex filtering, the SupportsAndConjunction and SupportsOrConjunction can be set in addition. See also the Filtering and Sorting section of the QIfFilterAndBrowseModel.
Once a content type has been set on the backend, the queryIdentifiersChanged() signal needs to be emitted to inform the frontend about all identifiers that can be used to filter and sort the model. For convenience, the identifiersFromItem() function can be used to return all properties of a QMetaObject based type. Afterwards the filter query can be set on the QIfFilterAndBrowseModel and will result in a call to setupFilter(). All following calls to retrieve the content of the model need to work on the filtered data.
Changing Model Data
To allow changing the Items within the model, the following capabilities can be set:
Calls to one of the updating functions in QIfFilterAndBrowseModel are forwarded to the matching function in the backend: insert, move and remove. All those functions need to emit the dataChanged signal.
See also QIfFilterAndBrowseModel.
Member Function Documentation
[signal] void QIfFilterAndBrowseModelInterface::availableContentTypesChanged(const QStringList &availableContentTypes)
Emitted during the initialization phase, to inform about all available content types(availableContentTypes).
The value is provided to the user as indication of which content types can be used.
Note: The QIfFilterAndBrowseModel doesn't check the validity of the contentType, this is the responsibility of the backend.
See also setContentType.
[signal] void QIfFilterAndBrowseModelInterface::canGoBackChanged(const QUuid &identifier, bool canGoBack)
Emitted to inform the QIfFilterAndBrowseModel instance, identified by identifier, whether it canGoBack to the data set previously shown. If the instance can display the previous data set, canGoBack is set to true.
See Browsing for more information on how this is used.
See also goBack.
[signal] void QIfFilterAndBrowseModelInterface::canGoForwardChanged(const QUuid &identifier, const QVector<bool> &indexes, int start)
Emitted to inform the QIfFilterAndBrowseModel instance identified by identifier that the following indexes can be used to show a new set of data.
The start parameter can be used to inform only about a limited set of indexes. This signal can be emitted during a QIfPagingModelInterface::fetchData() call to inform about the state of the just fetched data.
See Browsing for more information on how this is used.
See also goForward.
[signal] void QIfFilterAndBrowseModelInterface::contentTypeChanged(const QUuid &identifier, const QString &contentType)
Emitted as a result of a call to setContentType, to inform the QIfFilterAndBrowseModel instance identified by identifier about it's new contentType.
See also setContentType.
[pure virtual] QIfPendingReply<QString> QIfFilterAndBrowseModelInterface::goBack(const QUuid &identifier)
Requests to go back to the previous displayed data set of the QIfFilterAndBrowseModel instance identified by identifier.
The new content type is returned in the form of a QIfPendingReply. Once ready the new content type must be set using setSuccess(), or using setFailed() if there's an error.
See Browsing for more information on how this is used.
See also canGoBackChanged().
[pure virtual] QIfPendingReply<QString> QIfFilterAndBrowseModelInterface::goForward(const QUuid &identifier, int index)
Requests to go to the next data set of the QIfFilterAndBrowseModel instance identified by identifier at index.
The new content type is returned in the form of a QIfPendingReply. Once ready the new content type must be set using setSuccess(), or using setFailed() if there's an error.
See Browsing for more information on how this is used.
See also canGoForwardChanged().
[protected] template <typename T> QSet<QString> QIfFilterAndBrowseModelInterface::identifiersFromItem()
Returns all properties of type T.
These can registered as identifiers for the Qt Interface Framework Query Language using the queryIdentifiersChanged() signal.
[pure virtual] QIfPendingReply<int> QIfFilterAndBrowseModelInterface::indexOf(const QUuid &identifier, const QVariant &item)
Determines the index of item in the model identified by identifier.
[pure virtual] QIfPendingReply<void> QIfFilterAndBrowseModelInterface::insert(const QUuid &identifier, int index, const QVariant &item)
Adds the browsable item to the current dataset of the QIfFilterAndBrowseModel instance identified by identifier at index.
The provided item could be owned by another model or QML, because of that it's expected that the backend stores its internal representation.
See also dataChanged().
[pure virtual] QIfPendingReply<void> QIfFilterAndBrowseModelInterface::move(const QUuid &identifier, int currentIndex, int newIndex)
Moves the browsable item at position currentIndex of the current dataset of the QIfFilterAndBrowseModel instance identified by identifier to the new position newIndex.
See also dataChanged().
[signal] void QIfFilterAndBrowseModelInterface::queryIdentifiersChanged(const QUuid &identifier, const QSet<QString> &queryIdentifiers)
Emitted as a result of a call to setContentType, to inform the QIfFilterAndBrowseModel instance identified by identifier about the currently supported queryIdentifiers.
The queryIdentifiers are used to setup the Qt Interface Framework Query Language to be able to show meaningful errors for invalid queries. Not emitting this signal, will cause the Qt Interface Framework Query Language to not limit the possible identifiers.
[pure virtual] QIfPendingReply<void> QIfFilterAndBrowseModelInterface::remove(const QUuid &identifier, int index)
Removes the browsable item at position index from the current dataset of the QIfFilterAndBrowseModel instance identified by identifier.
See also dataChanged().
[pure virtual] void QIfFilterAndBrowseModelInterface::setContentType(const QUuid &identifier, const QString &contentType)
Sets the contentType of the QIfFilterAndBrowseModel instance identified by identifier. The given contenType can contain additional path information. The encoding is defined by the goForward() method. In case the contentType is not valid the error() signal should be used.
Note: The QIfFilterAndBrowseModel doesn't check the validity of the contentType, this is the backend's responsibility.
If the QIfFilterAndBrowseModel supports filtering (see QIfPagingModel::capabilitiesChanged), the backend needs to emit the queryIdentifiersChanged signal once the contentType is set.
Finally, the contentTypeChanged signal needs to be emitted, when the backend has set the contentType and it's ready for use.
Calls to this function are followed by calls to setupFilter() and fetchData().
See also identifiersFromItem, queryIdentifiersChanged, and contentTypeChanged.
[pure virtual] void QIfFilterAndBrowseModelInterface::setupFilter(const QUuid &identifier, QIfAbstractQueryTerm *term, const QList<QIfOrderTerm> &orderTerms)
Setup the filter for the QIfFilterAndBrowseModel instance identified by identifier.
The term and orderTerms arguments are representations of the query which is used for filtering and sorting. The term argument is a null-pointer when the backend doesn't support filtering and sorting or when no query was defined in the QIfFilterAndBrowseModel instance.
© 2023 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.