Criar um plugin QGIS é muito mais simples do que parece, especialmente para quem está começando a programar. Com o Plugin Builder, é possível gerar em poucos minutos toda a estrutura de um plugin, sem escrever código complexo.
Neste segundo artigo do tutorial, vamos ver como criar seu primeiro plugin QGIS usando o Plugin Builder, passo a passo: instalação da ferramenta, escolha do template, desativação das opções avançadas e geração do plugin.
O objetivo é obter rapidamente um plugin funcional no QGIS, para compreender o funcionamento geral antes de avançar gradualmente no código Python.
Criar o primeiro plugin com o Plugin Builder
No primeiro artigo, vimos para que servem os plugins QGIS e de quais arquivos eles são compostos. Agora é hora de colocar a mão na massa.
O objetivo deste artigo é simples: criar um plugin QGIS funcional sem escrever código complexo, para entender o ciclo básico de desenvolvimento de um plugin.
Para isso, vamos utilizar uma ferramenta essencial para iniciantes: Plugin Builder.
O que é o Plugin Builder?
O Plugin Builder é um plugin oficial do QGIS que gera automaticamente a estrutura básica de um plugin.
Ele cria para você:
- a estrutura de pastas,
- os arquivos Python essenciais,
- o arquivo
metadata.txt, - um plugin que pode ser carregado imediatamente no QGIS.
O Plugin Builder evita erros comuns no início e permite focar no mais importante: entender e modificar um plugin existente.
Instalar o Plugin Builder
- Abra o QGIS
- Vá em Complementos → Gerenciar e Instalar Complementos
- Procure por Plugin Builder
- Instale o plugin
Após a instalação, o Plugin Builder estará disponível no menu Complementos.
Iniciar o assistente de criação
- Menu Complementos → Plugin Builder → Plugin Builder
- O assistente de criação será aberto
Você precisará preencher várias informações. Não se preocupe: algumas são apenas descritivas.
Informações gerais do plugin
Nome e descrição
- Nome do plugin: nome legível para o usuário (ex.: MeuPrimeiroPlugin)
- Descrição: frase curta explicando a finalidade do plugin
Essas informações aparecerão no gerenciador de plugins do QGIS.
Versão e autor
- Versão: comece simplesmente com
0.1 - Autor: seu nome ou o nome da sua organização
Configurações técnicas importantes
Escolha do template
O Plugin Builder oferece vários templates (modelos de plugin).
Para quem está começando, é fortemente recomendado escolher:
Template: Tool button with dialog
Esse template é o mais didático porque:
- cria um botão na interface do QGIS,
- prepara uma janela gráfica simples,
- corresponde à maioria dos plugins comuns.
Ele será uma base sólida para os próximos artigos.
Opções que devem ser desmarcadas no início
Para o primeiro plugin, é aconselhável desmarcar todas as opções avançadas, especialmente:
- Internationalization (traduções)
- Help (documentação integrada)
- Unit testing
- Empacotamento avançado
Essas funcionalidades são úteis em plugins mais maduros, mas complicam desnecessariamente a estrutura para iniciantes.
Vamos abordá-las mais adiante, quando os fundamentos estiverem bem consolidados.
Classe do plugin
O Plugin Builder solicita o nome da classe principal do plugin.
Exemplo:
- Nome do plugin:
MeuPrimeiroPlugin - Classe:
MeuPrimeiroPlugin
Por convenção, utiliza-se o mesmo nome e capitalização para evitar confusões.
Menu e ícone
Você pode indicar:
- o menu onde o plugin aparecerá (normalmente Complementos),
- um ícone (opcional nesta etapa).
Essas escolhas podem ser alteradas facilmente depois.
Geração do plugin
Depois de preencher todos os campos:
- Clique em Generate
- Escolha a pasta de destino
O Plugin Builder criará automaticamente a pasta do plugin com todos os arquivos necessários.
Onde colocar o plugin?
Para que o QGIS reconheça o plugin, ele deve estar na pasta de plugins do usuário.
Dependendo do sistema operacional:
- Windows
C:/Users/.../AppData/Roaming/QGIS/QGIS3/profiles/default/python/plugins - Linux
~/.local/share/QGIS/QGIS3/profiles/default/python/plugins - macOS
~/Library/Application Support/QGIS/QGIS3/profiles/default/python/plugins
💡 Dica: o Plugin Builder normalmente sugere essa pasta por padrão.
Ativar o plugin no QGIS
- Vá em Complementos → Gerenciar e Instalar Complementos
- Aba Instalados
- Marque o seu plugin
Se tudo tiver funcionado corretamente, o plugin aparecerá no menu e poderá ser ativado.
👉 Neste ponto, o plugin praticamente não faz nada… e isso é completamente normal.
Entender o que o Plugin Builder criou
Antes de seguir adiante, reserve um tempo para abrir os arquivos gerados:
__init__.pymetadata.txt- o arquivo Python principal
Agora você deve reconhecer os elementos descritos no artigo anterior.
Erros comuns para iniciantes
- o plugin não aparece → pasta incorreta
- erro ao carregar → problema de maiúsculas/minúsculas no nome da classe
- QGIS rejeita o plugin → versão mínima do QGIS incorreta
Esses erros são normais e fazem parte do processo de aprendizagem.
O que você aprendeu
Ao final deste artigo, você já sabe:
- instalar o Plugin Builder,
- gerar um plugin QGIS vazio,
- instalá-lo localmente,
- ativá-lo no QGIS.
Você atingiu uma etapa importante: agora é oficialmente um desenvolvedor de plugins QGIS.
E no próximo artigo?
No próximo artigo, veremos:
- como adicionar um botão ao QGIS,
- como exibir uma janela simples,
- como organizar o código sem se perder.
👉 Um plugin que hoje não faz nada pode se tornar amanhã uma ferramenta poderosa.
