ListModel Struct

template <typename T> struct Qul::ListModel

Inherit from this class to expose a model to QML. More...

Header: #include <qul/model.h>
Since: Qt Quick Ultralite 1.0
Instantiated By: ListModel
Inherits: Qul::Object

This struct was introduced in Qt Quick Ultralite 1.0.

Public Functions

virtual int count() const = 0
virtual T data(int index) const = 0
T get(int index) const

Public Variables

Signal<void (int)> dataChanged
Signal<void ()> modelReset

Static Public Members

const int StaticCount

Detailed Description

Using C++ models is useful for exposing existing C++ data models or other complex datasets to QML. Creating a model in C++ is the only way to have a non-readonly model: The ones defined in QML cannot be modified at runtime.

To create your own model, declare a class that derives from Qul::ListModel.

Use a struct describing the model data as the template argument. Its public fields become the model roles. The struct must be equality-comparable. Alternatively, the template argument can be a simple type supported by Qul (for example, int or Qul::qreal).


struct MyModelData {
    int field1;
    Qul::qreal field2;

inline bool operator==(const MyModelData &lhs, const MyModelData &rhs)
    return lhs.field1 == rhs.field1 && lhs.field2 == rhs.field2;

struct MyModel : public Qul::ListModel<MyModelData> {
    MyModel() {
        m_data.push_back({ 1, 2.0 });

    int count() const override {
        return m_data.size();
    MyModelData data(int index) const override {
        return m_data.at(index);
    std::vector<MyModelData> m_data;

    // It is also possible to add some functions that can be called from QML or C++
    void add(int f1, Qul::qreal f2) {
        MyModelData data = { f1, f2 };
    void updateField1(int index, int value) {
        m_data.at(index).field1 = value;

The modelReset and dataChanged signals are used to trigger a refresh of a view.

The modelReset signal must be emitted whenever number of elements of the model changes after it's instantiation by a view.

The dataChanged signal must be emitted whenever existing element of the model is modified.

Dynamic strings

Passing strings form C++ to QML has some implications on how glyphs are generated by the fontcompiler. It's possible that some characters will not be rendered in the QML by default. For more detailed description see Rendering dynamic strings in QML.

See also Models and Views in Qt Quick Ultralite, C++ Data Models, and Text Rendering and Fonts.

Member Function Documentation

[pure virtual] int ListModel::count() const

Returns the number of data entries in the model.

See also StaticCount.

[pure virtual] T ListModel::data(int index) const

Returns the data stored at the given index.

T ListModel::get(int index) const

Returns the item at index. Exists for QML interface compatibility.

See also data.

Member Variable Documentation

const int ListModel::StaticCount

The static member variable indicating the exact number of elements in the model, it must be overriden for the model to be used by a Repeater.

Note: This variable must be overridden by defining a static const int StaticCount the derived class.

See also count.

Signal<void (int)> ListModel::dataChanged

Emit this signal to tell the view to reload the data for the item at the given index.

See also modelReset.

Signal<void ()> ListModel::modelReset

Emit this signal to tell the view that the model needs to be reloaded. This must be emitted when the number of rows, is changed

See also dataChanged.

Available under certain Qt licenses.
Find out more.