FalkonTutorials/qml/articles/8.Extension_settings.md

# 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
```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
```

main.qml
```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)

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.
```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)