Writing Applications

Writing an application to run as a client within the application manager is similar to writing a stand-alone QML application, except for these three additional tasks or limitations:

1. If you write a QML application, make your QML scene's root element an ApplicationManagerWindow; or derive your own custom root item from it.
2. Provide a valid info.yaml file.
3. Restart the application manager to make it aware of your application.

The Root Element

It's recommended to use either an ApplicationManagerWindow or a QtObject as the root of your QML application. This is especially important if you require similar behavior in single-process and multi-process mode. If you use a QtObject, any visible base elements should still be ApplicationManagerWindows. Nevertheless, other root elements are supported for convenience, as well.

Here are a few things to consider:

• Only ApplicationManagerWindows support window properties that are shared between the System UI and the client applications.
• In multi-process mode, Window root elements always get a decoration (unless you set QT_WAYLAND_DISABLE_WINDOWDECORATION) and are invisible by default. QQuick Items are wrapped inside a Window representing a Wayland client window.
• In single-process mode Window root elements appear parallel to instead of inside the System UI.

The Manifest

The Manifest Definition has all the information you need to produce a minimal info.yaml file.

Finding and parsing info.yaml files recursively, for potentially hundreds of applications can be a very time consuming task and would severely slow down the application manager's startup. Therefore, all manifest files are cached in a binary database. The application manager automatically detects when a manifest has changed and updates the cache accordingly, but you can also force a rebuild of this database by calling appman --clear-cache.

CMake Integration

The Application Manager CMake integration provides two functions to add applications to the build system:

1. qt_am_create_builtin_package for builtin packages
2. qt_am_create_installable_package for dynamically installable packages

Builtin Packages

Builtin packages are applications that are built into the System UI and are always available. They are defined in the System UI's am-config.yaml file using the applications/builtinAppsManifestDir.

The qt_am_create_builtin_package function is mainly used to provide a good QtCreator integration, as it provides a Run Target for every application added this way. This makes it easier to start, stop, debug and profile applications. In addition this function manages installable files: it copies them to the build directory when necessary and also provides a CMake install target.

A simple builtin application could look like this:

qt_am_create_builtin_package(myapp
    FILES
        apps/myapp/info.yaml
        apps/myapp/icon.png
        apps/myapp/main.qml
)

See the Hello World! example for a complete example.

Installable Packages

Installable packages are applications that can be installed into the System UI at runtime.

Similar to built-in packages, the qt_am_create_installable_package function is used to provide run targets in QtCreator, but it also adds additional targets to create installable packages which can be installed into the System UI at runtime.

A simple installable application could look like this:

qt_am_create_installable_package(myapp
    OUTPUT_DIRECTORY apps/myapp
    FILES
        apps/myapp/info.yaml
        apps/myapp/icon.png
        apps/myapp/main.qml
)

See the Package Installation Example} for a complete example.

Using the QML script compiler in Applications

The QML script compiler is a tool that compiles QML files into binary files and makes the code more efficient. It is used behind the scenes if you are using the qt_add_qml_module function to specify a QML module. Such a module can also be used in applications by doing the following modifications:

Build the module using qt_add_qml_module and add it as dependency to the application:

qt_add_qml_module(mymodule
    URI com.example.mymodule
    VERSION 1.0
    QML_FILES
        MyItem.qml
)
qt_am_create_builtin_package(myapp
    FILES
        apps/myapp/info.yaml
        apps/myapp/icon.png
        apps/myapp/main.qml
    DEPENDENCIES
        mymodule
)

Load the module library file instead of the application's QML file in the info.yaml file:
\code
  runtimeParameters:
    resources: [ "libmymodule.so" ]

See the Application Features Example for a complete example of a builtin package and the Package Installation Example for a complete example of an installable package.