# pdfviewer — `u_pbt_pdfviewer` #

← Riferimento dei componenti · Sommario della guida

> Visualizzatore PDF integrato: mostra un documento locale o pubblicato sul web, direttamente nella Sua finestra, con paginazione, zoom e stampa.

> ▶ Vederlo dal vivo — Applicazione dimostrativa, riquadro PDF viewer: l'anteprima, il codice che lo produce e questa pagina, affiancati.

## In breve #

Userobject | `u_pbt_pdfviewer`
Classe degli item | — (componente senza item)
Serve per | Visualizzare una fattura, un ordine d'acquisto, un contratto o un manuale senza avviare un'applicazione esterna
Opzioni opt-in | —

Il componente sostituisce il classico « salvare il PDF in un file temporaneo e poi chiamare `ShellExecute` »: il documento resta all'interno della Sua applicazione, l'utente non lascia mai la schermata corrente.

## Avvio rapido #

    // event open della finestra : visualizzare un documento presente su disco
    uo_pdf.is_source = "C:\factures\FA-2026-0142.pdf"

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

Tutto qui: impostare `is_source` è sufficiente per caricare e visualizzare il documento.

## Proprietà #

Proprietà | Tipo | Predefinito | Ruolo
--- | --- | --- | ---
`is_source` | string | `""` | Documento da visualizzare: un percorso di file su disco (assoluto o relativo all'applicazione) oppure un indirizzo web (`https://…`). Impostare il valore avvia il caricamento; impostare `""` svuota il visualizzatore
`ii_page` | integer | `0` | Pagina visualizzata, contata a partire da 1 (`0` = la prima pagina del documento). Caricare un altro documento la azzera: conservare quella del precedente farebbe atterrare il lettore in mezzo a un file appena aperto. Sola scrittura: rileggendola si ottiene l'ultima pagina richiesta, non quella a schermo. Il lettore è quello del motore web e non riferisce nulla.
`ii_zoom` | integer | `0` | Zoom in percentuale (`0` = lasciato al lettore). Impostare uno zoom annulla `is_fit`, che lo contraddice. Sola scrittura, come `ii_page`: se l'utente ingrandisce con la barra del lettore, questa proprietà non segue.
`is_fit` | string | `""` | Adattamento: `FIT_PAGE`, `FIT_WIDTH`, `FIT_HEIGHT`, oppure `""` per nessuno. Annulla `ii_zoom`
`ib_viewer_toolbar` | boolean | `true` | Mostra la barra propria del lettore (numero di pagina, zoom, stampa, download). La nasconda quando la sua finestra porta essa stessa questi comandi
`is_theme_style` | string | `fluent` | Stile visivo del componente (costanti `THEME_STYLE_*`)
`is_theme_mode` | string | `light` | Variante chiara o scura (costanti `THEME_MODE_*`)
`il_theme_accent` | long | `-1` | Colore d'accento di questo componente (`-1` = accento del tema)

## Metodi #

Metodo | Ruolo
--- | ---
`of_refresh ( )` | Ricarica il documento corrente — per esempio dopo la rigenerazione del file su disco
`of_reset ( )` | Svuota il visualizzatore e riporta tutte le proprietà al valore predefinito
`of_set_redraw (boolean)` | Raggruppa una raffica di modifiche in un unico rendering
`of_save_as_png (string)` · `of_save_as_jpg (string)` | Esporta il rendering come immagine

## Event #

Event | Attivato quando
--- | ---
`ue_load_completed (string as_source)` | Il documento ha terminato il caricamento; `as_source` ricorda che cosa è stato visualizzato
`ue_ready ( )` | Il componente ha terminato il caricamento; tutto ciò che è stato inviato prima è stato riprodotto
`ue_runtime_missing ( )` | Il runtime WebView2 è assente: il componente resta vuoto
`ue_bg_color (long al_color)` | Il componente ha calcolato il colore di sfondo del proprio tema; l'userobject lo ha già adottato (`backcolor`)

## Che cosa può fare l'utente, senza una riga di codice #

Il visualizzatore mostra la sua barra degli strumenti integrata sopra il documento. Non c'è nulla da programmare: viene fornita e localizzata dal sistema.

Azione | Come
--- | ---
Paginazione | Rotellina e barra di scorrimento, oppure digitando direttamente il numero di pagina nel contatore `n / totale`
Zoom | Pulsanti `+` / `−`, `Ctrl` + rotellina, adatta alla pagina o alla larghezza
Ricerca | `Ctrl+F` nel testo del documento
Stampa | Pulsante stampante della barra degli strumenti, oppure `Ctrl+P`
Salvataggio | Pulsante di download, per salvare una copia del documento
Rotazione | Rotazione delle pagine dal menu della barra degli strumenti

## Esempi #

### Aprire un documento locale #

    // Percorso assoluto, oppure relativo alla directory dell'applicazione
    uo_pdf.is_source = "doc\conditions-generales.pdf"

### Aprire un documento pubblicato sul web #

    // Un indirizzo web si carica esattamente come un file locale
    uo_pdf.is_source = "https://www.monsite.fr/tarifs/catalogue-2026.pdf"

Ovviamente è necessaria una connessione a internet; il caricamento è asincrono, `ue_load_completed` Le segnala la fine.

### Visualizzare il PDF appena prodotto da una DataWindow #

    string ls_fichier

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

    // La DataWindow produce il file...
    dw_etat.SaveAs(ls_fichier, PDF!, false)

    // ...e il visualizzatore lo mostra immediatamente
    uo_pdf.is_source = ls_fichier

### Aggiornare dopo la rigenerazione del file #

    // Il file e stato riscritto nella stessa posizione : ricaricare senza toccare is_source
    uo_pdf.of_refresh()

### Concatenare più documenti nello stesso visualizzatore #

    // event ue_row_changed di dw_liste : visualizzare l'allegato della riga corrente
    string ls_pdf

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

    if ls_pdf = "" then
        uo_pdf.of_reset()          // nessun allegato : visualizzatore vuoto
    else
        uo_pdf.is_source = ls_pdf
    end if

### Seguire la fine del caricamento #

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

### Anteprima in una scheda, accanto all'inserimento dati #

    // event open : il visualizzatore occupa una pagina della scheda, l'inserimento dati l'altra
    uo_tab.of_add_page("saisie",  "Inserimento",   uo_page_saisie)
    uo_tab.of_add_page("apercu",  "Anteprima",   uo_page_apercu)

    // Il visualizzatore e collocato in uo_page_apercu come qualsiasi altro controllo
    uo_pdf.is_source = is_document_courant

Il componente si ospita senza particolari precauzioni in un tab o in un pannello dockcontainer.

### Verificare il file prima di visualizzarlo #

    string ls_chemin

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

    if not FileExists(ls_chemin) then
        // Niente da mostrare : si svuota il visualizzatore invece di lasciare il documento precedente
        uo_pdf.of_reset()
        uo_statut.of_item("main").is_text = "Fattura non trovata"
        return
    end if

    uo_pdf.is_source = ls_chemin

## Formati e percorsi accettati #

Forma di `is_source` | Esempio | Nota
--- | --- | ---
Percorso assoluto | `"C:\docs\contrat.pdf"` | Il più affidabile
Percorso relativo | `"doc\notice.pdf"` | Relativo alla directory dell'applicazione
Percorso di rete | `"\\serveur\partage\bon.pdf"` | L'utente deve avere i diritti di lettura
Indirizzo web | `"https://…/catalogue.pdf"` | Caricamento asincrono, connessione necessaria
Vuoto | `""` | Svuota il visualizzatore

Questo componente supporta soltanto il PDF: per un'immagine, usi picture; per una pagina HTML, webbrowser.

## Buone pratiche #

- Verifichi l'esistenza del file prima di assegnare `is_source`: un percorso non valido lascia semplicemente il visualizzatore vuoto, senza errori bloccanti.
- Chiami `of_reset()` quando non deve più essere visualizzato alcun documento (cambio di riga senza allegato): altrimenti il documento precedente resta visibile.
- Preferisca `of_refresh()` a una riassegnazione di `is_source` per ricaricare lo stesso documento: è più rapido e la posizione di lettura viene ripristinata correttamente.
- Preveda un indicatore di attesa per i documenti remoti o voluminosi, e lo nasconda su `ue_load_completed`.
- Dia al componente una superficie confortevole (almeno metà della finestra): la barra degli strumenti integrata e il documento hanno bisogno di spazio per restare leggibili.
- Per visualizzare una pagina web anziché un PDF, usi webbrowser; per un'immagine, picture.

← Riferimento dei componenti · Sommario della guida