Розробка плаґінів на Python¶

Створення необхідних файлів¶

Нижче наведено вміст каталогу нашого демонстраційного плаґіна

PYTHON_PLUGINS_PATH/
  MyPlugin/
    __init__.py    --> *required*
    mainPlugin.py  --> *required*
    metadata.txt   --> *required*
    resources.qrc  --> *likely useful*
    resources.py   --> *compiled version, likely useful*
    form.ui        --> *likely useful*
    form.py        --> *compiled version, likely useful*

Для чого потрібні ці файли:

• __init__.py = точка входу плаґіна. Тут знаходиться метод classFactory() та інший код ініціалізації.

• mainPlugin.py = основний код плаґіна. Містить інформацію про всі «дії» плаґіна та основний код.

• resources.qrc = XML-документ, створений Qt Designer. Тут зберігаються відносні шляхи до ресурсів форм.

• resources.py = адаптована для Python версія вищеописаного файлу.

• form.ui = графічний інтерфейс (GUI), створений у Qt Designer.

• form.py = адаптована для Python версія вищеописаного файлу.

• metadata.txt = необхідний для QGIS >= 1.8.0. Містить загальну інформацію про плаґін: його версію, назву та інші метадані, необхідні для нового репозиторію плаґінів. Починаючи з QGIS 2.0 метадані з __init__.py не використовуються, файл metadata.txt є обов’язковим.

Тут знаходиться онлайновий генератор базових файлів (основи) типового плаґіна для QGIS.

Також можна скористатися плаґіном Plugin Builder, який дозволяє створювати шаблон плаґінів прямо з QGIS та не потребує доступу до інтернету. Рекомендуємо використовувати саме цей варіант, оскільки він генерує файли, сумісні з QGIS 2.0.

Метадані плаґіна¶

Перш за все Менеджер плаґінів повинен отримати основну інформацію про плаґін: назву, опис тощо. Ці дані повинні знаходитися у файлі metadata.txt.

За замовчанням плагіни додаються у меню Плаґіни (нижче показується як додати плаґін до меню), але також можна розмістити плаґін у меню Растр, Вектор, База даних та Інтернет.

Відповідне значення метаданих category допомогає класифікувати плаґіни. Ця величина використовується як підказка для користувачів та показує де (у якому меню) шукати плаґін. Допустимі значення Raster, Vector, Database та Web. Наприклад, ваш плаґін буде доступний з меню Растр, тоді у файлі metadata.txt необхідно вказати

category=Raster

Приклад metadata.txt

; the next section is mandatory

[general]
name=HelloWorld
email=me@example.com
author=Just Me
qgisMinimumVersion=2.0
description=This is an example plugin for greeting the world.
    Multiline is allowed:
    lines starting with spaces belong to the same
    field, in this case to the "description" field.
    HTML formatting is not allowed.
about=This paragraph can contain a detailed description
    of the plugin. Multiline is allowed, HTML is not.
version=version 1.2
; end of mandatory metadata

; start of optional metadata
category=Raster
changelog=The changelog lists the plugin versions
    and their changes as in the example below:
    1.0 - First stable release
    0.9 - All features implemented
    0.8 - First testing release

; Tags are in comma separated value format, spaces are allowed within the
; tag name.
; Tags should be in English language. Please also check for existing tags and
; synonyms before creating a new one.
tags=wkt,raster,hello world

; these metadata can be empty, they will eventually become mandatory.
homepage=http://www.itopen.it
tracker=http://bugs.itopen.it
repository=http://www.itopen.it/repo
icon=icon.png

; experimental flag (applies to the single version)
experimental=True

; deprecated flag (applies to the whole plugin and not only to the uploaded version)
deprecated=False

; if empty, it will be automatically set to major version + .99
qgisMaximumVersion=2.0

__init__.py¶

This file is required by Python’s import system. Also, Quantum GIS requires that this file contains a classFactory() function, which is called when the plugin gets loaded to QGIS. It receives reference to instance of QgisInterface and must return instance of your plugin’s class from the mainplugin.py — in our case it’s called TestPlugin (see below). This is how __init__.py should look like

def classFactory(iface):
  from mainPlugin import TestPlugin
  return TestPlugin(iface)

## any other initialisation needed

mainPlugin.py¶

Тут відбувається вся магія, і ось як це виглядає

from PyQt4.QtCore import *
from PyQt4.QtGui import *
from qgis.core import *

# initialize Qt resources from file resources.py
import resources

class TestPlugin:

  def __init__(self, iface):
    # save reference to the QGIS interface
    self.iface = iface

  def initGui(self):
    # create action that will start plugin configuration
    self.action = QAction(QIcon(":/plugins/testplug/icon.png"), "Test plugin", self.iface.mainWindow())
    self.action.setObjectName("testAction")
    self.action.setWhatsThis("Configuration for test plugin")
    self.action.setStatusTip("This is status tip")
    QObject.connect(self.action, SIGNAL("triggered()"), self.run)

    # add toolbar button and menu item
    self.iface.addToolBarIcon(self.action)
    self.iface.addPluginToMenu("&Test plugins", self.action)

    # connect to signal renderComplete which is emitted when canvas
    # rendering is done
    QObject.connect(self.iface.mapCanvas(), SIGNAL("renderComplete(QPainter *)"), self.renderTest)

  def unload(self):
    # remove the plugin menu item and icon
    self.iface.removePluginMenu("&Test plugins",self.action)
    self.iface.removeToolBarIcon(self.action)

    # disconnect form signal of the canvas
    QObject.disconnect(self.iface.mapCanvas(), SIGNAL("renderComplete(QPainter *)"), self.renderTest)

  def run(self):
    # create and show a configuration dialog or something similar
    print "TestPlugin: run called!"

  def renderTest(self, painter):
    # use painter for drawing to map canvas
    print "TestPlugin: renderTest called!"

У коді плаґіна(наприклад, у mainPlugin.py) aлe обов’язково повинні буди два методи:

• __init__ –> which gives access to Quantum GIS’ interface

• initGui() — викликається під час активації плаґіна

• unload() — викликається коли плаґін деактивується

Ви можете бачити, що у нашому прикладі використовується метод ``:func:`addPluginToMenu`<http://qgis.org/api/classQgisInterface.html#ad1af604ed4736be2bf537df58d1399c3>`_. Він відповідає за створення вкладеного меню плаґіна в основному меню Модулі. Список цих методів:

• addPluginToRasterMenu()
• addPluginToVectorMenu()
• addPluginToDatabaseMenu()
• addPluginToWebMenu()

Їх синтаксис співпадає з синтаксисом методу addPluginToMenu().

Бажано розміщувати плаґін в одному з цих меню, щоб підтримувати однорідність розміщення плаґінів. Але можна створити власний елемент головного меню, як показано нижче:

def initGui(self):
    self.menu = QMenu(self.iface.mainWindow())
    self.menu.setObjectName("testMenu")
    self.menu.setTitle("MyMenu")

    self.action = QAction(QIcon(":/plugins/testplug/icon.png"), "Test plugin", self.iface.mainWindow())
    self.action.setObjectName("testAction")
    self.action.setWhatsThis("Configuration for test plugin")
    self.action.setStatusTip("This is status tip")
    QObject.connect(self.action, SIGNAL("triggered()"), self.run)
    self.menu.addAction(self.action)

    menuBar = self.iface.mainWindow().menuBar()
    menuBar.insertMenu(self.iface.firstRightStandardMenu().menuAction(), self.menu)

def unload(self):
    self.menu.deleteLater()

Don’t forget to set QAction and QMenu objectName to a name specific to your plugin so that it can be customized.

Файл ресурсів¶

Як ви бачили, в коді метода initGui() ми використовували іконку з файлу ресурсів (в нашому випадку resources.qrc)

<RCC>
  <qresource prefix="/plugins/testplug" >
     <file>icon.png</file>
  </qresource>
</RCC>

Щоб запобігти конфліктам з іншими плаґінами або з QGIS варто вказувати префікс. Якщо цього не зробити можна отримати не той ресурс, який потрібен. Тепер можна згенерувати опис ресурсів у форматі Python. Це робиться за допомогою команди pyrcc4

pyrcc4 -o resources.py resources.qrc

Ось і все... нічого особливого :-).

Якщо ви все зробили правильно, то можете побачити свій плаґін у Менеджері плаґінів, активувати його та спостерігати повідомлення у консолі після натискання на кнопку або після вибору відповідного пункту меню.

Під час розробки реальних плаґінів краще працювати в окремому (робочому) каталозі та створити makefile, який буде генерувати інтерфейс та ресурси і копіювати плаґін до каталогу плаґінів QGIS.