# pdfviewer — `u_pbt_pdfviewer` #

← Référence des composants · Sommaire du guide

> Visionneuse PDF intégrée : affiche un document local ou publié sur le web, directement dans votre fenêtre, avec pagination, zoom et impression.

> ▶ Le voir en vrai — Application de démonstration, tuile PDF viewer : l'aperçu, le code qui le produit et cette page, côte à côte.

## En bref #

Userobject | `u_pbt_pdfviewer`
Classe d'items | — (composant sans items)
Sert à | Afficher une facture, un bon de commande, un contrat ou une notice sans lancer d'application externe
Options opt-in | —

Le composant remplace le classique « enregistrer le PDF dans un fichier temporaire puis appeler `ShellExecute` » : le document reste dans votre application, l'utilisateur ne quitte jamais l'écran en cours.

## Démarrage rapide #

    // event open de la fenetre : afficher un document present sur le disque
    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 = "Document affiche"

C'est tout : poser `is_source` suffit à charger et afficher le document.

## Propriétés #

Propriété | Type | Défaut | Rôle
--- | --- | --- | ---
`is_source` | string | `""` | Document à afficher : un chemin de fichier sur le disque (absolu ou relatif à l'application) ou une adresse web (`https://…`). Poser la valeur déclenche le chargement ; poser `""` vide la visionneuse
`ii_page` | integer | `0` | Page affichée, comptée à partir de 1 (`0` = la première page du document). Charger un autre document la remet à zéro : garder la page du précédent ferait atterrir le lecteur au milieu d'un fichier qu'il vient d'ouvrir. En écriture seule : la relire donne la dernière page demandée, pas celle affichée. Le lecteur est celui du moteur web, il ne rend compte de rien.
`ii_zoom` | integer | `0` | Zoom en pourcentage (`0` = laissé au lecteur). Poser un zoom annule `is_fit`, qui le contredit. En écriture seule, comme `ii_page` : si l'utilisateur zoome avec la barre du lecteur, cette propriété ne suit pas.
`is_fit` | string | `""` | Ajustement : `FIT_PAGE`, `FIT_WIDTH`, `FIT_HEIGHT`, ou `""` pour aucun. Annule `ii_zoom`
`ib_viewer_toolbar` | boolean | `true` | Affiche la barre du lecteur (numéro de page, zoom, impression, téléchargement). Masquez-la quand votre fenêtre porte elle-même ces commandes
`is_theme_style` | string | `fluent` | Style visuel du composant (constantes `THEME_STYLE_*`)
`is_theme_mode` | string | `light` | Variante claire ou sombre (constantes `THEME_MODE_*`)
`il_theme_accent` | long | `-1` | Couleur d'accent de ce composant (`-1` = accent du thème)

## Méthodes #

Méthode | Rôle
--- | ---
`of_refresh ( )` | Recharge le document courant — par exemple après régénération du fichier sur le disque
`of_reset ( )` | Vide la visionneuse et remet toutes les propriétés à leur défaut
`of_set_redraw (boolean)` | Regroupe une rafale de modifications en un seul rendu
`of_save_as_png (string)` · `of_save_as_jpg (string)` | Exporte le rendu en image

## Événements #

Événement | Déclenché quand
--- | ---
`ue_load_completed (string as_source)` | Le document a fini de se charger ; `as_source` rappelle ce qui a été affiché
`ue_ready ( )` | Le composant a fini de charger ; tout ce qui a été envoyé avant a été rejoué
`ue_runtime_missing ( )` | Le runtime WebView2 est absent : le composant reste vide
`ue_bg_color (long al_color)` | Le composant a calculé sa couleur de fond de thème ; l'userobject l'a déjà adoptée (`backcolor`)

## Ce que l'utilisateur peut faire, sans une ligne de code #

La visionneuse affiche sa barre d'outils intégrée au-dessus du document. Vous n'avez rien à programmer : elle est fournie et localisée par le système.

Action | Comment
--- | ---
Pagination | Molette et barre de défilement, ou saisie directe du numéro de page dans le compteur `n / total`
Zoom | Boutons `+` / `−`, `Ctrl` + molette, ajustement à la page ou à la largeur
Recherche | `Ctrl+F` dans le texte du document
Impression | Bouton imprimante de la barre d'outils, ou `Ctrl+P`
Enregistrement | Bouton de téléchargement, pour sauver une copie du document
Rotation | Rotation des pages depuis le menu de la barre d'outils

## Exemples #

### Ouvrir un document local #

    // Chemin absolu, ou relatif au repertoire de l'application
    uo_pdf.is_source = "doc\conditions-generales.pdf"

### Ouvrir un document publié sur le web #

    // Une adresse web se charge exactement comme un fichier local
    uo_pdf.is_source = "https://www.monsite.fr/tarifs/catalogue-2026.pdf"

Une connexion internet est évidemment nécessaire ; le chargement est asynchrone, `ue_load_completed` vous signale la fin.

### Afficher le PDF que vient de produire une DataWindow #

    string ls_fichier

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

    // La DataWindow produit le fichier...
    dw_etat.SaveAs(ls_fichier, PDF!, false)

    // ...et la visionneuse l'affiche immediatement
    uo_pdf.is_source = ls_fichier

### Rafraîchir après régénération du fichier #

    // Le fichier a ete reecrit au meme emplacement : recharger sans retoucher is_source
    uo_pdf.of_refresh()

### Enchaîner plusieurs documents dans la même visionneuse #

    // event ue_row_changed de dw_liste : afficher la piece jointe de la ligne courante
    string ls_pdf

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

    if ls_pdf = "" then
        uo_pdf.of_reset()          // aucune piece : visionneuse vide
    else
        uo_pdf.is_source = ls_pdf
    end if

### Suivre la fin du chargement #

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

### Aperçu dans un onglet, à côté de la saisie #

    // event open : la visionneuse occupe une page d'onglet, la saisie l'autre
    uo_tab.of_add_page("saisie",  "Saisie",   uo_page_saisie)
    uo_tab.of_add_page("apercu",  "Apercu",   uo_page_apercu)

    // La visionneuse est posee dans uo_page_apercu comme n'importe quel controle
    uo_pdf.is_source = is_document_courant

Le composant s'héberge sans précaution particulière dans un tab ou un panneau dockcontainer.

### Vérifier le fichier avant de l'afficher #

    string ls_chemin

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

    if not FileExists(ls_chemin) then
        // Rien a montrer : on vide la visionneuse plutot que de laisser l'ancien document
        uo_pdf.of_reset()
        uo_statut.of_item("main").is_text = "Facture introuvable"
        return
    end if

    uo_pdf.is_source = ls_chemin

## Formats et chemins acceptés #

Forme de `is_source` | Exemple | Remarque
--- | --- | ---
Chemin absolu | `"C:\docs\contrat.pdf"` | Le plus fiable
Chemin relatif | `"doc\notice.pdf"` | Relatif au répertoire de l'application
Chemin réseau | `"\\serveur\partage\bon.pdf"` | L'utilisateur doit avoir les droits de lecture
Adresse web | `"https://…/catalogue.pdf"` | Chargement asynchrone, connexion requise
Vide | `""` | Vide la visionneuse

Seul le PDF est pris en charge par ce composant : pour une image, utilisez picture ; pour une page HTML, webbrowser.

## Bonnes pratiques #

- Vérifiez l'existence du fichier avant d'affecter `is_source` : un chemin invalide laisse simplement la visionneuse vide, sans erreur bloquante.
- Appelez `of_reset()` quand plus aucun document ne doit être affiché (changement de ligne sans pièce jointe) : sinon le document précédent reste visible.
- Préférez `of_refresh()` à une réaffectation de `is_source` pour recharger le même document : c'est plus rapide et la position de lecture est rétablie proprement.
- Prévoyez un indicateur d'attente pour les documents distants ou volumineux, et masquez-le sur `ue_load_completed`.
- Donnez au composant une surface confortable (au moins la moitié de la fenêtre) : la barre d'outils intégrée et le document ont besoin de place pour rester lisibles.
- Pour afficher une page web plutôt qu'un PDF, utilisez webbrowser ; pour une image, picture.

← Référence des composants · Sommaire du guide