Archivos, plantillas y scripting

Pestañas de documentos

Cada archivo abierto es una pestaña sobre la barra de herramientas: Formulario · login.pzform o Componente · rating.pzcomp (con un icono de acento). Un punto marca los cambios sin guardar, y el final de la barra de pestañas dice en qué vista estás: Vista de formulario o Vista de componente.

Haz clic en una pestaña para cambiar. Cada documento conserva su selección y su historial de deshacer; al dejar una pestaña se aplica y se cierra el editor de código (si el código no se puede analizar, el cambio espera a que lo arregles).
La × de una pestaña la cierra. Con cambios sin guardar, un diálogo ofrece Save, Don’t save y Cancel.
Abrir un archivo que ya está abierto cambia a su pestaña y conserva sus cambios sin guardar. Un formulario vacío sin título que no has tocado se sustituye en lugar de acumular pestañas.
Doble clic en un componente diseñado colocado abre su archivo en una pestaña.
Arrastra una pestaña a lo largo de la fila para reordenarla. Sácala de la ventana para abrirla en una ventana propia, con sus pestañas, su barra de herramientas y su lienzo; arrastra una pestaña sobre otra ventana de Pyzed Design para apilarla entre sus pestañas. Mover la pestaña a una ventana nueva y Mover la pestaña a la ventana principal (menú Ver, paleta de comandos) hacen lo mismo sin ratón, también en Wayland, donde las apps no saben dónde están sus ventanas.
Los paneles (Propiedades, Esquema, Código, Eventos…) se quedan en la ventana principal y siguen al documento que usaste por última vez. Una ventana que no es la activa muestra su formulario tal cual; su primer clic solo la activa, así que un clic nunca cambia un formulario que no estabas mirando. Cerrar una ventana de documento devuelve sus pestañas a la ventana principal.

El título de la ventana muestra el documento activo, tras un ● cuando tiene cambios sin guardar.

Nuevo formulario

Nuevo formulario (Ctrl+N, el botón Nuevo… de la barra de herramientas o el menú ☰) abre el diálogo Nuevo. Arriba, Formulario o Componente elige qué crear (Nuevo componente, Ctrl+Shift+N, lo abre en Componente).

El diálogo Nuevo formulario con sus plantillas

Campo	Significado
Nombre	El nombre del archivo y el prefijo de los manejadores del formulario. Se propone uno libre (`form1`, `form2`…).
Título	El título de la ventana (el nombre si está vacío).
Carpeta	Dónde van los archivos: la carpeta del documento actual o la carpeta `ui/` del proyecto. El diálogo muestra la ruta que va a crear y avisa si ya existe.
Plantilla	El punto de partida (abajo).

Plantilla	Te da
En blanco	Una ventana vacía.
Diálogo	Un título, un mensaje y una fila con los botones Cancelar y Aceptar anclada abajo, los dos ya conectados para cerrar la ventana.
Inicio de sesión	Correo, contraseña, “recordarme”, un botón para entrar y una etiqueta de estado en una columna centrada.
Barra lateral	Botones de navegación en una columna a la izquierda y una columna de contenido a la derecha.
Ajustes	Opciones con etiqueta (cuadro de texto, desplegable, interruptor, deslizador) en una grilla de dos columnas, con un botón Guardar.

Crear escribe el .pzform y su .py y los abre. Formulario sin guardar abre la plantilla sin escribir nada: se guarda (pidiendo una ruta) la primera vez que guardes. Los formularios nuevos toman el tamaño de cuadrícula de los Ajustes.

Abrir, guardar y guardar como

Abrir… (Ctrl+O, o clic en el nombre del archivo en la barra de título) lista todos los archivos de Pyzed del proyecto (o de la carpeta de trabajo), saltando .git, .venv, node_modules, build…: formularios (.pzform), componentes (.pzcomp), shaders (.pzshad) y bibliotecas de animaciones (.pzanim). Escribe para filtrar la lista, escribe una ruta y pulsa Enter, o pulsa Examinar… para el diálogo de archivos del sistema. Formularios, componentes y shaders se abren en su vista; una biblioteca de animaciones se abre como JSON en el editor de código, con un aviso que lista sus clips.
Los instaladores hacen que el sistema abra estos cuatro tipos de archivo en Pyzed Design con doble clic (y pyzed design ruta/al/archivo abre cualquiera de ellos, o un script en el editor de código).
Los archivos recientes aparecen al final del menú ☰ (los cinco últimos).
Guardar (Ctrl+S) escribe el documento y su archivo de código. Un documento sin título pide antes una ruta. Guardar también refresca el formulario que se ejecuta desde F5.
Guardar como… (Ctrl+Shift+S) pide una ruta nueva, relativa a la carpeta de trabajo; la extensión se añade si la omites.

Los archivos

Un formulario son dos archivos juntos, pensados para guardarse en git:

login.pzform   ← disposición: JSON, con diffs legibles
login.py       ← manejadores de eventos: Python normal

El archivo .pzform guarda los ajustes del formulario y, para cada control, su tipo, posición, tamaño, propiedades, anclajes y qué manejador llama cada evento:

{
  "format": "pyzed.form/1",
  "form": { "name": "login", "title": "Sign in", "width": 440, "height": 400, "theme": "One Dark", "events": { "load": "form_load" } },
  "controls": [
    { "name": "sign_in", "type": "button", "x": 48, "y": 304, "width": 344, "height": 32,
      "props": { "text": "Sign in", "variant": "solid", "icon": "log-in" },
      "events": { "click": "sign_in_click" }, "anchor": ["left", "top"] }
  ]
}

El editor modifica el archivo .py con ast: encuentra, añade, renombra y sustituye funciones manejadoras sin tocar el resto del archivo, así que tus imports, funciones auxiliares y comentarios quedan como los escribiste. También puedes editar el archivo de código en cualquier otro editor; el formulario solo necesita que existan las funciones manejadoras.

Un componente diseñado también son dos archivos, rating.pzcomp (disposición) y rating.py (la clase); ver Vista de componente.

Añadir tus propios componentes

Registra un componente y aparece en la caja de herramientas, con sus propiedades en la grilla y sus eventos en el panel Eventos:

from pyzed import ui
from pyzed.designer import Component, Prop, register

register(Component(
    type="rating", label="Rating", icon="star", category="Custom", size=(120, 24),
    props=(Prop("value", "number", 3, min=0, max=5),),
    events=("change",),
    render=lambda control, ctx: ui.label("★" * int(control.props["value"])),
))

render se usa tanto en el editor (inerte) como al ejecutar; usa ctx.on(control, "change", "value") para los callbacks y el mismo código funciona en los dos. Todas las subclases de pz.Component de tu proyecto aparecen también en la caja de herramientas (ver Componentes), igual que los componentes que dibujas en el diseñador de componentes.

Se cargan cada vez que se abre un proyecto (al arrancar, desde el selector de proyectos o desde una carpeta reciente) y cuando abres un formulario de otra carpeta. Pyzed importa un módulo por sus componentes solo si su nivel superior se limita a definir cosas: un módulo que llama a pz.run(...) fuera de if __name__ == "__main__": se omite. Un control cuyo componente no se encuentra (su módulo falla al importarse, o el formulario viene de un Pyzed más nuevo) se ve como un recuadro amarillo Component not found con su tipo: el resto del formulario se abre igual y sus propiedades y eventos se conservan al guardar.

Tus propias plantillas

Las plantillas de Nuevo formulario son datos, no código. Cada una es una carpeta:

toolbar/
├── template.json      {"label": "Toolbar", "icon": "panel-top", "description": "A row of buttons on top.", "order": 10}
├── form.pzform        el formulario de partida: dibújalo en el diseñador y guárdalo aquí
└── handlers.py.tmpl   opcional: el código de los eventos que conecta el formulario (Python)

{title} en los textos del formulario se cambia por el título del formulario nuevo, y un tamaño pedido en el diálogo redimensiona el formulario siguiendo los anclajes. Las incluidas están en pyzed/designer/templates/. Carga una carpeta tuya con:

from pyzed.designer import new

new.load_templates("mis_plantillas")   # cada subcarpeta con un template.json

Una plantilla también puede ser una función de Python que rellena un formulario vacío:

def toolbar(form):
    ...  # añade controles al formulario vacío

new.register_template(new.Template("toolbar", "Toolbar", "panel-top", "A row of buttons on top.", toolbar))

Las plantillas registradas aparecen en el diálogo Nuevo formulario después de las incluidas.

Formularios desde código

Todo lo que hace el editor está disponible desde Python, algo útil para generar formularios o para tests:

from pyzed import designer
from pyzed.designer import Document

doc = Document(designer.Form(name="hello", title="Hello", width=320, height=140))
doc.add("input", 16, 16, 200, 28)
doc.add("button", 224, 16)
doc.select_all()
doc.align("middle")
handler = doc.wire("button1", "click")
doc.set_handler_source(handler, "def button1_click(form, event):\n    form.button1.text = form.input1.text\n")
doc.save("hello.pzform")

designer.run("hello.pzform")

designer.new_form(path, template="dialog") crea un formulario y su módulo de manejadores a partir de una plantilla (en un proyecto, project.find().new_form("settings") lo pone en ui/). designer.open_window(form_or_path, data=...) devuelve el comando que abre un formulario desde cualquier app, y también acepta un designer.Form construido en código (con handlers={"name": function}). La API completa está en la referencia del diseñador.

Cómo está hecho

classDiagram
    class Form { controls; events; theme; grid }
    class Control { name; type; x; y; width; height; props; events; anchor }
    class Component { type; props; events; render() }
    class Document { form; code; selection; history; add(); align(); wire() }
    class History { push(); undo(); redo() }
    class Designer { pyzed App: docks and gestures }
    class FormRuntime { dispatch(); view() }
    Form "1" *-- "*" Control
    Control ..> Component : type
    Document --> Form
    Document --> History
    Designer --> Document
    FormRuntime --> Form

model.py: el formulario y sus controles, guardados como JSON.
components.py: la biblioteca de componentes y el render que comparten el editor y el runtime.
geometry.py: snap, alineación, distribución, redimensionado, anclajes y guías inteligentes (funciones puras).
layout.py: dónde va cada control, incluidos los contenedores flex y grilla.
history.py: deshacer/rehacer como instantáneas; las ediciones repetidas de un campo se juntan en un paso.
code.py: encuentra, añade, renombra y sustituye funciones manejadoras con ast.
document.py: cada comando de edición, sin UI, así que se puede probar entero.
commands.py: todos los comandos en una tabla, que leen los menús, la paleta, el teclado y la lista de atajos.
docks.py, panels.py, surface.py, dialogs.py, console.py, project_panel.py: las vistas.
app.py: la app Designer, que conecta clics y teclas con el documento.
scene.py, scene_code.py, scene_runtime.py, scene_panel.py: el diseñador de componentes.
runtime.py: FormApp y FormWindow, que dibujan un formulario y llaman a sus manejadores.
lsp.py, intellisense.py, code_panel.py, settings.py: el editor de código y sus servidores de lenguaje.
preferences.py, locale.py: los ajustes del editor y sus traducciones, leídas de locales/<idioma>.json.
new.py: las plantillas de Nuevo formulario, leídas de las carpetas de templates/.