# pdfviewer — `u_pbt_pdfviewer` #

← Referência dos componentes · Índice do guia

> Visualizador de PDF integrado: apresenta um documento local ou publicado na web, diretamente na janela da aplicação, com paginação, zoom e impressão.

> ▶ Ver ao vivo — Aplicação de demonstração, mosaico PDF viewer: a pré-visualização, o código que o produz e esta página, lado a lado.

## Em resumo #

Userobject | `u_pbt_pdfviewer`
Classe de items | — (componente sem items)
Serve para | Apresentar uma fatura, uma nota de encomenda, um contrato ou um manual sem iniciar qualquer aplicação externa
Opções opt-in | —

O componente substitui o clássico «gravar o PDF num ficheiro temporário e depois chamar `ShellExecute`»: o documento permanece dentro da aplicação e o utilizador nunca sai do ecrã em curso.

## Início rápido #

    // event open da janela : apresentar um documento presente no 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 apresentado"

É tudo: basta definir `is_source` para carregar e apresentar o documento.

## Propriedades #

Propriedade | Tipo | Predefinição | Função
--- | --- | --- | ---
`is_source` | string | `""` | Documento a apresentar: um caminho de ficheiro no disco (absoluto ou relativo à aplicação) ou um endereço web (`https://…`). Definir o valor desencadeia o carregamento; definir `""` esvazia o visualizador
`ii_page` | integer | `0` | Página apresentada, contada a partir de 1 (`0` = a primeira página do documento). Carregar outro documento repõe-na: conservar a do anterior faria o leitor aterrar a meio de um ficheiro que acabou de abrir. Apenas escrita: ao relê-la obtém a última página pedida, não a apresentada. O leitor é o do motor web e não comunica nada.
`ii_zoom` | integer | `0` | Zoom em percentagem (`0` = deixado ao leitor). Definir um zoom anula `is_fit`, que o contradiz. Apenas escrita, tal como `ii_page`: se o utilizador ampliar com a barra do leitor, esta propriedade não acompanha.
`is_fit` | string | `""` | Ajuste: `FIT_PAGE`, `FIT_WIDTH`, `FIT_HEIGHT`, ou `""` para nenhum. Anula `ii_zoom`
`ib_viewer_toolbar` | boolean | `true` | Apresenta a barra do próprio leitor (número de página, zoom, impressão, transferência). Oculte-a quando a sua janela tiver esses comandos
`is_theme_style` | string | `fluent` | Estilo visual do componente (constantes `THEME_STYLE_*`)
`is_theme_mode` | string | `light` | Variante clara ou escura (constantes `THEME_MODE_*`)
`il_theme_accent` | long | `-1` | Cor de destaque deste componente (`-1` = destaque do tema)

## Métodos #

Método | Função
--- | ---
`of_refresh ( )` | Recarrega o documento atual — por exemplo após a regeneração do ficheiro no disco
`of_reset ( )` | Esvazia o visualizador e repõe todas as propriedades nos respetivos valores predefinidos
`of_set_redraw (boolean)` | Agrupa uma sequência de modificações numa única representação
`of_save_as_png (string)` · `of_save_as_jpg (string)` | Exporta a representação como imagem

## Eventos #

Evento | Acionado quando
--- | ---
`ue_load_completed (string as_source)` | O documento terminou de carregar; `as_source` recorda o que foi apresentado
`ue_ready ( )` | O componente terminou o carregamento; tudo o que foi enviado antes foi reproduzido
`ue_runtime_missing ( )` | O runtime WebView2 está ausente: o componente permanece vazio
`ue_bg_color (long al_color)` | O componente calculou a cor de fundo do respetivo tema; o userobject já a adotou (`backcolor`)

## O que o utilizador pode fazer, sem uma linha de código #

O visualizador apresenta a sua barra de ferramentas integrada por cima do documento. Não é necessário programar nada: ela é fornecida e localizada pelo sistema.

Ação | Como
--- | ---
Paginação | Roda do rato e barra de deslocamento, ou introdução direta do número de página no contador `n / total`
Zoom | Botões `+` / `−`, `Ctrl` + roda do rato, ajuste à página ou à largura
Pesquisa | `Ctrl+F` no texto do documento
Impressão | Botão de impressora da barra de ferramentas, ou `Ctrl+P`
Gravação | Botão de transferência, para guardar uma cópia do documento
Rotação | Rotação das páginas a partir do menu da barra de ferramentas

## Exemplos #

### Abrir um documento local #

    // Caminho absoluto, ou relativo ao diretorio da aplicacao
    uo_pdf.is_source = "doc\conditions-generales.pdf"

### Abrir um documento publicado na web #

    // Um endereco web carrega-se exatamente como um ficheiro local
    uo_pdf.is_source = "https://www.monsite.fr/tarifs/catalogue-2026.pdf"

É evidentemente necessária uma ligação à internet; o carregamento é assíncrono e `ue_load_completed` assinala o fim.

### Apresentar o PDF acabado de produzir por uma DataWindow #

    string ls_fichier

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

    // A DataWindow produz o ficheiro...
    dw_etat.SaveAs(ls_fichier, PDF!, false)

    // ...e o visualizador apresenta-o imediatamente
    uo_pdf.is_source = ls_fichier

### Atualizar após a regeneração do ficheiro #

    // O ficheiro foi reescrito no mesmo local : recarregar sem alterar is_source
    uo_pdf.of_refresh()

### Encadear vários documentos no mesmo visualizador #

    // event ue_row_changed de dw_liste : apresentar o anexo da linha atual
    string ls_pdf

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

    if ls_pdf = "" then
        uo_pdf.of_reset()          // nenhum anexo : visualizador vazio
    else
        uo_pdf.is_source = ls_pdf
    end if

### Acompanhar o fim do carregamento #

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

### Pré-visualização num separador, ao lado da introdução de dados #

    // event open : o visualizador ocupa uma pagina de separador, a introducao de dados a outra
    uo_tab.of_add_page("saisie",  "Introducao", uo_page_saisie)
    uo_tab.of_add_page("apercu",  "Previsao",   uo_page_apercu)

    // O visualizador esta colocado em uo_page_apercu como qualquer outro controlo
    uo_pdf.is_source = is_document_courant

O componente aloja-se sem qualquer precaução especial num tab ou num painel dockcontainer.

### Verificar o ficheiro antes de o apresentar #

    string ls_chemin

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

    if not FileExists(ls_chemin) then
        // Nada a mostrar : esvazia-se o visualizador em vez de deixar o documento anterior
        uo_pdf.of_reset()
        uo_statut.of_item("main").is_text = "Fatura nao encontrada"
        return
    end if

    uo_pdf.is_source = ls_chemin

## Formatos e caminhos aceites #

Forma de `is_source` | Exemplo | Observação
--- | --- | ---
Caminho absoluto | `"C:\docs\contrat.pdf"` | O mais fiável
Caminho relativo | `"doc\notice.pdf"` | Relativo ao diretório da aplicação
Caminho de rede | `"\\serveur\partage\bon.pdf"` | O utilizador tem de possuir direitos de leitura
Endereço web | `"https://…/catalogue.pdf"` | Carregamento assíncrono, ligação necessária
Vazio | `""` | Esvazia o visualizador

Apenas o PDF é suportado por este componente: para uma imagem, deve utilizar-se picture; para uma página HTML, webbrowser.

## Boas práticas #

- Verificar a existência do ficheiro antes de atribuir `is_source`: um caminho inválido deixa simplesmente o visualizador vazio, sem erro bloqueante.
- Chamar `of_reset()` quando já nenhum documento deve ser apresentado (mudança de linha sem anexo): caso contrário, o documento anterior permanece visível.
- Preferir `of_refresh()` a uma reatribuição de `is_source` para recarregar o mesmo documento: é mais rápido e a posição de leitura é reposta corretamente.
- Prever um indicador de espera para os documentos remotos ou volumosos, e ocultá-lo em `ue_load_completed`.
- Atribuir ao componente uma superfície confortável (pelo menos metade da janela): a barra de ferramentas integrada e o documento precisam de espaço para permanecerem legíveis.
- Para apresentar uma página web em vez de um PDF, deve utilizar-se webbrowser; para uma imagem, picture.

← Referência dos componentes · Índice do guia