Develop and Configure

Version added 26-Jun-2018| Modified 15-Jul-2019

To create a QML app, you must write the source code and prepare the required configuration files.

For easier understanding, the process to create a QML app is explained using the example of an app named com.example.app.qml that has the following features:

  • When the app is launched, it displays a "Hello, QML Application" message on the screen.

  • When the user clicks on the screen, it calls the com.webos.service.systemservice/clock/getTime method. "UTC" time on the response is printed on the screen.

  • Prints log on the /var/log/messages file

    • when it is first launched and relaunched, outputting the "params" value which is passed on the launch method of System and Application Manager (SAM)

    • when windowState changed.

The directory structure of com.example.app.qml must be as follows:

com.example.app.qml
├── main.qml
├── appinfo.json
├── icon.png
├── com.example.app.qml.pro
└── README.md

Read the following sections to learn how to create the files mentioned in the directory structure.

Prerequisites

Before you begin developing the QML app, you must:

  • Build and flash the webOS OSE image. For detailed information, see Building webOS OSE and Flashing webOS OSE.

  • Create a project directory (com.example.app.qml) for the sample QML app.

$ mkdir com.example.app.qml

Source Code

First, define the functionality of the QML app on the source code.

main.qml

For the sample QML app (com.example.app.qml), you must:

  • Create and update the file : main.qml

    • Directory : com.example.app.qml

import QtQuick 2.4
import WebOSServices 1.0
import Eos.Window 0.1
import PmLog 1.0
 
WebOSWindow {
    id: root
    width: 1920
    height: 1080
    visible: true
    appId: "com.example.app.qml"
    title: "QML app"
    color: "lightblue"
     
    Text {
        id: mainText
        anchors.centerIn: parent
        font.family: "Helvetica"
        font.pointSize: 50
        text: "Hello, QML Appplication!!"       
    }
               
    property var launchParams: params
    onLaunchParamsChanged: {
        pmLog.info("LAUNCH_PARAMS", {"params": launchParams})
    }
 
    Service {
        id: systemService
        appId: "com.example.app.qml"
   
        function getTime() {
            call("luna://com.webos.service.systemservice","/clock/getTime","{}")
        }
 
        onResponse: {
            var jsonObject = JSON.parse(payload);
            pmLog.info("GETTIME", {"utc": jsonObject.utc});
            mainText.text = "UTC : " + jsonObject.utc
        }
 
        onError: {
            var jsonObject = JSON.parse(payload);
            pmLog.error("GETTIME", {"error": jsonObject});
        }
    }
   
    MouseArea {
        anchors.fill: parent
        onClicked: systemService.getTime()
    }
 
    onWindowStateChanged: {
        pmLog.info("WINDOW_CHANGED", {"status": windowState})
    }
 
    PmLog {
        id: pmLog
        context: "QMLApp"
    }
}

A brief explanation of the above file:

  • Line(1) : Import QtQuick 2.4 to use QML.

  • Line(2) : Import WebOS services to call System services via luna-service.

  • Line(3) : Import Eos.Window to use WebOSWindow QML component.

  • Line(4) : Import Pmlog to print log.

  • Line(6~61) :  Declare a WebOSWindow object with child objects.

    • Line(7~13) : Set WebOSWindow properties and size and color.

    • Line(15~21) : Declare Text object and string.

    • Line(23~26) : A QML app (with the type "qml" on appinfo.json) is launched and registered to SAM by qml-runner. Through this process, the QML app can receive the parameters passed with the launch method call as "params". With each launch method call, onLaunchParamsChanged is called even if the value of "params" does not change from that of the previous call. For details of PmLog usage, refer to Using PmLog in QML.

    • Line(28~46) : Declare Service object to call systemservice's getTime method. If the object receives the response, the app prints the UTC time on the screen.

    • Line(48~51) : When the user clicks on the screen, systemservice's getTime method is called.

    • Line(53~55) : windowState is a value that the WebOSWindow QML component sends to the app. Whenever the windowState value changes, onWindowStateChanged is called. Its value is 1 when the app is in the background and 4 when the app is in the foreground, following the definition of Qt::WindowState. For details, see https://doc.qt.io/qt-5/qt.html#WindowState-enum.

    • Line(57~60) : Declare PmLog object.

For detailed information for Qt, see Qt Documentation.

README.md

This file provides general information of the QML app. For the sample app (com.example.app.qml), you should:

  • Create and update the file : README.md

    • Directory : com.example.app.qml

If the REAMD.md file is missing, a build error occurs.
Make sure the 'Summary' subsection is a single line. Even a blank space before the 'Description' section is considered a part of the summary and can cause the build to fail. 
Here is a snippet of the README.md file that will not cause a build error. Any whitespace character in the red-colored line would cause a build error.

Summary
-------
QML app sample
(no blank space)
Description
-----------

Summary
-------
QML app sample

Description
-----------
QML app sample

How to Build on Linux
---------------------

## Dependencies

Below are the tools and libraries (and their minimum versions) required to build sample program:

* qmake

## Building

    $ cd build-webos
    $ source oe-init-build-env
    $ bitbake com.example.app.qml

Copyright and License Information
=================================
Unless otherwise specified, all content, including all source code files and
documentation files in this repository are:

Copyright (c) 2018 LG Electronics, Inc.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

SPDX-License-Identifier: Apache-2.0

Configuration Files

This section describes how to prepare the configuration files required to build and test the QML app.

appinfo.json

Apps are required to have metadata before they can be packaged. This metadata is stored in a file called appinfo.json, which is used by the webOS device to identify the app, its icon, and other information that is needed to launch the app. For the sample QML app (com.example.app.qml), you must:

  • Create and update the file : appinfo.json

    • Directory : com.example.app.qml

{
    "id": "com.example.app.qml",
    "version": "1.0.0",
    "vendor": "My Company",
    "type": "qml",
    "main": "main.qml",
    "title": "QML App",
    "icon": "icon.png", 
    "requiredPermissions" : ["time"]
}

A brief explanation of the above file:

  • Line(2) : The ID for the app.

  • Line(5) : The type of the QML app.

  • Line(6) : The executable file name.

  • Line(7) : The title to be shown on the Home Launcher app.

  • Line(8) : The icon to be shown on the Home Launcher app. Make sure the icon file is available in the project root directory. You can use your own icon.png (80*80) file.

  • Line(9) : Specify the group to which the external service's method called by the app belongs. Because systemservice's getTime method belongs to "time" group, put "time" in this property. To check the group of each method, use ls-monitor command with "-i" option.

For more details, see appinfo.json.

qmake Project File

This file specifies the application name and the qmake template to be used for generating the project, as well as the source, header, and UI files included in the project.

  • Create and update the file : com.example.app.qml.pro

    • Directory : com.example.app.qml

TEMPLATE = aux
!load(webos-variables):error("Cannot load webos-variables.prf")

# install
defined(WEBOS_INSTALL_WEBOS_APPLICATIONSDIR, var) {
    INSTALL_APPDIR = $$WEBOS_INSTALL_WEBOS_APPLICATIONSDIR/com.example.app.qml
    target.path = $$INSTALL_APPDIR

    appinfo.path = $$INSTALL_APPDIR
    appinfo.files = appinfo.json 

    base.path = $$INSTALL_APPDIR
    base.files = main.qml

    icon.path = $$INSTALL_APPDIR
    icon.files = icon.png

    INSTALLS += target appinfo base icon
}

A brief explanation of the above file:

  • Line(1) : We do not require any actual compilation or link steps for the QML app. So, we set "TEMPLATE = aux".

  • Line(2) : webOS platform "load(webos-variables)" will set WEBOS_INSTALL_WEBOS_APPLICATIONSDIR, which we will use as the deployment target folder.

  • Line(6) : Set installation directory on target board. INSTALL_APPDIR would be /usr/palm/applications/com.example.app.qml on the target.

  • Line(7~16) : *.files specifies a path in the project directory and *.path specifies the path to the file system to be installed on the target.

  • Line(18) : Add target, appinfo, base, and icon to INSTALLS list.

For more details, see qmake Project Files.

Except as noted, this content is licensed under Creative Commons Attribution 4.0 and sample code is licensed under Apache License 2.0.