# pdfviewer — `u_pbt_pdfviewer` #

← Referencia de componentes · Índice de la guía

> Visor de PDF integrado: muestra un documento local o publicado en la web, directamente dentro de su ventana, con paginación, zoom e impresión.

> ▶ Verlo en vivo — Aplicación de demostración, mosaico PDF viewer: la vista previa, el código que lo genera y esta página, uno al lado del otro.

## De un vistazo #

Userobject | `u_pbt_pdfviewer`
Clase de items | — (componente sin items)
Sirve para | Mostrar una factura, un pedido, un contrato o un manual sin abrir una aplicación externa
Opciones opt-in | —

El componente sustituye al clásico «guardar el PDF en un fichero temporal y después llamar a `ShellExecute`»: el documento permanece dentro de su aplicación y el usuario nunca abandona la pantalla en curso.

## Inicio rápido #

    // event open de la ventana : mostrar un documento presente en el disco
    uo_pdf.is_source = "C:\factures\FA-2026-0142.pdf"

    // event ue_load_completed de uo_pdf : (string as_source)
    uo_statut.of_item("main").is_text = "Documento mostrado"

Eso es todo: basta con asignar `is_source` para cargar y mostrar el documento.

## Propiedades #

Propiedad | Tipo | Predeterminado | Función
--- | --- | --- | ---
`is_source` | string | `""` | Documento que se debe mostrar: una ruta de fichero en el disco (absoluta o relativa a la aplicación) o una dirección web (`https://…`). Asignar el valor desencadena la carga; asignar `""` vacía el visor
`ii_page` | integer | `0` | Página mostrada, contada a partir de 1 (`0` = la primera página del documento). Cargar otro documento la reinicia: conservar la del anterior haría aterrizar al lector en medio de un archivo que acaba de abrir. Solo escritura: al releerla se obtiene la última página solicitada, no la mostrada. El lector es el del motor web y no informa de nada.
`ii_zoom` | integer | `0` | Zoom en porcentaje (`0` = a cargo del visor). Fijar un zoom anula `is_fit`, que lo contradice. Solo escritura, como `ii_page`: si el usuario amplía con la barra del lector, esta propiedad no lo sigue.
`is_fit` | string | `""` | Ajuste: `FIT_PAGE`, `FIT_WIDTH`, `FIT_HEIGHT`, o `""` para ninguno. Anula `ii_zoom`
`ib_viewer_toolbar` | boolean | `true` | Muestra la barra propia del visor (número de página, zoom, impresión, descarga). Ocúltela cuando su ventana lleve esos comandos ella misma
`is_theme_style` | string | `fluent` | Estilo visual del componente (constantes `THEME_STYLE_*`)
`is_theme_mode` | string | `light` | Variante clara u oscura (constantes `THEME_MODE_*`)
`il_theme_accent` | long | `-1` | Color de acento de este componente (`-1` = acento del tema)

## Métodos #

Método | Función
--- | ---
`of_refresh ( )` | Vuelve a cargar el documento actual — por ejemplo, después de regenerar el fichero en el disco
`of_reset ( )` | Vacía el visor y restablece todas las propiedades a su valor predeterminado
`of_set_redraw (boolean)` | Agrupa una ráfaga de modificaciones en una sola representación
`of_save_as_png (string)` · `of_save_as_jpg (string)` | Exporta la representación como imagen

## Eventos #

Evento | Se activa cuando
--- | ---
`ue_load_completed (string as_source)` | El documento ha terminado de cargarse; `as_source` recuerda lo que se ha mostrado
`ue_ready ( )` | El componente ha terminado de cargarse; todo lo enviado antes se ha reproducido
`ue_runtime_missing ( )` | El runtime WebView2 está ausente: el componente permanece vacío
`ue_bg_color (long al_color)` | El componente ha calculado el color de fondo de su tema; el userobject ya lo ha adoptado (`backcolor`)

## Lo que el usuario puede hacer, sin una sola línea de código #

El visor muestra su barra de herramientas integrada encima del documento. Usted no tiene que programar nada: la proporciona y la traduce el sistema.

Acción | Cómo
--- | ---
Paginación | Rueda del ratón y barra de desplazamiento, o escritura directa del número de página en el contador `n / total`
Zoom | Botones `+` / `−`, `Ctrl` + rueda, ajuste a la página o al ancho
Búsqueda | `Ctrl+F` en el texto del documento
Impresión | Botón de impresora de la barra de herramientas, o `Ctrl+P`
Guardado | Botón de descarga, para guardar una copia del documento
Rotación | Rotación de las páginas desde el menú de la barra de herramientas

## Ejemplos #

### Abrir un documento local #

    // Ruta absoluta, o relativa al directorio de la aplicacion
    uo_pdf.is_source = "doc\conditions-generales.pdf"

### Abrir un documento publicado en la web #

    // Una direccion web se carga exactamente como un fichero local
    uo_pdf.is_source = "https://www.monsite.fr/tarifs/catalogue-2026.pdf"

Evidentemente se necesita una conexión a internet; la carga es asíncrona y `ue_load_completed` le indica el final.

### Mostrar el PDF que acaba de producir una DataWindow #

    string ls_fichier

    ls_fichier = "C:\temp\etat_" + String(Today(), "yyyymmdd") + ".pdf"

    // La DataWindow produce el fichero...
    dw_etat.SaveAs(ls_fichier, PDF!, false)

    // ...y el visor lo muestra inmediatamente
    uo_pdf.is_source = ls_fichier

### Actualizar después de regenerar el fichero #

    // El fichero se ha reescrito en la misma ubicacion : recargar sin modificar is_source
    uo_pdf.of_refresh()

### Encadenar varios documentos en el mismo visor #

    // event ue_row_changed de dw_liste : mostrar el adjunto de la fila actual
    string ls_pdf

    ls_pdf = dw_liste.GetItemString(dw_liste.GetRow(), "chemin_pdf")

    if ls_pdf = "" then
        uo_pdf.of_reset()          // ningun adjunto : visor vacio
    else
        uo_pdf.is_source = ls_pdf
    end if

### Seguir el final de la carga #

    // event ue_load_completed de uo_pdf : (string as_source)
    uo_attente.Hide()
    uo_imprimer.ib_enabled = true

### Vista previa en una pestaña, junto a la entrada de datos #

    // event open : el visor ocupa una pagina de pestana, la entrada de datos la otra
    uo_tab.of_add_page("saisie",  "Entrada",   uo_page_saisie)
    uo_tab.of_add_page("apercu",  "Vista previa",   uo_page_apercu)

    // El visor se coloca en uo_page_apercu como cualquier otro control
    uo_pdf.is_source = is_document_courant

El componente se aloja sin ninguna precaución especial dentro de un tab o de un panel dockcontainer.

### Comprobar el fichero antes de mostrarlo #

    string ls_chemin

    ls_chemin = "C:\factures\" + is_numero + ".pdf"

    if not FileExists(ls_chemin) then
        // Nada que mostrar : vaciamos el visor en lugar de dejar el documento anterior
        uo_pdf.of_reset()
        uo_statut.of_item("main").is_text = "Factura no encontrada"
        return
    end if

    uo_pdf.is_source = ls_chemin

## Formatos y rutas admitidos #

Forma de `is_source` | Ejemplo | Observación
--- | --- | ---
Ruta absoluta | `"C:\docs\contrat.pdf"` | La más fiable
Ruta relativa | `"doc\notice.pdf"` | Relativa al directorio de la aplicación
Ruta de red | `"\\serveur\partage\bon.pdf"` | El usuario debe tener permisos de lectura
Dirección web | `"https://…/catalogue.pdf"` | Carga asíncrona, se necesita conexión
Vacío | `""` | Vacía el visor

Este componente solo admite PDF: para una imagen, utilice picture; para una página HTML, webbrowser.

## Buenas prácticas #

- Compruebe que el fichero existe antes de asignar `is_source`: una ruta no válida simplemente deja el visor vacío, sin ningún error bloqueante.
- Llame a `of_reset()` cuando ya no deba mostrarse ningún documento (cambio de fila sin adjunto): de lo contrario, el documento anterior permanece visible.
- Prefiera `of_refresh()` a una reasignación de `is_source` para volver a cargar el mismo documento: es más rápido y la posición de lectura se restablece correctamente.
- Prevea un indicador de espera para los documentos remotos o voluminosos, y ocúltelo en `ue_load_completed`.
- Dé al componente una superficie cómoda (al menos la mitad de la ventana): la barra de herramientas integrada y el documento necesitan espacio para seguir siendo legibles.
- Para mostrar una página web en lugar de un PDF, utilice webbrowser; para una imagen, picture.

← Referencia de componentes · Índice de la guía