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, PDF forms and full screen 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. ii_page and ii_zoom say where to open the document, not where the user is. This is a deliberate choice for 4.0; 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 #

// ue_row_changed event of dw_list : display the attachment of the current row
string ls_pdf

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

// No attachment empties the viewer ; otherwise it shows it
if ls_pdf = "" then
    uo_pdf.of_reset()          // no attachment : empty viewer
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: every change reloads the document. 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.of_reset()
    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

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.
• Call of_reset() when no document should be displayed any more (moving to a row without an attachment): otherwise the previous document stays visible.
• 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_page, ii_zoom, is_fit or ib_viewer_toolbar 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.
• 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