FalkonTutorials/articles/3. Adding a button to the toolbar.md

Falkon Python Tutorial - 3. Adding a button to the toolbar

In this chapter will be shown how to add Simple button to the toolbar.
The button has to be added to every window.
The button has to be added to new windows and removed when the window is closing.

Fill metadata

It feels like a paperwork but it has to be done.

metadata.desktop

[Desktop Entry]
Name=Falkon Python Tutorial 3
Comment=Adding a button to the toolbar
Icon=
Type=Service
X-Falkon-Type=Extension/Python

X-Falkon-Author=Juraj Oravec
X-Falkon-Email=sgd.orava@gmail.com
X-Falkon-Version=1.0.0
X-Falkon-Settings=false

Create button

TutorialButton.py

import Falkon


class TutorialButton(Falkon.AbstractButtonInterface):
    def __init__(self):
        super().__init__()

        self.number = 0

        self.setTitle("Tutorial 3")
        self.setToolTip("Increment the number")
        self.setBadgeText(str())

        self.clicked.connect(self.onClicked)

    def id(self):
        return "falkon-python-tutorial-3-button"

    def name(self):
        return "Falkon Python Tutorial 3 Button"

    def onClicked(self, controller):
        self.number += 1
        self.setBadgeText(str(self.number))

The button class has to inherit from Falkon.AbstractButtonInterface1

Falkon.AbstractButtonInterface

The interface class for Falkon buttons.

id()

This id 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.

setTitle()

I did not find a sensible use for this function in the Falkons code yet.

setToolTip()

The buttons tooltip which will be displayed when you hover with mouse over the button.

setBadgeText()

The text in a form of a badge over the button.
Used by AdBlock plugin to show how many item it blocked.

Note: When I set the badgeText in _init_() it did not show in UI. Maybe bug, maybe intentional behaviour, ask the Falkon author.

clicked event

Emitted when the mouse click on the button.
In this example this signal is connected to onClicked() method

onClicked()

The variable number is increased and its value is shown in the button badge.

Plugin module

_init_.py

import Falkon
from PySide2 import QtCore
from Tutorial3.TutorialButton import TutorialButton


class Tutorial3_Plugin(Falkon.PluginInterface, QtCore.QObject):
    def init(self, state, settingsPath):
        self.buttons = {}

        plugins = Falkon.MainApplication.instance().plugins()

        plugins.mainWindowCreated.connect(self.mainWindowCreated)
        plugins.mainWindowDeleted.connect(self.mainWindowDeleted)

        if state == Falkon.PluginInterface.LateInitState:
            for window in Falkon.MainApplication.instance().windows():
                self.mainWindowCreated(window)

    def unload(self):
        for window in Falkon.MainApplication.instance().windows():
            self.mainWindowDeleted(window)

    def testPlugin(self):
        return True

    def mainWindowCreated(self, window):
        b = TutorialButton()
        window.navigationBar().addToolButton(b)
        self.buttons[window] = b

    def mainWindowDeleted(self, window):
        if window not in self.buttons:
            return

        b = self.buttons[window]
        window.navigationBar().removeToolButton(b)
        del self.buttons[window]


Falkon.registerPlugin(Tutorial3_Plugin())

To add a button to the Falkon interface we need to create new button for each window and store it somewhere.

To add button to each window we create mainWindowCreated() and mainWindowDeleted() methods.

    def mainWindowCreated(self, window):
        b = TutorialButton() # Create an instance of the button
        window.navigationBar().addToolButton(b) # Add button to toolbar
        self.buttons[window] = b # store the button

    def mainWindowDeleted(self, window):
        if window not in self.buttons: # Check if the button exist for selected window
            return

        b = self.buttons[window]
        window.navigationBar().removeToolButton(b) # remove the button from toolbar
        del self.buttons[window]

When the methods are ready we connect them to mainWindowCreated and mainWindowDeleted event.

        plugins = Falkon.MainApplication.instance().plugins()

        plugins.mainWindowCreated.connect(self.mainWindowCreated)
        plugins.mainWindowDeleted.connect(self.mainWindowDeleted)

Variable plugins is an instance of PluginProxy.

In case the extension is enabled when Falkon is already running we need to manually call mainWindowCreated method for each window.

        if state == Falkon.PluginInterface.LateInitState:
            for window in Falkon.MainApplication.instance().windows(): # Get list of currently open windows
                self.mainWindowCreated(window)

Add button to statusbar

At the moment of writing this tutorial Falkon does not have any kind of configuration dialog to arrange buttons.
Buttons in statusbar are shown on 'first come first served' basis.

To add button to statusbar only two lines are needed.

Update mainWindowCreated()

The line which needs to be added:

        window.statusBar().addButton(b)

Update mainWindowDeleted()

The line which needs to be added:

        window.statusBar().removeButton(b)

The result

    def mainWindowCreated(self, window):
        b = TutorialButton()
        window.navigationBar().addToolButton(b)
        window.statusBar().addButton(b) # For statusbar
        self.buttons[window] = b

    def mainWindowDeleted(self, window):
        if window not in self.buttons:
            return

        b = self.buttons[window]
        window.navigationBar().removeToolButton(b)
        window.statusBar().removeButton(b) # For statusbar
        del self.buttons[window]

It is simple, right ?