# Grupo de alternancia

> Un control segmentado solo con iconos. 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/toggle-group/

:::tip[En pocas palabras]
Una fila de botones con iconos en la que solo uno puede estar activo, como elegir alinear a la izquierda, al centro o a la derecha.
:::

Una fila de botones de icono en la que hay exactamente uno seleccionado, como la alineación del texto en un editor. `options` son pares `(valor, icono)` y `on_select` recibe el valor elegido.

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

**Código:**

```python
pz.row([
    ui.toggle_group([("left", "align-left"), ("center", "align-center"), ("right", "align-right")],
                    "center", on_align),
    ui.toggle_group([("list", "list"), ("grid", "layout-grid")], "grid", on_layout),
], spacing=16)
```

## Cuándo usarlo

- Para un conjunto pequeño de modos excluyentes con iconos claros.
- Con etiquetas de texto, usa [Segmentado](https://albakore.github.io/pyzed/es/library/segmented/).

## Uso

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

class Toolbar(pz.App):
    def __init__(self):
        self.align = "left"

    def view(self):
        return ui.toggle_group(
            [("left", "align-left"), ("center", "align-center"), ("right", "align-right")],
            self.align, lambda value: setattr(self, "align", value),
        )
```

## 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.toggle_group([("list", "list"), ("grid", "layout-grid")], "list", on_select)
```

```python
ui.toggle_group([("left", "align-left"), ("center", "align-center"), ("right", "align-right")],
                "center", on_select)
```

```python
ui.toggle_group([("b", "bold"), ("i", "italic"), ("u", "underline"), ("s", "strikethrough")],
                "b", on_select)
```

### Selección

```python
ui.toggle_group([("left", "align-left"), ("center", "align-center"), ("right", "align-right")],
                "left", on_select)
```

```python
ui.toggle_group([("left", "align-left"), ("center", "align-center"), ("right", "align-right")],
                "right", on_select)
```

```python
ui.toggle_group([("left", "align-left"), ("center", "align-center"), ("right", "align-right")],
                None, on_select)
```

### Estados y eventos

Un tercer elemento en una opción añade un tooltip: `(valor, icono, tooltip)`.

```python
ui.toggle_group([("b", "bold"), ("i", "italic"), ("u", "underline")], {"b", "u"}, on_select, multiple=True)
```

```python
ui.toggle_group([("left", "align-left"), ("center", "align-center"), ("right", "align-right")],
                "left", on_select, disabled={"right"})
```

## Eventos

Grupo de alternancia 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` | `(value)` | 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 Toolbar(pz.App):
    def __init__(self):
        self.align = "left"

    def set_align(self, value):          # on_select gets the value of the pressed option
        self.align = value

    def view(self):
        return ui.toggle_group([("left", "align-left"), ("center", "align-center"), ("right", "align-right")],
                               self.align, self.set_align)
```

**Declarativo:**

```python
from dataclasses import dataclass

@dataclass
class Align:
    value: str

class Toolbar(pz.App):
    align = "left"

    def update(self, message):
        match message:
            case Align(value):
                self.align = value

    def view(self):
        return ui.toggle_group([("left", "align-left"), ("center", "align-center")],
                               self.align, Align)   # the class builds the message from the value
```

**Funcional:**

```python
from dataclasses import dataclass

@dataclass(frozen=True)
class State:
    align: str = "left"

def view(state, set_state):
    return ui.toggle_group([("left", "align-left"), ("center", "align-center"), ("right", "align-right")],
                           state.align, lambda value: set_state(align=value))
```

## Propiedades y API

### `ui.toggle_group`

```python
toggle_group(
    options,
    selected,
    on_select=None,
    *,
    disabled=False,
    multiple=False,
    theme=None,
)
```

Un control segmentado solo con iconos.

| Propiedad | Por defecto | Descripción |
| --- | --- | --- |
| `options` | *obligatorio* | `(valor, nombre_de_icono)` o `(valor, nombre_de_icono, tooltip)`. |
| `selected` | *obligatorio* | Valor actual (una colección con `multiple`). |
| `disabled` | `False` | `True`, o los valores a desactivar. |
| `multiple` | `False` | Cada botón activa o desactiva su valor. |
| `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/#toggle_group)

## Relacionados

- [Segmentado](https://albakore.github.io/pyzed/es/library/segmented/): Un grupo de botones de texto excluyentes.
- [Grupo de radios](https://albakore.github.io/pyzed/es/library/radio-group/): Opciones excluyentes como botones de radio.
- [Botón de icono](https://albakore.github.io/pyzed/es/library/icon-button/): Un botón cuadrado con solo un icono y un tooltip opcional.