QML: Add extension settings tutorial

Signed-off-by: Juraj Oravec <jurajoravec@mailo.com>

qml/README.md

@@ -7,3 +7,4 @@
 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/)
 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/)

qml/articles/8.Extension_settings.md

@@ -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)

qml/extensions/qml_tutorial_8/main.qml

@@ -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!')
+                }
+            }
+        }
+    }
+}

qml/extensions/qml_tutorial_8/metadata.desktop

@@ -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