What is the use of the ui.qml files in Qt5 (QML)?

Question

As far as I can see the .qml files can be used to define the UI, which seems to override whatever is written in ui.qml file. So, what exactly is the use of the ui.qml file?

I'm using Qt5 with Qt Creator.

Solution

The .ui.qml file exists to help Qt Quick Designer out. Normal QML files can contain JavaScript expressions, for example, but these are difficult for Qt Quick Designer to work with. Plain QML, on the other hand, is not as difficult, and is closer to the widgets equivalent of .ui files - a document that details a set of items in a user interface, not so much the logic behind them.

The feature was proposed several years ago on the blog:

The classical Widget Designer is built around the distinction between declarative form and imperative logic. The declarative form is designable and stored in .ui files.

In Qml it is easy to mix declarative code and imperative code. If you add imperative instructions (affecting visual aspects) to your Qml files they are not purely declarative anymore and the visual representation in the visual editor will break. The visual editor needs a way to translate the visual description back into the text description. For imperative code this is not possible in general and the Qt Quick Designer does not even try.

The QML Documents documentation states:

Since Qt 5.4, a document can also have the file extension ".ui.qml". The QML engine handles these files like standard .qml files and ignores the .ui part of the extension. Qt Creator handles those files as UI forms for the Qt Quick Designer. The files can contain only a subset of the QML language that is defined by Qt Creator.

Qt Quick UI Forms:

You can use Qt Creator wizards to create UI forms that have the filename extension .ui.qml. The UI forms contain a purely declarative subset of the QML language. It is recommended that you edit the forms in the Design mode. However, exporting items as alias properties is a commercial only feature, and therefore you must use the Edit mode to do it if you are using the open source version of Qt Creator. Qt Creator enforces the use of the supported QML features by displaying error messages.

The following features are not supported:

• JavaScript blocks
• Function definitions
• Function calls (except qsTr)
• Other bindings than pure expressions
• Signal handlers
• States in other items than the root item
• Root items that are not derived from QQuickItem or Item

The following types are not supported:

• Behavior
• Binding
• Canvas
• Component
• Shader Effect
• Timer
• Transform
• Transition