Añadir un botón en la interfaz de QGIS suele ser el primer paso concreto cuando se desarrolla un plugin. Es lo que transforma un simple script en Python en una herramienta realmente utilizable por el usuario.
En este tercer artículo del tutorial, veremos cómo añadir un botón y mostrar una ventana en un plugin QGIS, apoyándonos en el código generado por Plugin Builder. Nos detendremos en los elementos esenciales: el método initGui(), las acciones (QAction) y el disparo del diálogo.
Este tutorial está dirigido a principiantes en el desarrollo de plugins QGIS, que desean comprender cómo interactuar con la interfaz de QGIS antes de avanzar hacia la lógica de negocio.
Añadir un botón y mostrar una ventana en QGIS
En los dos primeros artículos sentamos las bases: entender qué es un plugin QGIS y crear un plugin vacío con Plugin Builder. Ahora es el momento de darle un comportamiento visible a nuestro plugin.
En este artículo aprenderemos a:
- añadir un botón en la interfaz de QGIS,
- comprender el código generado por Plugin Builder,
- mostrar una ventana (diálogo) sencilla.
El objetivo no es aún hacer algo complejo, sino comprender el mecanismo fundamental de cualquier plugin QGIS.
Recordatorio: el plugin generado por Plugin Builder
Cuando elegimos la plantilla “Tool button with dialog”, Plugin Builder ya preparó muchos elementos por nosotros:
- un botón en la barra de herramientas,
- una entrada de menú en QGIS,
- una ventana gráfica asociada.
Aunque todo funcione desde el principio, es fundamental entender cómo está conectado todo.
El archivo principal del plugin
Abre el archivo Python principal de tu plugin (por ejemplo mi_primer_plugin.py).
Encontrarás una clase principal que lleva el nombre del plugin. Es ella la que controla todo el comportamiento.
class MiPrimerPlugin:
def __init__(self, iface):
self.iface = iface
👉 iface es el objeto que permite al plugin comunicarse con QGIS (menús, capas, mensajes, etc.).
El método initGui(): punto de entrada visual
El método initGui() se llama automáticamente cuando el plugin se activa en QGIS.
Aquí se definen:
- el botón en la barra de herramientas,
- la entrada de menú,
- la acción asociada.
Ejemplo típico:
def initGui(self):
self.action = QAction(
QIcon(':/plugins/MiPrimerPlugin/icon.png'),
'Mi primer plugin',
self.iface.mainWindow()
)
self.action.triggered.connect(self.run)
self.iface.addToolBarIcon(self.action)
Aunque no entiendas cada línea en detalle, recuerda que:
- se crea una acción,
- se conecta a un método (
run), - se añade a la interfaz de QGIS.
El método run(): qué ocurre al hacer clic
El método run() se ejecuta cuando el usuario hace clic en el botón del plugin.
En la plantilla generada, su función principal es mostrar una ventana.
def run(self):
self.dlg.show()
👉 En este punto, el plugin solo hace una cosa: abrir un diálogo.
📦 Qué hace realmente un botón en QGIS
Cuando se hace clic en un botón en QGIS, no ocurre nada “mágico”.
Un botón de plugin es simplemente un disparador que llama a una función Python concreta.
El funcionamiento es siempre el mismo:
- el plugin crea una acción (
QAction), - esa acción se asocia a una función (por ejemplo
run()), - cuando el usuario hace clic, QGIS ejecuta esa función.
En nuestro caso, la función run() solo muestra una ventana. Pero más adelante, esa misma función podrá:
- leer parámetros introducidos por el usuario,
- analizar capas,
- lanzar procesos,
- producir resultados.
👉 Un botón en QGIS solo hace una cosa: ejecutar código Python.
Toda la potencia del plugin está en ese código.
Comprender la ventana (diálogo)
La ventana mostrada está definida en un archivo .ui, creado con Qt Designer.
Este archivo se carga luego en Python, lo que permite:
- mostrar la ventana,
- recuperar los valores introducidos por el usuario,
- conectar botones a código.
Por ahora, vamos a limitarnos a modificar el aspecto visual.
Modificar el texto de la ventana
Abre el archivo .ui con Qt Designer.
Prueba, por ejemplo, a:
- cambiar el título de la ventana,
- modificar un texto (label),
- añadir un botón.
Guarda el archivo, recarga el plugin en QGIS y haz clic en el botón.
👉 Acabas de modificar la interfaz de un plugin QGIS sin escribir código Python.
Probar y recargar el plugin
Cada vez que modifiques el código o la interfaz:
- desactiva el plugin en el gestor de extensiones,
- vuelve a activarlo,
o utiliza la opción Recargar plugin si tienes instalada la extensión correspondiente.
Errores frecuentes en esta etapa
- no pasa nada al hacer clic → el método
run()no está conectado - error al cargar → error de mayúsculas/minúsculas en los nombres
- ventana vacía → archivo
.uimal referenciado
Estos problemas son normales y forman parte del aprendizaje.
Lo que has aprendido
Al finalizar este artículo, sabes:
- dónde se crea el botón de un plugin QGIS,
- cómo una acción se conecta a código,
- cómo mostrar y modificar una ventana.
Ya tienes el bloque esencial de cualquier plugin QGIS interactivo.
¿Y en el próximo artículo?
En el siguiente artículo veremos:
- cómo recuperar los valores introducidos en la ventana,
- cómo interactuar con las capas de QGIS,
- cómo estructurar el código para ir más lejos.
👉 A partir de aquí, tu plugin empieza de verdad a ser útil.
