QIfPagingModel Class

The QIfPagingModel is a generic model to load its data using the "Paging" aproach. More...

Header: #include <QIfPagingModel>
qmake: QT += interfaceframework
Instantiated By: PagingModel
Inherits: QIfAbstractFeatureListModel
Inherited By:

QIfFilterAndBrowseModel

Public Types

enum LoadingType { FetchMore, DataChanged }
enum Roles { NameRole, TypeRole, ItemRole }

Properties

Public Functions

QIfPagingModel(QObject *parent = nullptr)
T at(int i) const
QtInterfaceFrameworkModule::ModelCapabilities capabilities() const
int chunkSize() const
int fetchMoreThreshold() const
QVariant get(int i) const
QIfPagingModel::LoadingType loadingType() const
void reload()
void setChunkSize(int chunkSize)
void setFetchMoreThreshold(int fetchMoreThreshold)
void setLoadingType(QIfPagingModel::LoadingType loadingType)

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 capabilitiesChanged(QtInterfaceFrameworkModule::ModelCapabilities capabilities)
void chunkSizeChanged(int chunkSize)
void countChanged()
void fetchMoreThresholdChanged(int fetchMoreThreshold)
void fetchMoreThresholdReached() const
void loadingTypeChanged(QIfPagingModel::LoadingType loadingType)

Reimplemented Protected Functions

virtual void clearServiceObject() override
virtual void connectToServiceObject(QIfServiceObject *serviceObject) override
virtual void disconnectFromServiceObject(QIfServiceObject *serviceObject) override

Detailed Description

The QIfPagingModel should be used directly or as a base class whenever a lot of data needs to be presented in a ListView.

The model only fetches the data it really needs and can it can be configured how this can be done using the loadingType property.

The backend filling the model with data needs to implement the QIfPagingModelInterface class.

Setting it up

The QIfPagingModel is using QtInterfaceFramework's Dynamic Backend System and is derived from QIfAbstractFeatureListModel. Other than most "QtInterfaceFramework Feature classes", the QIfPagingModel 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();
QIfPagingModel *model = new QIfPagingModel();
model->setServiceObject(player->serviceObject());

Loading Types

Multiple loading types are supported, as the QIfPagingModel is made to work with asynchronous 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.

See the Models section for more information about all models in QtInterfaceFramework.

Member Type Documentation

enum QIfPagingModel::LoadingType

ConstantValueDescription
QIfPagingModel::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.
QIfPagingModel::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.

enum QIfPagingModel::Roles

ConstantValueDescription
QIfPagingModel::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.
QIfPagingModel::TypeRoleQt::UserRoleThe type of the item. E.g. "artist", "track", "contact".
QIfPagingModel::ItemRoleQt::UserRole + 1The item itself. This provides access to the properties which are type specific. E.g. the address of a contact.

Property Documentation

[read-only] capabilities : const QtInterfaceFrameworkModule::ModelCapabilities

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

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

Access functions:

QtInterfaceFrameworkModule::ModelCapabilities capabilities() const

Notifier signal:

void capabilitiesChanged(QtInterfaceFrameworkModule::ModelCapabilities 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)

[read-only] 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 : QIfPagingModel::LoadingType

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

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

Access functions:

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

Notifier signal:

void loadingTypeChanged(QIfPagingModel::LoadingType loadingType)

Member Function Documentation

QIfPagingModel::QIfPagingModel(QObject *parent = nullptr)

Constructs a QIfPagingModel.

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

[signal] void QIfPagingModel::fetchMoreThresholdReached() const

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

template <typename T> T QIfPagingModel::at(int i) const

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

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

Reimplements: QAbstractItemModel::canFetchMore(const QModelIndex &parent) const.

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

Reimplements: QIfAbstractFeatureListModel::clearServiceObject().

[override virtual protected] void QIfPagingModel::connectToServiceObject(QIfServiceObject *serviceObject)

Reimplements: QIfAbstractFeatureListModel::connectToServiceObject(QIfServiceObject *serviceObject).

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

Reimplements: QAbstractItemModel::data(const QModelIndex &index, int role) const.

[override virtual protected] void QIfPagingModel::disconnectFromServiceObject(QIfServiceObject *serviceObject)

Reimplements: QIfAbstractFeatureListModel::disconnectFromServiceObject(QIfServiceObject *serviceObject).

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

Reimplements: QAbstractItemModel::fetchMore(const QModelIndex &parent).

[invokable] QVariant QIfPagingModel::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.

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

[invokable] void QIfPagingModel::reload()

Resets the model and starts fetching the content again.

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

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

Reimplements: QAbstractItemModel::roleNames() const.

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