pdfviewer — u_pbt_pdfviewer #

← Component reference · Guide contents

Built-in PDF viewer: displays a local document or one published on the web, straight inside your window, with pagination, zoom and printing.

▶ See it live — Demo application, PDF viewer tile: the preview, the code behind it and this page, side by side.

At a glance #

The component replaces the classic "save the PDF to a temporary file, then call ShellExecute": the document stays inside your application, and the user never leaves the current screen.

Quick start #

// window open event : display a document stored on disk
uo_pdf.is_source = "C:\factures\FA-2026-0142.pdf"

// ue_load_completed event of uo_pdf : (string as_source)
uo_status.of_panel(/*key*/ "main").is_text = "Document displayed"

That is all: setting is_source is enough to load and display the document.

Properties #

Methods #

Events #

Why a document is not shown #

as_reason of ue_load_failed is one of these u_pbt_pdfviewer constants. A PDF is recognised this way: a local file has the .pdf extension and starts with the %PDF- signature; a remote document is served with the application/pdf type (the only one the engine hands to its reader); a data: address announces application/pdf.

What the user can do, without a single line of code #

The viewer displays its built-in toolbar above the document. There is nothing for you to program: it is provided and localized by the system.

The browser's shortcuts — Ctrl+F, Ctrl+P, Ctrl + wheel — are switched off in every component, this one included: use the buttons of the reader's toolbar.

What the reader does not say #

The reader is the one built into the web engine: nothing to install, printing, search and PDF forms included. In return, it reports nothing to your application: not the page on screen, not the number of pages, not the real zoom, not the selected text, and search cannot be driven from code: the reader ignores the open parameters that would highlight a text or open its side panel. It has no Full screen command, and it follows the light or dark theme of the application, never the component's. ii_page and ii_zoom say where to open the document, not where the user is. A password-protected PDF: the reader asks the user for the password itself, your application cannot give it. This is a deliberate choice; a scriptable rendering would need an external library.

Examples #

Opening a local document #

// Absolute path, or relative to the application directory
uo_pdf.is_source = "doc\conditions-generales.pdf"

Opening a document published on the web #

// A web address loads exactly like a local file
uo_pdf.is_source = "https://www.monsite.fr/tarifs/catalogue-2026.pdf"

An internet connection is of course required; the load is asynchronous, and ue_load_completed tells you when it is done.

Displaying the PDF a DataWindow has just produced #

// Local variables
string ls_file

// One file per day, in the temporary folder
ls_file = "C:\temp\report_" + String(Today(), "yyyymmdd") + ".pdf"

// The DataWindow produces the file...
dw_report.SaveAs(ls_file, PDF!, false)

// ...and the viewer displays it immediately
uo_pdf.is_source = ls_file

Refreshing after the file has been regenerated #

// The file was rewritten in the same location : reload without touching is_source
uo_pdf.of_refresh()

Chaining several documents in the same viewer #

// rowfocuschanged event of dw_list : (long currentrow)
// Local variables
string ls_pdf

// The path of the PDF of the current row
ls_pdf = dw_list.GetItemString(currentrow, "pdf_path")

// No attachment empties the viewer (its settings kept) ; otherwise it shows it
if ls_pdf = "" then
	uo_pdf.is_source = ""
else
	uo_pdf.is_source = ls_pdf
end if

Tracking the end of the load #

// ue_load_completed event of uo_pdf : (string as_source)
uo_wait.Hide()

// of_print prints the document on screen
uo_print_button.ib_enabled = true

Saying why the document is not there #

// ue_load_failed event of 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 = "Document not found: " + as_source
	case uo_pdf.REASON_NOT_PDF
		uo_status.of_panel(/*key*/ "main").is_text = "This file is not a PDF"
	case else
		uo_status.of_panel(/*key*/ "main").is_text = "Document unavailable (" + as_reason + ")"
end choose

Opening a link of the document elsewhere #

// ue_link_clicked event of uo_pdf : (string as_url)
// The viewer stays on the document : the link opens in the window's browser
uo_web.is_address = as_url

Printing the document #

// clicked of the Print button : the PDF reader's preview, on the document itself
if uo_pdf.of_print() = -4 then
	uo_status.of_panel(/*key*/ "main").is_text = "No document to print"
end if

Showing without letting save or print #

// A confidential document : neither Save nor Print in the reader's bar
uo_pdf.ib_allow_save = false
uo_pdf.ib_allow_print = false
uo_pdf.is_source = is_current_document

Set them before is_source: the document loads only once. Each viewer keeps its own setting. It is not a protection: the file stays readable on the disk, and of_print still prints.

Preview in a tab, next to data entry #

// open event : the viewer takes one tab page, data entry the other
uo_tab.of_add_page(/*key*/ "entry",  /*title*/ "Entry",   /*page*/ uo_page_entry)
uo_tab.of_add_page(/*key*/ "preview",  /*title*/ "Preview",   /*page*/ uo_page_preview)

// The viewer sits inside uo_page_preview like any other control
uo_pdf.is_source = is_current_document

The component is hosted with no special precautions inside a tab or a dockcontainer panel.

Checking the file before displaying it #

// Local variables
string ls_path

// The file of the invoice on screen
ls_path = "C:\factures\" + is_number + ".pdf"

// No file, nothing to show : clear the viewer rather than leave the previous document
if not FileExists(ls_path) then
    uo_pdf.is_source = ""
    uo_status.of_panel(/*key*/ "main").is_text = "Invoice not found"
    return
end if

// Otherwise, the invoice is shown
uo_pdf.is_source = ls_path

Showing a PDF read from the database (blob) #

// Local variables
blob lblb_pdf

// The invoice stored in the database, read into a blob
SELECTBLOB pdf_file INTO :lblb_pdf FROM invoice WHERE invoice_no = :is_number USING SQLCA;

// Shown straight from memory : no temporary file, whatever its size
if SQLCA.SQLCode = 0 then
	uo_pdf.of_load_blob(/*pdf*/ lblb_pdf, /*name*/ "invoice-" + is_number + ".pdf")
end if

The name given comes back in is_source and in ue_load_completed; the blob is released by the next document or by of_reset.

Opening on a chapter #

// Opened on the chapter "prices" of the catalogue; the reader's Table of contents button lists the bookmarks
uo_pdf.is_destination = "prices"
uo_pdf.is_source = "doc\catalogue-2026.pdf"

The name of a destination is the one written by the tool that produced the PDF: your document generator knows it.

A document behind a token, or served as octet-stream #

// Local variables
long ll_status
string ls_file

// The restclient (inv_rest, set up when the window opened) sends the token and downloads the file
ls_file = "C:\temp\invoice-4152.pdf"
ll_status = inv_rest.of_download(/*url*/ "/orders/4152/invoice.pdf", /*path*/ ls_file)

// Then the viewer shows the file, whatever type the server announced
if ll_status = 200 then
	uo_pdf.is_source = ls_file
end if

The engine's reader can neither send a token nor show an application/octet-stream answer (REASON_AUTH, REASON_NOT_PDF): the restclient does it for it.

Accepted formats and paths #

This component only supports PDF: anything else is refused and reported by ue_load_failed (REASON_NOT_PDF). For an image, use picture; for an HTML page, webbrowser.

Best practices #

• Watch ue_load_failed: an invalid path, a file that is not a PDF or an unreachable site is reported there with its reason, and the viewer stays empty.
• To clear the viewer (moving to a row without an attachment), set is_source = "": otherwise the previous document stays visible. of_reset() clears it too, but also puts every setting back to its default — Save and Print included.
• of_refresh() is the way to show a file regenerated at the same path: it reads the file again without touching the settings. It does not keep the scrolling position — the reader starts again at ii_page.
• Every change of ii_zoom, is_fit, ib_viewer_toolbar, is_destination, ib_allow_save or ib_allow_print reloads the document (the reader only reads its settings when a document loads) and raises ue_load_completed again: set them before is_source for a single load. The same value set again reloads nothing. ii_page set while a document is shown applies to that document: to open another one on a page, set is_source then ii_page.
• Provide a waiting indicator for remote or large documents, and hide it on ue_load_completed and on ue_load_failed.
• Give the component a comfortable area (at least half the window): the built-in toolbar and the document both need room to stay readable.
• To display a web page rather than a PDF, use webbrowser; for an image, picture.

Inherited from the common base #

These members exist on every visual component — they are not specific to this one. They are detailed once, in the transverse chapters; this table only says where to read them.

Two helpers are not inherited: of_icon and of_escape_markup live on n_pbt_utils. Declare one — n_pbt_utils lnv_utils, nothing to create — and call them on it.

← Component reference · Guide contents