1
FalkonTutorials/qml/articles/8.Extension_settings.md
Juraj Oravec 5e6b860531
QML: Use Pane as container in settings example
Using QtQuick.Controls Pane allows the resulting UI element to be styled
by system theme.
Using Rectangle forces some color, if not specified white is used.

Signed-off-by: Juraj Oravec <jurajoravec@mailo.com>
2022-07-14 10:33:45 +02:00

2.6 KiB

Falkon QML Tutorial - 8. Extension settings

Hello, in this chapter I will show you how to create a settings dialog.

These settings are stored as ini files in the profile/extensions/some_extension/settings.ini and thus are suitable only for small data storage like global user settings.

Use Settings

At first set the settings option X-Falkon-Settings=true in the desktop file to tell Falkon the settings for the extension are available.

metadata.desktop

[Desktop Entry]
Name=Tutorial8 QML
Comment=Example QML extension with settings
Icon=
Type=Service
X-Falkon-Type=Extension/Qml

X-Falkon-Author=Juraj Oravec
X-Falkon-Email=jurajoravec@mailo.com
X-Falkon-Version=1.0.0
X-Falkon-Settings=true

main.qml

import QtQuick.Controls 2.3

Falkon.Settings {
    id: settings
    name: 'Tutorial8_settings'
}

settingsWindow: Pane {
    id: window
    width: 256
    height: 200
}

In this example Falkon settings API can be accessed through settings object. The available API can be found at documentation or code

The settingsWindow is same as button popup and sidebar content. It contains some QMT element to draw stuff.

Troubleshooting

If you try to use the Qt style settings syntax settings.value('key', 'default') you will receive an error message like this one:

"Could not convert argument 0 at"
    "@file://falkon/plugins/qml_tutorial_8/main.qml:13"
"Passing incompatible arguments to C++ functions from JavaScript is dangerous and deprecated."
"This will throw a JavaScript TypeError in future releases of Qt!"
Unable to get value: key not defined

Thus use a proper Falkon settings syntax eg.

settings.value({
    key: 'password'
    defaultValue: '1234567890'
})

Limitations

I am aware of these potential limitation.

  • I was unable to find a way to close a settings window from QML script
  • Try to avoid saving variable of type bool with settings. The results might not be as expected.

Example

The example will create a button which will be placed into the toolbar and though settings optionaly adds icon to the statusbar. The settings for the statusbar icon will change after browser restart.

The setting window contains an image and a checkbox.

This example is partialy ripped of from Falkon example extension.

Window with sidebar and view menu

Code

The code for this example can be found at extensions/qml_tutorial_8