1

QML: Add extension settings tutorial

Signed-off-by: Juraj Oravec <jurajoravec@mailo.com>
This commit is contained in:
Juraj Oravec 2022-04-04 23:04:36 +02:00
parent d392774e66
commit 112191b027
Signed by: SGOrava
GPG Key ID: 13660A3F1D9F093B
5 changed files with 170 additions and 0 deletions

View File

@ -7,3 +7,4 @@
5. [Using notifications](articles/5.Using_notifications.md) - [Extension](extensions/qml_tutorial_5/) 5. [Using notifications](articles/5.Using_notifications.md) - [Extension](extensions/qml_tutorial_5/)
6. [Using clipboard](articles/6.Using_clipboard.md) - [Extension](extensions/qml_tutorial_6/) 6. [Using clipboard](articles/6.Using_clipboard.md) - [Extension](extensions/qml_tutorial_6/)
7. [Adding a sidebar](articles/7.Adding_a_sidebar.md) - [Extension](extensions/qml_tutorial_7/) 7. [Adding a sidebar](articles/7.Adding_a_sidebar.md) - [Extension](extensions/qml_tutorial_7/)
8. [Extension settings](articles/8.Extension_settings.md) - [Extension](extensions/qml_tutorial_8/)

View File

@ -0,0 +1,84 @@
# 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.
```ini
[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
```
```qml
Falkon.Settings {
id: settings
name: 'Tutorial8_settings'
}
settingsWindow: Rectangle {
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](http://falkon.sgorava.xyz/docs/class_qml_settings.html)
or
[code](https://github.com/KDE/falkon/blob/master/src/lib/plugins/qml/api/settings/qmlsettings.h)
## 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.
```qml
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](../images/tutorial8/settings_window.png)
### Code
The code for this example can be found at
[extensions/qml_tutorial_8](../extensions/qml_tutorial_8)

View File

@ -0,0 +1,74 @@
import org.kde.falkon 1.0 as Falkon
import QtQuick.Controls 2.3
import QtQuick 2.3
Falkon.PluginInterface {
Falkon.Settings {
id: settings
name: 'Tutorial8_settings'
}
init: function(state, settingsPath) {
console.log(i18n('"Tutorial8" plugin loaded'))
}
testPlugin: function() {
return true
}
unload: function() {
console.log(i18n('"Tutorial8" plugin unloaded'))
}
Falkon.BrowserAction {
name: 'QML Tutorial 8'
identity: 'qml-tutorial-8-id'
title: i18n('Qml Tutorial 8')
toolTip: i18n('My little button')
icon: 'falkon'
location: Falkon.BrowserAction.NavigationToolBar | (settings.value({key: 'statusbar', defaultValue: 1}) == 1 ? Falkon.BrowserAction.StatusBar : 0)
popup: Rectangle {
width: 100;
height: 100;
}
}
settingsWindow: Rectangle {
id: window
width: 256
height: 200
Image {
id: image
source: 'qrc:/icons/other/about.svg'
anchors.top: parent.top
anchors.left: parent.left
anchors.right: parent.right
}
CheckBox {
id: checkStatusbar
checked: settings.value({key: 'statusbar', defaultValue: 1}) == 1
text: 'Show in statusbar'
anchors.top: image.bottom
}
Button {
id: button
text: i18n('Save')
width: 256
height: 50
anchors.top: checkStatusbar.bottom
onClicked: function() {
var res = settings.setValue({
key: 'statusbar',
value: checkStatusbar.checked ? 1 : 0
})
var sync = settings.sync()
if (res && sync) {
button.text = i18n('Saved!')
} else {
button.text = i18n('Error occurred, try again!')
}
}
}
}
}

View File

@ -0,0 +1,11 @@
[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

Binary file not shown.

After

Width:  |  Height:  |  Size: 15 KiB