Tu primera ventana en Pyzed Design

Vas a construir una ventana pequeña que te saluda por tu nombre. La vas a dibujar con el mouse, como en Visual Basic o Qt Designer, y a ejecutarla con una tecla. No hay que escribir código hasta el último paso (que es opcional), y ese paso es una línea.

Objetivo	Tiempo	Nivel	Necesitas
Una ventana con un título, un cuadro de texto y un botón	15 minutos	Básico · sin código	Pyzed Design (abajo)

Qué vas a aprender

• Abrir Pyzed Design y crear un formulario (una ventana de tu app).
• Colocar controles desde las Herramientas y cambiarlos en el panel Propiedades.
• Hacer que un control se estire cuando la ventana crece, con anclajes.
• Guardar y ejecutar el formulario con F5.
• Conectar un botón a un manejador de eventos de Python (opcional).

Lo que tendrás al final: una ventana nativa de verdad.

Antes de empezar

Pyzed Design es el editor visual de Pyzed. Instálalo de una de estas formas:

uv

Windows, macOS y Linux

uv tool install "pyzed-ui[designer]"   # instala el comando pyzed
pyzed design hello.pzform

pip

macOS y Linux

python3 -m venv .venv
source .venv/bin/activate
python -m pip install "pyzed-ui[designer]"
pyzed design hello.pzform

Windows (PowerShell)

py -m venv .venv
.venv\Scripts\Activate.ps1
python -m pip install "pyzed-ui[designer]"
pyzed design hello.pzform

python

Con Pyzed ya instalado

python -m pyzed.designer hello.pzform   # lo mismo, sin el comando pyzed en el PATH

¿No tienes Python?

Descarga la app Pyzed Design desde la página de Descarga. Trae su propio Python y uv, así que no hay que instalar nada más.

El editor en español

Pyzed Design usa el idioma de tu sistema. En esta página los nombres de paneles y propiedades aparecen en español, con el nombre en inglés entre paréntesis la primera vez, por si tu editor está en inglés.

Pasos

1. Crea el formulario. En Pyzed Design pulsa Ctrl+N (o ☰ → Nueva). Elige la tarjeta Formulario (Form), escribe hello como Nombre (Name), Hello como Título (Title), deja la plantilla En blanco (Blank) y pulsa Crear (Create). Si abriste el editor con pyzed design hello.pzform, el formulario vacío ya está abierto.

   

   El diálogo Nueva: un formulario, un componente o un shader.

2. Añade un título. En las Herramientas (Toolbox) de la izquierda, busca Título (Heading; escríbelo en Buscar componentes…) y arrástralo al formulario. Con él seleccionado, mira el panel Propiedades (Properties) de la derecha y cambia:

   • Nombre: headline (pulsa Enter). Así lo llamará tu código más adelante.
   • Texto (Text): Hello, Pyzed!

3. Añade una etiqueta y un cuadro de texto. Arrastra una Etiqueta de texto (Label) debajo del título y pon en su Texto Type your name and press the button. y en su Color text_muted (un gris más suave que sigue al tema). Luego arrastra un Cuadro de texto (Text box) debajo, llámalo your_name y pon en su Texto de ayuda (Placeholder) Your name y en su Icono (Icon) user.

   

   Haz clic en un control de las Herramientas y luego haz clic o arrastra un rectángulo en el formulario.

4. Añade el botón. Arrastra un Botón (Button) debajo del cuadro de texto, llámalo greet, pon en su Texto Greet, en su Variante (Variant) solid y en su Icono hand.

5. Alinea todo. Arrastra los controles hasta que las guías inteligentes rojas muestren que sus bordes izquierdos coinciden. Selecciona varios (arrastra un recuadro alrededor) y usa Alinear a la izquierda (Align left) en la barra de herramientas para una línea perfecta.

6. Haz que se estire. Selecciona el cuadro de texto y abre la sección Posición (Position) de Propiedades. En la cuadrícula de presets de anclaje elige el que estira a izquierda y derecha. Haz lo mismo con el título y la etiqueta. Para el botón elige arriba · derecha, así sigue al borde derecho.

7. Guarda y ejecuta. Pulsa Ctrl+S: el editor escribe hello.pzform (el diseño) y hello.py (su código, todavía vacío). Pulsa F5: tu formulario se abre como una ventana de verdad. Cambia su tamaño y mira cómo se estira el cuadro de texto.

Hay nombres ocupados

Un control no puede llamarse name, title, size, data ni window: tu código usa esas palabras para el propio formulario (form.title es el título de la ventana). Por eso el cuadro de texto es your_name y el título headline.

Arrastrar controles desde las herramientas a un formulario, como colocaste los tuyos.

Extra: que el botón haga algo

1. Haz doble clic en el botón en el lienzo. El panel Eventos (Events) conecta su evento click a una función nueva, greet_click, y la abre en el editor de código de abajo.

   

   Panel Eventos: haz doble clic en un evento (o en el control) para escribir su código.

2. Escribe una línea (dos, si quieres) dentro de la función:

   def greet_click(form, event):
       form.headline.text = f"Hello, {form.your_name.text}!"

   form es la ventana en ejecución: cada control es un atributo (form.your_name), y al cambiar una propiedad (.text) se redibuja enseguida. Escribe form. y el editor te lista tus controles.

3. Conecta también Enter. Selecciona el cuadro de texto, abre Eventos y haz doble clic en su evento submit (pulsar Enter). En la nueva función your_name_submit, llama al manejador del botón:

   def your_name_submit(form, event):
       return greet_click(form, event)

4. Guarda (Ctrl+S). Si el formulario sigue en ejecución se actualiza en el sitio; si no, pulsa F5 otra vez. Escribe tu nombre y pulsa Greet.

Los archivos terminados

El formulario son dos archivos juntos: hello.pzform (un JSON que describe la ventana, lo escribe el diseñador) y hello.py (tu código). Los dos están en examples/tutorial/designer.

examples/tutorial/designer/hello.py

"""Event handlers for the hello form (tutorial: Your first window in Pyzed Design).

    pyzed run examples/tutorial/designer/hello.pzform      # run it
    pyzed design examples/tutorial/designer/hello.pzform   # open it in the designer

Each function receives the running ``form`` (controls are attributes: ``form.your_name.text``)
and an ``event`` with ``event.sender``, ``event.name`` and ``event.value``.
"""


def greet_click(form, event):
    """Runs when greet is clicked."""
    name = form.your_name.text.strip() or "stranger"
    form.headline.text = f"Hello, {name}!"
    form.subtitle.text = "Change the name and press the button again."


def your_name_submit(form, event):
    """Runs when Enter is pressed in your_name: the same as clicking the button."""
    return greet_click(form, event)

Ejecuta el ejemplo terminado sin abrir el diseñador:

uv

Windows, macOS y Linux

uv run --with pyzed-ui pyzed run examples/tutorial/designer/hello.pzform

pip

macOS / Linux

python3 -m venv .venv
source .venv/bin/activate
python -m pip install pyzed-ui
pyzed run examples/tutorial/designer/hello.pzform

Windows (PowerShell)

py -m venv .venv
.venv\Scripts\Activate.ps1
python -m pip install pyzed-ui
pyzed run examples\tutorial\designer\hello.pzform

python

macOS / Linux (con Pyzed ya instalado)

python3 -m pyzed run examples/tutorial/designer/hello.pzform

Windows (con Pyzed ya instalado)

py -m pyzed run examples\tutorial\designer\hello.pzform

De dónde vienen las ideas

El lienzo, las herramientas y la grilla de propiedades siguen a los diseñadores RAD clásicos (Visual Basic, el diseñador de WinForms, Qt Designer); los anclajes funcionan como los de WinForms, Godot y Unreal Engine. El aspecto del editor está inspirado en el editor de código Zed.

Eventos de este tutorial

Control	Evento	Handler	Qué hace aquí
greet (Botón)	click	greet_click	Escribe el saludo en headline.
your_name (Caja de texto)	submit	your_name_submit	Enter hace lo mismo que el botón.

Prueba más eventos

Haz doble clic en un evento del panel Eventos para crear su handler y pega el cuerpo:

def your_name_change(form, event):          # cada tecla: event.value es el texto
    form.greet.enabled = bool(event.value.strip())


def headline_double_click(form, event):     # una etiqueta tiene click y double_click
    form.headline.text = "¡Hola!"
    form.your_name.text = ""


def form_key(form, event):                  # cualquier tecla en la ventana: event.value es la combinación
    if event.value == "escape":
        return form.close()

Todo control tiene además mouse_enter, mouse_leave y right_click. La lista completa de cada control está en Eventos y handlers, y cómo reciben sus eventos formularios, apps y componentes en Apps, ventanas, formularios y componentes.

Siguiente

• Un formulario que hace algo: varios campos, validación y la consola.
• El manual de Pyzed Design: cada panel del editor en detalle.
• Herramientas y lienzo: todas las formas de colocar, seleccionar y alinear controles.