ViewerPreferences Complete Reference

ViewerPreferences 可控制 PDF 檔案在支援的檢視器中如何呈現，以及部分預設列印設定如何初始化。目前 HotPDF library 支援 14 個 ViewerPreferences values，以及相關的 InitialZoom property

Current Data Types

THPDFDirection = (LeftToRight, RightToLeft);
THPDFNonFullScreenPageMode = (
  nfpmUseNone, nfpmUseOutlines, nfpmUseThumbs, nfpmUseOC, nfpmUseAttachments
);
THPDFPrintScaling = (psNone, psAppDefault);
THPDFDuplex = (dupSimplex, dupDuplexFlipShortEdge, dupDuplexFlipLongEdge);
THPDFPageBoundary = (pbMediaBox, pbCropBox, pbBleedBox, pbTrimBox, pbArtBox);
THPDFInitialZoom = (
  FitNone, FitPage, FitWidth, FitHeight, FitBox, FitBoxWidth, FitBoxHeight,
  Zoom50, Zoom75, Zoom100, Zoom125, Zoom150, Zoom200
);

THPDFViewerPreference = (
  vpHideToolbar, vpHideMenubar, vpHideWindowUI, vpFitWindow, vpCenterWindow,
  vpDisplayDocTitle, vpDirection, vpNonFullScreenPageMode, vpPrintScaling,
  vpDuplex, vpPickTrayByPDFSize, vpNumCopies, vpPrintArea, vpPrintClip,
  vpViewArea, vpViewClip
);

THPDFViewerPreferences = set of THPDFViewerPreference;

Supported ViewerPreferences

Option	Companion Property	說明
vpHideToolbar	None	Hide the viewer toolbar.
vpHideMenubar	None	Hide the viewer menu bar.
vpHideWindowUI	None	Hide UI elements such as scroll bars and navigation controls.
vpFitWindow	None	Resize the document window to fit the first displayed page.
vpCenterWindow	None	Center the document window on the screen.
vpDisplayDocTitle	Title	Display the document title instead of the file name in the viewer caption.
vpDirection	Direction	Store the predominant reading order using `LeftToRight` or `RightToLeft`.
vpNonFullScreenPageMode	NonFullScreenPageMode	Choose the page mode to use after leaving full-screen mode.
vpPrintScaling	PrintScaling	Choose `psNone` or `psAppDefault` for default print scaling.
vpDuplex	Duplex	Choose simplex or duplex printing behavior.
vpPickTrayByPDFSize	None	Request printer tray selection based on the PDF page size.
vpNumCopies	NumCopies	Store the suggested print copy count.
vpPrintArea	PrintArea	Select the page boundary used for print rendering.
vpPrintClip	PrintClip	Select the page boundary used for print clipping.
vpViewArea	ViewArea	Page boundary used for the on-screen view area (PDF 1.4 12.2). Available since HotPDF v2.29.0.
vpViewClip	ViewClip	Page boundary used for the on-screen view clipping (PDF 1.4 12.2). Available since HotPDF v2.29.0.

Companion Property Values

只有啟用相符 ViewerPreferences flag 時，這些 properties 才會寫入

Property	Values
Direction	LeftToRight, RightToLeft
NonFullScreenPageMode	nfpmUseNone, nfpmUseOutlines, nfpmUseThumbs, nfpmUseOC, nfpmUseAttachments
PrintScaling	psNone, psAppDefault
Duplex	dupSimplex, dupDuplexFlipShortEdge, dupDuplexFlipLongEdge
PrintArea / PrintClip / ViewArea / ViewClip	pbMediaBox, pbCropBox, pbBleedBox, pbTrimBox, pbArtBox

InitialZoom Integration

InitialZoom 會補足 ViewerPreferences，控制檔案開啟時的初始頁面顯示模式

預設值：自 HotPDF v2.3.11 起，預設值為 FitHeight（PDF /FitV destination），因此產生的檔案開啟時每頁會符合 viewer 視窗高度。將 InitialZoom 設為 FitNone 可省略 OpenAction，讓 viewer fallback 到自己的預設 zoom

// Complete document presentation setup
HotPDF.ViewerPreferences := [vpFitWindow, vpCenterWindow, vpDisplayDocTitle];
HotPDF.InitialZoom := FitWidth;

// Technical document setup
HotPDF.ViewerPreferences := [vpDisplayDocTitle, vpPrintScaling];
HotPDF.InitialZoom := Zoom125;

// Presentation mode
HotPDF.ViewerPreferences := [vpFitWindow, vpHideToolbar, vpHideMenubar];
HotPDF.InitialZoom := FitPage;

Implementation Example

var
  VPref: THPDFViewerPreferences;
begin
  VPref := [vpFitWindow, vpCenterWindow, vpDisplayDocTitle];

  if EnableDirection then
  begin
    Include(VPref, vpDirection);
    HotPDF.Direction := RightToLeft;
  end;

  if EnablePrintScaling then
  begin
    Include(VPref, vpPrintScaling);
    HotPDF.PrintScaling := psNone;
  end;

  HotPDF.ViewerPreferences := VPref;
  HotPDF.InitialZoom := FitWidth;
end;

Compatibility Notes

Acrobat 與 Reader：通常提供最完整的 ViewerPreferences 功能支援
其他 Viewers：支援程度不一，因為這些值是 preferences，而不是硬性要求
優雅降級：符合規範的檢視器應安全忽略不支援的設定

Demo Applications

下列 demos 已與目前 library 支援同步：

Demo\Delphi\ViewerPref
Demo\CBuilder\ViewerPref