2  Prefácio e roteiro de aprendizagem

2.1 Prefácio

Este manual foi concebido para quem utiliza QGIS e pretende passar de utilizador avançado a criador de ferramentas reutilizáveis. O objectivo não é apenas mostrar como colocar um botão no QGIS. O foco é ensinar um processo completo: identificar um problema, desenhar uma arquitectura simples, desenvolver uma interface segura, trabalhar com dados geográficos, manter compatibilidade entre versões, testar, empacotar, publicar e evoluir o plugin sem perder qualidade.

Os exemplos centrais são dois plugins desenvolvidos a partir de necessidades reais:

  • GPX Batch Converter, que transforma lotes de ficheiros GPX em formatos GIS, suporta fusão, execução em segundo plano, cancelamento, relatórios e validações de segurança;
  • GeoClick Capture, que regista cliques no mapa como pontos auditáveis, aplica snapping, transforma coordenadas, identifica feições, efectua geocodificação reversa opcional e organiza sessões num painel lateral.

Os dois estudos de caso foram escolhidos porque representam famílias diferentes de plugins. O primeiro é orientado a processamento de ficheiros e tarefas demoradas. O segundo é orientado a interacção com o mapa, edição, rede e controlo de estado. Em conjunto, cobrem grande parte dos padrões encontrados no desenvolvimento profissional de extensões QGIS.

Este texto usa Python, PyQGIS e qgis.PyQt. As práticas são pensadas para QGIS 3.28 ou superior e para a transição para QGIS 4 e Qt 6. A API evolui; por isso, antes de adoptar um método específico num projecto de longo prazo, consulte sempre a documentação da versão de QGIS que será suportada.

2.1.1 Como utilizar o manual

O manual está organizado em seis partes:

  1. Fundamentos - arquitectura, ambiente e planeamento;
  2. Primeiro plugin - estrutura mínima, acções e interface;
  3. Nível intermédio - camadas, CRS, ficheiros, tarefas, mapa e definições;
  4. Nível avançado - Qt 5/6, segurança, testes, CI/CD e publicação;
  5. Estudos de caso - decisões reais dos dois plugins;
  6. Projecto prático - construção de um plugin completo e exercícios.

Pode seguir os capítulos em sequência ou usar o manual como referência. Os blocos Prática recomendada, Erro comum e Decisão de arquitectura destacam os pontos que normalmente causam falhas em produção.

2.2 Roteiro de aprendizagem

Ao concluir este manual, o leitor deverá ser capaz de:

  • distinguir um script da consola Python, um algoritmo Processing e um plugin completo;
  • estruturar um pacote instalável pelo gestor de plugins do QGIS;
  • implementar correctamente classFactory(), initGui(), run() e unload();
  • criar acções, menus, barras de ferramentas, diálogos e painéis laterais;
  • utilizar widgets QGIS, como QgsMapLayerComboBox;
  • ler e escrever camadas vectoriais e transformar coordenadas entre CRS;
  • executar tarefas demoradas sem bloquear a interface;
  • adicionar cancelamento, progresso, logs e resultados estruturados;
  • criar ferramentas de clique e snapping no mapa;
  • efectuar pedidos de rede através de QgsNetworkAccessManager;
  • persistir preferências com QgsSettings;
  • manter compatibilidade entre Qt 5 e Qt 6;
  • reduzir riscos relacionados com subprocessos, caminhos e serviços externos;
  • criar testes unitários e validações de pacote;
  • automatizar releases e preparar o plugin para o repositório oficial do QGIS.

Ciclo completo de desenvolvimento