# Capa

> Dibuja una capa encima de tu vista; al pulsar fuera se cierra. Componente de Pyzed para GUIs de escritorio en Python, con ejemplos y API.

Source: https://albakore.github.io/pyzed/es/library/layer/

:::tip[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](https://albakore.github.io/pyzed/es/library/#capas-flotantes) · [Referencia completa →](https://albakore.github.io/pyzed/es/reference/ui/#layer)

**Código:**

```python
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](https://albakore.github.io/pyzed/es/library/dialog-layer/) ya los centra sobre un fondo oscurecido.

## Uso

```python
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

:::note[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

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

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

```python
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.

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

```python
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](https://albakore.github.io/pyzed/es/guides/events/) y [Eventos de cada componente](https://albakore.github.io/pyzed/es/library/events/).

| 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](https://albakore.github.io/pyzed/es/guides/code-styles/).

**Imperativo:**

```python
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:**

```python
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:**

```python
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`

```python
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](#eventos)).

[Referencia completa →](https://albakore.github.io/pyzed/es/reference/ui/#layer)

## Relacionados

- [Modal](https://albakore.github.io/pyzed/es/library/modal/): Una superficie de diálogo con título, contenido y botones al pie.
- [Popover](https://albakore.github.io/pyzed/es/library/popover/): Contenido flotante en un punto: menús contextuales, selectores de color.
- [Capa de diálogo](https://albakore.github.io/pyzed/es/library/dialog-layer/): Centra un diálogo encima de tu vista con el fondo oscurecido.