{"id":16381,"date":"2026-06-10T10:00:00","date_gmt":"2026-06-10T08:00:00","guid":{"rendered":"https:\/\/www.sigterritoires.fr\/?p=16381"},"modified":"2026-06-10T10:30:41","modified_gmt":"2026-06-10T08:30:41","slug":"develop-qgis-plugin-add-button-dialog","status":"publish","type":"post","link":"https:\/\/www.sigterritoires.fr\/index.php\/en\/develop-qgis-plugin-add-button-dialog\/","title":{"rendered":"[EN]Developing a QGIS Plugin: Adding a Button and a Dialog"},"content":{"rendered":"\n

<\/p>\n\n\n\n

\n\n\n\n

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.<\/p>\n\n\n\n

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()<\/code> method, actions (QAction<\/code>), and how a dialog is triggered.<\/p>\n\n\n\n

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.<\/p>\n\n\n\n

\n\n\n\n\n\n\n
\n\n\n\n\n\nContenu <\/p>\nToggle<\/span>
Adding a Button and Displaying a Dialog in QGIS<\/a><\/li>
Reminder: the Plugin Generated by Plugin Builder<\/a><\/li>
The Main Plugin File<\/a><\/li>
The initGui() Method: the Visual Entry Point<\/a><\/li>
The run() Method: When the Button Is Clicked<\/a><\/li>
📦 What a Button Really Does in QGIS<\/a><\/li>
Understanding the Dialog Window<\/a><\/li>
Modifying the Dialog Text<\/a><\/li>
Testing and Reloading the Plugin<\/a><\/li>
Common Errors at This Stage<\/a><\/li>
What You Have Learned<\/a><\/li>
What\u2019s Next?<\/a><\/li><\/ul><\/nav><\/div>\n<\/span>Adding a Button and Displaying a Dialog in QGIS<\/span><\/h2>\n\n\n\nIn the first two articles, we laid the foundations: understanding what a QGIS plugin is and creating an empty plugin using Plugin Builder. Now it\u2019s time to give our plugin a visible behavior.<\/p>\n\n\n\n
In this article, you will learn how to:<\/p>\n\n\n\n
\nadd a button to the QGIS interface,<\/li>\n\n\n\n
understand the code generated by Plugin Builder,<\/li>\n\n\n\n
display a simple dialog window.<\/li>\n<\/ul>\n\n\n\nThe goal is not yet to build something complex, but to understand the fundamental mechanism behind every QGIS plugin.<\/p>\n\n\n\n
\n\n\n\n<\/span>Reminder: the Plugin Generated by Plugin Builder<\/span><\/h2>\n\n\n\nWhen we chose the \u201cTool button with dialog\u201d<\/strong> template, Plugin Builder already prepared many things for us:<\/p>\n\n\n\n
\na toolbar button,<\/li>\n\n\n\n
a menu entry in QGIS,<\/li>\n\n\n\n
an associated graphical dialog.<\/li>\n<\/ul>\n\n\n\nEven though everything already works, it is essential to understand how all these elements are connected.<\/p>\n\n\n\n
\n\n\n\n<\/span>The Main Plugin File<\/span><\/h2>\n\n\n\nOpen the main Python file of your plugin (for example mon_premier_plugin.py<\/code>).<\/p>\n\n\n\n
You will find a main class named after your plugin. This class controls the entire behavior of the plugin.<\/p>\n\n\n\n
class MonPremierPlugin:\n    def __init__(self, iface):\n        self.iface = iface\n<\/code><\/pre>\n\n\n\n👉 iface<\/code> is the object that allows the plugin to interact with QGIS (menus, layers, messages, etc.).<\/p>\n\n\n\n
\n\n\n\n<\/span>The initGui()<\/code> Method: the Visual Entry Point<\/span><\/h2>\n\n\n\nThe initGui()<\/code> method is automatically called when the plugin is activated in QGIS.<\/p>\n\n\n\n
This is where the following elements are defined:<\/p>\n\n\n\n
\nthe toolbar button,<\/li>\n\n\n\n
the menu entry,<\/li>\n\n\n\n
the associated action.<\/li>\n<\/ul>\n\n\n\nTypical example:<\/p>\n\n\n\n
def initGui(self):\n    self.action = QAction(\n        QIcon(':\/plugins\/MonPremierPlugin\/icon.png'),\n        'My first plugin',\n        self.iface.mainWindow()\n    )\n    self.action.triggered.connect(self.run)\n    self.iface.addToolBarIcon(self.action)\n<\/code><\/pre>\n\n\n\nEven without understanding every line, remember that:<\/p>\n\n\n\n
\nan action is created,<\/li>\n\n\n\n
it is connected to a method (run<\/code>),<\/li>\n\n\n\n
it is added to the QGIS interface.<\/li>\n<\/ul>\n\n\n\n
\n\n\n\n<\/span>The run()<\/code> Method: When the Button Is Clicked<\/span><\/h2>\n\n\n\nThe run()<\/code> method is called when the user clicks the plugin button.<\/p>\n\n\n\n
In the template generated by Plugin Builder, its main purpose is to display a dialog window.<\/p>\n\n\n\n
def run(self):\n    self.dlg.show()\n<\/code><\/pre>\n\n\n\n👉 At this stage, the plugin does only one thing: open a dialog.<\/p>\n\n\n\n
\n\n\n\n<\/span>📦 What a Button Really Does in QGIS<\/span><\/h2>\n\n\n\nWhen you click a button in QGIS, nothing \u201cmagical\u201d happens.<\/p>\n\n\n\n
A plugin button is simply a trigger: it calls a specific Python function.<\/p>\n\n\n\n
In practice, the workflow is always the same:<\/p>\n\n\n\n
\nthe plugin creates an action (QAction<\/code>),<\/li>\n\n\n\n
this action is linked to a function (for example run()<\/code>),<\/li>\n\n\n\n
when the user clicks the button, QGIS executes this function.<\/li>\n<\/ul>\n\n\n\nIn our case, the run()<\/code> function only displays a dialog. But later, this same function can:<\/p>\n\n\n\n
\nread parameters entered by the user,<\/li>\n\n\n\n
analyze layers,<\/li>\n\n\n\n
launch processing algorithms,<\/li>\n\n\n\n
produce results.<\/li>\n<\/ul>\n\n\n\n👉 A QGIS button does only one thing: it runs Python code.
All the real power of the plugin lies in that code.<\/p>\n\n\n\n
\n\n\n\n<\/span>Understanding the Dialog Window<\/span><\/h2>\n\n\n\nThe displayed dialog is defined in a .ui<\/code> file, created with Qt Designer<\/strong>.<\/p>\n\n\n\n
This file is then loaded in Python, which allows you to:<\/p>\n\n\n\n
\ndisplay the window,<\/li>\n\n\n\n
retrieve values entered by the user,<\/li>\n\n\n\n
connect buttons to Python code.<\/li>\n<\/ul>\n\n\n\nFor now, we will simply modify the visual content.<\/p>\n\n\n\n
\n\n\n\n<\/span>Modifying the Dialog Text<\/span><\/h2>\n\n\n\nOpen the .ui<\/code> file with Qt Designer.<\/p>\n\n\n\n
Try, for example, to:<\/p>\n\n\n\n
\nchange the window title,<\/li>\n\n\n\n
modify a label,<\/li>\n\n\n\n
add a button.<\/li>\n<\/ul>\n\n\n\nSave the file, reload the plugin in QGIS, and click the button.<\/p>\n\n\n\n
👉 You have just modified a QGIS plugin interface without writing any Python code<\/strong>.<\/p>\n\n\n\n
\n\n\n\n<\/span>Testing and Reloading the Plugin<\/span><\/h2>\n\n\n\nAfter each modification to the code or interface:<\/p>\n\n\n\n
\ndisable the plugin in the Plugin Manager,<\/li>\n\n\n\n
re-enable it,<\/li>\n<\/ul>\n\n\n\nor use the Reload plugin<\/strong> option if you have installed the dedicated plugin.<\/p>\n\n\n\n
\n\n\n\n<\/span>Common Errors at This Stage<\/span><\/h2>\n\n\n\n\nnothing happens when clicking \u2192 run()<\/code> method not connected<\/li>\n\n\n\n
error on loading \u2192 incorrect capitalization in class or file names<\/li>\n\n\n\n
empty dialog \u2192 .ui<\/code> file incorrectly referenced<\/li>\n<\/ul>\n\n\n\nThese issues are normal and part of the learning process.<\/p>\n\n\n\n
\n\n\n\n<\/span>What You Have Learned<\/span><\/h2>\n\n\n\nBy the end of this article, you now know:<\/p>\n\n\n\n
\nwhere a QGIS plugin button is created,<\/li>\n\n\n\n
how an action is connected to Python code,<\/li>\n\n\n\n
how to display and modify a dialog window.<\/li>\n<\/ul>\n\n\n\nYou now have the essential building block of any interactive QGIS plugin.<\/p>\n\n\n\n
\n\n\n\n<\/span>What\u2019s Next?<\/span><\/h2>\n\n\n\nIn the next article, we will see:<\/p>\n\n\n\n
\nhow to retrieve values entered in the dialog,<\/li>\n\n\n\n
how to interact with QGIS layers,<\/li>\n\n\n\n
how to structure the code to go further.<\/li>\n<\/ul>\n\n\n\n👉 From this point on, your plugin really starts to become useful.<\/p>\n\n\n\n
\n","protected":false},"excerpt":{"rendered":"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.…<\/p>\n","protected":false},"author":1,"featured_media":16327,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_bbp_topic_count":0,"_bbp_reply_count":0,"_bbp_total_topic_count":0,"_bbp_total_reply_count":0,"_bbp_voice_count":0,"_bbp_anonymous_reply_count":0,"_bbp_topic_count_hidden":0,"_bbp_reply_count_hidden":0,"_bbp_forum_subforum_count":0,"sfsi_plus_gutenberg_text_before_share":"","sfsi_plus_gutenberg_show_text_before_share":"","sfsi_plus_gutenberg_icon_type":"","sfsi_plus_gutenberg_icon_alignemt":"","sfsi_plus_gutenburg_max_per_row":"","_monsterinsights_skip_tracking":false,"_monsterinsights_sitenote_active":false,"_monsterinsights_sitenote_note":"","_monsterinsights_sitenote_category":0,"_jetpack_newsletter_access":"","_jetpack_dont_email_post_to_subs":false,"_jetpack_newsletter_tier_id":0,"_jetpack_memberships_contains_paywalled_content":false,"_jetpack_memberships_contains_paid_content":false,"footnotes":"","jetpack_post_was_ever_published":false},"categories":[3394,1377],"tags":[4196,4198,1758,4200,1386],"class_list":["post-16381","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-pluigin-en","category-qgis-en","tag-button","tag-dialog","tag-plugin-en","tag-plugin-builder","tag-qgis-en"],"aioseo_notices":[],"jetpack_featured_media_url":"https:\/\/i0.wp.com\/www.sigterritoires.fr\/wp-content\/uploads\/2026\/01\/pluginsQGIS3.jpg?fit=409%2C307&ssl=1","jetpack_shortlink":"https:\/\/wp.me\/p6XU0A-4gd","jetpack_sharing_enabled":true,"_links":{"self":[{"href":"https:\/\/www.sigterritoires.fr\/index.php\/wp-json\/wp\/v2\/posts\/16381","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.sigterritoires.fr\/index.php\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.sigterritoires.fr\/index.php\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.sigterritoires.fr\/index.php\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/www.sigterritoires.fr\/index.php\/wp-json\/wp\/v2\/comments?post=16381"}],"version-history":[{"count":0,"href":"https:\/\/www.sigterritoires.fr\/index.php\/wp-json\/wp\/v2\/posts\/16381\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/www.sigterritoires.fr\/index.php\/wp-json\/wp\/v2\/media\/16327"}],"wp:attachment":[{"href":"https:\/\/www.sigterritoires.fr\/index.php\/wp-json\/wp\/v2\/media?parent=16381"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.sigterritoires.fr\/index.php\/wp-json\/wp\/v2\/categories?post=16381"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.sigterritoires.fr\/index.php\/wp-json\/wp\/v2\/tags?post=16381"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}