Animaciones y efectos

Cada control visual tiene dos secciones al final del panel Propiedades, después de su estilo: Efectos y Animación. Lo que fijes ahí se guarda en el .pzform y se reproduce cuando el formulario se ejecuta. Es el mismo sistema que widget.animate() y los efectos de estilo de la biblioteca.

Efectos

Campo	Qué hace
Opacidad	Cuánto se ve el control y todo lo que tiene dentro (1 es opaco).
Sombra	Una sombra proyectada: elige un color y luego Desplazamiento (X e Y) y Desenfoque.
Desenfoque	Desenfoca el control y todo lo que contiene, en píxeles.
Desenfoque del fondo	Desenfoca lo que hay detrás de la caja, en píxeles.
Resplandor	Un halo suave alrededor de la caja. Elige un color (o un token del tema como accent); Tamaño del resplandor fija cuánto se extiende.
Bloom	Luz que desborda de las partes brillantes del control. Intensidad va de 0 a 1.
Cristal	Un panel translúcido que desenfoca lo que tiene detrás, con un borde claro. Matiz lo colorea e Intensidad del tinte fija cuánto se nota el tinte.

La rotación está en la sección Posición. Los subcampos solo aparecen mientras el efecto está activo. Borra el color (o apaga Cristal) para quitarlo. Los efectos son propiedades de estilo (opacity, shadow, blur, backdrop_blur, glow, bloom, glass), así que en el código aparecen en control.style y Restablecer el estilo también los quita. El cristal luce mejor sobre un fondo colorido, como un panel con degradado.

Animación

Una animación son dos decisiones: cuándo se reproduce y qué se reproduce (un preset como Aparecer subiendo, Latido o Sacudida). Un control sin animaciones muestra algunas listas para añadir con un clic (Aparecer al mostrarse, Elevar al pasar el ratón, Latir al hacer clic, Sacudir si el valor no es válido…), solo las que encajan con el control, y Añadir animación para cualquier otra.

Cada fila es una animación: un icono de lo que la reproduce, un resumen (Aparecer subiendo · 280 ms, con +retardo y ×repeticiones si las tiene) y el disparador debajo. El botón ▶ la previsualiza y la papelera la quita. Haz clic en una fila para abrir su editor:

Campo	Significado
Cuándo	Qué la reproduce (ver la tabla de abajo). Debajo del campo, una línea explica cómo empieza la elegida.
Control, Evento	Solo con Con un evento de otro control: qué control (o el formulario) y cuál de sus eventos.
Animación	El preset. Primero salen los que encajan con el disparador (entradas para al aparecer, interacciones para encima y pulsar, de atención para clics y eventos); el tooltip describe el elegido.
Duración, Retardo	Milisegundos. Vacío mantiene el timing propio del preset.
Curva	Cómo cambia la velocidad por el camino (suave, lineal, frenar cúbica, muelle…).
Repetir	1, 2, 3, 5 o infinito.

Cuándo	Se reproduce
Al aparecer	Una vez, al abrir el formulario o al mostrarse el control.
Con el ratón encima, Mientras se pulsa, Mientras tiene el foco	Hacia delante mientras se cumple la condición, y hacia atrás cuando termina.
Al hacer clic, Al hacer doble clic, Al hacer clic derecho	Una vez en cada clic.
Cuando entra el puntero, Cuando sale el puntero	Una vez cada vez que el ratón entra o sale.
Cuando cambia su valor	Una vez con cada valor nuevo (al escribir, al elegir otra opción, al cambiar un interruptor…).
Al pulsar Enter	Una vez cuando el usuario envía un campo de texto.
Cuando su valor no es válido	Una vez cada vez que falla una regla de validación: la clásica sacudida con una contraseña mal escrita.
Con un evento de otro control	Una vez con cada evento de otro control o del formulario: una etiqueta que late al pulsar Guardar, una tarjeta que aparece al cargar el formulario.
Al reproducirla desde el código	Solo cuando un manejador llama a play_animation() (ver abajo).

Los disparadores por evento funcionan aunque el control no tenga manejador para ese evento, y se reproducen antes de que corra el manejador. Añadir animación añade una fila (un aparecer subiendo al aparecer) y la abre. Elegir otro preset restablece el timing de la fila al del nuevo preset. Todos los cambios se pueden deshacer.

Reproducirla desde tu código

Elige Al reproducirla desde el código y la animación espera a tus manejadores: no se reproduce al abrir el formulario. La fila abierta muestra la línea que la reproduce, con un botón para copiarla. Pégala en cualquier manejador (el clic de un botón, el tick de un temporizador, una validación que falla):

def sign_in_click(form, event):
    if not form.password.validate():
        form.password.play_animation()      # reproduce las animaciones "desde el código" del campo

play_animation() también repite las animaciones Al aparecer del control. Pásale un nombre de preset, un pz.Animation o valores de propiedades para reproducir algo que el control no tiene en sus filas, y usa stop_animation() para parar lo que inició (un bucle, por ejemplo):

Llamada	Qué se reproduce
form.title.play_animation()	Sus filas Al reproducirla desde el código (y repite las de Al aparecer).
form.title.play_animation("tada")	Ese preset, una vez.
form.badge.play_animation("pulse", repeat=3, duration=400)	Un preset con otro tiempo (cualquier opción de animate()).
form.card.play_animation(scale=1.05, duration=200)	Hasta esos valores y de vuelta.
form.spinner.stop_animation()	Para lo que inició play_animation.

Empieza aquí: aplicar y reproducir lo compara con pz.Trigger, la forma de hacer lo mismo en una app solo con código.

Vista previa

El lienzo se queda quieto mientras editas, para que los controles no se muevan bajo el ratón. Vista previa (al final de la sección, o ▶ en una fila) reproduce una vez en el lienzo las animaciones del control, como si acabara de aparecer; Detener termina la previsualización. Ejecuta el formulario (F5) para ver cada animación con su disparador real.

En código

Las animaciones se guardan como datos simples en el control:

"animations": [
  {"preset": "fade_in_up"},
  {"preset": "lift", "on": "hover", "duration": 180}
]

Los valores de "on" son mount (por defecto), hover, press, focus, click, double_click, right_click, enter, leave, change, submit, invalid, event y manual (Al reproducirla desde el código). Una entrada event nombra además su origen y su evento: {"preset": "tada", "on": "event", "source": "save", "event": "click"} (un source vacío es el formulario). Document.set_animations(name, animations) las cambia desde un script y Control.animations las lee. Para reproducir una desde un manejador, llama a form.<control>.play_animation(...) (ver arriba); para crear tus propios presets, usa pz.Animation y define_animation de la biblioteca (ver la lista de presets).

Animaciones con línea de tiempo

Para animaciones que mueven varios controles a la vez (una entrada, una transición entre estados), abre el panel Animation desde View → Animation (Ctrl+Shift+M). Edita clips: líneas de tiempo guardadas en el .pzform que se reproducen igual que con pz.AnimationPlayer en código.

Con el panel vacío se ven los tres pasos (añadir una pista, añadir keys, reproducirlo) y un botón Nueva animación.

Acción	Resultado
Añadir pista para …	Añade una pista para una propiedad del control seleccionado (opacidad, posición, escala, colores, tamaño…) o cualquiera de sus propiedades, como el texto de una etiqueta.
Clic en cualquier punto de la regla o las pistas, o arrastrar	Mueve el cabezal; el lienzo muestra el formulario en ese tiempo. Se pega a las keys cercanas.
Doble clic en una pista	Añade una key en ese tiempo con el valor que la pista tiene ahí.
Arrastrar una key	La mueve en el tiempo. Puedes agarrarla desde unos píxeles de distancia (el puntero se vuelve una mano) y se pega a las keys de las otras pistas, al principio y al final. Una etiqueta muestra su tiempo y su valor mientras la arrastras o pasas por encima.
Clic en una key	La selecciona: edita su tiempo, su valor y su curva debajo de las pistas.
Clic derecho en una key	La borra.
Pista Llamadas	Escribe el nombre de un manejador y pulsa Intro (o haz doble clic en la pista) para llamar a ese método del archivo de código del formulario en el cabezal. Arrastra una llamada para moverla; clic derecho para quitarla.
Duración, bucle, autoplay	Indican cuánto dura el clip, si se repite y si se reproduce al abrir el formulario.

Con el puntero sobre el panel, el teclado edita la línea de tiempo:

Tecla	Hace
Supr / Retroceso	Borra la key seleccionada.
Espacio	Reproduce o pausa la vista previa.
← / →	Mueve la key seleccionada (o el cabezal) 0,01 s; con Mayús, 0,1 s.
Inicio / Fin	Salta al principio o al final.

Los controles dentro de un contenedor animado siguen su opacidad, posición y desenfoque. Todos los cambios se pueden deshacer.

Cómo empieza un clip

Un clip se reproduce de una de estas dos formas, y la barra bajo las pistas dice cuál se aplica al clip que editas:

• ⚡ Reproducir al abrir el formulario (en la barra de herramientas) lo convierte en el clip de autoplay del formulario: “Se reproduce al abrir el formulario.”
• Si no, espera a un manejador. La barra muestra la línea a llamar, con un botón para copiarla:

def replay_click(form, event):
    form.animations.play("intro", restart=True)  # desde el principio, aunque esté sonando
    # también: form.animations.pause(), .resume(), .seek(0.5), .play_backwards("intro"), .queue("outro")

form.animations es el pz.AnimationPlayer del formulario: también pausa, salta a un tiempo, encola clips y avisa cuando uno termina. La sección Animación explica a fondo los clips, las pistas, las keys, las curvas y el reproductor.