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 #

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_status.of_panel(/*key*/ "main").is_text = "Documento apresentado"

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

Propriedades #

Métodos #

Eventos #

Porque é que um documento não é apresentado #

as_reason de ue_load_failed é uma destas constantes de u_pbt_pdfviewer. Um PDF reconhece-se assim: um ficheiro local tem a extensão .pdf e começa pela assinatura %PDF-; um documento remoto é servido com o tipo application/pdf (o único que o motor entrega ao seu leitor); um endereço data: anuncia application/pdf.

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.

Os atalhos do navegador — Ctrl+F, Ctrl+P, Ctrl + roda do rato — estão desativados em todos os componentes, este incluído: use os botões da barra do leitor.

O que o leitor não diz #

O leitor é o integrado no motor web: nada a instalar, impressão, pesquisa, formulários PDF e ecrã inteiro incluídos. Em contrapartida, não comunica nada à sua aplicação: nem a página apresentada, nem o número de páginas, nem o zoom real, nem o texto selecionado, e a pesquisa não se conduz por código (is_find realça um texto na abertura, nada mais). ii_page e ii_zoom dizem onde abrir o documento, não onde o utilizador está. Um PDF protegido por palavra-passe: o leitor pede-a ele próprio ao utilizador, a sua aplicação não a pode fornecer. É uma escolha deliberada; uma apresentação programável exigiria uma biblioteca externa.

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 #

// Local variables
string ls_file

// Um ficheiro por dia, na pasta temporaria
ls_file = "C:\temp\report_" + String(Today(), "yyyymmdd") + ".pdf"

// A DataWindow produz o ficheiro...
dw_report.SaveAs(ls_file, PDF!, false)

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

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 rowfocuschanged de dw_list : (long currentrow)
// Local variables
string ls_pdf

// O caminho do PDF da linha atual
ls_pdf = dw_list.GetItemString(currentrow, "pdf_path")

// Sem anexo o visualizador esvazia-se (definicoes mantidas) ; caso contrario mostra-o
if ls_pdf = "" then
	uo_pdf.is_source = ""
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_wait.Hide()

// of_print imprime o documento apresentado
uo_print_button.ib_enabled = true

Dizer porque é que o documento não está lá #

// event ue_load_failed de uo_pdf : (string as_source, string as_reason)
uo_wait.Hide()
choose case as_reason
	case uo_pdf.REASON_NOT_FOUND
		uo_status.of_panel(/*key*/ "main").is_text = "Documento nao encontrado: " + as_source
	case uo_pdf.REASON_NOT_PDF
		uo_status.of_panel(/*key*/ "main").is_text = "Este ficheiro nao e um PDF"
	case else
		uo_status.of_panel(/*key*/ "main").is_text = "Documento indisponivel (" + as_reason + ")"
end choose

Abrir noutro lado uma ligação do documento #

// event ue_link_clicked de uo_pdf : (string as_url)
// O visualizador permanece no documento : a ligacao abre no navegador da janela
uo_web.is_address = as_url

Imprimir o documento #

// clicked do botao Imprimir : a pre-visualizacao do leitor PDF, sobre o proprio documento
if uo_pdf.of_print() = -4 then
	uo_status.of_panel(/*key*/ "main").is_text = "Nenhum documento para imprimir"
end if

Mostrar sem deixar guardar nem imprimir #

// Um documento confidencial : nem Guardar nem Imprimir na barra do leitor
uo_pdf.ib_allow_save = false
uo_pdf.ib_allow_print = false
uo_pdf.is_source = is_current_document

Defina-os antes de is_source: o documento carrega uma única vez. Cada visualizador mantém a sua própria definição. Não é uma proteção: o ficheiro continua legível no disco, e of_print continua a imprimir.

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(/*key*/ "entry",  /*title*/ "Introducao", /*page*/ uo_page_entry)
uo_tab.of_add_page(/*key*/ "preview",  /*title*/ "Previsao",   /*page*/ uo_page_preview)

// O visualizador esta colocado em uo_page_preview como qualquer outro controlo
uo_pdf.is_source = is_current_document

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

Verificar o ficheiro antes de o apresentar #

// Local variables
string ls_path

// O ficheiro da fatura apresentada
ls_path = "C:\factures\" + is_number + ".pdf"

// Sem ficheiro, nada a mostrar : esvazia-se o visualizador em vez de deixar o documento anterior
if not FileExists(ls_path) then
    uo_pdf.is_source = ""
    uo_status.of_panel(/*key*/ "main").is_text = "Fatura nao encontrada"
    return
end if

// Caso contrario, a fatura e apresentada
uo_pdf.is_source = ls_path

Apresentar um PDF lido da base de dados (blob) #

// Local variables
blob lblb_pdf

// A fatura guardada na base de dados, lida num blob
SELECTBLOB pdf_file INTO :lblb_pdf FROM invoice WHERE invoice_no = :is_number USING SQLCA;

// Apresentada diretamente a partir da memoria : nenhum ficheiro temporario, seja qual for o tamanho
if SQLCA.SQLCode = 0 then
	uo_pdf.of_load_blob(/*pdf*/ lblb_pdf, /*name*/ "invoice-" + is_number + ".pdf")
end if

O nome dado volta em is_source e em ue_load_completed; o blob é libertado pelo documento seguinte ou por of_reset.

Mostrar uma linha precisa do documento #

// O leitor abre na primeira passagem deste texto, realcada
uo_pdf.is_find = "Delivery and assembly"
uo_pdf.is_source = "C:\factures\FA-2026-0142.pdf"

Abrir num capítulo, marcadores visíveis #

// O painel lateral e os seus marcadores, aberto no capitulo "prices" do catalogo
uo_pdf.ib_navigation_pane = true
uo_pdf.is_destination = "prices"
uo_pdf.is_source = "doc\catalogue-2026.pdf"

O nome de um destino é o que a ferramenta que produziu o PDF escreveu: o seu gerador de documentos conhece-o.

Um documento atrás de um token, ou servido como octet-stream #

// Local variables
long ll_status
string ls_file

// O restclient (inv_rest, preparado na abertura da janela) envia o token e descarrega o ficheiro
ls_file = "C:\temp\invoice-4152.pdf"
ll_status = inv_rest.of_download(/*url*/ "/orders/4152/invoice.pdf", /*path*/ ls_file)

// Depois o visualizador apresenta o ficheiro, seja qual for o tipo anunciado pelo servidor
if ll_status = 200 then
	uo_pdf.is_source = ls_file
end if

O leitor do motor não sabe enviar um token nem apresentar uma resposta application/octet-stream (REASON_AUTH, REASON_NOT_PDF): o restclient fá-lo por ele.

Formatos e caminhos aceites #

Apenas o PDF é suportado por este componente: o resto é recusado e assinalado por ue_load_failed (REASON_NOT_PDF). Para uma imagem, deve utilizar-se picture; para uma página HTML, webbrowser.

Boas práticas #

• Vigiar ue_load_failed: um caminho inválido, um ficheiro que não é um PDF ou um site inacessível é aí assinalado com a sua causa, e o visualizador permanece vazio.
• Para esvaziar o visualizador (mudança de linha sem anexo), defina is_source = "": caso contrário, o documento anterior permanece visível. of_reset() também o esvazia, mas além disso repõe todas as definições no seu valor por omissão — Guardar e Imprimir incluídos.
• of_refresh() é o meio de apresentar um ficheiro regenerado no mesmo caminho: volta a ler o ficheiro sem alterar as definições. Não conserva a posição de deslocamento — o leitor recomeça em ii_page.
• Cada alteração de ii_zoom, is_fit, ib_viewer_toolbar, ib_navigation_pane, is_destination, is_find, ib_allow_save ou ib_allow_print recarrega o documento (o leitor só lê as suas definições no carregamento) e volta a acionar ue_load_completed: defina-os antes de is_source para um único carregamento. O mesmo valor definido de novo não recarrega nada. ii_page definido enquanto um documento é apresentado vale para esse documento: para abrir outro numa página, defina is_source e depois ii_page.
• Prever um indicador de espera para os documentos remotos ou volumosos, e ocultá-lo em ue_load_completed e em ue_load_failed.
• 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.

Herdado da base comum #

Estes membros existem em todos os componentes visuais — não são próprios deste. São detalhados uma só vez, nos capítulos transversais; esta tabela apenas diz onde os ler.

Duas ajudas não são herdadas: of_icon e of_escape_markup vivem em n_pbt_utils. Declare um — n_pbt_utils lnv_utils, nada a criar — e chame-as nele.

← Referência dos componentes · Índice do guia