16.1. Estruturando Complementos Python

Para criar um complemento, aqui estão alguns passos a seguir:

Idéia: tenha uma idéia sobre o que você deseja fazer com seu novo complemento QGIS. Por que você quer fazer isso? Que problema você quer resolver? Já existe outro complemento para esse problema?
Criar arquivos: alguns são essenciais (veja Arquivos de complementos)
Escrevendo o código: Escreva o código nos arquivos apropriados
Teste: Reload your plugin para verificar se tudo está OK
Publicando: publique seu complemento no repositório QGIS ou faça seu próprio repositório como um “arsenal” de “armas GIS” pessoais.

16.1.1. Escrevendo um complemento 

Desde a introdução dos complementos Python no QGIS, vários complementos apareceram. A equipe do QGIS mantém um Repositório Oficial de complementos Python. Você pode usar sua fonte para aprender mais sobre programação com PyQGIS ou descobrir se você está duplicando o esforço de desenvolvimento.

16.1.1.1. Arquivos de complementos 

Aqui está a estrutura de diretórios do nosso exemplo de complemento

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

Qual é o significado dos arquivos:

__init__.py = O ponto de partida do complemento. Ele deve ter o método classFactory() e pode ter qualquer outro código de inicialização.
mainPlugin.py = O código principal de trabalho do complemento. Contém todas as informações sobre as ações do complemento e o código principal.
resources.qrc = O documento .xml criado pelo Qt Designer. Contém caminhos relativos aos recursos dos formulários.
resources.py = A tradução do arquivo .qrc descrito acima para Python.
form.ui = A GUI criada pelo Qt Designer.
form.py = A tradução do form.ui descrito acima para Python.
metadata.txt = Contém informações gerais, versão, nome e alguns outros metadados usados pelo site de complementos e pela infraestrutura de complementos.

Aqui é uma maneira de criar os arquivos básicos (esqueleto) de um complemento típico do QGIS Python.

Existe um complemento do QGIS chamado Plugin Builder 3 que cria um modelo de complemento para o QGIS. Esta é a opção recomendada, pois produz fontes compatíveis com 3.x.

Aviso

Se você planeja fazer o upload do complemento para Repositório Oficial de complementos Python, verifique se o seu complemento segue algumas regras adicionais necessárias para o complemento Validação

16.1.2. Conteúdo do complemento 

Aqui você pode encontrar informações e exemplos sobre o que adicionar em cada um dos arquivos na estrutura de arquivos descrita acima.

16.1.2.1. Metadados do complemento 

Primeiro, o gerenciador de complementos precisa recuperar algumas informações básicas sobre o complemento, como nome, descrição etc. O arquivo metadata.txt é o lugar certo para colocar essas informações.

Nota

Todos os metadados devem estar na codificação UTF-8.

Nome dos metadados	Requerido	Notas
nome	True	uma string curta que contém o nome do complemento
qgisMinimumVersion	True	notação dotted da versão mínima do QGIS
qgisMaximumVersion	False	notação dotted da versão máxima do QGIS
descrição	True	texto breve que descreve o complemento, HTML não permitido
sobre	True	texto mais longo que descreve o complemento em detalhes, não é permitido HTML
versão	True	string curta com a notação dotted da versão
autor	True	nome do autor
email	True	email do autor, mostrado apenas no site para usuários logados, mas visível no Gerenciador de complementos após a instalação do complemento
changelog	False	string, pode ser multilinha, não é permitido HTML
experimental	False	boolean flag, `True` or `False` - `True` if this version is experimental
descontinuada	False	boolean flag, `True` or `False`, applies to the whole plugin and not just to the uploaded version
etiquetas	False	lista separada por vírgula, são permitidos espaços dentro de tetiquetas individuais
página inicial	False	um URL válido apontando para a página inicial do seu complemento
repositório	True	uma URL válida para o repositório de código-fonte
tracker	False	um URL válido para tickets e relatórios de erros
ícone	False	um nome de arquivo ou um caminho relativo (relativo à pasta base do pacote compactado do complemento) de uma imagem amigável da Web (PNG, JPEG)
categoria	False	one of `Raster`, `Vector`, `Database` and `Web`
dependencies_de_complemento	False	PIP-like comma separated list of other plugins to install, use plugin names coming from their metadata’s name field
servidor	False	boolean flag, `True` or `False`, determines if the plugin has a server interface
hasProcessingProvider	False	boolean flag, `True` or `False`, determines if the plugin provides processing algorithms

Por padrão, os complementos são colocados no menu Complementos (veremos na próxima seção como adicionar uma entrada de menu ao seu complemento), mas também podem ser colocados nos menus Raster, Vetor, Banco de dados e Web.

Existe uma entrada de metadados de “categoria” correspondente para especificar isso, para que o complemento possa ser classificado de acordo. Essa entrada de metadados é usada como dica para os usuários e informa onde (em qual menu) o complemento pode ser encontrado. Os valores permitidos para “categoria” são: Vetor, Raster, Banco de dados ou Web. Por exemplo, se o seu complemento estará disponível no menu Raster, adicione-o a metadata.txt

category=Raster

Nota

Se qgisMaximumVersion estiver vazio, ele será automaticamente definido para a versão principal mais` .99` quando carregado no Repositório Oficial de complementos Python.

Um exemplo para este metadata.txt

; the next section is mandatory

[general]
name=HelloWorld
email=me@example.com
author=Just Me
qgisMinimumVersion=3.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
tracker=http://bugs.itopen.it
repository=http://www.itopen.it/repo
; 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=https://www.itopen.it
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=3.99

; Since QGIS 3.8, a comma separated list of plugins to be installed
; (or upgraded) can be specified.
; The example below will try to install (or upgrade) "MyOtherPlugin" version 1.12
; and any version of "YetAnotherPlugin".
; Both "MyOtherPlugin" and "YetAnotherPlugin" names come from their own metadata's
; name field
plugin_dependencies=MyOtherPlugin==1.12,YetAnotherPlugin

16.1.2.2. init.py 

Este arquivo é requerido pelo sistema de importação do Python. Além disso, o QGIS exige que este arquivo contenha uma função classFactory (), chamada quando o complemento é carregado no QGIS. Ele recebe uma referência à QgisInterface e deve retornar um objeto da classe do seu complemento a partir de mainplugin.py — no nosso caso, é chamado TestPlugin (veja abaixo). É assim que __init __. Py deve se parecer

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

# any other initialisation needed

16.1.2.3. mainPlugin.py 

É aqui que a mágica acontece e é assim que a mágica se parece: (por exemplo mainPlugin.py)

from qgis.PyQt.QtGui import *
from qgis.PyQt.QtWidgets import *

# initialize Qt resources from file resources.py
from . 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")
    self.action.triggered.connect(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
    self.iface.mapCanvas().renderComplete.connect(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
    self.iface.mapCanvas().renderComplete.disconnect(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!")

As únicas funções de complemento que devem existir no arquivo principal de complemento (por exemplo mainPlugin.py) são:

__init__, que dá acesso à interface QGIS
initGui () chamado quando o complemento é carregado
unload () chamado quando o complemento é descarregado

In the above example, addPluginToMenu() is used. This will add the corresponding menu action to the Plugins menu. Alternative methods exist to add the action to a different menu. Here is a list of those methods:

All of them have the same syntax as the addPluginToMenu() method.

É recomendável adicionar o menu do complemento a um desses métodos predefinidos para manter a consistência na organização das entradas do complemento. No entanto, você pode adicionar seu grupo de menus personalizado diretamente à barra de menus, como o próximo exemplo demonstra:

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")
    self.action.triggered.connect(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()

Não se esqueça de definir QAction e QMenu objectName com um nome específico ao seu complemento para que ele possa ser personalizado.

16.1.2.4. Arquivo de Recurso 

Você pode ver que em initGui () usamos um ícone do arquivo de recursos (chamado resources.qrc no nosso caso)

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

É bom usar um prefixo que não colide com outros plugins ou qualquer parte do QGIS; caso contrário, você poderá obter recursos que não deseja. Agora você só precisa gerar um arquivo Python que conterá os recursos. É feito com pyrcc5 command:

pyrcc5 -o resources.py resources.qrc

Nota

Em ambientes Windows, a tentativa de executar o comando pyrcc5 no prompt de comando ou no Powershell provavelmente resultará no erro “O Windows não pode acessar o dispositivo, caminho ou arquivo especificado […]”. A solução mais fácil é provavelmente usar o OSGeo4W Shell, mas se você estiver confortável modificando a variável de ambiente PATH ou especificando o caminho do executável explicitamente, poderá encontrá-lo em <Your QGIS Install Directory>\bin\pyrcc5.exe.

E isso é tudo … nada complicado :)

Se você tiver feito tudo corretamente, poderá encontrar e carregar seu complemento no gerenciador de complementos e ver uma mensagem no console quando o ícone da barra de ferramentas ou o item de menu apropriado estiver selecionado.

Ao trabalhar em um complemento real, é aconselhável gravá-lo em outro diretório (ativo) e criar um makefile que gere arquivos de recursos + interface do usuário e instale o complemento na instalação do QGIS.

16.1.3. Documentação 

A documentação para o complemento pode ser escrita como arquivos de ajuda em HTML. O módulo qgis.utils fornece uma função showPluginHelp(), que abrirá o navegador de arquivos de ajuda, da mesma maneira que outras ajudas do QGIS.

A função showPluginHelp() procura por arquivos de ajuda no mesmo diretório que o módulo de chamada. Ele procurará, por sua vez, index-ll_cc.html, index-ll.html, index-en.html, index-en_us.html `e :file:`index.html, exibindo o que encontrar primeiro. Aqui ll_cc é o local QGIS. Isso permite que várias traduções da documentação sejam incluídas no complemento.

A função showPluginHelp() também pode usar os parâmetros packageName, que identifica um complemento específico para o qual a ajuda será mostrada, o nome do arquivo, que pode substituir o “índice” nos nomes dos arquivos pesquisados e a seção, que é o nome de uma marca de âncora html no documento em que o navegador será posicionado.

16.1.4. Tradução 

Com algumas etapas, você pode configurar o ambiente para a localização do complemento para que, dependendo das configurações de localidade do seu computador, o complemento seja carregado em diferentes idiomas.

16.1.4.1. Requisitos de software 

A maneira mais fácil de criar e gerenciar todos os arquivos de tradução é instalar o Qt Linguist. Em um ambiente GNU/Linux baseado no Debian, você pode instalá-lo digitando:

sudo apt install qttools5-dev-tools

16.1.4.2. Arquivos e diretório 

Ao criar o complemento, você encontrará a pasta i18n no diretório principal do complemento.

Todos os arquivos de tradução devem estar dentro deste diretório.

16.1.4.2.1. Arquivo .pro 

Primeiro, você deve criar um arquivo .pro, que é um arquivo projeto que pode ser gerenciado pelo Qt Linguist.

Neste arquivo .pro, você deve especificar todos os arquivos e formulários que deseja traduzir. Este arquivo é usado para configurar os arquivos e variáveis de localização. Um possível arquivo de projeto, correspondendo à estrutura de nosso example plugin:

FORMS = ../form.ui
SOURCES = ../your_plugin.py
TRANSLATIONS = your_plugin_it.ts

Seu complemento pode seguir uma estrutura mais complexa e pode ser distribuído por vários arquivos. Se for esse o caso, lembre-se de que pylupdate5, o programa que usamos para ler o arquivo .pro e atualizar a string traduzível, não expande caracteres curinga, portanto, você deve colocar todos os arquivos explicitamente no arquivo .pro. O arquivo do seu projeto pode se parecer com algo assim:

FORMS = ../ui/about.ui ../ui/feedback.ui \
        ../ui/main_dialog.ui
SOURCES = ../your_plugin.py ../computation.py \
          ../utils.py

Além disso, o arquivo your_plugin.py é o arquivo que chama todos os menus e submenus do seu complemento na barra de ferramentas QGIS e você deseja traduzir todos eles.

Finalmente, com a variável TRANSLATIONS, você pode especificar os idiomas de tradução que deseja.

Aviso

Certifique-se de nomear o arquivo ts como your_plugin_ + language + .ts, caso contrário, o carregamento do idioma falhará! Use o atalho de 2 letras para o idioma (it para italiano, de para alemão, etc…)

16.1.4.2.2. Arquivo .ts 

Depois de criar o .pro, você estará pronto para gerar os arquivos .ts para o(s) idioma(s) do seu complemento.

Abra um terminal, vá para o diretório your_plugin/i18n e digite:

pylupdate5 your_plugin.pro

você deve ver os arquivos your_plugin_language.ts.

Abra o arquivo .ts com Qt Linguist e comece a traduzir.

16.1.4.2.3. Arquivo .qm 

Quando você terminar de traduzir seu complemento (se algumas strings de caracteres não forem concluídas, o idioma de origem será usado), você deverá criar o arquivo .qm (o arquivo .ts compilado que será usado por QGIS).

Basta abrir um cd do terminal no diretório your_plugin/i18n e digite:

lrelease your_plugin.ts

Agora, no diretório i18n, você verá o(s) arquivo(s) your_plugin.qm.

16.1.4.3. Traduzindo usando Makefile 

Como alternativa, você pode usar o makefile para extrair mensagens do código python e das caixas de diálogo Qt, se você criou seu complemento com o Plugin Builder. No início do Makefile, há uma variável LOCALES:

LOCALES = en

Adicione a abreviação do idioma a essa variável, por exemplo, para o idioma húngaro:

LOCALES = en hu

Agora você pode gerar ou atualizar o arquivo hu.ts (e também o arquivo en.ts) a partir das fontes:

make transup

Depois disso, você atualizou o arquivo .ts para todos os idiomas definidos na variável LOCALES. Use Qt Linguist para traduzir as mensagens do programa. Terminando a tradução, os arquivos .qm podem ser criados pelo transcompile:

make transcompile

Você precisa distribuir arquivos .ts com o seu complemento.

16.1.4.4. Carregue o complemento 

Para ver a tradução do seu complemento, abra o QGIS, altere o idioma (Configurações -> Opções -> Geral) e reinicie o QGIS.

Você deve ver seu complemento no idioma correto.

Aviso

Se você alterar algo no seu complemento (novas UIs, novo menu, etc.), será necessário gerar novamente a versão de atualização do arquivo .ts e .qm, portanto, execute novamente o comando acima.

my_plugin = qgis.utils.plugins['My Plugin']

16.1.5.3. Mensagens de log 

Os complementos têm sua própria guia dentro de O painel Registo de Mensagens.

16.1. Estruturando Complementos Python

16.1.1. Escrevendo um complemento 

16.1.1.1. Arquivos de complementos 

16.1.2. Conteúdo do complemento 

16.1.2.1. Metadados do complemento 

16.1.2.2. init.py 

16.1.2.3. mainPlugin.py 

16.1.2.4. Arquivo de Recurso 

16.1.3. Documentação 

16.1.4. Tradução 

16.1.4.1. Requisitos de software 

16.1.4.2. Arquivos e diretório 

16.1.4.2.1. Arquivo .pro 

16.1.4.2.2. Arquivo .ts 

16.1.4.2.3. Arquivo .qm 

16.1.4.3. Traduzindo usando Makefile 

16.1.4.4. Carregue o complemento 

16.1.5. Dicas e truques 

16.1.5.1. Recarregador de Complementos 

16.1.5.2. Acessando Complementos 

16.1.5.3. Mensagens de log 