Creating a traditional QGIS plugin

Plugins are the best way to extend QGIS, as they can be easily updated and reused by other people. And as we'll see throughout this book, you can use Python to create plugins. When you create a Python-based plugin, you can usually access that plugin's functionality through the PyQGIS API.

Getting ready

The easiest approach to creating a plugin is to use the Plugin Builder plugin to jump-start development. You can find it in the main QGIS plugin repository and install it.

How to do it...

Perform the following steps to create a simple plugin that displays a dialog box with a custom message:

1. Start QGIS.
2. From the Plugins menu, select Plugin Builder and then click on Plugin Builder in the submenu.
3. In the QGIS Plugin Builder dialog, name the class MyPlugin.
4. Name the plugin MyPlugin.
5. Type a short description, such as A demonstration Plugin.
6. Enter myplugin as the Module name.
7. Leave the default version numbers as they are.
8. Enter your name and e-mail address for author information.
9. Click Next.
10. Enter a description of the plugin in the About field.
11. Click Next.
12. In the Text for menu item field, enter My Plugin.
13. Click Next and then on the next dialog click Next again.
14. For the Bug Tracker field, enter https://github.com/GeospatialPython/Learn/issues.
15. For the Repository field, https://github.com/GeospatialPython/Learn/.
16. Ensure that the checkbox labeled Flag the plugin as experimental is checked.
17. Click on the OK button.
18. A file browser dialog will appear. You can choose a folder in which you want to create your plugin. Select one of the folders called plugins within the python folder in either the main user directory or the QGIS program directory. The following examples are from a Windows machine. You should use the folder in your user directory, which is the preferred place for third-party plugins. QGIS standard plugins go to the main program directory:

      C:\Users\<username>\.qgis2\python\plugins or the %USERPROFILE%
          environment variable
    
    C:\Program Files\QGIS2.18\apps\qgis\python\plugins
    

    On OS X or Linux machines, the .qgis2 directory will be in your home directory.

19. Close the Plugin Builder information dialog by clicking on the OK button.
20. Using Command Prompt, navigate to your new plugin template folder.
21. Use the pyrcc4 command to compile the resource file:

          pyrcc4 -o resources_rc.py resources.qrc
    

    Tip

    If you are on Windows, it is easier to use the OSGEO4W shell, which is installed along with QGIS for the Qt compilation tools to work properly.

22. In a text editor, such as Windows Notepad or vi on Linux, open the user interface XML file named myplugin_dialog_base.ui.
23. Insert the following XML for a custom label near line 31, just before the last </widget> tag. Save the file after this edit:

            <widget class="QLabel" name="label"> 
              <property name="geometry"> 
                <rect> 
                  <x>120</x> 
                  <y>80</y> 
                  <width>201</width> 
                  <height>20</height> 
                </rect> 
              </property> 
              <property name="font"> 
                <font> 
                  <pointsize>14</pointsize> 
                </font> 
              </property> 
              <property name="text"> 
                <string>Geospatial Python Rocks!</string> 
              </property> 
            </widget> 
    

24. Now compile the ui file using the pyuic4 tool:

    pyuic4 -o ui_myplugin.py ui_myplugin.ui
    

25. Your plugin is now ready. Restart QGIS.
26. Select My Plugin from the Plugins menu and then select My Plugin from the submenu to see the dialog you created within QGIS, as shown here:
    

How it works...

This recipe shows you the bare bones needed to make a working plugin. Although we haven't altered it, the code for the plugin's behavior is contained in myplugin.py. You can change the icon and the GUI and just recompile any time you want. Note that we must compile the Qt4 portion of the plugin, which creates the dialog box. The entire QGIS GUI is built on the Qt4 library, so the pyrrc4 compiler and pyuic4 is included to compile the GUI widgets.

You can download the completed plugin with both the source and compiled UI and resource files at https://github.com/GeospatialPython/Learn/raw/master/MyPlugin.zip.

Note

You can find out more about QGIS plugins, including the purpose of the other files in the directory, from the QGIS documentation at http://docs.qgis.org/testing/en/docs/pyqgis_developer_cookbook/plugins.html.

There's more...

We have edited the myplugin_dialog_base.ui XML file manually to make a small change. However, there is a better way to use Qt Creator. Qt Creator is a fully fledged open source GUI designer for the Qt framework. It is an easy what-you-see-is-what-you-get editor for Qt Widgets, including PyQGIS plugins, that uses the included Qt Designer interface. On Windows, Qt Designer can be found in the QGIS program directory within the bin directory. It is named designer.exe. On other platforms, Qt Designer is included as part of the qt4-devel package.

Note

You can also download Qt Creator, which includes Qt Designer, from https://www.qt.io/download/.

When you run the installer, you can uncheck all the installation options, except the Tools category, to install just the IDE.