Writing a Symbolibre applet in QML

Note

We cannot offer any guarantee on the stability of the APIs.

Basics

The SLStandardApplet type represents the root of an applet and implements function bar handling.

Thus, the basic skeleton of an applet is as follows:

import org.symbolibre.applet 0.2

SLStandardApplet {
    // your code goes here
}

Note that you don’t have to create a window, the user interface you write will be directly inserted into the window of the Symbolibre shell.

Installing the applet

Applets are stored in the apps subdirectory of the static data directory of Symbolibre. On Unix systems, this may be /usr/share/symbolibre/apps or /usr/local/share/symbolibre/apps if the project was installed globally.

To allow the Symbolibre shell to find your applet and display it in the main menu, you need to write an application.json file in the directory of the applet. Its structure is as follows:

{
  "id": "example",
  "applet": "Example.qml",
  "name": "My first applet",
  "icon": "example.png"
}

You can also provide translated names by specifying name_LANG strings, e.g. "name_fr": "Mon premier applet".

The icon should be in the icons directory next to apps.

The complete directory structure of this example applet would look like this:

example/
| application.json
| Example.qml

Function keys

A function key is defined by a FunctionKeyModel, with two attributes text and color and one signal activated. Functions can be assigned to the F1…F5 keys using the FunctionBar attached property which has six attributes: f1 to f5 and combine.

Function keys shown on the bar are determined by scanning the tree from the active focus item up to the parents until an item with a FunctionBar attached property is found.

import QtQuick.Controls 2.5
import org.symbolibre.applet 0.2

SLStandardApplet {
    text: "Button"
    FunctionBar.f1: FunctionKeyModel {
        text: "Foo"
    }
    Button {
        FunctionBar.f1: FunctionKeyModel {
            text: "Bar"
        }
    }
}

In the above example, if the button has active focus, the F1 key label reads “Bar”, otherwise it reads “Foo”.

Normally the search stops once an item that specifies function keys if found. If the FunctionBar.combine attribute is set to true, the search will continue and the function keys will combine with whatever the next parent to define function keys provides. Remember that since the search is bottom-up, the combine property should be set on the child.