Develop and Configure

Version added 26-Jun-2018| Modified 21-Sep-2018

To create a QML app, you must define the source code and 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:

  • Displays a "Hello, QML Application" message on screen.

  • Calls the com.webos.service.applicationmanager/registerNativeApp method.

  • Prints log on /var/log/messages file when it is launched first time.

  • Prints log with the updated parameter and status whenever the app is relaunched.

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

 

Setup Development Environment

Before starting development, you must do the following:

  1. Clone the build-webos repository.

    $ git clone https://github.com/webosose/build-webos.git
    
  2. Install all required components (on Ubuntu).

    $ sudo scripts/prerequisites.sh
  3. Configure the build.

    $ ./mcf -p 0 -b 0 raspberrypi3
  4. Build the webOS image.

    $ source oe-init-build-env  
    $ bitbake webos-image 

This is only a list of the main steps. For detailed information, see Building webOS OSE and Flashing webOS OSE.

 

Define Source Code

Define the functionality of the QML app.

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: appWindow
    width: 1920
    height: 1080
    visible: true
    appId: "com.example.app.qml"
    title: "QML app"
    color: "lightblue"
       
    Text {
        anchors.centerIn: parent
        font.family: "Helvetica"
        font.pointSize: 50
        text : "Hello, QML Application!!"
    }
 
    Service {
        id: registerApp;
        appId: "com.example.app.qml"
 
        Component.onCompleted:{
            call("luna://com.webos.service.applicationmanager","/registerNativeApp","{\"subscribe\":true}")
        }
        onResponse: {
            var jsonObject = JSON.parse(payload);
            pmLog.info("REGISTER_APP", {"payload": jsonObject});
 
            if(!jsonObject.returnValue)
            {
                pmLog.error("REGISTER_FAILED", {"payload" : jsonObject});
                return;
            }
 
            // TO DO:
            if( jsonObject.message === "registered" ){
                //process the first launched
 
            } else if( jsonObject.message === "relaunch" ) {
                if(jsonObject.parameters) {
                    pmLog.info("REGISTER_APP", {"parameters": jsonObject.parameters});
                    //process relaunched
                }
            }
        }
 
        onError: {
            pmLog.error("REGISTER_APP", {}, "register App error!!");
        }
    }
 
    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~60) :  Declare a WebOSWindow object with child objects.

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

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

    • Line(22~54) : Declare Service obejct to call applicationmanager's registerNativeApp method 

      • When the app first calls the method,  "message" value is "registered" in response.

      • When the app is already running and launch() method of System and Application Manager (SAM) is called, the value of "message" comes up as "relaunch". If the user gives a parameter of "params" when calling launch, the app can be delivered with the value of "parameters".

    • Line(56~59) : Declare PmLog object.

For detailed information for Qt, see QT Documentation.

 

appinfo.json

Apps are required to have metadata before they can be packaged. This metadata is stored in a file that 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"
}

A brief explanation of the above file:

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

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

  • Line(6) : The executable file name.

  • Line(7) : The title to be shown on the Launcher on the target device.

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

For more details, see appinfo.json.

 

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

Make sure the 'Summary' subsection is a single line. Even a blankspace 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 shows the blankspace that can cause the error:

Summary
-------
QML app sample
(no blankspace)
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

 

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 target.

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

  • Line(18) : Adds 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.