# Casilla

> Una casilla de verificación con etiqueta opcional. Un componente nativo de Pyzed para GUIs de escritorio en Python, con vista previa, ejemplos y su API.

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

:::tip[En pocas palabras]
Un cuadrado que marcas para decir que sí a una opción.
:::

Una casilla con los colores del tema. `on_toggle` recibe el nuevo `bool`; `label` añade un texto pulsable al lado.

`ui.checkbox` · Categoría: [Formularios](https://albakore.github.io/pyzed/es/library/#formularios) · [Referencia completa →](https://albakore.github.io/pyzed/es/reference/ui/#checkbox)

**Código:**

```python
pz.column([
    ui.checkbox(True, on_toggle, label="Format on save"),
    ui.checkbox(False, on_toggle, label="Show hidden files"),
    ui.checkbox(True, on_toggle, label="Use tabs"),
], spacing=10)
```

## Cuándo usarlo

- Para opciones que se aplican después (un formulario que envías) o una lista de opciones independientes.
- Para un ajuste que se aplica al momento, un [Interruptor](https://albakore.github.io/pyzed/es/library/switch/) se entiende mejor.

## Uso

```python
import pyzed as pz
from pyzed import ui

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

    def view(self):
        return ui.checkbox(self.accepted, lambda value: setattr(self, "accepted", value),
                           label="I accept the terms")
```

## 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.
:::

### Estado

```python
ui.checkbox(True, on_toggle, label="Format on save")
```

```python
ui.checkbox(False, on_toggle, label="Format on save")
```

```python
ui.checkbox(True, label="Managed by your admin")
```

### Contenido

```python
ui.checkbox(True, on_toggle)
```

```python
pz.column([ui.checkbox(True, on_toggle, label="Python"),
           ui.checkbox(False, on_toggle, label="Rust"),
           ui.checkbox(True, on_toggle, label="TypeScript")], spacing=8)
```

### Estados y eventos

```python
ui.checkbox(None, on_toggle, label="Some files")
```

```python
ui.checkbox(True, on_toggle, label="Locked", disabled=True)
```

```python
ui.checkbox(True, on_toggle, label="Small", size="sm")
```

```python
ui.checkbox(True, on_toggle, label="Large", size="lg")
```

### Widget base

El widget `pz.*` de debajo: sin tema, todos los colores y tamaños son tuyos.

```python
pz.checkbox(True, "pz.checkbox", on_toggle=on_toggle, accent="#c678dd", size=18)
```

## Eventos

Casilla 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 | De | El handler recibe | Cuándo |
| --- | --- | --- | --- |
| `on_toggle` | `ui.checkbox`, `pz.checkbox` | `(checked)` | Callable que recibe el nuevo `bool` (o mensaje que se envía). |

**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 Settings(pz.App):
    def __init__(self):
        self.options = {"Format on save": True, "Show hidden files": False}

    def toggle(self, name, checked):     # on_toggle gets True or False
        self.options[name] = checked

    def view(self):
        return pz.column([
            ui.checkbox(on, lambda checked, name=name: self.toggle(name, checked), label=name)
            for name, on in self.options.items()
        ], spacing=10)
```

**Declarativo:**

```python
from dataclasses import dataclass

@dataclass
class Toggle:
    name: str
    checked: bool

class Settings(pz.App):
    options = {"Format on save": True, "Show hidden files": False}

    def update(self, message):
        match message:
            case Toggle(name, checked):
                self.options = {**self.options, name: checked}

    def view(self):
        return pz.column([ui.checkbox(on, lambda c, n=name: Toggle(n, c), label=name)
                          for name, on in self.options.items()], spacing=10)
```

**Funcional:**

```python
from dataclasses import dataclass

@dataclass(frozen=True)
class State:
    format_on_save: bool = True
    hidden_files: bool = False

def view(state, set_state):
    return pz.column([
        ui.checkbox(state.format_on_save, lambda c: set_state(format_on_save=c), label="Format on save"),
        ui.checkbox(state.hidden_files, lambda c: set_state(hidden_files=c), label="Show hidden files"),
    ], spacing=10)
```

## Consejos

:::tip
Al pulsarla o llegar con Tab tiene el foco del teclado (un anillo aparece al usar las teclas): Espacio la marca o desmarca.
:::

## Propiedades y API

### `ui.checkbox`

```python
checkbox(
    checked,
    on_toggle=None,
    *,
    label=None,
    size='md',
    disabled=False,
    id=None,
    theme=None,
)
```

Una casilla de verificación. `checked=None` muestra el estado mixto (parte de un grupo marcada); al pulsarla se marca.

| Propiedad | Por defecto | Descripción |
| --- | --- | --- |
| `checked` | *obligatorio* | Estado actual. |
| `label` | `None` | Texto de la etiqueta. |
| `size` | `"md"` | `"sm"`, `"md"` o `"lg"`. |
| `disabled` | `False` | La atenúa e ignora los clics. |
| `id` | `None` | Identificador estable para enfocarlo o desplazarlo con un `Command`. |
| `theme` | `None` | Tema a usar en lugar del actual (`pyzed.theme.current()`). |

Eventos: `on_toggle` ([eventos](#eventos)).

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

### `pz.checkbox`

```python
checkbox(
    checked,
    label=None,
    *,
    on_toggle=None,
    size=None,
    text_size=None,
    accent=None,
    bg=None,
    border_color=None,
    check_color=None,
    color=None,
)
```

Una casilla de verificación.

| Propiedad | Por defecto | Descripción |
| --- | --- | --- |
| `checked` | *obligatorio* | Estado actual. |
| `label` | `None` | Texto de la etiqueta. |
| `size` | `None` | Tamaño de la casilla. |
| `text_size` | `None` | Tamaño del texto. |
| `accent` | `None` | Color de acento (parte activa). |
| `bg` | `None` | Color de fondo (`"#rrggbb[aa]"`, `(r, g, b[, a])` o `"transparent"`). |
| `border_color` | `None` | Color del borde. |
| `check_color` | `None` | Color de la marca. |
| `color` | `None` | Color del texto o del icono. |

Eventos: `on_toggle` ([eventos](#eventos)).

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

## Relacionados

- [Interruptor](https://albakore.github.io/pyzed/es/library/switch/): Un interruptor para ajustes que se aplican al momento.
- [Grupo de radios](https://albakore.github.io/pyzed/es/library/radio-group/): Opciones excluyentes como botones de radio.
- [Campo de formulario](https://albakore.github.io/pyzed/es/library/field/): Una fila de ajustes: título y descripción a la izquierda, control a la derecha.