Adicionar um botão à interface do QGIS costuma ser o primeiro passo concreto no desenvolvimento de um plugin. É isso que transforma um simples script em Python em uma ferramenta realmente utilizável pelo usuário.
Neste terceiro artigo do tutorial, veremos como adicionar um botão e exibir uma janela em um plugin QGIS, com base no código gerado pelo Plugin Builder. Vamos dedicar um tempo para compreender os elementos essenciais: o método initGui(), as ações (QAction) e o acionamento do diálogo.
Este tutorial é voltado para iniciantes no desenvolvimento de plugins QGIS que desejam entender como interagir com a interface do QGIS antes de avançar para a lógica de negócio.
Adicionar um botão e exibir uma janela no QGIS
Nos dois primeiros artigos, estabelecemos as bases: entender o que é um plugin QGIS e criar um plugin vazio usando o Plugin Builder. Agora é hora de dar um comportamento visível ao nosso plugin.
Neste artigo, vamos aprender a:
- adicionar um botão à interface do QGIS,
- compreender o código gerado pelo Plugin Builder,
- exibir uma janela (diálogo) simples.
O objetivo ainda não é fazer algo complexo, mas entender o mecanismo fundamental de qualquer plugin QGIS.
Lembrete: o plugin gerado pelo Plugin Builder
Quando escolhemos o template Tool button with dialog, o Plugin Builder já preparou muita coisa para nós:
- um botão na barra de ferramentas,
- um item de menu no QGIS,
- uma janela gráfica associada.
Mesmo que tudo isso já funcione, é essencial entender como esses elementos estão conectados.
O arquivo principal do plugin
Abra o arquivo Python principal do seu plugin (por exemplo mon_premier_plugin.py).
Você encontrará uma classe principal com o nome do plugin. É ela que controla todo o comportamento.
class MonPremierPlugin:
def __init__(self, iface):
self.iface = iface
👉 iface é o objeto que permite ao plugin dialogar com o QGIS (menus, camadas, mensagens…).
O método initGui(): ponto de entrada visual
O método initGui() é chamado automaticamente quando o plugin é ativado no QGIS.
É aqui que são definidos:
- o botão na barra de ferramentas,
- a entrada no menu,
- a ação associada.
Exemplo típico:
def initGui(self):
self.action = QAction(
QIcon(':/plugins/MonPremierPlugin/icon.png'),
'Meu primeiro plugin',
self.iface.mainWindow()
)
self.action.triggered.connect(self.run)
self.iface.addToolBarIcon(self.action)
Mesmo sem entender cada linha em detalhe, guarde o essencial:
- uma ação é criada,
- ela é conectada a um método (
run), - ela é adicionada à interface do QGIS.
O método run(): quando o botão é clicado
O método run() é chamado quando o usuário clica no botão do plugin.
No template gerado, ele serve principalmente para exibir uma janela.
def run(self):
self.dlg.show()
👉 Neste estágio, o plugin faz apenas uma coisa: abrir um diálogo.
📦 O que um botão faz de verdade no QGIS
Quando clicamos em um botão no QGIS, nada “mágico” acontece.
Um botão de plugin é simplesmente um gatilho: ele chama uma função Python específica.
Concretamente, o funcionamento é sempre o mesmo:
- o plugin cria uma ação (
QAction), - essa ação é associada a uma função (por exemplo
run()), - quando o usuário clica no botão, o QGIS executa essa função.
No nosso caso, a função run() apenas exibe uma janela. Mais adiante, essa mesma função poderá:
- ler parâmetros informados pelo usuário,
- analisar camadas,
- executar processamentos,
- produzir resultados.
👉 Um botão no QGIS faz apenas uma coisa: executar código Python.
Todo o poder do plugin está nesse código.
Entendendo a janela (diálogo)
A janela exibida é definida em um arquivo .ui, criado com o Qt Designer.
Esse arquivo é então carregado em Python, permitindo:
- exibir a janela,
- recuperar valores informados pelo usuário,
- conectar botões a código.
Por enquanto, vamos apenas modificar o conteúdo visual.
Modificar o texto da janela
Abra o arquivo .ui no Qt Designer.
Experimente, por exemplo:
- mudar o título da janela,
- alterar um rótulo (label),
- adicionar um botão.
Salve o arquivo, recarregue o plugin no QGIS e clique no botão.
👉 Você acabou de modificar a interface de um plugin QGIS sem escrever código Python.
Testar e recarregar o plugin
A cada modificação no código ou na interface:
- desative o plugin no gerenciador de extensões,
- reative-o,
ou utilize a opção Recarregar plugin, se tiver instalado a extensão apropriada.
Erros frequentes nesta etapa
- nada acontece ao clicar → método
run()não conectado, - erro ao carregar → diferença de maiúsculas/minúsculas nos nomes,
- janela vazia → arquivo
.uimal referenciado.
Esses problemas são normais e fazem parte do aprendizado.
O que você aprendeu
Ao final deste artigo, você sabe:
- onde o botão de um plugin QGIS é criado,
- como uma ação é conectada a código,
- como exibir e modificar uma janela.
Agora você possui o elemento essencial de qualquer plugin QGIS interativo.
E no próximo artigo?
No próximo artigo, veremos:
- como recuperar valores digitados na janela,
- como interagir com camadas do QGIS,
- como estruturar o código para ir mais longe.
👉 A partir daqui, seu plugin começa a se tornar realmente útil.
