Модули (Плагины)

Чтобы создать модуль, руководствуйтесь следующим:

  1. Придумать идею - функционал, решающий какую-то проблему.

  2. Создать структуру плагина - файлы и папки.

  3. Написать код.

  4. Протестировать.

  5. Опубликовать.

Совет

Изучайте исходный код готовых модулей.

Структура модуля

Модуль для Аксиомы.ГИС это специально оформленный модуль Python с дополнительными файлами.

Рассмотрим структуру минимального модуля с обязательными параметрами и более расширенного:

Минимальный:

ru_mycompany_minimal_module  # папка с модулем
├── __init__.py  # точка входа
└── manifest.ini  # информация о модуле

Расширенный:

ru_mycompany_extended_module
├── documentation
│   └── index.html
├── business_logic.py
├── i18n
│   ├── translation_en.qm
│   └── translation_en.ts
├── __init__.py
├── manifest.ini
└── ui
    ├── form.ui
    ├── image.png
    └── logo.png

Идентификатор модуля

ru_mycompany_minimal_module - папка с модулем, она же - уникальный идентификатор модуля. Так же, как и при создании обычных модулей Python, избегайте конфликтов имен. Делайте имя модуля уникальным. Для этого следуйте простому соглашению именования: - используйте имя вашего веб-сайта или электронной почты, разделив на слова в обратном порядке; - используйте только маленькие латинские буквы и символ нижнего подчеркивания "_", т.е. [a-z0-9_].

Так для модуля mymodule рекомендуемым идентификатором будет: - для веб-сайта axioma-gis.ru - ru_axioma_gis_mymodule - для почты andrey@yandex.ru - ru_yandex_at_andrey_mymodule

Точка входа

__init__.py - точка входа в модуль, так же как и для любого другого модуля Python - является обязательным для системы импорта. Содержит основной код модуля или импортирует другие локальные файлы.

См.также

Точка входа может содержать специальный Класс Plugin.

Информация о модуле

manifest.ini - содержит основную информацию, версию, название и прочее. Является ini-файлом c простыми парами ключ=значение.

Примечание

Файл manifest.ini должен иметь кодировку UTF-8.

Минимальный пример содержимого:

[general]
name=Пример модуля
description=Короткий текст с описанием модуля.

Параметры:

  • name - короткая строка с именем модуля

  • description - короткий текст с описанием

См.также

Для более подробного описания формата ini, поддерживаемого Аксиомой.ГИС, смотрите документацию configparser.

Например, могут содержаться другие необязательные параметры:

; может содержать коментарии
; следующая секция обязательна
[general]
name=Пример модуля
description=Короткий текст с описанием модуля.
    Может быть многострочным.
; конец обязательных параметров

; необязательные параметры
version=1.0
author=Андрей
email=andrey@axioma-gis.ru
homepage=https://andrey.axioma-gis.ru
repository=https://github.com/andey/mymodule
license=New BSD

; секция локализации
[i18n]
name_en=Plugin example
description_en=Plugin example description.

Документация

Документация может быть написана в HTML файлах. Аксиома.ГИС откроет документацию в системном веб-браузере. Аксиома ищет документацию в папке с модулем documentation - файлы index[locale].html. Пользователь откроет документацию с суффиксом локали, совпадающим с языком системы. При отсутствии совпадения будет открываться файл без суффикса - index.html.

Переводы

Можно предусмотреть загрузку модуля на разных языках.

Название и описание самого модуля может быть переведено на другие языки в манифесте в секции i18n:

; секция локализации
[i18n]
name_en=Plugin example
description_en=Plugin example description.
name_fr=Exemple de plugin
description_fr=Description de l'exemple de plugin.

У пользователя отобразится название и описание в случае, если язык системы будет совпадать с суффиксом локали. Иначе отобразится название и описание из основной секции general.

Наиболее простой способ создания и сопровождения переводов строк из исходного кода - использование «Qt Linguist».

Примечание

Подробнее о переводе в документации Qt Linguist.

Основные этапы:

  1. Отмечаются строки, предназначенные для перевода.

  2. Для экспорта строк используется утилита lupdate. Она проходит по файлам с исходным кодом и забирает все встречаемые строки, отмеченные для перевода. Результатом является файл с расширением .ts - простой структурированный xml файл со строками.

  3. .ts - файл открывается в «Qt Linguist» и переводится на один или более языков.

  4. После завершения перевода отдельных строк файл .ts “компилируется” в бинарный файл с расширением .qm, который будет загружен Аксиомой.ГИС. Для компиляции используется утилита lrelease.

lrelease your_plugin.ts
  1. .qm - файлы размещаются в подпапке i18n внутри модуля. Они будут загружены вместе с модулем.

Класс Plugin

Модули рекомендуется писать в объектном стиле. Для этого точка входа __init__.py может содержать класс Plugin. Тогда Аксиома.ГИС при загрузке модуля создаст его экземпляр, а при выгрузке - уничтожит его.

Пример модуля __init__.py

"""Пример добавления кнопки и подключение действия по нажатию на нее
(показ сообщения). При выгрузке кнопка удаляется из интерфейса.
"""
from PySide2.QtWidgets import QMessageBox


class Plugin:
    def __init__(self, iface):
        self.iface = iface
        menubar = iface.menubar
        self.__action = menubar.create_button('Пример действия',
                icon='://icons/share/32px/run.png', on_click=self.show_message)
        position = menubar.get_position('Основные', 'Команды')
        position.add(self.__action)

    def unload(self):
        self.iface.menubar.remove(self.__action)

    def show_message(self):
        QMessageBox.information(None, 'Сообщение',
                'Пример выполнения действия по нажатию кнопки')
  • В конструктор __init__ передается экземпляр объекта интерфейса Аксиомы axipy.interface.AxiomaInterface как параметр iface.

  • unload - вызывается, когда модуль выгружается.

Вспомогательный класс axipy.interface.AxiomaInterface содержит свойства и функции, необходимые почти для любого плагина. Например, загрузка/сохранение настроек settings, получение файлов внутри папки с модулем local_file(), перевод строк tr(), добавление кнопок в интерфейс menubar и другое.