# Segmentado

> Un grupo de botones de texto excluyentes. 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/segmented/

:::tip[En pocas palabras]
Una fila de botones unidos en la que hay exactamente uno elegido, como Día / Semana / Mes en un calendario.
:::

Una fila de botones unidos en la que uno está seleccionado. `on_select` recibe la opción elegida.

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

**Código:**

```python
pz.column([
    ui.segmented(["Editor", "Terminal", "Both"], "Editor", on_select),
    ui.segmented(["Day", "Week", "Month"], "Week", on_select),
], spacing=14, align="center")
```

## Cuándo usarlo

- Para cambiar entre dos y cinco vistas o modos (Día / Semana / Mes).
- Solo con iconos, usa un [Grupo de alternancia](https://albakore.github.io/pyzed/es/library/toggle-group/).

## Uso

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

class Calendar(pz.App):
    def __init__(self):
        self.mode = "Week"

    def view(self):
        return ui.segmented(["Day", "Week", "Month"], self.mode, lambda m: setattr(self, "mode", m))
```

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

### Opciones

```python
ui.segmented(["Code", "Preview"], "Code", on_select)
```

```python
ui.segmented(["Day", "Week", "Month"], "Week", on_select)
```

```python
ui.segmented(["XS", "S", "M", "L", "XL"], "M", on_select)
```

### Selección

```python
ui.segmented(["Editor", "Terminal", "Both"], "Editor", on_select)
```

```python
ui.segmented(["Editor", "Terminal", "Both"], "Both", on_select)
```

### Estados y eventos

```python
ui.segmented([("list", "List", "list"), ("grid", "Grid", "layout-grid")], "grid", on_select)
```

```python
ui.segmented(["Day", "Week", "Month"], "Week", on_select, width=320)
```

```python
ui.segmented(["Day", "Week", "Month"], "Day", on_select, disabled={"Month"})
```

```python
ui.segmented(["Code", "Preview"], "Code", on_select, size="sm")
```

## Eventos

Segmentado 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_select` | `(item)` | Callable que recibe el elemento elegido. |

**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 Calendar(pz.App):
    def __init__(self):
        self.mode = "Week"

    def view(self):
        return pz.column([
            ui.segmented(["Day", "Week", "Month"], self.mode, lambda m: setattr(self, "mode", m)),
            ui.label(f"Showing a {self.mode.lower()}"),
        ], spacing=8, align="center")
```

**Declarativo:**

```python
from dataclasses import dataclass

@dataclass
class Mode:
    name: str

class Calendar(pz.App):
    mode = "Week"

    def update(self, message):
        match message:
            case Mode(name):
                self.mode = name

    def view(self):
        return ui.segmented(["Day", "Week", "Month"], self.mode, Mode)
```

**Funcional:**

```python
from dataclasses import dataclass

@dataclass(frozen=True)
class State:
    mode: str = "Week"

def view(state, set_state):
    return ui.segmented(["Day", "Week", "Month"], state.mode, lambda m: set_state(mode=m))
```

## Consejos

:::tip
Al pulsarlo o llegar con Tab tiene el foco del teclado: ←/→ eligen la opción anterior o la siguiente (saltando las desactivadas) e Inicio/Fin la primera y la última.
:::

## Propiedades y API

### `ui.segmented`

```python
segmented(
    options,
    selected,
    on_select=None,
    *,
    size='md',
    width=None,
    disabled=False,
    id=None,
    theme=None,
)
```

Un grupo de botones mutuamente excluyentes.

| Propiedad | Por defecto | Descripción |
| --- | --- | --- |
| `options` | *obligatorio* | Textos, `(valor, etiqueta)` o `(valor, etiqueta, icono)`. |
| `selected` | *obligatorio* | El valor activo. |
| `size` | `"md"` | `"sm"`, `"md"` o `"lg"`. |
| `width` | `None` | `"fill"` reparte el ancho entre los botones. |
| `disabled` | `False` | `True`, o los valores a desactivar. |
| `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_select` ([eventos](#eventos)).

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

## Relacionados

- [Grupo de alternancia](https://albakore.github.io/pyzed/es/library/toggle-group/): Un control segmentado solo con iconos.
- [Grupo de radios](https://albakore.github.io/pyzed/es/library/radio-group/): Opciones excluyentes como botones de radio.
- [Barra de pestañas](https://albakore.github.io/pyzed/es/library/tab-bar/): Pestañas de editor con iconos, puntos de cambios y botón de cerrar.