Модули (Плагины)¶
Чтобы создать модуль, руководствуйтесь следующим:
Придумать идею - функционал, решающий какую-то проблему.
Создать структуру плагина - файлы и папки.
Написать код.
Протестировать.
Опубликовать.
Совет
Изучайте исходный код готовых модулей.
Структура модуля¶
Модуль для Аксиомы.ГИС это специально оформленный модуль 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.
Основные этапы:
Отмечаются строки, предназначенные для перевода.
Для экспорта строк используется утилита
lupdate
. Она проходит по файлам с исходным кодом и забирает все встречаемые строки, отмеченные для перевода. Результатом является файл с расширением.ts
- простой структурированный xml файл со строками..ts
- файл открывается в «Qt Linguist» и переводится на один или более языков.После завершения перевода отдельных строк файл
.ts
“компилируется” в бинарный файл с расширением.qm
, который будет загружен Аксиомой.ГИС. Для компиляции используется утилитаlrelease
.
lrelease your_plugin.ts
.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
и другое.