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.