Adding a button to the QGIS interface is often the first concrete step when developing a plugin. It is what turns a simple Python script into a tool that can actually be used by end users.
In this third article of the tutorial, we will see how to add a button and display a dialog window in a QGIS plugin, based on the code generated by Plugin Builder. We will take the time to understand the essential elements: the initGui() method, actions (QAction), and how a dialog is triggered.
This tutorial is aimed at beginners in QGIS plugin development who want to understand how to interact with the QGIS interface before moving on to more advanced business logic.
Adding a Button and Displaying a Dialog in QGIS
In the first two articles, we laid the foundations: understanding what a QGIS plugin is and creating an empty plugin using Plugin Builder. Now it’s time to give our plugin a visible behavior.
In this article, you will learn how to:
- add a button to the QGIS interface,
- understand the code generated by Plugin Builder,
- display a simple dialog window.
The goal is not yet to build something complex, but to understand the fundamental mechanism behind every QGIS plugin.
Reminder: the Plugin Generated by Plugin Builder
When we chose the “Tool button with dialog” template, Plugin Builder already prepared many things for us:
- a toolbar button,
- a menu entry in QGIS,
- an associated graphical dialog.
Even though everything already works, it is essential to understand how all these elements are connected.
The Main Plugin File
Open the main Python file of your plugin (for example mon_premier_plugin.py).
You will find a main class named after your plugin. This class controls the entire behavior of the plugin.
class MonPremierPlugin:
def __init__(self, iface):
self.iface = iface
👉 iface is the object that allows the plugin to interact with QGIS (menus, layers, messages, etc.).
The initGui() Method: the Visual Entry Point
The initGui() method is automatically called when the plugin is activated in QGIS.
This is where the following elements are defined:
- the toolbar button,
- the menu entry,
- the associated action.
Typical example:
def initGui(self):
self.action = QAction(
QIcon(':/plugins/MonPremierPlugin/icon.png'),
'My first plugin',
self.iface.mainWindow()
)
self.action.triggered.connect(self.run)
self.iface.addToolBarIcon(self.action)
Even without understanding every line, remember that:
- an action is created,
- it is connected to a method (
run), - it is added to the QGIS interface.
The run() Method: When the Button Is Clicked
The run() method is called when the user clicks the plugin button.
In the template generated by Plugin Builder, its main purpose is to display a dialog window.
def run(self):
self.dlg.show()
👉 At this stage, the plugin does only one thing: open a dialog.
📦 What a Button Really Does in QGIS
When you click a button in QGIS, nothing “magical” happens.
A plugin button is simply a trigger: it calls a specific Python function.
In practice, the workflow is always the same:
- the plugin creates an action (
QAction), - this action is linked to a function (for example
run()), - when the user clicks the button, QGIS executes this function.
In our case, the run() function only displays a dialog. But later, this same function can:
- read parameters entered by the user,
- analyze layers,
- launch processing algorithms,
- produce results.
👉 A QGIS button does only one thing: it runs Python code.
All the real power of the plugin lies in that code.
Understanding the Dialog Window
The displayed dialog is defined in a .ui file, created with Qt Designer.
This file is then loaded in Python, which allows you to:
- display the window,
- retrieve values entered by the user,
- connect buttons to Python code.
For now, we will simply modify the visual content.
Modifying the Dialog Text
Open the .ui file with Qt Designer.
Try, for example, to:
- change the window title,
- modify a label,
- add a button.
Save the file, reload the plugin in QGIS, and click the button.
👉 You have just modified a QGIS plugin interface without writing any Python code.
Testing and Reloading the Plugin
After each modification to the code or interface:
- disable the plugin in the Plugin Manager,
- re-enable it,
or use the Reload plugin option if you have installed the dedicated plugin.
Common Errors at This Stage
- nothing happens when clicking →
run()method not connected - error on loading → incorrect capitalization in class or file names
- empty dialog →
.uifile incorrectly referenced
These issues are normal and part of the learning process.
What You Have Learned
By the end of this article, you now know:
- where a QGIS plugin button is created,
- how an action is connected to Python code,
- how to display and modify a dialog window.
You now have the essential building block of any interactive QGIS plugin.
What’s Next?
In the next article, we will see:
- how to retrieve values entered in the dialog,
- how to interact with QGIS layers,
- how to structure the code to go further.
👉 From this point on, your plugin really starts to become useful.
