QIfFilterAndBrowseModel Class
The QIfFilterAndBrowseModel is a generic model which can be used to search, browse, filter and sort data. More...
Header: | #include <QIfFilterAndBrowseModel> |
qmake: | QT += interfaceframework |
In QML: | FilterAndBrowseModel |
Inherits: | QIfPagingModel |
Public Types
enum | NavigationType { InModelNavigation, OutOfModelNavigation } |
enum | Roles { CanGoForwardRole } |
Properties
- availableContentTypes : const QStringList
- canGoBack : const bool
- contentType : QString
- query : QString
Public Functions
QIfFilterAndBrowseModel(QObject *parent = nullptr) | |
QStringList | availableContentTypes() const |
bool | canGoBack() const |
bool | canGoForward(int i) const |
QString | contentType() const |
void | goBack() |
QIfFilterAndBrowseModel * | goForward(int i, QIfFilterAndBrowseModel::NavigationType navigationType) |
QIfPendingReply<int> | indexOf(const QVariant &variant) |
QIfPendingReply<void> | insert(int index, const QVariant &variant) |
QIfPendingReply<void> | move(int cur_index, int new_index) |
QString | query() const |
QIfPendingReply<void> | remove(int index) |
void | setContentType(const QString &contentType) |
void | setQuery(const QString &query) |
Reimplemented Public Functions
virtual QVariant | data(const QModelIndex &index, int role) const override |
virtual QHash<int, QByteArray> | roleNames() const override |
Signals
void | availableContentTypesChanged(const QStringList &availableContentTypes) |
void | canGoBackChanged(bool canGoBack) |
void | contentTypeChanged(const QString &contentType) |
void | queryChanged(const QString &query) |
Reimplemented Protected Functions
virtual void | clearServiceObject() override |
virtual void | connectToServiceObject(QIfServiceObject *serviceObject) override |
Detailed Description
The QIfFilterAndBrowseModel should be used directly or as a base class whenever a lot of data needs to be presented in a ListView.
The model is built upon the basic principle of filtering and sorting the data already where they are created instead of retrieving everything and sort or filter it locally. In addition the QIfFilterAndBrowseModel only fetches the data it really needs and can it can be configured how this can be done.
The backend filling the model with data needs to implement the QIfFilterAndBrowseModelInterface class.
Setting it up
The QIfFilterAndBrowseModel is using QtInterfaceFramework's Dynamic Backend System and is derived from QIfAbstractFeatureListModel. Other than most "QtInterfaceFramework Feature classes", the QIfFilterAndBrowseModel doesn't automatically connect to available backends.
The easiest approach to set it up, is to connect to the same backend used by another feature. E.g. for connecting to the media backend, use the instance from the mediaplayer feature:
QIfMediaPlayer *player = new QIfMediaPlayer(); player->startAutoDiscovery(); QIfFilterAndBrowseModel *model = new QIfFilterAndBrowseModel(); model->setServiceObject(player->serviceObject());
Content Types
Once the model is connected to a backend, the contentType needs to be selected. All possible content types can be queried from the availableContentTypes property. As the name already suggests, this property selects what type of content should be shown in the model. For the mediaplayer example, the available content types could be "track", "album" and "artist".
Filtering and Sorting
One of the main use case of the QIfFilterAndBrowseModel is to provide a powerful way of filtering and sorting the content of the underlying data model. As explained above, the filtering and sorting is supposed to happen where the data is produced. To make this work across multiple backends the Qt Interface Framework Query Language was invented.
The query property is used to sort the content of the model: e.g. by setting the string "[/name]", the content will be sorted by name in ascending order.
For filtering, the same property is used but without the brackets e.g. "name='Example Item'" for only showing items which have the 'name' property set to 'Example Item'.
Filtering and sorting can also be combined in one string and the filter part can also be more complex. More on that can be found in the detailed Qt Interface Framework Query Language Documentation.
Browsing
In addition to filtering and sorting, the QIfFilterAndBrowseModel also supports browsing through a hierarchy of different content types. The easiest way to explain this is to look at the existing media example.
When implementing a library view of all available media files, you might want to provide a way for the user to browse through the media database and select a song. You might also want to provide several staring points and from there limit the results. E.g.
- Artist -> Album -> Track
- Album -> Track
- Track
This can be achieved by defining a complex filter query which takes the previously selected item into account. That is the most powerful way of doing it, as the developer/designer can define the browsing order and it can easily be changed. The downside of this is that the backend needs to support this way of filtering and sorting as well, which is not always be the case. A good example here is a DLNA backend, where the server already defines a fixed browsing order.
The QIfFilterAndBrowseModel provides the following methods for browsing:
- canGoForward()
- goForward()
- canGoBack()
- goBack()
Navigation Types
The QIfFilterAndBrowseModel supports two navigation types when browsing through the available data: for most use cases the simple InModelNavigation type is sufficient. By using this, the content type of the current model instance changes when navigating and the model is reset to show the new data. The other navigation type is OutOfModelNavigation and leaves the current model instance as it is. Instead the goForward() method returns a new model instance which contains the new data. This is especially useful when several views need to be open at the same time. E.g. when used inside a QML StackView.
QIfFilterAndBrowseModel *artistModel = new QIfFilterAndBrowseModel(); model->setContentType("artist"); //Returns a new instance of QIfFilterAndBrowseModel which contains all albums from the artist at index '0' QIfFilterAndBrowseModel *albumModel = artistModel->goForward(0, QIfFilterAndBrowseModel::OutOfModelNavigation);
Note: Please also see the QIfPagingModel documentation for how the data loading works and the Models section for more information about all models in QtInterfaceFramework.
Member Type Documentation
enum QIfFilterAndBrowseModel::NavigationType
Constant | Value | Description |
---|---|---|
QIfFilterAndBrowseModel::InModelNavigation | 0 | The new content will be loaded into this model and the existing model data will be reset |
QIfFilterAndBrowseModel::OutOfModelNavigation | 1 | A new model will be returned which loads the new content. The model data of this model will not be changed and can still be used. |
enum QIfFilterAndBrowseModel::Roles
Constant | Value | Description |
---|---|---|
QIfFilterAndBrowseModel::CanGoForwardRole | QIfPagingModel::LastRole + 1 | True if this item can be used to go one level forward and display the next set of items. See also goForward() |
See also QIfPagingModel::Roles.
Property Documentation
[read-only]
availableContentTypes : const QStringList
Holds all the available content types
Access functions:
QStringList | availableContentTypes() const |
Notifier signal:
void | availableContentTypesChanged(const QStringList &availableContentTypes) |
See also contentType.
[read-only]
canGoBack : const bool
Holds whether the goBack() function can be used to return to the previous content.
See Browsing for more information.
Access functions:
bool | canGoBack() const |
Notifier signal:
void | canGoBackChanged(bool canGoBack) |
contentType : QString
Holds the current type of content displayed in this model.
Note: When changing this property the content will be reset.
Access functions:
QString | contentType() const |
void | setContentType(const QString &contentType) |
Notifier signal:
void | contentTypeChanged(const QString &contentType) |
See also availableContentTypes.
query : QString
Holds the current query used for filtering and sorting the current content of the model.
Note: When changing this property the content will be reset.
See Qt Interface Framework Query Language for more information.
Access functions:
QString | query() const |
void | setQuery(const QString &query) |
Notifier signal:
void | queryChanged(const QString &query) |
See also FilteringAndSorting.
Member Function Documentation
[explicit]
QIfFilterAndBrowseModel::QIfFilterAndBrowseModel(QObject *parent = nullptr)
Constructs a QIfFilterAndBrowseModel.
The parent argument is passed on to the QIfAbstractFeatureListModel base class.
[invokable]
bool QIfFilterAndBrowseModel::canGoForward(int i) const
Returns true when the item at index i can be used to show the next set of elements.
See also Browsing for more information.
Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.
[override virtual protected]
void QIfFilterAndBrowseModel::clearServiceObject()
Reimplements: QIfPagingModel::clearServiceObject().
[override virtual protected]
void QIfFilterAndBrowseModel::connectToServiceObject(QIfServiceObject *serviceObject)
Reimplements: QIfPagingModel::connectToServiceObject(QIfServiceObject *serviceObject).
[override virtual]
QVariant QIfFilterAndBrowseModel::data(const QModelIndex &index, int role) const
Reimplements: QIfPagingModel::data(const QModelIndex &index, int role) const.
[invokable]
void QIfFilterAndBrowseModel::goBack()
Goes one level back in the navigation history.
See also Browsing for more information.
Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.
[invokable]
QIfFilterAndBrowseModel *QIfFilterAndBrowseModel::goForward(int i, QIfFilterAndBrowseModel::NavigationType navigationType)
Returns true when the item at index i can be used to show the next set of elements.
Uses the item at index i and shows the next set of items. The navigationType can be used to control whether the new data should be shown in this model instance or whether a new instance should be created and returned. If a instance is returned, this instance is owned by the caller.
Note: Whether the OutOfModelNavigation navigation type is supported is decided by the backend.
See also Browsing for more information.
Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.
[invokable]
QIfPendingReply<int> QIfFilterAndBrowseModel::indexOf(const QVariant &variant)
Determines the index of variant in this model.
The result is returned as a QIfPendingReply.
Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.
[invokable]
QIfPendingReply<void> QIfFilterAndBrowseModel::insert(int index, const QVariant &variant)
Insert the variant at the position index.
If the backend doesn't accept the provided item, this operation will end in a no op.
The returned QIfPendingReply notifies about when the action has been done or whether it failed.
Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.
[invokable]
QIfPendingReply<void> QIfFilterAndBrowseModel::move(int cur_index, int new_index)
Moves the item at position cur_index to the new position new_index.
The returned QIfPendingReply notifies about when the action has been done or whether it failed.
Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.
[invokable]
QIfPendingReply<void> QIfFilterAndBrowseModel::remove(int index)
Removes the item at position index.
The returned QIfPendingReply notifies about when the action has been done or whether it failed.
Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.
[override virtual]
QHash<int, QByteArray> QIfFilterAndBrowseModel::roleNames() const
Reimplements: QIfPagingModel::roleNames() const.
© 2024 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.