QtDesignStudio/BackendApi

Backend API and Simulation

Overview

The Backend API mechanism separates UI presentation from application data layer by routing data through a centralized singleton.

Instead of hardcoding the values directly in QML, properties are delegated to a BackendApi which then reads values from the Backend implementation (by default, BackendSimulation, but any other implementation might be used).

This enables designers to work with live-editable data and allows developers to easily replace the simulation with a real backend written in either QML or C++. Most importantly, without touching the UI code.

Architecture

UI Components ---binding---> BackendApi <---propagates--- Backend (e.g. Simulation) ---reads---> backend.json

Where:

Component	Component	Relation
UI Components	BackendApi	A UI component binds to BackendApi.<propertyName>
BackendApi	Backend	BackendApi declares properties that are bound to Backend.<propertyName>
Backend	backend.json	BackendSimulation reads values from the backend.json at runtime, loads them into internal properties and automatically propagates them to UI components through the BackendApi bindings.

Converting a property into a Backend property

User Scenario

Given a QML component of type Text, its text property is set to "Hello". You want to move that value to the backend so it can be managed centrally and supplied by a real data source.

1. You select the Text component in the Qt Design Studio Form Editor or Navigator.
2. In the Property editor of the Text component, find text property and click on a small gear icon button next to it.
3. From the context menu, select "Convert to Backend property".
4. A dialog appears prompting you to enter a backend property name.
5. Click "Convert".

What happens next?

A new property is inserted in between the @properties-begin and @properties-end markers in the BackendApi.qml file of your project:

QtObject {
    // @properties-begin
    property string text: Backend.text
    // @properties-end
}

Where:

1. The property name is what you entered into the dialog.
2. The property type is inferred from the original property (text property of the Text component in that case).

Next, the backend.json file gets updated:

{
    "text": "Hello"
}

Where:

1. The property name is what you entered into the dialog.
2. The value is same as the original value of the text property of the Text component.

Next, the property binding in your Text component is updated:

Text {
    text: BackendApi.text
}

Duplicates handling

If a backend property with the same name already exists, the system reuses it, i.e. it's not added again to BackendApi. The component's property is still re-bound to BackendApi.<propertyName> tough.

Enumeration values

Enumeration properties are automatically converted to their integer representation before adding them to BackendApi or backend.json.

Files

BackendApi.qml, BackendSimulation.qml and backend.json files are all stored under:

/qt-automotive-studio/share/qtcreator/qmldesigner/studio_templates/projects/shared-plugin/name/

BackendApi.qml

Public API singleton that exposes all backend properties to the UI components.

1. Registered as singleton.
2. UI components bind to BackendApi.<propertyName>.
3. Each property delegates to Backend.<propertyName>, creating a layer of indirection. The Backend singleton can be swapped out without changing any UI bindings.
4. The @properties-begin and @properties-end comment markers are used by the code generator to locate and insert new properties. Do not remove or reorder these markers.
5. You may manually add properties between the markers as long as you also add corresponding entries to backend.json.

BackendSimulation.qml

Default implementation of the Backend singleton. Loads values from backend.json.

1. Registered as singleton Backend in the module (note: the QML type name is Backend, not BackendSimulation).
2. Uses FileReader from QtQuick.Studio.Utils to load backend.json.
3. Reloads automatically when backend.json changes on disk.
4. Properties are read-only.

backend.json

Data file that stores the property values used by BackendSimulation.

Replacing BackendSimulation with a Custom Backend

The default BackendSimulation is a convenience for prototyping in Qt Design Studio. For production applications, you will typically replace it with a backend that connects to real data sources like REST APIs, databases, vehicle bus systems, or application logic.

The key requirements are:

1. your replacement must be a QML singleton registered as Backend in the module,
2. it must expose the same property names that BackendApi.qml references.

Example

#pragma once

#include <QObject>
#include <QQmlEngine>

class Backend : public QObject
{
    Q_OBJECT
    QML_ELEMENT
    QML_SINGLETON

    Q_PROPERTY(QString text READ text NOTIFY textChanged)

public:
    explicit Backend(QObject *parent = nullptr) : QObject{parent} {}

    QString text() const { return m_text; }

signals:
    void textChanged();

private:
    QString m_text = "Hello";
};

To use your Custom Backend C++ implementation, it's enough to remove BackendSimulation and backend.json from your project and build it with your custom implementation instead.