Introduction

This example shows a very simple System-UI implementation, in the spirit of "Hello World!" examples, showcasing the fundamental building blocks of Qt Application Manager. You're able to see icons and names of the available applications on the left, start and stop them by clicking on their respective icons, and see their windows in a column layout on the right side.

The applications themselves just display "Hello World!" against a background of a specific color.

Files and folder structure

This example is comprised of a System-UI and three sample applications ("Hello Red", "Hello Green" and "Hello Blue"), making for four separate QML applications in total. System-UI is also just a QML application in the end, albeit a special one.

Each application is put in its own separate directory as described below:

• system-ui.qml
• apps
  • hello-world.blue
    • icon.png
    • info.yaml
    • main.qml
  • hello-world.red
    • icon.png
    • info.yaml
    • main.qml
  • hello-world.green
    • icon.png
    • info.yaml
    • main.qml

As you can see above, each application, besides its main QML file, also has an icon and a info.yaml. That YAML file contains the application metadata (it tells System-UI the name of the application, its icon filename, etc).

Running

Assuming the appman executable is in your path, you can run the System-UI as follows:

examples/applicationmanager/hello-world$ appman --builtin-apps-manifest-dir ./apps system-ui.qml

The first command line parameter tells appman where to find bult-in applications (ie, applications that come pre-installed and cannot be removed via ApplicationInstaller APIs). In this case, they're in the apps subdirectory. The last parameter is the main QML file of the System-UI.

And this is what you should see:

For information on these and other command line options you can run appman --help.

System-UI implementation

Our Hello World System-UI code starts like any simple QML application, with some imports and a plain Item at the root. The only difference is that it also imports the QtApplicationManager.SystemUI module, besides QtQuick.

import QtQuick 2.4
import QtApplicationManager.SystemUI 2.0

Item {
    width: 800
    height: 600

Next we have a Column on the left side of the root Item where we lay out the icons of the available applications along with their names.

    // Show application names and icons
    Column {
        spacing: 20
        Repeater {
            model: ApplicationManager
            Column {
                Image {
                    source: model.icon
                    MouseArea {
                        anchors.fill: parent
                        onClicked: model.isRunning ? application.stop() : application.start()
                    }
                }
                Text {
                    font.pixelSize: 20
                    text: model.name
                }
            }
        }
    }

As the model we use the ApplicationManager singleton which provides a row for each available application. Each row has, among others, an icon role containing the icon URL, a name role with the localized application name, a boolean isRunning role that tells whether the application is currently running and a application role containing its ApplicationObject. For information on other roles see the ApplicationManager documentation.

Clicking on an icon will either start its application or stop it in case it's already running.

Next we place a Column anchored to the right side of the root Item. In that column we lay out the existing windows from all currently running applications:

    // Show windows
    Column {
        anchors.right: parent.right
        Repeater {
            model: WindowManager
            WindowItem {
                width: 600
                height: 200
                window: model.window
            }
        }
    }

This time we use the WindowManager singleton as the model. There's a row for each window, with its WindowObject in the window role.

In order to have a window rendered in our System-UI we have to assign its WindowObject to a WindowItem, as was above. By default the window will be resized to match the size of the WindowItem rendering it.

Application implementation

Our Hello World applications just display a "Hello World!" text against a colored background.

import QtQuick 2.4
import QtApplicationManager.Application 2.0

ApplicationManagerWindow {
    color: "blue"

    Text {
        anchors.centerIn: parent
        text: "Hello World!"
    }
}

The only difference from a plain QML application is that the root element is an ApplicationManagerWindow, provided by the QtApplicationManager.Application module.

Application metadata

The info.yaml file contains the metadata about an application.

It starts with some boilerplate telling that this file contains Qt Application Manager application metadata.

formatVersion: 1
formatType: am-application
---

Then comes the application id, which uniquely identifies the application. It's recommended to follow a reverse DNS scheme, although this is not enforced. Here it's the "Blue" application from the "Hello World" example UI.

id:      'hello-world.blue'

Then the icon filename, which is self-explanatory:

icon:    'icon.png'

The entry point of the application is specified by the code field. For QML applications this means the filename of the main QML file.

code:    'main.qml'

The runtime field specifies the runtime used by the application. In this Hello World example, all applications are written in QML and hence we use the 'qml' runtime. Another runtime is 'native' for instance, used for compiled, executable, applications where the code entry would point to its binary executable filename.

runtime: 'qml'

And finally comes the user-visible name of the application in any number of languages (in this example, only English was provided):

name:
  en: 'Hello Blue'

Files:

• applicationmanager/hello-world/apps/hello-world.blue/info.yaml
• applicationmanager/hello-world/apps/hello-world.blue/main.qml
• applicationmanager/hello-world/apps/hello-world.green/info.yaml
• applicationmanager/hello-world/apps/hello-world.green/main.qml
• applicationmanager/hello-world/apps/hello-world.red/info.yaml
• applicationmanager/hello-world/apps/hello-world.red/main.qml
• applicationmanager/hello-world/hello-world.pro
• applicationmanager/hello-world/system-ui.qml

Images:

• applicationmanager/hello-world/apps/hello-world.blue/icon.png
• applicationmanager/hello-world/apps/hello-world.green/icon.png
• applicationmanager/hello-world/apps/hello-world.red/icon.png