The use of system APIs in Sailfish OS

Introduction

Voice assistants on mobile devices are not static and are continuously evolving. Voice assistant for Sailfish OS, presented last fall, is no exception and also acquires new functionality.

In that article, focusing on the basic principle of the internal operation of the application. This material offers a series of two articles in which it will be discussed in detail:

the
1. Working with undocumented APIs for device management (current);
the
2. Working with interfaces D-Bus, provided by the operating system.

In the current article describes how to control the screen brightness and system volume, and how to enable or disable Bluetooth and flight mode.

Assumes that the reader already set Sailfish OS SDK and developed applications using it.

the

to obtain information

While developing for Sailfish OS you can not do without the documentation provided on official website and in the IDE. Documentation is written efficiently, with examples, but not without fault — it is short and covers only the basic functionality available to a programmer.

But Sailfish OS, like other operating systems, hides more described in the documentation. You just have to know where to look. And it is necessary to look in the source code as the most reliable source of information. Benefit of the Sailfish OS — an open software product based on GNU/Linux.

For starters, you need to connect to the phone via SSH (figure 1). For this we need to enable remote connection (1), password (2) and use one of the IP addresses (3). After done action to navigate to the directory /usr/share. This directory contains interface codes and scripts almost all applications installed on the phone.


[Figure 1 — connection setup to the phone via SSH.]

Catalogs of third-party apps start (in most cases) with the prefix harbour followed by the program ID. The prefix allows to prevent crossing of names to system names. Catalogs of standard applications are accompanied by prefixes jolla and sailfish. The rest refers to system functions.


[Figure 2 — Example application directory.]

the

adjust screen brightness

Controls the brightness of the screen belongs to the user's system settings, hence the interest in the directory /usr/share/jolla-settings, which contains the following objects:
the

the
• entries — stores information about the structure of preferences;
the
• the pages — stores page elements and settings;
the
• widgets is generally not used;
the
• File settings.qml — the main startup file of the application settings;
the
• File x-openvpn.xml — stores information about the connection with the VPN server.

From the list it is seen that the marked task is required to access the directory pages. It is divided into subdirectories according to the configuration types: bluetooth, sounds etc. the screen Settings are located in the directory display. Therefore /usr/share/jolla-settings/pages/display is the full path relative to which will be the follow-up work.

The first step is to search for a keyword:

grep -H 'brightness' *

$ cd /usr/share/jolla-settings/pages/display
$ grep -H 'brightness' *
BrightnessSlider.qml: label: qsTrId("settings_display-la-brightness")
BrightnessSlider.qml: value: displaySettings.brightness
BrightnessSlider.qml: onValueChanged: displaySettings.brightness = Math.round(value)
BrightnessSlider.qml: onBrightnessChanged: slider.value = brightness
display.qml: entryPath: "system_settings/look_and_feel/display/brightness_slider"
display.qml: text: qsTrId("settings_display-la-adaptive_brightness")

The results show that the code set the brightness of the screen is in the file BrightnessSlider.qml.

Next, we need to clarify how exactly you manage:

grep -C 1 'displaySettings' ./BrightnessSlider.qml

$ grep -C 1 'displaySettings' ./BrightnessSlider.qml
label: qsTrId("settings_display-la-brightness")
maximumValue: displaySettings.maximumBrightness
minimumValue: 1
value: displaySettings.brightness
stepSize: 1

onValueChanged: displaySettings.brightness = Math.round(value)

DisplaySettings {
id: displaySettings
onBrightnessChanged: slider.value = brightness

After a search on the file it becomes obvious that to control the brightness of the device you want to create the object DisplaySettings and change the value of the field brightness, taking into account that the minimum value of brightness equal to one and the maximum is stored in the maximumBrightness.

The final touch is to determine the required imports:

grep 'import' ./BrightnessSlider.qml

$ grep 'import' ./BrightnessSlider.qml
import QtQuick 2.0
import Sailfish.Silica 1.0
import com.jolla.settings.system 1.0
import org.nemomobile.systemsettings 1.0

QtQuick and Sailfish.Silica are standard modules for interface development and do not provide access to settings. com.jolla.settings.system contains the internal objects for the application settings and not of interest to other programs. Remains org.nemomobile.systemsettings, opisyvaemye required component.

Thus, it becomes possible to form a control screen brightness for subsequent inclusion in the project:

BrightnessControl.qml

import QtQuick 2.0
import org.nemomobile.systemsettings 1.0

Item {
id: brightnessControl

/* Set the brightness to the specified value.
* @param: value-the number from 1 (minimum) to maximumBrightness (maximum)
*/
function setBrightness(value) {
if (value <= 1) setMinimumBrightness();
else if (value >= displaySettings.maximumBrightness) setMaximumBrightness();
else displaySettings.brightness = value;
}

/* Increase brightness.
* @param: percents-percentage of the brightness range.
*/
increaseBrightness function(percents) {
setBrightness(displaySettings.brightness + _calcDelta(percents))
}

/* Decrease the brightness.
* @param: percents-percentage of the brightness range.
*/
decreaseBrightness function(percents) {
setBrightness(displaySettings.brightness - _calcDelta(percents))
}

/* Set minimum brightness.
*/
setMinimumBrightness function() {
displaySettings.brightness = 1
}

/* Set the maximum brightness.
*/
setMaximumBrightness function() {
displaySettings.brightness = displaySettings.maximumBrightness
}

/* Calculate absolute value of the change.
* @param: percents-percentage of the brightness range.
* @return Boolean change the brightness in absolute units.
*/
_calcDelta function(percents) {
return Math.round(displaySettings.maximumBrightness / 100 * percents)
}

DisplaySettings { id: displaySettings }
}

the

system volume

Here we use the already known method of finding information. Go to the directory /usr/share/jolla-settings/pages/sounds and check the keywords:

grep -i-C 1-H 'volume' *

$ cd /usr/share/jolla-settings/pages/sounds
$ grep -i-C 1-H 'volume' *
SoundsPage.qml-
SoundsPage.qml: VolumeSlider {
SoundsPage.qml: id: volumeSlider
SoundsPage.qml: property string entryPath: "system_settings/look_and_feel/sounds/ringer_volume"
SoundsPage.qml - width: parent.width
--
VolumeSlider.qml - height: implicitHeight + valueLabel.height + Theme.paddingSmall
VolumeSlider.qml: //% "Ringtone volume"
VolumeSlider.qml: label: qsTrId("settings_sounds_la_volume")
VolumeSlider.qml - maximumValue: 100
--
VolumeSlider.qml - if (!externalChange) {
VolumeSlider.qml: profileControl.ringerVolume = value
VolumeSlider.qml - profileControl.profile = (value > 0) ? "general" : "silent"
--
VolumeSlider.qml slider.externalChange = true
VolumeSlider.qml: slider.value = profileControl.ringerVolume
VolumeSlider.qml slider.externalChange = false
--
VolumeSlider.qml-
VolumeSlider.qml: onRingerVolumeChanged: {
VolumeSlider.qml slider.externalChange = true
VolumeSlider.qml: slider.value = profileControl.ringerVolume
VolumeSlider.qml slider.externalChange = false

From the result shows that maximum volume is 100, minimum is 0; and the control is performed using the element profileControl, and requires not only specifying a value for the volume, but switch profile. Get more information about the mentioned item:
if (!externalChange) {
profileControl.ringerVolume = value
profileControl.profile = (value > 0) ? "general" : "silent"
}
--
slider.externalChange = true
slider.value = profileControl.ringerVolume
slider.externalChange = false
--
ProfileControl {
id: profileControl

--
slider.externalChange = true
slider.value = profileControl.ringerVolume
slider.externalChange = false
$ grep 'import' ./VolumeSlider.qml
import QtQuick 2.0
import Sailfish.Silica 1.0
import com.jolla.settings.system 1.0
import org.nemomobile.systemsettings 1.0