Writing QGIS plugins

One of the main reasons of the popularity of QGIS is its extensibility. Using the basic tools and features provided by the QGIS API, new functionality can be implemented and added as a new plugin that can be shared by contributing it to the QGIS plugins repository.

Getting ready

To be able to develop a new QGIS plugin, you should be familiar with the Python programming language. If the plugin has a graphical interface, you should have some knowledge of the Qt framework, as this is used for all UI elements, such as dialogs. To access the QGIS functionality, it is required that you know the QGIS API.

A very handy resource for all these (plus a few others) is the GeoAPIs website, which is created by SourcePole at http://geoapis.sourcepole.com/.

To simplify the creation of a plugin, we will use an additional plugin named Plugin Builder. It should be installed in your QGIS application.

How to do it…

The following steps create a new plugin that will print out detailed information about the layers currently loaded in your QGIS project:

Open Plugin Builder by navigating to Plugin | Plugin Builder.
Fill out the dialog that will appear, as shown in the following screenshot:
Click on OK.
In the folder selector dialog that will appear, select the folder where you want to store your plugin. Click on OK and the plugin skeleton will be created. In the selected folder, you will now have a subfolder named LayerInfoPlugin, with the following content (items in square brackets indicate folders):
```
[help]
[i18n]
[scripts]
[test]
icon.png
layerinfo.py
layerinfo_dialog.py
layerinfo_dialog_base.ui
Makefile
metadata.txt
pb_tool.cfg
plugin_upload.py
pylintrc
README.html
README.txt
resources.qrc
__init__.py
```

Open the layerinfo.py file in a text editor. At the end of it, you will find the run() method, with the following code:

def run(self):
  """Run method that performs all the real work"""
# show the dialog
self.dlg.show()
# Run the dialog event loop
result = self.dlg.exec_()
# See if OK was pressed
if result: pass

Replace the run method with the following code:

  def run(self):
    layers = self.iface.legendInterface().layers()
    print "---LAYERS INFO---"
    for layer in layers:
      print "Layer name: " + layer.name()
      print "Layer source " + layer.source()
      print "Extent: " + layer.extent().asWktCoordinates()
      print

Install the pb_tool application by opening a terminal and running easy_install pb_tool (you can also use pip install pb_tool or any other way of installing a library from PyPI).
Open a terminal in the folder where you have the plugin code and run pb_tool and compile. Then, run pb_tool deploy to install the plugin in your local QGIS.
Open QGIS. Go to Plugin Manager and make sure that the new plugin we have created is there and is enabled:
In the Plugins menu, you will now have the entry corresponding to the plugin:
Populate your project with some layers so that the plugin can display information about them.
Open the QGIS Python console.
Run the plugin by selecting its menu entry. Information about the layers in the project will be shown in the console:

How it works…

The Plugin Builder plugin takes some basic information about the plugin to create it, and uses it to create its skeleton. By default, it includes a menu entry, which becomes the entry point to the plugin from the QGIS interface.

When the menu item is selected, the corresponding action in the plugin code is executed. In this case, it runs the run() method, where we have added our code.

The plugin will always have a reference to the QGIS instance (an object of class QgsInterface), which can be used to access the QGIS API and connect with the elements in the current QGIS session. In our case, this is used to access the legend, which contains a list of all the layers loaded in the current project. Calling the corresponding methods in each one of these layers, the information about them is retrieved and printed out.

The standard output is redirected to the QGIS Python console, so printing a text using the built-in Python print command will cause the text to appear in the console in case it is open.

QGIS stores its plugins in the .qgis2/python/plugin folder under the current user folder. For instance, this is when you download a new plugin using Plugin Manager. Each time you start QGIS, it will look for plugins there and load them. Copying the folder is done by the deploy task that we have run, and this allows QGIS to discover the plugin and add it to the list of available plugins when QGIS is started.

There's more…

The following are some ideas to create better plugins and manage them.

Creating plugins with more complex UI elements

The plugin that we have created has no UI elements. However, among the files created by the plugin builder, you can find a basic dialog file with the .ui extension. You can edit this to create a dialog that can later be used, by calling it from your plugin code. To know more about how to create and use UI elements from the Qt framework (QGIS is built on top of this framework), check out the PyQt documentation.

Documenting you plugin

Another thing that is created by the Plugin Builder is a Sphinx documentation project where you can write the usage documentation of your plugin using RestructuredText. To know more about Sphinx, you can visit the Sphinx official site at http://www.sphinx-doc.org/en/stable/.

The documentation project is built when the deploy task is run, and will create HTML files and place them in the plugin folder.

Releasing your plugin

Once your plugin is finished, it would be a good idea to share it and let other people use it. If you upload your plugin to the QGIS plugin server, it would be easy for all QGIS users to get it using Plugin Manager and also get the latest updates.

To upload the plugin, you first need to create a ZIP file containing all its code and resources. There is a pb_tool task for this, and you just have to run pb_tool zip in a terminal. With the resulting zip file, you can start the release process. More information about it can be found at http://docs.qgis.org/2.6/en/docs/pyqgis_developer_cookbook/releasing.html.

Previous Chapter

Writing Processing algorithms

Next Chapter

Using external tools

Table of Contents for QGIS: Becoming a GIS Power User