I'm just trying to understand the architecture of a QGIS Plugin created with the QGIS Plugin Builder, as well as the workflow and the linkage among generated files. If possible, I'd prefer a diagram.

It would also be helpful to know what the following functions do in the Python code. I'm new in QGIS Plugin creation.

  1. __init__( self, iface )
  2. tr( self, message )
  3. add_action( self )
  4. initGui( self )
  5. unload( self )
  6. run( self )
  • There is some information in the following link:docs.qgis.org/testing/en/docs/pyqgis_developer_cookbook/…. Unfortunately I don't think there's a 'Dummies Guide' in developing QGIS plugins (as I could sure do with one!).
    – Joseph
    Jan 23 '15 at 15:49
  • sorry to say that the above url was not found on the server.
    – User123
    Jan 23 '15 at 17:21
  • It is a pure Python question of creation of classes (general and with PyQt4). The only PyQGIS question here is what is iface ( the QGIS interface). It seems to me that if you know Python, the scripts are self-explanatory (with all the # descriptions)
    – gene
    Jan 23 '15 at 18:44
  • Fine.I am just wondering how will each functions reflect the qgis. Say for example run function code changes will reflect in our plugin.
    – User123
    Jan 24 '15 at 7:54
  • Strange, the url was working before...try this: docs.qgis.org/testing/en/docs/pyqgis_developer_cookbook/…
    – Joseph
    Jan 26 '15 at 9:45

The PyQGIS Cookbook explains what files are common in QGIS plugins. As you can see there, you would only need three files to run a minimal plugin:

  • __init__.py
  • metadata.txt
  • mainPlugin.py

The __init__.py file lets QGIS know the Plugin folder is a Python module. It must contain a classFactory(iface) function that QGIS uses to initialize your plugin, making use of your main Plugin class, which is in the mainPlugin.py file.

metadata.txt is where you specify the metadata of your plugin, i.e., plugin's name, author, license, version, homepage, bugtracker, repository, among others.

mainPlugin.py might be named in other ways. This is the file referenced in __init__.py and contains the functions you enumerated in your question. I'd say this file is the core of your plugin.

Regarding the QGIS Plugin Builder, I suggest you to read the official documentation to get an idea of how it is structured. I actually prefer not to use such plugin, because it creates lots of stuff you wouldn't like to be aware while you are learning the basics of plugin development.

I recommend you starting from plugins you completely understand. That is, start with a very basic (even the minimal) plugin structure and add complexity only when necessary, and when you master the basics.

On the other hand, I'll tell you what the functions you enumerated are for:

  1. __init__( self, iface )

This is the constructor of your plugin. When QGIS recognizes a folder as a Python plugin, the __init__() method is executed, and the interface object, iface, is passed to your plugin, so that it can access QGIS afterwards.

You should use this method to save a reference to iface (as it will be your entry point to QGIS components) as well as to initialize other variables you will use in other functions of your plugin.

  1. tr( self, message )

This is a Python function to get translations from strings. Of course you'll need to provide translations, but you do that in other Qt files (namely, in .ts files).

In general, you wouldn't need this function unless you're going to support languages other than English. It is definitely not a priority for new PyQGIS developers.

  1. add_action( self )

This is a function I've only seen in plugins generated via QGIS Plugin Builder. It helps you set up your plugin GUI. I personally do not use it in my plugins.

  1. initGui( self )

This is a method to set up your Plugin's GUI within QGIS. Here you specify whether you want a button in the QGIS Plugin's toolbar, a custom toolbar, a button inside an existing QGIS menu, and/or (not recommended) a new custom menu.

This is also a good place to establish SIGNAL/SLOT connections betweeen your plugin buttons (or other controls) and your functions.

  1. unload( self )

This is a method to remove your plugin widgets (buttons, menus, and the like) from QGIS GUI.

This is also a good place to disconnect SIGNALS and SLOTS that you have connected in initGui( self ).

  1. run( self )

This is the main method of your plugin. Here you put the code that will run when the user clicks on your plugin's button. By and large, you start by getting some data from the current QGIS project and then do some editing, processing, or reporting. It's totally up to you.

If your plugin has a dialog, this is the method where you should open it, so that the user can start interacting with the dialog. The dialog logic is normally handled in other Python files, in order to distribute your code and favor maintenance and encapsulation.

Note that run() is not a good place to set SIGNAL/SLOT connections, because doing so, they will be set every time you open your plugin's dialog, triggering your (SLOT) functions multiple times like in Odd behavior in a QGIS plugin: my function is triggered twice.

Finally, the best way to learn to program QGIS plugins is to read other plugins' source code. Start with simple ones and when you master them, go ahead to more complex ones.

I've created a (very simple) demo plugin to help you understand how QGIS plugins work. You can access it from here. There are installation instructions in the README file. The plugin lets you know, through message boxes, when each function you asked for is executed.

  • 1
    Thank you gcarrillo for your clear explanation.I am sure it will be exceedingly helpful to me as a beginner.
    – User123
    Feb 1 '15 at 9:36
  • 1
    Question about the run method. I have also seen it named onRun. Can I assume that the naming does not matter, but it generally contains the word run out of habit? Feb 1 '15 at 11:13
  • 2
    Right @BritishSteel, you could name such method as you want. run() is a sort of convention. Usually in initGui() you set a connection between a click on your plugin button and your run() method, so if you want to give it another name, you should also update the slot used in this connection. Something like self.action.triggered.connect(self.myCustomRun). Feb 1 '15 at 12:58
  • 1
    This is just great, I will also find this incredibly useful!
    – Joseph
    Feb 2 '15 at 13:30
  • 1
    Hi @nickves, I migrated the demo plugin to QGIS v3 and updated the link. Jun 20 '20 at 23:51

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.