1
FalkonTutorials/qml/articles/2.Basic_extension.md
Juraj Oravec 72099ed55f
Fix broken Markdown links
Signed-off-by: Juraj Oravec <jurajoravec@mailo.com>
2022-03-29 01:02:35 +02:00

3.2 KiB

Falkon QML Tutorial - 2. Basic extension

This will create a basic extension which Falkon will be able to load and unload. It will also print text to the standard output and to see it start falkon from terminal.

File structure

Each extension has to contain:

  • metadata.desktop
  • main.qml

Anything else depend on the creator.

metadata.desktop

This file contain information which are displayed in Falkon settings and some configuration.

Example file

[Desktop Entry]
Name=Example QML
Comment=Example QML extension
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=false

Name

Extension name shown in Falkon settings.

Comment

Extension description shown in Falkon settings.

Icon

Extension Icon shown in Falkon settings.
Path to icon file or icon name from icon theme.
For the final product it is best to provide the icon with the extension so that machines without this icon or on some obscure systems the icon will be present.

Type

Keep: Service
I did not find a use of this field in code yet (maybe legacy ?).

X-Falkon-Type

Falkon Extension type.
For QML extension use: Extension/Qml

X-Falkon-Author

Author`s name shown in Falkon settings.

X-Falkon-Email

Author`s email shown in Falkon settings.

X-Falkon-Version

Extension version shown in Falkon settings.

X-Falkon-Settings

If extension has a setting dialog.
Extension Settings button in Falkon preferences depends on this variable.
Possible values: true or false

main.qml

Entry point to our program.
This file will be called when extension is loaded.
Some people consider leaving this file almost empty with only license and import line.
I will leave the decision up to you.

Example extension

import org.kde.falkon 1.0 as Falkon

Falkon.PluginInterface {

    init: function(state, settingsPath){
        console.log(i18n('"Tutorial2" plugin loaded'))
    }

    testPlugin: function() {
        return true
    }

    unload: function() {
        console.log(i18n('"Tutorial2" plugin unloaded'))
    }

}

The plugin / extension inherits from Falkon.PluginInterfacelink. The full code can be found at extensions/qml_tutorial_2

Methods used

init()

Called when extension is loaded.

  • state: possible values
    • Falkon.PluginInterface.InitState.StartupInitState
      Normal init state during Falkon start, nothing to do for us.
    • Falkon.PluginInterface.LateInitState
      The extension was loaded long after Falkon started.
      In this case we need to manually call functions which would normally be called during the start.
      The exact usecase will be shown in one of the next chapters.
  • settingsPath: Contains path to an extension setting directory

unload()

Called when the plugin is uloading by being disabled in settings or when Falkon is closing.

testPlugin()

Method to check if plugin is compatible with current Falkon version.
Return true if is and false if not.