The rationale behind using .ui.qml files in Qt Design Studio

QML is to versatile for a visual tool because it was designed as a programming language. JavaScript can be easily added and imperative JavaScript statements affect the semantics, even of e.g. the visual layout/positioning.

QML is also very easy to extend and it is possible to create custom sub dialects of QML that will not work well with the tooling we provide. (CSS for QML is an extreme case, but it was done)

Many features of QtQuick like 2D particles, behaviors are not supported by the visual tooling because a visual editor works with the direct manipulation paradigm. For that we not only need to translate from the data or textual(qml file) representation to the visual representation like a interpreter or compiler does but from the visual representation to the textual representation too. For example if you click on a item the editor has to know what he has to change in the text file. Qml makes that harder because it was designed to make the life of a programmer easier but that increases the complexity of the visual editor. If every entry has an unique id it is much easier for the tool to do the reverse mapping. If types would be fully qualified it would be much easier to map the type without import management. A tool doesn't cares how much to type but easier mappings are reducing the code complexity of the tool. So reducing the feature set of ui file is reducing the reverse mapping code. In many cases a reverse mapping is not possible because imperative code has no reverse function.

Therefore we decided to introduce a subset of ui.qml that restricts QML to a purely declarative subset in which only the features supported by the tooling are allowed.

Elements like Behavior , Binding, Canvas, Shader Effect, Timer, Transform are not allowed in ui.qml files and the use of JavaScript is heavily limited. Property bindings have to be expresions, signals handlers have to be part of Connections.

Only a limited number of JavaScript functions are allowed in ui.qml files.

In short .ui.qml files are expected to work with the visual tooling and are typical created with visual tooling or with the limitations in mind. The code editor of Qt Creator/Qt Design Studio enforces the limitations by creating error messages, when "breaking the rules".

This is documented here: https://doc.qt.io/qtdesignstudio/creator-quick-ui-forms.html

Even in relativly simple QML there are "patterns" that break the visual tooling.

Examples are: Using ambigous ids that we do not allow, like 'text' , 'color', or 'data', because they can easily be ambigous and collide with properties. This should be added to qmllint (QTBUG-117801).

The size of the root item depends on its parent and the document refers to the parent on component and not instance level.

Example: bluetooth Dialog.qml

width: parent.width / 3 * 2

Header.qml

 width: parent.width

We should fix our examples, but third party code will have these issues (QDS-10829).

Features that are not supported in .ui.qml files are:

• Inline Components
  e.g. StockQt NumberPad.qml

    component DigitButton: CalculatorButton {
        onPressed: function() {
            window.digitPressed(text)
            updateDimmed()
        }
    }

• Positioners Transitions

move: Transition {
            NumberAnimation {
                properties: "y"
                easing.type: Easing.OutBounce
            }
        }

• ApplicationWindow
  The ApplicationWindow is currently not supported, because it spawns an additional top level window. (QDS-10914)

Defining the exact limitations of .ui.qml files is not trivial, because QML is so versatile. The short versions would be that everything that Qt Design Studio can create visually is supported.
This means that .ui.qml files are limited to the C++ types/modules/imports that are provided by the item library.

If the user adds other imports there is no gurantee that the result will work (QDS-10830).

Using ui.qml files allows the user to create a clear distiction between files that can be visually edited by e.g. a technical artist and .qml files that contain JavaScript or a feature that is known to break the visual tooling.

Projects files that are created without visual tooling use the ending .qml. Therefore users do not (automatically) expect them to work in the visual tooling, which helps managing expectations.

Since QML, the modules provided by us evolve, it is not clearly defined what exactly works with the visual tooling and what does not work. This clearly applies to some of the more advanced features like components, delegates and list views. People guided by the visual tooling usually create something that also works, otherwise they consider it a bug and report it.
Users not relying on the visual tooling are far more likely to use features that are not supported.