QIviSearchAndBrowseModel Class

The QIviSearchAndBrowseModel is a generic model which can be used to search, browse, filter and sort data. More...

Header: #include <QIviSearchAndBrowseModel>
qmake: QT += ivicore
Instantiated By: SearchAndBrowseModel
Inherits: QIviAbstractFeatureListModel

Public Types

flags Capabilities
enum Capability { NoExtras, SupportsFiltering, SupportsSorting, SupportsAndConjunction, ..., SupportsRemove }
enum LoadingType { FetchMore, DataChanged }
enum NavigationType { InModelNavigation, OutOfModelNavigation }
enum Roles { NameRole, TypeRole, ItemRole, CanGoForwardRole }

Properties

Public Functions

QIviSearchAndBrowseModel(QObject *parent = nullptr)
~QIviSearchAndBrowseModel()
T at(int i) const
QStringList availableContentTypes() const
bool canGoBack() const
bool canGoForward(int i) const
QIviSearchAndBrowseModel::Capabilities capabilities() const
int chunkSize() const
QString contentType() const
int fetchMoreThreshold() const
QVariant get(int i) const
void goBack()
QIviSearchAndBrowseModel *goForward(int i, QIviSearchAndBrowseModel::NavigationType navigationType)
void indexOf(const QVariant &variant, const QJSValue &functor)
void insert(int index, const QVariant &variant)
QIviSearchAndBrowseModel::LoadingType loadingType() const
void move(int cur_index, int new_index)
QString query() const
void remove(int index)
void setChunkSize(int chunkSize)
void setContentType(const QString &contentType)
void setFetchMoreThreshold(int fetchMoreThreshold)
void setLoadingType(QIviSearchAndBrowseModel::LoadingType loadingType)
void setQuery(const QString &query)

Reimplemented Public Functions

virtual bool canFetchMore(const QModelIndex &parent) const override
virtual QVariant data(const QModelIndex &index, int role) const override
virtual void fetchMore(const QModelIndex &parent) override
virtual QHash<int, QByteArray> roleNames() const override
virtual int rowCount(const QModelIndex &parent = QModelIndex()) const override

Signals

void availableContentTypesChanged(const QStringList &availableContentTypes)
void canGoBackChanged(bool canGoBack)
void capabilitiesChanged(QIviSearchAndBrowseModel::Capabilities capabilities)
void chunkSizeChanged(int chunkSize)
void contentTypeChanged(const QString &contentType)
void countChanged()
void fetchMoreThresholdChanged(int fetchMoreThreshold)
void fetchMoreThresholdReached() const
void loadingTypeChanged(QIviSearchAndBrowseModel::LoadingType loadingType)
void queryChanged(const QString &query)

Reimplemented Protected Functions

virtual bool acceptServiceObject(QIviServiceObject *serviceObject) override
virtual void clearServiceObject() override
virtual void connectToServiceObject(QIviServiceObject *serviceObject) override
virtual void disconnectFromServiceObject(QIviServiceObject *serviceObject) override

Additional Inherited Members

Detailed Description

The QIviSearchAndBrowseModel is a generic model which can be used to search, browse, filter and sort data.

The QIviSearchAndBrowseModel 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 QIviSearchAndBrowseModel 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 QIviSearchAndBrowseModelInterface class.

Setting it up

The QIviSearchAndBrowseModel is using QtIviCore's Dynamic Backend System and is derived from QIviAbstractFeatureListModel. Other than most "QtIvi Feature classes", the QIviSearchAndBrowseModel 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:

QIviMediaPlayer *player = new QIviMediaPlayer();
player->startAutoDiscovery();
QIviSearchAndBrowseModel *model = new QIviSearchAndBrowseModel();
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 QIviSearchAndBrowseModel 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 IVI 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 IVI Query Language Documentation.

Browsing

In addition to filtering and sorting, the QIviSearchAndBrowseModel 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 QIviSearchAndBrowseModel provides the following methods for browsing:

Navigation Types

The QIviSearchAndBrowseModel 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.

QIviSearchAndBrowseModel *artistModel = new QIviSearchAndBrowseModel();
model->setContentType("artist");
//Returns a new instance of QIviSearchAndBrowseModel which contains all albums from the artist at index '0'
QIviSearchAndBrowseModel *albumModel = artistModel->goForward(0, QIviSearchAndBrowseModel::OutOfModelNavigation);

Loading Types

Multiple loading types are supported, as the QIviSearchAndBrowseModel is made to work with asynchrounous requests to fetch its data. The FetchMore loading type is the default and is using the canFetchMore()/fetchMore() functions of QAbstractItemModel to fetch new data once the view hits the end of the currently available data. As fetching can take some time, there is the fetchMoreThreshold property which controls how much in advance a new fetch should be started.

The other loading type is DataChanged. In contrast to FetchMore, the complete model is pre-populated with empty rows and the actual data for a specific row is fetched the first time the data() function is called. Once the data is available, the dataChanged() signal will be triggered for this row and the view will start to render the new data.

Please see the documentation of LoadingType for more details on how the modes work and when they are suitable to use.

Member Type Documentation

enum QIviSearchAndBrowseModel::Capability
flags QIviSearchAndBrowseModel::Capabilities

ConstantValueDescription
QIviSearchAndBrowseModel::NoExtras0x0The backend does only support the minimum feature set and is stateful.
QIviSearchAndBrowseModel::SupportsFiltering0x1The backend supports filtering of the content. QIviSearchAndBrowseModelInterface::availableContentTypes() and QIviSearchAndBrowseModelInterface::supportedIdentifiers() will be used as input for the Qt IVI Query Language.
QIviSearchAndBrowseModel::SupportsSorting0x2The backend supports sorting of the content. QIviSearchAndBrowseModelInterface::availableContentTypes() and QIviSearchAndBrowseModelInterface::supportedIdentifiers() will be used as input for the Qt IVI Query Language.
QIviSearchAndBrowseModel::SupportsAndConjunction0x4The backend supports handling multiple filters at the same time and these filters can be combined by using the AND conjunction.
QIviSearchAndBrowseModel::SupportsOrConjunction0x8The backend supports handling multiple filters at the same time and these filters can be combined by using the OR conjunction.
QIviSearchAndBrowseModel::SupportsStatelessNavigation0x10The backend is stateless and supports handling multiple instances of a QIviSearchAndBrowseModel requesting different data at the same time. E.g. One request for artists, sorted by name and another request for tracks. The backend has to consider that both request come from models which are currently visible at the same time.
QIviSearchAndBrowseModel::SupportsGetSize0x20The backend can return the final number of items for a specific request. This makes it possible to support the QIviSearchAndBrowseModel::DataChanged loading type.
QIviSearchAndBrowseModel::SupportsInsert0x40The backend supports inserting new items at a given position.
QIviSearchAndBrowseModel::SupportsMove0x80The backend supports moving items within the model.
QIviSearchAndBrowseModel::SupportsRemove0x100The backend supports removing items from the model.

The Capabilities type is a typedef for QFlags<Capability>. It stores an OR combination of Capability values.

See also QIviSearchAndBrowseModelInterface::registerContentType and QIviSearchAndBrowseModelInterface::registerContentType.

enum QIviSearchAndBrowseModel::LoadingType

ConstantValueDescription
QIviSearchAndBrowseModel::FetchMore0This is the default and can be used if you don't know the final size of the list (e.g. a infinite list). The list will detect that it is near the end (fetchMoreThreshold) and then fetch the next chunk of data using canFetchMore and fetchMore. The drawback of this method is that you can't display a dynamic scroll-bar indicator which is resized depending on the content of the list, because the final size of the data is not known. The other problem could be fast scrolling, as the data might not arrive in-time and scrolling stops. This can be tweaked by the fetchMoreThreshold property.
QIviSearchAndBrowseModel::DataChanged1For this loading type you need to know how many items are in the list, as dummy items are created and the user can already start scrolling even though the data is not yet ready to be displayed. Similar to FetchMore, the data is also loaded in chunks. You can safely use a scroll indicator here. The delegate needs to support this approach, as it doesn't have content when it's first created.
ConstantValueDescription
QIviSearchAndBrowseModel::InModelNavigation0The new content will be loaded into this model and the existing model data will be reset
QIviSearchAndBrowseModel::OutOfModelNavigation1A 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 QIviSearchAndBrowseModel::Roles

ConstantValueDescription
QIviSearchAndBrowseModel::NameRoleQt::DisplayRoleThe name of the item. E.g. The name of a contact in a addressbook, or the artist-name in a list of artists.
QIviSearchAndBrowseModel::TypeRoleQt::UserRoleThe type of the item. E.g. "artist", "track", "contact".
QIviSearchAndBrowseModel::ItemRoleQt::UserRole + 1The item itself. This provides access to the properties which are type specific. E.g. the address of a contact.
QIviSearchAndBrowseModel::CanGoForwardRoleQt::UserRole + 2True if this item can be used to go one level forward and display the next set of items.

See also goForward().

Property Documentation

availableContentTypes : const QStringList

Holds all the available content types

Access functions:

QStringList availableContentTypes() const

Notifier signal:

void availableContentTypesChanged(const QStringList &availableContentTypes)

See also contentType.

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)

capabilities : const QIviSearchAndBrowseModel::Capabilities

Holds the capabilities of the backend for the current content of the model.

The capabilties controls what the current contentType supports. e.g. filtering or sorting.

Access functions:

QIviSearchAndBrowseModel::Capabilities capabilities() const

Notifier signal:

void capabilitiesChanged(QIviSearchAndBrowseModel::Capabilities capabilities)

chunkSize : int

Holds the number of rows which are requested from the backend interface.

This property can be used to fine tune the loading performance.

Bigger chunks means less calls to the backend and to a potential IPC underneath, but more data to be transferred and probably longer waiting time until the request was finished.

Access functions:

int chunkSize() const
void setChunkSize(int chunkSize)

Notifier signal:

void chunkSizeChanged(int chunkSize)

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.

count : const int

Holds the current number of rows in this model.

Access functions:

virtual int rowCount(const QModelIndex &parent = QModelIndex()) const override

Notifier signal:

void countChanged()

fetchMoreThreshold : int

Holds the row delta to the end before the next chunk is loaded

This property can be used to fine tune the loading performance. When the threshold is reached the next chunk of rows are requested from the backend. How many rows are fetched can be defined by using the chunkSize property.

The threshold defines the number of rows before the cached rows ends.

Note: This property is only used when loadingType is set to FetchMore.

Access functions:

int fetchMoreThreshold() const
void setFetchMoreThreshold(int fetchMoreThreshold)

Notifier signal:

void fetchMoreThresholdChanged(int fetchMoreThreshold)

loadingType : QIviSearchAndBrowseModel::LoadingType

Holds the currently used loading type used for loading the data.

Note: When changing this property the content will be reset.

Access functions:

QIviSearchAndBrowseModel::LoadingType loadingType() const
void setLoadingType(QIviSearchAndBrowseModel::LoadingType loadingType)

Notifier signal:

void loadingTypeChanged(QIviSearchAndBrowseModel::LoadingType loadingType)

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 IVI 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

QIviSearchAndBrowseModel::QIviSearchAndBrowseModel(QObject *parent = nullptr)

Constructs a QIviSearchAndBrowseModel.

The parent argument is passed on to the QIviAbstractFeatureListModel base class.

QIviSearchAndBrowseModel::~QIviSearchAndBrowseModel()

Destroys the instance of QIviSearchAndBrowseModel.

[override virtual protected] bool QIviSearchAndBrowseModel::acceptServiceObject(QIviServiceObject *serviceObject)

Reimplemented from QIviAbstractFeatureListModel::acceptServiceObject().

T QIviSearchAndBrowseModel::at(int i) const

Returns the item at index i converted to the template type T.

[override virtual] bool QIviSearchAndBrowseModel::canFetchMore(const QModelIndex &parent) const

Reimplemented from QAbstractItemModel::canFetchMore().

bool QIviSearchAndBrowseModel::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.

[override virtual protected] void QIviSearchAndBrowseModel::clearServiceObject()

Reimplemented from QIviAbstractFeatureListModel::clearServiceObject().

[override virtual protected] void QIviSearchAndBrowseModel::connectToServiceObject(QIviServiceObject *serviceObject)

Reimplemented from QIviAbstractFeatureListModel::connectToServiceObject().

[override virtual] QVariant QIviSearchAndBrowseModel::data(const QModelIndex &index, int role) const

Reimplemented from QAbstractItemModel::data().

[override virtual protected] void QIviSearchAndBrowseModel::disconnectFromServiceObject(QIviServiceObject *serviceObject)

Reimplemented from QIviAbstractFeatureListModel::disconnectFromServiceObject().

[override virtual] void QIviSearchAndBrowseModel::fetchMore(const QModelIndex &parent)

Reimplemented from QAbstractItemModel::fetchMore().

[signal] void QIviSearchAndBrowseModel::fetchMoreThresholdReached() const

This signal is emitted whenever the fetchMoreThreshold is reached and new data is requested from the backend.

QVariant QIviSearchAndBrowseModel::get(int i) const

Returns the item at index i as QVariant.

This function is intended to be used from QML. For C++ please use the at() instead.

void QIviSearchAndBrowseModel::goBack()

Goes one level back in the navigation history.

See also Browsing for more information.

QIviSearchAndBrowseModel *QIviSearchAndBrowseModel::goForward(int i, QIviSearchAndBrowseModel::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.

void QIviSearchAndBrowseModel::indexOf(const QVariant &variant, const QJSValue &functor)

Determines the index of variant in this model and calls the functor once the result is ready. The result is passed as the first argument to the functor and is -1 if the item is not part of the list.

model.indexOf(item, function (index) {
    console.log("The index of item is: ", index)
})

void QIviSearchAndBrowseModel::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.

void QIviSearchAndBrowseModel::move(int cur_index, int new_index)

Moves the item at position cur_index to the new position new_index.

void QIviSearchAndBrowseModel::remove(int index)

Removes the item at position index.

[override virtual] QHash<int, QByteArray> QIviSearchAndBrowseModel::roleNames() const

Reimplemented from QAbstractItemModel::roleNames().

© 2018 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.