TPDFlibViewer

Viewer

Description

This page describes the TPDFlibViewer control in PDFlibPas under the "Viewer" topic. API names, parameters, class names, filenames, and literals are kept exactly as they appear in the Delphi library.

TPDFlibViewer (unit Lib\PDFlibViewer.pas) is a VCL scrolling control that displays PDF pages inside your application. It renders through the same engine TPDFlib uses (GDI+, Cairo or PDFium, following SelectRenderer on the attached instance).

Key Members

Function LoadFromFile(Const FileName, Password: WideString): Integer;
Procedure AttachLibrary(ALib: TPDFlib);
Procedure CloseDocument;
Function PageCount: Integer;
Function GoToPage(NewPage: Integer): Integer;
Function GoToPagePoint(NewPage: Integer; XPt, YPt: Double): Integer;
Procedure ScrollBy(DX, DY: Integer);
Function GetScrollPosForPage(APage: Integer): Integer;
Function ClientPointToPage(X, Y: Integer; Out APage: Integer; Out XPt, YPt: Double): Boolean;
Function PageRectToClientRect(APage: Integer; XPt, YPt, WPt, HPt: Double; Out R: TRect): Boolean;
Property HScrollPos: Integer;
Property VScrollPos: Integer;
Function NextPage: Integer;
Function PrevPage: Integer;
Procedure SetZoomPercent(Percent: Double);
Procedure SetZoomMode(Mode: TPDFlibViewerZoomMode);
Procedure SetDisplayMode(Mode: TPDFlibViewerDisplayMode);
Procedure SetCacheLimit(MegaBytes: Integer);
Procedure RefreshPage;
Function LinkActionAtPagePoint(APage: Integer; XPos, YPos: Double; Out Info: TPDFlibActionInfo): Integer;
Function AnnotAtPagePoint(APage: Integer; XPos, YPos: Double; Out Subtype: WideString): Integer;
Function SaveAnnotAttachmentToFile(APage, AnnotIndex: Integer; Const FileName: WideString): Integer;
Property AnnotHints: Boolean;
Property OnAnnotClick: TPDFlibViewerAnnotClick;
Function FormFieldAtPagePoint(APage: Integer; XPos, YPos: Double): Integer;
Function GetFormFieldPageRect(FieldIndex: Integer; Out APage: Integer; Out XPt, YPt, WPt, HPt: Double): Boolean;
Function ToggleCheckBoxField(FieldIndex: Integer): Integer;
Function SetFormFieldValueAndRefresh(FieldIndex: Integer; Const NewValue: WideString): Integer;
Function BeginEditFormField(FieldIndex: Integer): Integer;
Procedure CommitInplaceEditor(Save: Boolean);
Function FocusNextFormField(Backwards: Boolean= False): Integer;
Function SaveToFile(Const FileName: WideString): Integer;
Function SaveToStream(OutStream: TStream): Integer;
Property HighlightFormFields: Boolean;
Property FormHighlightColor: TColor;
Property OnFormFieldValueChanged: TPDFlibViewerFormFieldChange;
Function GetTextInRegion(APage: Integer; XPos, YPos, RWidth, RHeight: Double): WideString;
Function CopySelectedText: Integer;
Property ViewerMode: TPDFlibViewerMode;
Function CaptureRegion(Const Region: TRect): TBitmap;
Procedure AddHighlightRegion(APage: Integer; XPos, YPos, RWidth, RHeight: Double);
Procedure ClearHighlightRegions;
Function HighlightRegionCount: Integer;
Property HighlightColor: TColor;
Function HighlightSearchHits(Const Query: WideString; CaseSensitive: Boolean= False): Integer;
Procedure ClearSearchHighlights;
Function SearchHighlightCount: Integer;
Property SearchHighlightColor: TColor;
Property SnapshotToClipboard: Boolean;
Property DiskCacheFolder: WideString;
Property DiskCacheHits: Integer;
Property DiskCacheMaxDocuments: Integer;
Property PrefetchEnabled: Boolean;
Property OnBeforeSnapshot: TPDFlibViewerBeforeSnapshot;
Property OnSnapshot: TPDFlibViewerSnapshot;
Function PrintDoc(ShowPrintDialog: Boolean= True): Integer;
Function PrintDocRange(Const PrinterName: WideString; StartPage, EndPage, Copies: Integer; Collate: Boolean): Integer;
Procedure ZoomInStep;
Procedure ZoomOutStep;
Procedure RotateClockwise90;
Procedure RotateAntiClockwise90;
Property ViewRotation: Integer;
Property SelectedText: WideString;
Property Page: Integer;
Property DisplayMode: TPDFlibViewerDisplayMode;
Property ScrollHintEnabled: Boolean;
Property OnZoomChange: TPDFlibViewerZoomChange;
Property OnHScroll: TPDFlibViewerScroll;
Property OnVScroll: TPDFlibViewerScroll;
Property OnPageChange: TPDFlibViewerPageChange;
Property OnLinkClick: TPDFlibViewerLinkClick;

Remarks

LoadFromFile opens a document through the control's own TPDFlib instance; AttachLibrary displays the selected document of an instance you manage yourself (the caller keeps ownership). Zoom modes are a fixed percentage (zmPercent via SetZoomPercent), fit-to-width (zmFitWidth, the default) and fit-to-page (zmFitPage); fit modes recompute automatically when the control resizes. Navigation clamps to the document's page range and fires OnPageChange only when the visible page really changes; OnZoomChange reports every effective-zoom move (including fit-mode recomputation on resize or rotation) and OnHScroll / OnVScroll follow the scroll position, so toolbars and status bars stay in sync without polling. While the vertical scrollbar thumb is dragged a floating "Page N / M" bubble previews the landing page (ScrollHintEnabled, on by default). GoToPagePoint jumps to a page and scrolls a given page point to the top-left of the viewport (link destinations, search hits); ScrollBy, the read/write HScrollPos / VScrollPos properties (handy for synchronising two side-by-side viewers) and GetScrollPosForPage give programmatic scroll control, and the public bridges ClientPointToPage / PageRectToClientRect convert between client pixels and page user space through zoom, rotation and scroll. SetDisplayMode switches between single-page display (dmSinglePage, the default) and a continuous vertical scroll through the whole document (dmContinuous), where only the pages visible in the viewport are rendered and the current page follows the scroll position. Rendered pages are kept in a least-recently-used bitmap cache (128 MB by default, adjustable with SetCacheLimit), so scrolling back does not re-render. Setting DiskCacheFolder additionally persists rendered pages on disk across sessions: each document's pages are stored under a fingerprint of the file's path, size and write time (editing the file naturally invalidates its entries), the least recently used documents are pruned beyond a ten-document budget, and reopening a recently viewed file shows its pages without re-rendering (DiskCacheHits reports how often the disk served a page). The mouse wheel scrolls vertically and zooms along the standard preset ladder (1–3200%) while Ctrl is held; ZoomInStep / ZoomOutStep expose the same preset stepping programmatically (the toolbar zoom actions use it too). PageUp/PageDown, the arrow keys, Home and End navigate; Ctrl+'+'/'-' step the zoom, Ctrl+1/2/3 switch to actual size, fit width and fit page, and Shift+Up/Down jump to the first and last page. Neighbouring pages pre-render on a background thread so paging is instant (PrefetchEnabled, on by default, stops and restarts the worker), and DiskCacheMaxDocuments tunes how many documents the disk page cache keeps. OnBeforeSnapshot fires before a snapshot drag is captured and can take over the region entirely by setting Handled. Clicking a link annotation fires OnLinkClick with the page number and the typed action summary (TPDFlibActionInfo: web address, document destination, named action and more); LinkActionAtPagePoint exposes the hit test directly, taking coordinates in the same user space GetAnnotRectEx reports. Clicking any other annotation fires OnAnnotClick with the page, annotation index and subtype name (AnnotAtPagePoint is the programmatic hit test); hovering an annotation shows its Contents text as the control's hint when AnnotHints and ShowHint are on, and SaveAnnotAttachmentToFile writes a clicked FileAttachment annotation's embedded file to disk - together these make note popups, attachment saving and comment inspection straightforward. AcroForm fields fill interactively: clicking a checkbox or radio button toggles it, clicking a text or choice field opens an in-place editor over the field (Enter commits, Escape cancels, leaving the editor commits), the changed page re-renders automatically, and every write fires OnFormFieldValueChanged; HighlightFormFields paints a translucent backdrop over each fillable area, and FormFieldAtPagePoint, ToggleCheckBoxField, SetFormFieldValueAndRefresh and BeginEditFormField drive the same machinery programmatically (read-only fields are left alone). Multiline text fields edit in a memo (Enter inserts a line break, Ctrl+Enter commits); Tab and Shift+Tab cycle the in-place editor through the document's editable text and choice fields (FocusNextFormField is the programmatic form), and SaveToFile / SaveToStream write the displayed document - committed form edits included - back to disk or a stream, completing the fill-and-save loop inside the control. Dragging with the left mouse button selects text (a click on a link fires the link instead); Ctrl+C or CopySelectedText copies the selection, and GetTextInRegion performs the same block-based region lookup programmatically. The ViewerMode property decides what the left mouse button does: vmSelect (the default) drags a text selection, vmHand pans the view with a grab cursor while a plain click still follows links, vmZoom drags a marquee that zooms the banded area to fill the viewport (a plain click steps the zoom up), vmSnapshot copies the dragged region to the clipboard as a bitmap and fires OnSnapshot, and vmHighlight marks the dragged region with a persistent translucent highlight. CaptureRegion exposes the snapshot engine programmatically, and AddHighlightRegion / ClearHighlightRegions manage persistent highlights (in page coordinates, surviving zoom, rotation and navigation; colour via HighlightColor). PrintDoc prints the displayed document: by default it shows the standard Windows print dialog (printer choice, page range, copies, collation) and hands the job to the library's printing engine; PrintDoc(False) prints every page to the default printer without UI, and PrintDocRange is the fully programmatic sibling taking a printer name and page range. RotateClockwise90 and RotateAntiClockwise90 turn the whole view in 90-degree steps (also settable through ViewRotation: 0, 90, 180 or 270); rotation is a view attribute that leaves the document untouched, keeps links and text selection working at every angle, and resets when a new document is opened. The companion control TPDFlibOutlineViewer shows the document's bookmark tree beside the viewer: call its AttachViewer with the viewer instance and clicking a bookmark navigates to its destination page. HighlightSearchHits searches the whole document and paints a translucent bar (SearchHighlightColor) over every hit; the bars stay in place while scrolling, zooming and rotating until ClearSearchHighlights removes them. TPDFlibSearchPanel attaches the same way: RunSearch lists every hit in the document with its page and matching text, clicking a hit jumps to that page, and with HighlightInView (on by default) the panel also paints the hit bars in the attached viewer. TPDFlibThumbnailBar completes the family with a lazily rendered miniature of every page; clicking a thumbnail navigates to it. The companion unit Lib\PDFlibViewerActions.pas provides twenty ready-made TAction descendants (registered under the losLab PDF category) so toolbars and menus need no glue code: point each action's Viewer property at the control and TPDFlibViewerFirstPage / TPDFlibViewerPriorPage / TPDFlibViewerNextPage / TPDFlibViewerLastPage, TPDFlibViewerZoomIn / TPDFlibViewerZoomOut / TPDFlibViewerFitWidth / TPDFlibViewerFitPage / TPDFlibViewerActualSize, TPDFlibViewerRotateClockwise / TPDFlibViewerRotateAntiClockwise, TPDFlibViewerPrint, TPDFlibViewerFileOpen / TPDFlibViewerFileSaveAs, TPDFlibViewerCopyText and the tool-mode actions TPDFlibViewerSelectMode / TPDFlibViewerHandMode / TPDFlibViewerMarqueeZoomMode / TPDFlibViewerSnapshotMode / TPDFlibViewerHighlightMode keep their enabled and checked states in sync with the document and the active tool automatically. Install the design-time package Lib\PDFlibViewerPkg.dpk to place the control from the losLab PDF palette page at design time.