From 14f8f2a1502c42537097f7bbeddc1b3cf598545b Mon Sep 17 00:00:00 2001
From: Juraj Oravec <jurajoravec@mailo.com>
Date: Sun, 27 Mar 2022 15:42:39 +0200
Subject: [PATCH] Add QML toolbar button example

Signed-off-by: Juraj Oravec <jurajoravec@mailo.com>
---
 .../3.Adding_a_button_to_the_toolbar.md       | 76 +++++++++++++++++++
 .../qml_tutorial_2/metadata.desktop           |  2 +-
 qml/extensions/qml_tutorial_3/main.qml        | 44 +++++++++++
 .../qml_tutorial_3/metadata.desktop           | 11 +++
 4 files changed, 132 insertions(+), 1 deletion(-)
 create mode 100644 qml/articles/3.Adding_a_button_to_the_toolbar.md
 create mode 100644 qml/extensions/qml_tutorial_3/main.qml
 create mode 100644 qml/extensions/qml_tutorial_3/metadata.desktop

diff --git a/qml/articles/3.Adding_a_button_to_the_toolbar.md b/qml/articles/3.Adding_a_button_to_the_toolbar.md
new file mode 100644
index 0000000..4b932ec
--- /dev/null
+++ b/qml/articles/3.Adding_a_button_to_the_toolbar.md
@@ -0,0 +1,76 @@
+# Falkon QML Tutorial - 3. Adding a button to the toolbar
+
+In this chapter will be shown how to add Simple button to the toolbar
+and statusbar.
+
+
+## Create button
+
+The button in QML is represented by `Falkon.BrowserAction` and will be 
+automatically added to all windows. At the moment of writing this 
+article the button shares the same instance with all windows and thus 
+per window modifications are impossible (would be very inconsistent|.
+
+```qml
+Falkon.BrowserAction {
+    name: 'QML Tutorial 3'
+    identity: 'qml-tutorial-3-id'
+    title: i18n('Qml Tutorial 3')
+    toolTip: i18n('My little button')
+    icon: 'falkon'
+    location: Falkon.BrowserAction.NavigationToolBar | Falkon.BrowserAction.StatusBar
+    onClicked: someFunctions()
+    popup: Rectangle {
+        width: 100;
+        height: 100;
+    }
+}
+```
+
+### Falkon.BrowserAction
+The interface class for Falkon buttons.
+
+#### identity
+This identity will be used by Falkon when you add the button to toolbar
+to determinate its place in the toolbar.
+
+#### name
+The name which will be displayed in "Configure toolbar" dialog.
+
+#### title
+I did not find a sensible use for this function in the Falkons code yet.
+
+#### toolTip
+The buttons tooltip which will be displayed when you hover with mouse over the button.
+
+#### badgeText
+The text in a form of a badge over the button.  
+Used by **AdBlock** plugin to show how many item it blocked.
+
+#### icon
+Icon used for the button. If the icon is not specified the button will
+be left blank. The icon can either be name of system icon or a filename,
+in case of using filename the file should be provided together with the
+extension.
+
+#### position
+Configure where should the button be added.  
+In case of adding button to the toolbar in will only appear as available
+in the toolbar customize menu and user has to add it to the toolbar
+manualy. For statusbar the button will appear in the statusbar
+immediately but the order of icons cannot be customized at the moment.
+
+#### onClicked
+Called when the mouse click on the button.  
+Somehow handled by QML, it might be possible to add mouse hover
+detection and maybe some other things as well, I did not try that
+though.
+
+
+## Code
+The example code will add a button to main toolbar and statusbar. When
+user clicks on the button the small white rectangle will show up and the
+number displayed on the badge will increase.
+
+The code for this example can be found at
+[extensions/qml_tutorial_3](../extensions/qml_tutorial_3)
diff --git a/qml/extensions/qml_tutorial_2/metadata.desktop b/qml/extensions/qml_tutorial_2/metadata.desktop
index 9c82730..8d7ae6f 100644
--- a/qml/extensions/qml_tutorial_2/metadata.desktop
+++ b/qml/extensions/qml_tutorial_2/metadata.desktop
@@ -8,4 +8,4 @@ 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
+X-Falkon-Settings=false
diff --git a/qml/extensions/qml_tutorial_3/main.qml b/qml/extensions/qml_tutorial_3/main.qml
new file mode 100644
index 0000000..da820fe
--- /dev/null
+++ b/qml/extensions/qml_tutorial_3/main.qml
@@ -0,0 +1,44 @@
+import org.kde.falkon 1.0 as Falkon
+import QtQuick 2.3
+
+Falkon.PluginInterface {
+
+    QtObject {
+        id: tutorial3Object
+        property int clickCount
+    }
+
+    init: function(state, settingsPath){
+        console.log(i18n('"Tutorial3" plugin loaded'))
+        tutorial3Object.clickCount = 0;
+    }
+
+    testPlugin: function() {
+        return true
+    }
+
+    unload: function() {
+        console.log(i18n('"Tutorial3" plugin unloaded'))
+    }
+
+    function buttonClicked() {
+        tutorial3Object.clickCount++;
+        console.log(i18n('"Tutorial3" clickCount increased to ' + tutorial3Object.clickCount))
+    }
+
+    Falkon.BrowserAction {
+        name: 'QML Tutorial 3'
+        identity: 'qml-tutorial-3-id'
+        title: i18n('Qml Tutorial 3')
+        toolTip: i18n('My little button')
+        icon: 'falkon'
+        badgeText: tutorial3Object.clickCount
+        location: Falkon.BrowserAction.NavigationToolBar | Falkon.BrowserAction.StatusBar
+        onClicked: buttonClicked()
+        popup: Rectangle {
+            width: 100;
+            height: 100;
+        }
+    }
+
+}
diff --git a/qml/extensions/qml_tutorial_3/metadata.desktop b/qml/extensions/qml_tutorial_3/metadata.desktop
new file mode 100644
index 0000000..8283ff2
--- /dev/null
+++ b/qml/extensions/qml_tutorial_3/metadata.desktop
@@ -0,0 +1,11 @@
+[Desktop Entry]
+Name=Tutorial3 QML
+Comment=Example QML extension with button
+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