diff --git a/qml/articles/2.Basic_extension.md b/qml/articles/2.Basic_extension.md new file mode 100644 index 0000000..0225208 --- /dev/null +++ b/qml/articles/2.Basic_extension.md @@ -0,0 +1,132 @@ +# 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 + +```qml +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.PluginInterface`[1]. +The full code can be found at +[extensions/qml_tutorial_2](../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. + + + +[1]: https://github.com/KDE/falkon/blob/master/src/lib/plugins/qml/qmlplugininterface.h diff --git a/qml/extensions/qml_tutorial_2/main.qml b/qml/extensions/qml_tutorial_2/main.qml new file mode 100644 index 0000000..d88b510 --- /dev/null +++ b/qml/extensions/qml_tutorial_2/main.qml @@ -0,0 +1,17 @@ +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')) + } + +} diff --git a/qml/extensions/qml_tutorial_2/metadata.desktop b/qml/extensions/qml_tutorial_2/metadata.desktop new file mode 100644 index 0000000..9c82730 --- /dev/null +++ b/qml/extensions/qml_tutorial_2/metadata.desktop @@ -0,0 +1,11 @@ +[Desktop Entry] +Name=Tutorial2 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 \ No newline at end of file