Quando começamos a desenvolver plugins para o QGIS, é comum imaginar que um botão deveria “fazer alguma coisa” automaticamente quando é clicado.
Na realidade, um botão não faz absolutamente nada… até que você diga a ele o que deve fazer.
Neste artigo, veremos como recuperar os dados informados pelo usuário em uma interface de plugin QGIS, compreender onde esses dados são armazenados e desmistificar o que realmente acontece quando um botão é clicado.
O objetivo não é escrever muito código, mas compreender a ligação entre a interface gráfica e a lógica do plugin, sem jargões desnecessários.
Recuperando e utilizando os dados informados pelo usuário
Nos artigos anteriores, criamos um plugin QGIS mínimo, adicionamos um botão à interface e exibimos uma janela de diálogo quando o usuário clicava nela.
Esse foi um passo importante.
No entanto, nosso plugin ainda não realiza nenhuma tarefa útil.
Neste artigo, vamos dar o próximo passo fundamental: recuperar os dados informados pelo usuário e utilizá-los no código Python do plugin.
Mas antes…
Quando uma pessoa começa a desenvolver plugins QGIS, o primeiro contato com o código Python pode parecer intimidador.
Múltiplos arquivos, classes, métodos e palavras-chave desconhecidas podem dar a impressão de que tudo é muito mais complicado do que realmente é.
A boa notícia é que você não precisa entender tudo imediatamente.
Ler código é uma habilidade que se desenvolve gradualmente.
Se ainda não leu, recomendamos o artigo:
Como Ler o Código de um Plugin QGIS sem Entrar em Pânico
Esse artigo apresenta uma abordagem simples e tranquilizadora para compreender o código de um plugin sem se sentir sobrecarregado.
Por que um botão não “faz nada” sozinho?
Existe um conceito fundamental que vale a pena compreender desde o início:
👉 Uma janela de diálogo Qt não executa nenhuma ação por conta própria.
Sua função é simplesmente:
- exibir campos de entrada;
- permitir que o usuário informe ou selecione valores;
- apresentar informações por meio de uma interface gráfica.
Por exemplo, uma janela pode conter:
- campos de texto;
- listas suspensas;
- caixas de seleção;
- campos numéricos.
Se o plugin nunca ler esses valores, nada acontecerá.
E isso é perfeitamente normal.
A janela é apenas a interface do usuário.
O comportamento real do plugin é definido pelo código Python que recupera e utiliza esses valores.
Onde os dados são armazenados?
Cada campo exibido na janela é um objeto Python criado a partir do arquivo .ui desenvolvido com o Qt Designer.
Alguns exemplos comuns:
QLineEdit→ campo de textoQComboBox→ lista suspensaQCheckBox→ caixa de seleçãoQSpinBox→ campo numérico
Esses widgets podem ser acessados através do objeto de diálogo, normalmente chamado dlg.
Por exemplo:
self.dlg.lineEdit
self.dlg.comboBox
self.dlg.checkBox
O valor informado pelo usuário fica armazenado dentro do próprio widget.
Não existe nenhum local oculto onde os dados sejam guardados.
Se o plugin precisar desse valor, ele deverá recuperá-lo explicitamente a partir do widget correspondente.
Essa ideia simples está na base de toda interação entre o usuário e um plugin QGIS.
Lendo valores: exemplos simples
Depois de entender onde os dados são armazenados, o próximo passo é recuperá-los a partir dos widgets da janela.
Cada tipo de widget possui seu próprio método para acessar os dados informados pelo usuário.
Campo de texto (QLineEdit)
texto = self.dlg.lineEdit.text()
textocontém o que o usuário digitou no campo.
Lista suspensa (QComboBox)
opcao = self.dlg.comboBox.currentText()
opcaocontém o item atualmente selecionado.
Caixa de seleção (QCheckBox)
ativo = self.dlg.checkBox.isChecked()
ativocontémTrueouFalse.
Campo numérico (QSpinBox)
valor = self.dlg.spinBox.value()
valorcontém um valor numérico.
Neste estágio, não é necessário compreender todos os detalhes técnicos.
O importante é lembrar que cada widget possui um método específico para acessar seu conteúdo.
O momento crucial: quando ler os valores?
Um erro muito comum entre iniciantes é tentar recuperar os valores antes que o usuário tenha confirmado a janela.
Em um plugin QGIS típico, os valores devem ser recuperados apenas depois que a janela for aceita.
Por exemplo:
result = self.dlg.exec_()
if result:
# ler os valores aqui
A chamada para exec_() exibe a janela e aguarda a interação do usuário.
Somente quando o usuário clica em OK (ou valida a janela de outra forma) o código continua sua execução.
Se você tentar ler os valores antes da execução de exec_(), normalmente obterá campos vazios ou valores padrão.
O usuário deve primeiro preencher a janela e confirmá-la para que o plugin possa acessar os dados de forma confiável.
Este é um dos conceitos mais importantes ao trabalhar com diálogos Qt.
A janela coleta informações do usuário.
O código recupera essas informações somente após a validação da janela.
Uma forma simples de entender o processo
Você pode imaginar a janela como um formulário aguardando preenchimento.
O processo segue sempre a mesma sequência:
- O plugin exibe a janela.
- O usuário informa os dados.
- O usuário clica em OK.
- O plugin recupera os valores.
- O plugin executa uma ação.
Se uma dessas etapas estiver faltando, o processo estará incompleto.
Compreender essa sequência torna muito mais fácil entender como os plugins QGIS interagem com seus usuários.
Exemplo completo e mínimo
Vamos reunir tudo em um exemplo simples e propositalmente minimalista.
result = self.dlg.exec_()
if result:
texto = self.dlg.lineEdit.text()
opcao = self.dlg.comboBox.currentText()
ativo = self.dlg.checkBox.isChecked()
print("Texto:", texto)
print("Opção:", opcao)
print("Opção ativa:", ativo)
Neste momento, o plugin não realiza:
- nenhuma análise;
- nenhum processamento complexo;
- nenhuma interação com camadas QGIS.
O objetivo é apenas demonstrar que o plugin consegue recuperar corretamente os dados informados pelo usuário.
Quando você consegue fazer isso, já estabeleceu a conexão entre a interface gráfica e o código Python.
E isso representa um passo muito importante no desenvolvimento de plugins.
Por que nada acontece se você não ler os valores?
Esta é uma das perguntas mais frequentes entre iniciantes.
Um plugin QGIS não é um formulário automático.
Não existe nenhuma mágica escondida por trás da interface.
Quando o usuário digita um texto, seleciona uma opção ou marca uma caixa, o QGIS apenas armazena essa informação dentro do widget correspondente.
Se o seu código nunca recuperar esse valor, ele nunca será utilizado.
Nada acontece porque o plugin não recebeu nenhuma instrução sobre o que fazer com a informação fornecida.
Esse comportamento é intencional.
Ele oferece ao desenvolvedor controle total sobre o comportamento do plugin e sobre as ações que devem ser executadas.
Os dados informados pelo usuário só se tornam úteis quando o seu código os recupera e utiliza explicitamente.
O que você aprendeu
Ao final deste artigo, você agora sabe:
- onde os dados informados pelo usuário são armazenados;
- como recuperá-los em Python;
- quando esses dados devem ser lidos;
- por que nada acontece até que o plugin utilize esses valores explicitamente.
Esses conceitos formam a base de qualquer plugin QGIS interativo.
Seja para realizar um cálculo simples ou uma análise espacial complexa, quase todo plugin começa coletando informações do usuário.
E no próximo artigo?
Até agora, nosso plugin consegue recuperar informações fornecidas pelo usuário.
No entanto, ele ainda não faz nada útil com elas.
No próximo artigo, veremos como transformar esses dados em ações concretas.
Aprenderemos a:
- validar os dados informados;
- aplicar regras de negócio;
- tomar decisões com base nas escolhas do usuário;
- controlar o comportamento do plugin.
Recuperar os valores é o primeiro passo.
Utilizá-los de forma inteligente é o que transforma um plugin em uma ferramenta realmente útil.
Próximo artigo: Desenvolver um Plugin QGIS: Aplicando Lógica de Negócio aos Dados Informados pelo Usuário
