Capa

En pocas palabras

Pone algo encima de la pantalla, como un buscador, y lo cierra si pulsas fuera.

Apila overlay encima de base. Al pulsar fuera de la capa se envía on_dismiss, y backdrop oscurece la vista de detrás. Con overlay=None devuelve base sin cambios, así que puede envolver siempre tu vista. align_x, align_y y offset colocan la capa (por defecto centrada arriba, como una paleta de comandos).

ui.layer · Categoría: Capas flotantes · Referencia completa →

Vista previa

Código

ui.layer(
    main_view(),
    ui.picker("", on_query, [(ui.PaletteItem("notes.py", on_open, icon="file-code"), []),
                             (ui.PaletteItem("README.md", on_open, icon="file-text"), [])],
              placeholder="Search files…", width=420),
    on_dismiss=on_close, backdrop="#00000055", offset=40,
)

Cuándo usarlo

• Para mostrar paletas, buscadores, modales y menús encima de todo.
• Para diálogos, Capa de diálogo ya los centra sobre un fondo oscurecido.

Uso

import pyzed as pz
from pyzed import ui

class App(pz.App):
    def __init__(self):
        self.finder_open = False

    def view(self):
        overlay = self.finder() if self.finder_open else None
        return ui.layer(self.main_view(), overlay,
                        on_dismiss=lambda: setattr(self, "finder_open", False))

Variantes

Sobre estas capturas

Cada captura la graba pyzed mismo, fuera de pantalla a 2x, en One Dark o One Light según el tema de este sitio, y recortada al componente para que se vea a su tamaño real. El puntero pasa por encima, pulsa o escribe en él; un componente que no reacciona al puntero recorre algunos temas. Con movimiento reducido ves el primer fotograma. Abre Código bajo una captura para ver el fragmento que la dibuja; los nombres libres como on_save son tus propios callbacks.

Posición

Arriba (por defecto)

Código

ui.layer(main_view(), ui.card(ui.label("Overlay"), width=200), on_dismiss=on_close)

align_y="center"

Código

ui.layer(main_view(), ui.card(ui.label("Overlay"), width=200), align_y="center",
         on_dismiss=on_close)

align_x="end", align_y="end"

Código

ui.layer(main_view(), ui.card(ui.label("Overlay"), width=200), align_x="end", align_y="end",
         offset=16, on_dismiss=on_close)

Fondo

Con overlay=None la capa devuelve tu vista sin cambios.

backdrop="#00000088"

Código

ui.layer(main_view(), ui.card(ui.label("Overlay"), width=200), backdrop="#00000088",
         align_y="center", on_dismiss=on_close)

overlay=None

Código

ui.layer(main_view(), None)

Eventos

Capa tiene 1 evento propios, en la tabla de abajo. Como todo widget, también tiene los 18 eventos comunes (click, double_click, right_click, mouse_enter, drag, key_down, resize…), que se conectan con .on(...): mira Eventos y Eventos de cada componente.

Evento	El handler recibe	Cuándo
on_dismiss	()	Mensaje o callable que se envía al cerrar.

El handler recibe es lo que Pyzed le pasa a tu función: () es nada. Cualquier handler también puede ser un mensaje (un valor que no se puede llamar), que va a update().

Manejar los eventos

Los mismos eventos escritos de tres formas. Imperativa: métodos de la app que cambian self. Declarativa: los handlers producen mensajes y un único update() decide. Funcional: una función pura dibuja un estado inmutable y pide cambios con set_state(...). Mira Imperativo, declarativo y funcional.

Imperativo

class App(pz.App):
    def __init__(self):
        self.finder_open = True

    def view(self):
        finder = ui.card(ui.muted("Search files…"), width=320)
        return ui.layer(main_view(), finder if self.finder_open else None,
                        on_dismiss=lambda: setattr(self, "finder_open", False))   # click outside

Declarativo

class App(pz.App):
    finder_open = True

    def update(self, message):
        match message:
            case "open finder":
                self.finder_open = True
            case "close finder":
                self.finder_open = False

    def view(self):
        overlay = ui.card(ui.muted("Search files…"), width=320) if self.finder_open else None
        return ui.layer(main_view(), overlay, on_dismiss="close finder")

Funcional

from dataclasses import dataclass


@dataclass(frozen=True)
class State:
    finder_open: bool = True


def view(state, set_state):
    overlay = ui.card(ui.muted("Search files…"), width=320) if state.finder_open else None
    return ui.layer(main_view(), overlay, on_dismiss=lambda: set_state(finder_open=False))

Propiedades y API

ui.layer

layer(
    base,
    overlay=None,
    *,
    on_dismiss=None,
    backdrop=None,
    align_x='center',
    align_y='start',
    offset=72,
)

Apila overlay sobre base. Hacer clic fuera envía on_dismiss. Con overlay=None devuelve base tal cual.

Propiedad	Por defecto	Descripción
base	obligatorio	La interfaz de debajo.
overlay	None	Lo que flota encima (modal, paleta, menú).
backdrop	None	Color del fondo que oscurece la interfaz.
align_x	"center"	Alineación horizontal: "start"/"left", "center", "end"/"right".
align_y	"start"	Alineación vertical: "start"/"top", "center", "end"/"bottom".
offset	72	Distancia desde arriba cuando align_y es "start".

Eventos: on_dismiss (eventos).

Referencia completa →

Relacionados

ModalUna superficie de diálogo con título, contenido y botones al pie.

PopoverContenido flotante en un punto: menús contextuales, selectores de color.

Capa de diálogoCentra un diálogo encima de tu vista con el fondo oscurecido.