Diseñador visual (pyzed.designer)

pyzed.designer es el lado en código del diseñador visual: ejecuta archivos .pzform, abre formularios como ventanas, crea formularios en código y amplía la caja de herramientas con tus propios componentes y plantillas. Los componentes diseñados (.pzcomp) también se cargan desde aquí.

from pyzed import designer

designer.run("ui/main.pzform", reload=True)

Ejecutar formularios

run

run(path, *, reload=None, splash=None)

Ejecuta el formulario de path con toda la lógica conectada en el diseñador.

reload=True activa el hot reload: guardar el formulario (desde el diseñador o a mano) o su módulo de handlers actualiza la ventana en marcha sin reiniciarla. None sigue a PYZED_RELOAD, como pz.run.

load

load(path)

Lee un archivo .pzform.

open_form

open_form(path)

Carga un .pzform y sus handlers en una FormApp lista para run() o screenshot().

Si el formulario pertenece a un proyecto (ver pyzed.project), primero se activa el proyecto para que sus handlers puedan importar el backend y los paquetes de su .venv.

open_window

open_window(form, *, data=None, handlers=None, folder=None)

Un Command que abre form en una ventana nueva (los argumentos son los de form_window).

form_window

form_window(form, *, data=None, handlers=None, folder=None)

Una FormWindow para form (una ruta o nombre de .pzform, o un Form), lista para abrirse.

Un formulario cargado de un archivo recibe su módulo de handlers; un Form creado en código usa handlers (un dict de funciones). data llega al formulario nuevo como form.data.

new_form

new_form(
    path,
    *,
    title=None,
    template='blank',
    width=None,
    height=None,
    overwrite=False,
)

Crea path (se añade .pzform si falta) y su módulo de handlers a partir de template.

El formulario toma el nombre del archivo (order-details.pzform -> OrderDetails).

Devuelve la ruta del formulario. Lanza FileExistsError si ya existe, salvo con overwrite.

save

save(form, path)

Escribe form en path (se añade .pzform cuando no tiene extensión).

open_document

open_document(path)

Abre un .pzform como Document o un .pzcomp como SceneDocument.

design

design(path=None, *, theme=None)

Abre el diseñador visual, opcionalmente sobre un archivo .pzform (que se crea al guardar por primera vez).

Formularios y controles

Form

@dataclass
class Form(name='Form1', title='Form1', width=640.0, height=420.0, theme='One Dark', accent=None, background=None, radius=None, font_size=14.0, resizable=True, grid=8, style={}, controls=[], events={}, code=None, animations=[], autoplay='')

Una ventana diseñada visualmente: sus ajustes, sus controles (en orden z) y sus eventos.

theme es cualquier nombre de tema registrado; accent, radius y font_size lo ajustan sin escribir un archivo de tema. style es el estilo global del formulario (pz.Style.to_dict()), aplicado a toda la ventana. grid es el paso de ajuste del diseñador.

Métodos y propiedades

Form.get

Form.get(name)

Devuelve el control llamado name, o None si no hay ninguno.

Form.names

Form.names()

Devuelve los nombres de todos los controles, en orden z.

Form.children

Form.children(name)

Los controles directamente dentro de name (el propio formulario con None), en orden z.

Form.descendants

Form.descendants(name)

Todos los controles dentro de name, a cualquier profundidad (los padres antes que sus hijos).

Form.ancestors

Form.ancestors(name)

Los contenedores que contienen a name, del más cercano al más lejano.

Form.walk

Form.walk(parent=None, depth=0)

(control, depth) en orden de dibujo: cada control y luego lo que contiene.

Form.is_inside

Form.is_inside(name, container)

Si el control name está dentro de container, a cualquier profundidad.

Form.unique_name

Form.unique_name(base)

El primer base1, base2… libre (al estilo de Visual Basic).

Form.add

Form.add(control)

Añade control (encima del orden z) y lo devuelve.

Form.remove

Form.remove(names)

Quita controles y todo lo que contienen.

Form.rename

Form.rename(old, new)

Renombra un control y devuelve el nombre usado en realidad (único y válido).

Form.reorder

Form.reorder(names, where)

Mueve controles al frente ("front") o al fondo ("back") del orden z.

Form.to_dict

Form.to_dict()

Devuelve el formulario como datos listos para JSON: {"format", "form": ajustes, "controls": [...]}.

Form.from_dict

@classmethod
Form.from_dict(data)

Crea un formulario a partir de data guardados (ver to_dict), ignorando ajustes desconocidos y reparando padres rotos; lanza ValueError si no es un formulario de Pyzed.

Form.to_json

Form.to_json()

Devuelve el formulario como texto JSON indentado (el contenido de un archivo .pzform).

Form.from_json

@classmethod
Form.from_json(text)

Crea un formulario a partir del texto JSON text de un archivo .pzform.

Form.copy

Form.copy()

Devuelve una copia profunda del formulario y sus controles.

Control

@dataclass
class Control(name, type, x=0.0, y=0.0, width=100.0, height=28.0, props={}, events={}, anchor=('left', 'top'), visible=True, enabled=True, locked=False, parent=None, layout={}, style={}, animations=[], bind='', rules={}, hidden_in_editor=False)

Un componente colocado en un formulario.

x, y, width y height están en píxeles lógicos relativos al área cliente del formulario, o a la esquina superior izquierda de parent cuando el control está dentro de un contenedor (un panel, un group box, una fila flex…). props guarda las propiedades propias del componente (text, checked…) y events asocia nombres de evento ("click") a nombres de función handler. layout guarda opciones que lee el layout del padre, como grow en una fila flex o span en una grid. style guarda propiedades de estilo tipo CSS (pz.Style.to_dict(): fondo, borde, radio, fuente…) que se dibujan por encima de las props.

Métodos y propiedades

Control.min_size

Control.min_size  # property

El (ancho, alto) mínimo cuando el control se estira (0: sin límite).

Control.max_size

Control.max_size  # property

El (ancho, alto) máximo cuando el control se estira (0: sin límite).

Control.pivot

Control.pivot  # property

El punto (x, y) de 0 a 1 alrededor del que giran la rotación y la escala, y que se queda quieto cuando un límite de tamaño frena el estiramiento.

Control.rect

Control.rect  # property

El (x, y, width, height) del control, relativo a su padre (o al formulario).

Control.to_dict

Control.to_dict()

Devuelve el control como datos listos para JSON; parent, layout y style vacíos se omiten.

Control.from_dict

@classmethod
Control.from_dict(data)

Crea un control a partir de data guardados, ignorando claves desconocidas y anclajes no válidos.

Control.copy

Control.copy()

Devuelve una copia profunda del control.

Event

@dataclass
class Event(sender, name, value=None)

Lo que recibe un handler además del formulario: quién lo lanzó, qué evento y su valor.

FormApp

class FormApp

Un formulario como ventana principal de la aplicación.

path (lo fija open_form) es el archivo .pzform; con el hot reload activo, guardarlo o guardar su módulo de handlers actualiza la ventana en marcha.

Métodos y propiedades

FormApp.on_start

FormApp.on_start()

Vigila el formulario y su módulo de handlers para el hot reload (si está activo) y luego lanza load.

FormWindow

class FormWindow

Un formulario en una ventana extra (form.open(...), designer.open_window y la vista previa del diseñador).

Métodos y propiedades

FormWindow.on_open

FormWindow.on_open()

Lanza el evento load del formulario al abrirse la ventana.

Document

class Document

Un formulario abierto en el diseñador.

code es el texto del módulo de handlers, guardado en memoria y escrito junto al formulario al hacer save. selection guarda nombres de controles, el principal primero.

Métodos y propiedades

Document.clipboard

Document.clipboard  # property

Los controles copiados (como datos de Control.to_dict()), compartidos por todos los documentos.

Document.open

@classmethod
Document.open(path)

Carga en un documento nuevo el formulario de path y el texto de su módulo de handlers (si el archivo existe).

Document.code_path

Document.code_path  # property

Dónde se guarda el módulo de handlers, o None mientras el formulario no tenga archivo.

Document.display_name

Document.display_name  # property

El nombre que se muestra para el documento: su nombre de archivo, o <nombre del formulario>.pzform si no está guardado.

Document.save

Document.save(path=None)

Escribe el formulario y su módulo de handlers; devuelve la ruta del formulario.

Document.commit

Document.commit(group=None)

Guarda un paso de deshacer tras una edición (group une ediciones repetidas de un mismo campo).

Document.undo

Document.undo()

Retrocede un paso; devuelve False si no había nada que deshacer.

Document.redo

Document.redo()

Rehace un paso deshecho; devuelve False si no había nada que rehacer.

Document.selected

Document.selected  # property

Los controles seleccionados, el principal primero (se saltan los nombres que ya no existen).

Document.primary

Document.primary  # property

El control seleccionado principal (el primero), o None si no hay nada seleccionado.

Document.select

Document.select(names, *, add=False)

Selecciona los controles names (un nombre, varios, o None para ninguno); los nombres desconocidos se ignoran.

Document.select_all

Document.select_all()

Selecciona todos los controles del formulario.

Document.is_selected

Document.is_selected(name)

Si el control name está seleccionado.

Document.add

Document.add(type_, x, y, width=None, height=None, *, snap=True, parent=None)

Coloca un control nuevo de tipo type_ (ajustado a la cuadrícula) y lo selecciona.

Document.rects

Document.rects()

El rectángulo absoluto de cada control (ver layout.resolve).

Document.can_contain

Document.can_contain(container, name)

Si el control name puede moverse dentro de container (None es el formulario, que admite cualquiera): debe ser un contenedor distinto del propio control y que no esté dentro de él.

Document.reparent

Document.reparent(names, parent, *, index=None, at=None, commit=True, rects=None)

Mueve controles dentro de parent (o al formulario con None), dejándolos donde están.

Document.wrap

Document.wrap(type_, names=None, props=None)

Mete controles (por defecto, la selección) dentro de un contenedor nuevo de tipo type_ que los rodea.

Document.ungroup

Document.ungroup(names=None)

Saca los hijos de los contenedores seleccionados (donde están en pantalla) y quita los contenedores; los hijos quedan seleccionados. Devuelve los nombres de los contenedores quitados.

Document.move_out

Document.move_out(name)

Saca un control de su contenedor y lo pasa al padre de ese contenedor.

Document.set_layout

Document.set_layout(name, key, value)

Fija una opción que lee el layout del padre (grow, span).

Document.delete

Document.delete()

Quita los controles seleccionados (y lo que contienen); devuelve los nombres quitados.

Document.copy

Document.copy()

Copia la selección, con lo que haya dentro de los contenedores seleccionados.

Document.clipboard_text

Document.clipboard_text()

Los controles copiados como JSON para el portapapeles del sistema, para que otro formulario, otra ventana de Pyzed Design o un archivo de texto puedan tomarlos (ver paste_text).

Document.parse_clipboard

@staticmethod
Document.parse_clipboard(text)

Los controles del texto del portapapeles escrito por clipboard_text, o None si contiene otra cosa. Se descartan los controles de un tipo que este Pyzed no conoce.

Document.paste_text

Document.paste_text(text, offset=16)

Pega los controles del texto del portapapeles del sistema (ver clipboard_text); devuelve los nombres nuevos, o None si el texto no contiene controles de Pyzed.

Document.cut

Document.cut()

Copia la selección al portapapeles y la borra; devuelve cuántos controles se copiaron.

Document.paste

Document.paste(offset=16)

Añade copias del portapapeles (desplazadas offset) sin sus eventos; conservan su nombre si está libre en este formulario.

Document.duplicate

Document.duplicate()

Pega al momento una copia de la selección sin tocar el portapapeles; devuelve los nombres nuevos.

Document.size

Document.size  # property

El (width, height) del formulario en píxeles.

Document.nudge

Document.nudge(dx, dy)

Mueve dx, dy píxeles los controles seleccionados (los que no coloca un layout), sin salirse de su contenedor cuando comparten uno; los empujones repetidos se unen en un solo paso de deshacer.

Document.align

Document.align(edge, *, to_form=False)

Alinea los controles seleccionados en edge (ver geometry.align): entre sí, o al formulario con to_form o cuando solo hay un control seleccionado.

Document.center

Document.center(axis='both')

Centra la selección (como grupo) en el formulario.

Document.distribute

Document.distribute(axis)

Reparte los controles seleccionados con el mismo espacio a lo largo de axis (ver geometry.distribute).

Document.same_size

Document.same_size(which='both')

Da a los controles seleccionados el ancho, el alto o ambos (which) del principal.

Document.snap_to_grid

Document.snap_to_grid()

Ajusta a la cuadrícula del formulario los controles seleccionados (o todos si no hay selección).

Document.reorder

Document.reorder(where)

Mueve los controles seleccionados en el orden z (where: ver Form.reorder).

Document.set_rect

Document.set_rect(name, rect, *, group=None)

Fija la posición y el tamaño del control name a partir de rect (x, y, width, height), redondeados a píxeles enteros; las ediciones con el mismo group se unen en un paso de deshacer.

Document.set_prop

Document.set_prop(name, key, value)

Fija la propiedad key del control name a value (las ediciones repetidas se unen en un paso de deshacer).

Document.set_style

Document.set_style(name, key, value)

Fija una propiedad de estilo de un control, o del estilo global del formulario si name es None; None la quita.

Document.set_animations

Document.set_animations(name, animations, *, group=None)

Fija la lista de animaciones del control name (dicts con preset y, opcionalmente, on, duration, delay, easing y repeat); las ediciones con el mismo group se unen en un paso de deshacer.

Document.set_clip

Document.set_clip(clip, *, old=None, group=None)

Guarda el pz.Clip clip en el formulario (en lugar del clip old cuando se renombra).

Document.remove_clip

Document.remove_clip(name)

Quita el clip name (y deja de reproducirse al abrir el formulario).

Document.set_autoplay

Document.set_autoplay(name)

Reproduce el clip name al abrir el formulario ("": ninguno).

Document.clear_style

Document.clear_style(name)

Quita todas las propiedades de estilo de un control (o del estilo global del formulario).

Document.set_field

Document.set_field(name, key, value)

Fija un atributo de Control (x, y, width, height, visible, enabled, locked, anchor).

Document.set_bind

Document.set_bind(name, bind)

Enlaza el control name al campo (o, en los controles de visualización, a la expresión) bind de form.data; None o "" lo desenlaza.

Document.set_rule

Document.set_rule(name, rule, value)

Fija la regla de validación rule (required, min_length, pattern…) del control name; None, "" o False la quita.

Document.toggle_anchor

Document.toggle_anchor(name, edge)

Añade edge a los anclajes del control name, o lo quita si ya estaba.

Document.parent_size

Document.parent_size(name)

El tamaño del padre del control name (su contenedor o el formulario).

Document.set_anchor

Document.set_anchor(name, anchor, *, move=False, margin=0.0)

Ancla el control name con un preset, palabras o bordes; con move=True también lo lleva a ese sitio, a margin píxeles del borde.

Document.set_offset

Document.set_offset(name, side, value)

Fija la distancia de un lado (left, top, right, bottom) del control name al de su padre.

Document.set_pivot

Document.set_pivot(name, x, y)

Fija el pivote del control name (de 0 a 1 en cada eje).

Document.set_form

Document.set_form(key, value)

Fija el atributo key del formulario (un name nuevo se convierte antes en un identificador válido).

Document.reflow

Document.reflow(parent, size)

Tras cambiar el tamaño del formulario (parent None) o del contenedor parent desde size, mueve y dimensiona lo que hay dentro según sus anclajes (salvo con follow_anchors desactivado).

Document.rename

Document.rename(old, new)

Renombra un control, su entrada en la selección y los handlers que siguen la convención de nombres.

Document.owner

Document.owner(name)

El nombre visible y el mapa de eventos de un control, o del formulario si name es None.

Document.events_of

Document.events_of(name)

Devuelve los eventos del control name, o los del formulario si name es None.

Document.wire

Document.wire(name, event)

Conecta event a un handler (creando su esqueleto si hace falta) y devuelve el nombre de la función.

Document.unwire

Document.unwire(name, event, *, delete_code=False)

Desconecta event; con delete_code también quita el esqueleto si no se ha tocado.

Document.rename_handler

Document.rename_handler(old, new)

Hace que los eventos conectados al manejador old apunten a new (después de renombrar su función en el código); devuelve si algún evento lo usaba.

Document.handler_source

Document.handler_source(handler)

Devuelve el código de handler, o un esqueleto nuevo si aún no existe.

Document.set_handler_source

Document.set_handler_source(handler, source)

Reemplaza el código de un handler (lanza SyntaxError y no cambia nada si no es válido).

Document.set_code

Document.set_code(source)

Reemplaza todo el texto del módulo de handlers y marca el documento como modificado.

Enlace de datos y validación

check

check(value, rules, type_='input')

El mensaje de la primera regla que value incumple, o None si las cumple todas.

required (una casilla marcada para casillas e interruptores), min_length, max_length, pattern (una expresión regular que todo el texto debe cumplir), min y max. message, si está, sustituye el mensaje predeterminado. Los valores vacíos solo incumplen required.

translate

translate(value, language=None)

value con los textos @clave buscados en el idioma actual (o el indicado); las listas se traducen elemento a elemento y @@ representa una @ literal.

read

read(data, path, default=None)

El campo en path de data (dicts, listas y objetos), o default si falta.

write

write(data, path, value)

Fija el campo en path de data, creando por el camino los dicts que falten.

has

has(data, path)

Si data tiene un campo en path.

evaluate

evaluate(expression, data, **extra)

El valor de bind para data: el campo si es una ruta, si no la expresión de Python evaluada sobre los campos de los datos. Lanza un error si falta el campo o la expresión es incorrecta.

bound_prop

bound_prop(type_)

La propiedad que enlaza un control de tipo type_ (None si no se puede enlazar).

two_way

two_way(type_)

Si un control de tipo type_ escribe en los datos lo que cambia el usuario.

rules_for

rules_for(type_)

Las reglas de validación que tienen sentido para type_ (ninguna para los controles de visualización).

load_texts

load_texts(path)

Carga los catálogos de traducción del formulario en path: locales/ junto a él y en las carpetas superiores, hasta la raíz del proyecto. Devuelve los idiomas encontrados.

BIND_PROPS

La propiedad que enlaza cada tipo de control y si el usuario la edita (en los dos sentidos): {tipo: (propiedad, dos_sentidos)}.

Caja de herramientas

Component

@dataclass
class Component(type, label, icon, category, render, size=(120, 28), props=(), events=(), description='', visual=True, container=None, child_layout=(), children=(), role=None)

Una entrada de la caja de herramientas: cómo se ve, se comporta y se configura un control de este type.

Métodos y propiedades

Component.default_event

Component.default_event  # property

El evento que se abre al hacer doble clic en el control en el diseñador.

Component.all_events

Component.all_events  # property

Los eventos propios del control seguidos, en los componentes visuales, de los eventos de ratón comunes.

Component.defaults

Component.defaults()

Devuelve un dict nuevo con el valor por defecto de cada propiedad, por nombre.

Component.prop

Component.prop(name)

Devuelve la propiedad llamada name, o None si el componente no la tiene.

Component.create

Component.create(name, x=0, y=0, width=None, height=None)

Un control nuevo de este tipo con las propiedades por defecto.

Prop

@dataclass
class Prop(name, kind, default=None, label='', choices=(), min=None, max=None, step=1.0, group='Appearance', type='', accept='')

Una propiedad que se muestra en la rejilla de propiedades del diseñador.

kind elige el editor: text, multiline, number, bool, color, choice (de choices), list (un elemento por línea), rows (filas separadas por comas, la primera es la cabecera) o icon (un nombre de icono de Lucide).

Métodos y propiedades

Prop.title

Prop.title  # property

La etiqueta que se muestra en la rejilla de propiedades: label, o el nombre con espacios en lugar de guiones bajos.

RenderContext

class RenderContext

Lo que necesita el render de un componente: el tema y una forma de lanzar eventos.

live es False en el diseñador, donde los callbacks son marcadores inertes para que los controles se vean habilitados pero no hagan nada.

Métodos y propiedades

RenderContext.on

RenderContext.on(control, event, prop=None)

Un callback para event; si se da prop, el valor también se guarda ahí.

RenderContext.set

RenderContext.set(control, prop, value)

Guarda value en prop de un control en ejecución sin lanzar ningún evento (las carpetas abiertas de un árbol).

RenderContext.key

RenderContext.key(control)

Un id estable para widgets con estado interno (editores, campos de texto).

register

register(component)

Añade (o reemplaza) un componente en la caja de herramientas.

component

component(type_)

Devuelve el componente registrado para type_; lanza KeyError con la lista de tipos conocidos.

all_components

all_components()

Devuelve todos los componentes registrados, en orden de registro.

categories

categories()

Devuelve los componentes registrados agrupados por category (secciones de la caja de herramientas), en orden de registro.

Template

@dataclass
class Template(name, label, icon, description, build=None, size=(640, 420), handlers=(), form=None)

Un punto de partida para formularios nuevos.

register_template

register_template(template)

Añade (o reemplaza, por nombre) una plantilla del diálogo “Nuevo formulario”; la devuelve.

templates

templates()

Devuelve las plantillas de formulario registradas, en orden de registro.

Componentes diseñados

new_component

new_component(
    name='Component1',
    path=None,
    *,
    width=240,
    height=120,
    label='',
    icon='component',
    category='Custom',
    description='',
    extends=None,
)

Un componente diseñado nuevo (aún sin guardar; llama a save()): su escena y una clase vacía.

extends es el .pzcomp de un componente del que heredar: la clase nueva deriva de él y empieza con sus controles, propiedades, eventos y métodos.

load_component

load_component(path)

Importa la clase del componente guardado en path (de nuevo, para recoger los cambios).

Definir la clase la registra en la caja de herramientas, reemplazando una versión anterior. Devuelve la clase, o None (con el motivo en errors) si su código falla al importarse.

import_component

import_component(scene)

La clase del componente diseñado guardado en scene, para heredar de ella.

Una ruta relativa es relativa al módulo que la llama, así que un componente puede extender otro que esté a su lado:

Rating = import_component("rating.pzcomp")

class BigRating(Rating, scene="big_rating.pzcomp"):
    ...

La clase se importa una vez y se reutiliza hasta que cambia su código.

discover

discover(root=None, *, fresh=True)

Importa todos los componentes diseñados bajo root (por defecto, la carpeta actual).

Los componentes pueden usarse entre sí, así que una importación fallida se reintenta cuando los demás ya cargaron (errors guarda lo que siga fallando).

SceneDocument

class SceneDocument

Un componente abierto en el diseñador: su escena, el código de su clase, la selección y el deshacer.

Funcionan todos los comandos de Document (colocar, mover, alinear controles…). Los eventos de los controles se convierten en métodos de la clase (def ok_click(self, event)), y los eventos propios del componente son sus métodos de ciclo de vida (setup, on_mount…). Las propiedades y los eventos personalizados se leen de la clase y se escriben de vuelta en ella.

Métodos y propiedades

SceneDocument.scene

SceneDocument.scene  # property

La escena del componente (el form del documento, tipado como Scene).

SceneDocument.base_file

SceneDocument.base_file  # property

El .pzcomp que extiende este componente, o None.

SceneDocument.base

SceneDocument.base  # property

La escena que extiende este componente, con todo lo que ella misma hereda (None si no hay).

SceneDocument.inherited

SceneDocument.inherited(name)

True para un control que viene del componente base.

SceneDocument.own_scene

SceneDocument.own_scene()

Lo que guarda el .pzcomp propio de este componente: sus controles y los heredados que cambió.

SceneDocument.set_base

SceneDocument.set_base(path)

Hace que este componente herede del guardado en path (None no hereda de nada).

SceneDocument.base_info

SceneDocument.base_info()

Las clases de las que hereda este componente (la más cercana primero) como (nombre del archivo de escena, info de la clase).

SceneDocument.all_members

SceneDocument.all_members  # property

Las propiedades de este componente y las que hereda (los bindings pueden usar ambas).

SceneDocument.info

SceneDocument.info  # property

La clase tal como se analizó por última vez (el último análisis correcto mientras el código tenga un error de sintaxis).

SceneDocument.code_ok

SceneDocument.code_ok  # property

Si el código de la clase se puede analizar ahora (si no, info recurre al último análisis correcto).

SceneDocument.members

SceneDocument.members  # property

Las propiedades y el estado privado del componente tal como se declaran en su clase, en orden (una copia).

SceneDocument.member

SceneDocument.member(name)

Devuelve la propiedad o el estado declarado llamado name, o None.

SceneDocument.unique_member

SceneDocument.unique_member(base='value')

Devuelve base (convertido en identificador), o base2, base3… si ya lo usa un miembro, método, control o nombre reservado.

SceneDocument.add_member

SceneDocument.add_member(name='', type_='str', default=None, *, public=True, description='')

Declara una propiedad nueva (public=False la convierte en estado privado).

SceneDocument.update_member

SceneDocument.update_member(member, **changes)

Cambia una propiedad (name, type, default, public, description); devuelve su nombre.

SceneDocument.set_member_source

SceneDocument.set_member_source(name, source)

Pone como valor por defecto de la propiedad name la expresión de Python source ([1, 2], Point(x=1)…).

SceneDocument.remove_member

SceneDocument.remove_member(name)

Quita la propiedad name de la clase.

SceneDocument.move_member

SceneDocument.move_member(name, offset)

Mueve la propiedad name offset posiciones en el orden de declaración de la clase (dentro de los límites).

SceneDocument.custom_events

SceneDocument.custom_events  # property

Los eventos que declara el componente, como {nombre: descripción} (una copia).

SceneDocument.add_event

SceneDocument.add_event(name='changed', description='')

Declara un evento nuevo llamado name (hecho único) con description; devuelve su nombre.

SceneDocument.update_event

SceneDocument.update_event(name, *, new_name=None, description=None)

Renombra el evento name a new_name (si es válido y está libre) y/o cambia su description, manteniendo su posición; devuelve el nombre del evento. Lanza KeyError si no existe.

SceneDocument.remove_event

SceneDocument.remove_event(name)

Quita de la clase el evento declarado name.

SceneDocument.set_class_name

SceneDocument.set_class_name(name)

Renombra la clase del componente (convertido en un nombre de clase válido) en el código y la escena; devuelve el nombre nuevo.

SceneDocument.set_description

SceneDocument.set_description(text)

Fija la descripción del componente, también como docstring de su clase.

SceneDocument.set_scene

SceneDocument.set_scene(key, value)

Fija cómo aparece el componente en la caja de herramientas (label, icon, category) o su tamaño.

SceneDocument.set_binding

SceneDocument.set_binding(control, prop, expression)

Hace que prop de control siga a expression (None o "" quita el binding).

SceneDocument.add_method

SceneDocument.add_method(name='do_something', args='self', doc='')

Añade a la clase un método reutilizable (no un handler de evento); devuelve su nombre.

Scene

@dataclass
class Scene(name='Component1', title='Component1', width=240.0, height=120.0, theme='One Dark', accent=None, background=None, radius=None, font_size=14.0, resizable=False, grid=8, style={}, controls=[], events={}, code=None, animations=[], autoplay='', label='', icon='component', category='Custom', description='', extends='', bindings={})

El layout de un componente diseñado: un Form cuyo name es el nombre de la clase.

bindings asocia un nombre de control a {propiedad del control: expresión}; la expresión (normalmente una propiedad del componente, como value, o cualquier expresión de Python sobre ellas, como f"{value} stars") se evalúa en cada render.

Métodos y propiedades

Scene.class_name

Scene.class_name  # property

El nombre de la clase del componente (el name de la escena).

Scene.bound

Scene.bound(control)

Devuelve los bindings de control como {propiedad: expresión} (vacío si no tiene).

SceneComponent

class SceneComponent

Clase base de los componentes creados en el modo componente del diseñador.

scene es el archivo .pzcomp con el layout, relativo al módulo. La etiqueta, el icono, la categoría, la descripción y el tamaño por defecto en la caja de herramientas salen de la escena salvo que la clase los fije.

Métodos y propiedades

SceneComponent.scene_path

@classmethod
SceneComponent.scene_path()

Devuelve el archivo .pzcomp al que está ligada la clase, o None.

SceneComponent.scene_model

@classmethod
SceneComponent.scene_model()

La escena tal como está guardada (o previsualizada por el diseñador), o None.

SceneComponent.ctx

SceneComponent.ctx  # property

Un contexto de render para esta instancia, con el tema de su escena (lo que necesita ControlProxy.focus()).

render

render(control, ctx)

Dibuja control a su tamaño (con sus props, o los valores por defecto del componente si faltan).

Ayudas de layout

align

align(controls, edge, *, to=None)

Alinea controles en edge (left, center, right, top, middle, bottom).

Con to (p. ej. el rectángulo del formulario) se alinean a él; si no, a los límites de la selección, o al formulario cuando se pasa un solo control mediante to.

distribute

distribute(controls, axis)

Reparte tres o más controles con el mismo espacio en "horizontal" o "vertical".

same_size

same_size(controls, which='both', *, reference=None)

Da a todos los controles el "width", "height" o "both" de reference (el primero).

snap

snap(value, grid, enabled=True)

Redondea value al múltiplo más cercano de grid (sin cambios si está desactivado).

smart_guides

smart_guides(rect, others, size, threshold=4.0)

Ajusta un rectángulo en movimiento a los bordes y centros de others y del formulario.

Devuelve (dx, dy, lines): la corrección a aplicar y las líneas guía a dibujar (como cajas finas (x1, y1, x2, y2)), como las guías de alineación de Figma o Qt Designer.

anchored

anchored(control, design, actual)

Dónde va un control cuando su formulario pasa del tamaño design al tamaño actual.

Como los anclajes de WinForms: un borde anclado al formulario mantiene su distancia a ese lado; anclado a ambos lados se estira; anclado a ninguno mantiene su posición relativa (los controles centrados siguen centrados).

App del diseñador

Designer

class Designer

El editor visual de formularios.

EditorSettings

@dataclass
class EditorSettings(theme='', font_family='', font_size=14.0, tab_size=4, hard_tabs=False, convert_indentation=False, backspace_unindent=True, repeat_delay=500.0, repeat_rate=20.0, show_whitespace=False, wrap=False, line_numbers=True, highlight_line=True, autocomplete=True, code_lens=True, inline_diagnostics=True, format_on_apply=False, auto_close=True, folding=True, minimap=True, cursor_shape='bar', cursor_blink=True, cursor_width=2.0, line_height='standard', scrollbar=True, match_brackets=True, selection_highlight=True, hover=True, sticky_scroll=True, ty=True, ruff=True, keymap={})

Los ajustes del editor de código del diseñador (un dataclass): theme, font_size, tab_size, hard_tabs, convert_indentation, backspace_unindent, repeat_delay, repeat_rate, show_whitespace, wrap, line_numbers, highlight_line, autocomplete, code_lens, inline_diagnostics, format_on_apply, auto_close, folding, minimap, cursor_shape, cursor_blink, ty y ruff.

Métodos y propiedades

EditorSettings.key_repeat

EditorSettings.key_repeat  # property

Los repeat_delay y repeat_rate del editor (None donde se mantiene la repetición de teclas del sistema).

EditorSettings.to_dict

EditorSettings.to_dict()

Devuelve los ajustes como un dict listo para JSON.

EditorSettings.from_dict

@classmethod
EditorSettings.from_dict(data)

Crea los ajustes a partir de data guardados, con los valores por defecto para los que falten o no sean válidos, y limitando el tamaño de tabulación, el de fuente y la forma del cursor a valores válidos.

History

class History

Instantáneas de un formulario: push tras una edición, y luego undo/redo para moverse entre ellas.

Métodos y propiedades

History.push

History.push(form, group=None)

Guarda el estado actual del formulario; devuelve False si nada cambió.

History.steps

History.steps  # property

Cuántos pasos de deshacer hay (una marca para merge).

History.merge

History.merge(mark)

Convierte en un solo paso de deshacer todo lo guardado desde mark (steps antes de una tanda de cambios).

History.reset

History.reset(form)

Olvida todos los pasos de deshacer y rehacer y empieza de nuevo desde el estado actual de form.

History.can_undo

History.can_undo  # property

Si hay un paso que deshacer.

History.can_redo

History.can_redo  # property

Si hay un paso deshecho que rehacer.

History.undo

History.undo()

Retrocede una instantánea; devuelve el formulario anterior (un objeto nuevo) o None si no hay.

History.redo

History.redo()

Avanza una instantánea; devuelve el formulario restaurado (un objeto nuevo) o None si no hay.

theme_for

theme_for(form, theme_name=None)

El tema con el que se ejecuta un formulario: su tema base más los ajustes de acento, radio, fuente y fondo.

COMMON_EVENTS

Los eventos que cualquier control puede manejar en el panel Eventos del diseñador.

FORM_EVENTS

Los eventos del propio formulario (load, close, resize, key…).