# Visor de referencia

> Documentación integrada con buscador, como la de Godot: una lista de clases junto a la página abierta. Componente de Pyzed para GUIs en Python.

Source: https://albakore.github.io/pyzed/es/library/reference-browser/

:::tip[En pocas palabras]
Una ventana de ayuda con la documentación dentro de la app, con buscador y sin conexión.
:::

La referencia integrada: una lista de clases con buscador (la librería, tus componentes y las secciones que añadas con `reference.register`) junto a la página abierta, con atrás y adelante, enlaces internos y un botón Abrir en la web. Guarda un `pyzed.reference.Browser` en tu estado; el visor lo cambia. Los enlaces que salen de la referencia van a `on_open_url`. Ver [Referencia integrada](https://albakore.github.io/pyzed/es/editor/reference/).

`ui.reference_browser` · Categoría: [Código y herramientas](https://albakore.github.io/pyzed/es/library/#código-y-herramientas) · [Referencia completa →](https://albakore.github.io/pyzed/es/reference/ui/#reference_browser)

**Código:**

```python
from pyzed import reference

help = reference.Browser("pyzed.ui.button")
ui.reference_browser(help, on_open_url=open_in_browser, sidebar_width=230)
```

## Cuándo usarlo

- En una pestaña o ventana de Ayuda de una app hecha con Pyzed, para leer la API sin conexión.
- Con tus propias secciones `reference.Provider`, como la ayuda de tu app.

## Uso

```python
from pyzed import ui

from pyzed import reference

help = reference.Browser("pyzed.ui.button")
ui.reference_browser(help, on_open_url=open_in_browser, sidebar_width=230)
```

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

### Páginas

```python
from pyzed import reference

ui.reference_browser(reference.Browser("pyzed.ui.badge"), sidebar_width=200)
```

```python
from pyzed import reference

ui.reference_browser(reference.Browser("pyzed.row"), sidebar_width=200)
```

## Eventos

Visor de referencia 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_open_url` | `(url)` | Se llama con la URL de un enlace que sale de la referencia (ábrela en el navegador). |

**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
import webbrowser

from pyzed import reference

class Help(pz.App):
    def __init__(self):
        self.browser = reference.Browser("pyzed.ui.button")

    def view(self):
        return ui.reference_browser(self.browser, on_open_url=webbrowser.open)   # links to the web
```

**Declarativo:**

```python
from dataclasses import dataclass

from pyzed import reference

@dataclass
class OpenUrl:
    url: str

class Help(pz.App):
    browser = reference.Browser("pyzed.ui.button")

    def update(self, message):
        match message:
            case OpenUrl(url):
                print("open", url)

    def view(self):
        return ui.reference_browser(self.browser, on_open_url=OpenUrl)
```

**Funcional:**

```python
from dataclasses import dataclass

from pyzed import reference

BROWSER = reference.Browser("pyzed.ui.button")

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

def view(state, set_state):
    return ui.reference_browser(BROWSER, on_open_url=lambda url: set_state(last_url=url))
```

## Propiedades y API

### `ui.reference_browser`

```python
reference_browser(
    browser,
    *,
    on_open_url=None,
    sidebar_width=270,
    width='fill',
    height='fill',
    theme=None,
)
```

La referencia integrada, como la de Godot: una lista de clases con búsqueda junto a la página abierta.

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

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

## Relacionados

- [Atajos](https://albakore.github.io/pyzed/es/library/shortcuts/): Una lista de atajos agrupada y con búsqueda.
- [Acerca de](https://albakore.github.io/pyzed/es/library/about/): Una caja Acerca de con icono, versión, detalles y enlaces.
- [Markdown](https://albakore.github.io/pyzed/es/library/markdown/): Muestra Markdown con los colores del tema.