La vista de formulario

Un formulario es una ventana de tu app. La vista de formulario es donde la dibujas: eliges controles de una caja, los sueltas en la ventana, cambias su aspecto en una lista de propiedades y escribes unas líneas de Python para lo que pasa cuando el usuario hace clic o escribe. Si usaste Visual Basic, el diseñador de WinForms o Qt Designer, ya conoces la idea; si no, el recorrido de abajo lleva diez minutos.

Qué ves

Zona	En la vista de formulario
Herramientas (izquierda, arriba)	Todos los controles que puedes colocar, agrupados (Comunes, Presentación, Contenedores, Disposición, Navegación…), con un buscador.
Estructura (izquierda, abajo)	Los controles del formulario en árbol: selecciónalos, renómbralos, anídalos, ocúltalos y bloquéalos.
Barra de herramientas (centro, arriba)	Guardar, deshacer, alinear, distribuir, mismo tamaño, centrar, orden, cuadrícula, ajuste y guías.
Lienzo (centro)	El formulario dentro de un marco de ventana, tal como se ejecutará.
Propiedades (derecha)	El control seleccionado, o el formulario si no hay nada seleccionado.
Eventos (derecha)	A qué puede reaccionar el control seleccionado y la función Python conectada a cada evento.
Código (abajo)	El Python del formulario, que se abre al conectar un evento.

La vista de formulario con un formulario de inicio de sesión: herramientas y estructura a la izquierda, el formulario en el lienzo, las propiedades del botón seleccionado a la derecha — La vista de formulario con el ejemplo de inicio de sesión abierto y su botón seleccionado.

Cada zona se describe en detalle en su propia página: Herramientas y lienzo, Propiedades, Eventos y Editor de código.

Tu primer formulario: un saludador

Vas a crear una ventana con un cuadro de texto, un botón y una etiqueta. Al escribir un nombre y pulsar el botón, muestra “¡Hola, nombre!”.

Un botón, un cuadro de texto y una casilla arrastrados uno a uno desde las herramientas a un formulario vacío — Colocar controles: arrástralos desde las herramientas y suéltalos en el formulario.

Crea el formulario. Pulsa Ctrl+N. En el diálogo Nuevo deja Formulario, escribe hello como Nombre y Saludador como Título, elige la plantilla En blanco y pulsa Crear. Aparecen dos archivos: hello.pzform (el diseño) y hello.py (el código).

El diálogo Nuevo: nombre, título, carpeta y una plantilla de partida.
Coloca un cuadro de texto. En las herramientas, arrastra Cuadro de texto al formulario. Queda seleccionado y el panel Propiedades lo muestra. Cambia su Nombre a your_name y su Texto de ayuda a Tu nombre.
Coloca un botón. Haz clic en Botón en las herramientas y arrastra un rectángulo en el formulario bajo el cuadro de texto: el botón toma ese tamaño. Llámalo greet y pon su Texto en Saludar.

Con un control elegido, arrastra un rectángulo para darle tamaño.
Coloca una etiqueta. Añade una Etiqueta de texto bajo el botón, llámala message y borra su texto.
Alinéalos. Selecciona los tres controles (arrastra un rectángulo de selección alrededor) y pulsa Alinear a la izquierda en la barra de herramientas. Las guías inteligentes muestran líneas rosas cuando los bordes coinciden mientras arrastras.
Conecta el clic. Haz doble clic en el botón. El panel Eventos conecta su evento click a una función nueva, greet_click, y la abre en el editor de código. Escribe una línea:
hello.py
```
def greet_click(form, event):
    """Se ejecuta al pulsar greet."""
    form.message.text = f"¡Hola, {form.your_name.text}!"
```
form es la ventana en marcha: cada control es un atributo con su nombre (form.message) y sus propiedades son atributos del control (form.message.text). Al cambiarlos se actualiza la ventana.

El panel Eventos: doble clic en un evento para conectarlo e ir a su código.
Ejecútalo. Pulsa F5 (guarda antes). Tu formulario se abre como una ventana real; escribe un nombre y pulsa el botón. La consola de abajo muestra lo que imprime el formulario y cualquier error. Déjala abierta, cambia el color de la etiqueta en Propiedades y guarda: la ventana en marcha se actualiza.

F5 ejecuta el formulario con su código; al guardar se actualiza en vivo.

Ejecuta el formulario fuera del diseñador

El formulario y su código son archivos normales de tu proyecto. Ejecútalos desde una terminal:

uv run pyzed run hello.pzform
uv run pyzed run hello.pzform --reload   # se actualiza al guardar

pyzed run hello.pzform
pyzed run hello.pzform --reload

python3 -m pyzed run hello.pzform

py -m pyzed run hello.pzform

O desde tu propio código Python:

from pyzed import designer

designer.run("hello.pzform")

Qué más hace la vista de formulario

Tarea	Cómo	Más
Ordenar controles en filas, columnas y cuadrículas que se adaptan a la ventana	Selecciónalos, clic derecho → Agrupar en una fila / columna / cuadrícula, o usa un contenedor de las herramientas	Disposiciones
Mantener un control pegado a un borde cuando la ventana crece	Posición → Anclajes en Propiedades	Propiedades
Cambiar colores, fuentes, bordes y sombras	Estilo en Propiedades; la ventana entera en el Estilo del formulario	Estilos y temas
Animar al pasar el ratón o al hacer clic, añadir brillo, desenfoque o cristal	Efectos y Movimiento en Propiedades	Animaciones y efectos
Rellenar campos con datos y validarlos	Sección Datos: enlaces y reglas	Enlace de datos
Ver el formulario con otro tema, idioma o marco de sistema	Ver → Vista previa con tema / idioma / marco de ventana	Interfaz
Reutilizar un grupo de controles en muchos formularios	Conviértelo en un componente	Vista de componente
Pintar un fondo con un efecto de GPU	El control Shader de Presentación, con un `.pzshad`	Shading

El archivo `.pzform`

Un formulario es JSON: su tamaño y aspecto (form), y cada control con su tipo, posición y propiedades. Sus manejadores viven a su lado en un módulo Python con el mismo nombre. Ambos son tuyos para versionar, revisar y editar a mano.

{
  "format": "pyzed.form/1",
  "form": {"name": "hello", "title": "Saludador", "width": 360, "height": 220, "theme": "One Dark"},
  "controls": [
    {"name": "your_name", "type": "input", "x": 24, "y": 24, "width": 312, "height": 32,
     "props": {"placeholder": "Tu nombre"}, "events": {}},
    {"name": "greet", "type": "button", "x": 24, "y": 72, "width": 120, "height": 32,
     "props": {"text": "Saludar"}, "events": {"click": "greet_click"}}
  ]
}

Herramientas y lienzoColocar, seleccionar, ajustar, guías y la estructura.PropiedadesCada sección de la grilla de propiedades.Eventos y manejadoresCada evento y cómo escribir su código.