TPDFlibViewer

Viewer

Descrizione

Questa pagina descrive il controllo TPDFlibViewer in PDFlibPas nell'area "Visualizzatore". I nomi di API, parametri, classi, file e valori letterali restano invariati per corrispondere alla libreria Delphi

TPDFlibViewer (unità Lib\PDFlibViewer.pas) è un controllo VCL con scorrimento che visualizza le pagine PDF all'interno dell'applicazione. Esegue il rendering attraverso lo stesso motore usato da TPDFlib (GDI+, Cairo o PDFium, seguendo SelectRenderer sull'istanza collegata).

Membri principali

Function LoadFromFile(Const FileName, Password: WideString): Integer;
Procedure AttachLibrary(ALib: TPDFlib);
Property Lib: 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);
Property ZoomPercent: Double;
Procedure SetZoomMode(Mode: TPDFlibViewerZoomMode);
Property ZoomMode: TPDFlibViewerZoomMode;
Procedure SetDisplayMode(Mode: TPDFlibViewerDisplayMode);
Procedure SetCacheLimit(MegaBytes: Integer);
Function IsPageCached(APage: Integer): Boolean;
Procedure DrainPrefetched;
Property Cache: TPDFlibViewerBitmapCache;
Procedure RefreshPage;
Function RenderedWidth: Integer;
Function RenderedHeight: Integer;
Function EffectiveZoomPercent: Double;
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 InteractiveForms: Boolean;
Property InteractiveAnnotations: Boolean;
Property FormTextColor: TColor;
Property OnFormFieldValueChanged: TPDFlibViewerFormFieldChange;
Function GetFormFieldTabSequence(Out FieldIndices: TPDFlibViewerFormFieldIndices): Integer;
Function GetFormFieldEditorKind(FieldIndex: Integer): TPDFlibViewerFormEditorKind;
Function ActivateFormField(FieldIndex: Integer; Const TriggerEvent: WideString= 'U'): Integer;
Property EditingFieldIndex: Integer;
Property FocusedFormFieldIndex: Integer;
Property OnFormFieldAction: TPDFlibViewerFormFieldAction;
Function GetTextInRegion(APage: Integer; XPos, YPos, RWidth, RHeight: Double): WideString;
Function CopySelectedText: Integer;
Property ViewerMode: TPDFlibViewerMode;
Function CaptureRegion(Const Region: TRect): TBitmap;
Function CaptureCurrentView: TBitmap;
Function SaveCurrentViewToFile(Const FileName: WideString): Integer;
Function SelectRegion(APage: Integer; XPos, YPos, RWidth, RHeight: Double): Integer;
Function GetSelectedRegion(Index: Integer; Out Selection: TPDFlibViewerSelection): Boolean;
Procedure ClearSelectedRegions;
Function SelectedRegionCount: Integer;
Property SelectionColor: TColor;
Property OnMarqueeSelect: TPDFlibViewerMarqueeSelect;
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 ScreenDPI: Integer;
Property DisplayMode: TPDFlibViewerDisplayMode;
Property ScrollHintEnabled: Boolean;
Property OnZoomChange: TPDFlibViewerZoomChange;
Property OnHScroll: TPDFlibViewerScroll;
Property OnVScroll: TPDFlibViewerScroll;
Property OnPageChange: TPDFlibViewerPageChange;
Property OnLinkClick: TPDFlibViewerLinkClick;

Note

LoadFromFile apre un documento mediante l'istanza TPDFlib propria del controllo; AttachLibrary visualizza il documento selezionato di un'istanza gestita dal chiamante, che ne mantiene la proprietà. Le modalità di ingrandimento sono percentuale fissa (zmPercent tramite SetZoomPercent), adattamento alla larghezza (zmFitWidth, predefinito) e adattamento alla pagina (zmFitPage); le modalità di adattamento vengono ricalcolate automaticamente al ridimensionamento del controllo. La navigazione resta entro l'intervallo delle pagine del documento's e genera OnPageChange soltanto quando cambia effettivamente la pagina visibile; OnZoomChange segnala ogni variazione effettiva dell'ingrandimento, incluso il ricalcolo della modalità di adattamento durante ridimensionamento o rotazione, mentre OnHScroll / OnVScroll seguono la posizione di scorrimento, mantenendo sincronizzate barre degli strumenti e barre di stato senza polling. Durante il trascinamento del cursore della barra di scorrimento verticale, un fumetto mobile "Page N / M" mostra in anteprima la pagina di arrivo (ScrollHintEnabled, attivo per impostazione predefinita). GoToPagePoint passa a una pagina e porta un determinato punto della pagina nell'angolo superiore sinistro della visualizzazione, per destinazioni dei collegamenti e risultati di ricerca; ScrollBy, le proprietà di lettura/scrittura HScrollPos / VScrollPos, utili per sincronizzare due visualizzatori affiancati, e GetScrollPosForPage offrono il controllo programmatico dello scorrimento, mentre i bridge pubblici ClientPointToPage / PageRectToClientRect convertono tra pixel client e spazio utente della pagina tenendo conto di ingrandimento, rotazione e scorrimento. SetDisplayMode alterna tra visualizzazione a pagina singola (dmSinglePage, predefinita) e scorrimento verticale continuo dell'intero documento (dmContinuous), nel quale vengono sottoposte a rendering soltanto le pagine visibili e la pagina corrente segue la posizione di scorrimento. Le pagine sottoposte a rendering vengono conservate in una cache bitmap LRU, da 128 MB per impostazione predefinita e regolabile con SetCacheLimit, quindi tornando indietro non è necessario ripetere il rendering. L'impostazione di DiskCacheFolder conserva inoltre le pagine sottoposte a rendering sul disco tra le sessioni: le pagine di ogni documento's vengono memorizzate usando un'impronta di percorso, dimensione e data di scrittura del file, perciò la modifica del file invalida automaticamente le relative voci, i documenti usati meno di recente vengono eliminati oltre il limite di dieci documenti e la riapertura di un file visualizzato di recente ne mostra le pagine senza ripetere il rendering (DiskCacheHits indica la frequenza con cui il disco ha fornito una pagina). La rotellina del mouse scorre verticalmente e, tenendo premuto Ctrl, modifica l'ingrandimento secondo la scala predefinita (1–3200%); ZoomInStep / ZoomOutStep espongono programmaticamente gli stessi passaggi, usati anche dalle azioni di ingrandimento della barra degli strumenti. PageUp/PageDown, i tasti freccia, Home ed End consentono la navigazione; Ctrl+'+'/'-' modifica l'ingrandimento a passi, Ctrl+1/2/3 passa rispettivamente a dimensione effettiva, adattamento alla larghezza e adattamento alla pagina e Maiusc+Su/Giù passa alla prima o all'ultima pagina. Le pagine adiacenti vengono sottoposte a rendering anticipato in un thread in background affinché il cambio pagina sia immediato (PrefetchEnabled, attivo per impostazione predefinita, arresta e riavvia il worker), mentre DiskCacheMaxDocuments regola il numero di documenti conservati nella cache su disco. OnBeforeSnapshot viene generato prima dell'acquisizione mediante trascinamento e può gestire interamente la regione impostando Handled. Il clic su un'annotazione collegamento genera OnLinkClick con numero di pagina e riepilogo tipizzato dell'azione (TPDFlibActionInfo: indirizzo Web, destinazione del documento, azione denominata e altro); LinkActionAtPagePoint espone direttamente l'hit test, accettando coordinate nello stesso spazio utente indicato da GetAnnotRectEx. Il clic su qualsiasi altra annotazione genera OnAnnotClick con pagina, indice dell'annotazione e nome del sottotipo (AnnotAtPagePoint è l'hit test programmatico); passando sopra un'annotazione ne viene mostrato il testo Contents come suggerimento del controllo's quando AnnotHints e ShowHint sono attivi, mentre SaveAnnotAttachmentToFile scrive su disco il file incorporato dell'annotazione FileAttachment's selezionata: queste funzionalità semplificano popup delle note, salvataggio degli allegati ed esame dei commenti. I campi AcroForm possono essere compilati interattivamente: facendo clic su una casella di controllo o un pulsante di opzione lo si attiva o disattiva, mentre facendo clic su un campo testo o scelta si apre un editor sul posto sopra il campo, in cui Invio conferma, Esc annulla e l'uscita dall'editor conferma; la pagina modificata viene sottoposta nuovamente a rendering e ogni scrittura genera OnFormFieldValueChanged; HighlightFormFields disegna uno sfondo traslucido su ogni area compilabile e FormFieldAtPagePoint, ToggleCheckBoxField, SetFormFieldValueAndRefresh e BeginEditFormField controllano programmaticamente lo stesso meccanismo, lasciando invariati i campi di sola lettura. I campi di testo su più righe vengono modificati in un memo, dove Invio inserisce un'interruzione di riga e Ctrl+Invio conferma; Tab e Maiusc+Tab spostano l'editor sul posto tra i campi testo e scelta modificabili del documento's (FocusNextFormField è la forma programmatica), mentre SaveToFile / SaveToStream scrivono il documento visualizzato, incluse le modifiche ai moduli già confermate, su disco o in un flusso, completando nel controllo il ciclo di compilazione e salvataggio. Il trascinamento con il pulsante sinistro del mouse seleziona il testo, mentre un clic su un collegamento attiva il collegamento; Ctrl+C o CopySelectedText copia la selezione e GetTextInRegion esegue programmaticamente la stessa ricerca basata su blocchi in una regione. La proprietà ViewerMode determina la funzione del pulsante sinistro del mouse: vmSelect, predefinita, trascina una selezione di testo; vmHand sposta la vista con un cursore a mano, mentre un semplice clic continua ad attivare i collegamenti; vmZoom trascina un riquadro che ingrandisce l'area delimitata fino a riempire la visualizzazione, mentre un semplice clic aumenta l'ingrandimento di un passo; vmSnapshot copia la regione trascinata negli Appunti come bitmap e genera OnSnapshot; vmHighlight contrassegna la regione trascinata con un'evidenziazione traslucida persistente. CaptureRegion espone programmaticamente il motore di acquisizione e AddHighlightRegion / ClearHighlightRegions gestiscono le evidenziazioni persistenti, espresse in coordinate della pagina e conservate durante ingrandimento, rotazione e navigazione, con colore impostato da HighlightColor. PrintDoc stampa il documento visualizzato: per impostazione predefinita mostra la finestra di stampa standard di Windows, con scelta della stampante, intervallo di pagine, copie e fascicolazione, e affida il processo al motore di stampa della libreria's; PrintDoc(False) stampa tutte le pagine sulla stampante predefinita senza interfaccia utente, mentre PrintDocRange è la variante completamente programmatica che accetta nome della stampante e intervallo di pagine. RotateClockwise90 e RotateAntiClockwise90 ruotano l'intera vista a passi di 90 gradi, impostabili anche tramite ViewRotation: 0, 90, 180 o 270; la rotazione è un attributo della vista che non modifica il documento, mantiene operativi collegamenti e selezione del testo a ogni angolo e viene reimpostata all'apertura di un nuovo documento. Il controllo complementare TPDFlibOutlineViewer mostra l'albero dei segnalibri del documento's accanto al visualizzatore: chiamare il relativo AttachViewer con l'istanza del visualizzatore e fare clic su un segnalibro per passare alla pagina di destinazione. HighlightSearchHits cerca nell'intero documento e disegna una barra traslucida (SearchHighlightColor) su ogni risultato; le barre restano in posizione durante scorrimento, ingrandimento e rotazione finché ClearSearchHighlights non le rimuove. TPDFlibSearchPanel si collega nello stesso modo: RunSearch elenca ogni risultato del documento con pagina e testo corrispondente, un clic su un risultato passa alla relativa pagina e, con HighlightInView attivo per impostazione predefinita, il pannello disegna anche le barre dei risultati nel visualizzatore collegato. TPDFlibThumbnailBar completa la famiglia con una miniatura di ogni pagina sottoposta a rendering su richiesta; facendo clic su una miniatura si passa alla relativa pagina. L'unità complementare Lib\PDFlibViewerActions.pas fornisce venti discendenti TAction pronti all'uso, registrati nella categoria losLab PDF, affinché barre degli strumenti e menu non richiedano codice di collegamento: impostare la proprietà Viewer di ciascuna azione sul controllo e TPDFlibViewerFirstPage / TPDFlibViewerPriorPage / TPDFlibViewerNextPage / TPDFlibViewerLastPage, TPDFlibViewerZoomIn / TPDFlibViewerZoomOut / TPDFlibViewerFitWidth / TPDFlibViewerFitPage / TPDFlibViewerActualSize, TPDFlibViewerRotateClockwise / TPDFlibViewerRotateAntiClockwise, TPDFlibViewerPrint, TPDFlibViewerFileOpen / TPDFlibViewerFileSaveAs, TPDFlibViewerCopyText e le azioni per la modalità degli strumenti TPDFlibViewerSelectMode / TPDFlibViewerHandMode / TPDFlibViewerMarqueeZoomMode / TPDFlibViewerSnapshotMode / TPDFlibViewerHighlightMode mantengono automaticamente sincronizzati gli stati abilitato e selezionato con il documento e lo strumento attivo. Installare il pacchetto design-time Lib\PDFlibViewerPkg.dpk per inserire il controllo dalla pagina losLab PDF della tavolozza durante la progettazione. I membri restanti completano la superficie programmatica: RenderedWidth / RenderedHeight indicano le dimensioni in pixel della bitmap della pagina attualmente sottoposta a rendering, 0 prima della visualizzazione di un documento; EffectiveZoomPercent indica l'ingrandimento effettivo, inclusi i fattori di adattamento calcolati; ScreenDPI indica l'associazione tra punti e pixel, rilevata automaticamente dal monitor host e sostituibile per i test di rendering headless, la cui modifica cancella la cache bitmap; IsPageCached / Cache consentono di esaminare la cache bitmap; DrainPrefetched decodifica i rendering in background completati per gli host privi di message pump; Lib restituisce l'istanza TPDFlib collegata. È inoltre esposta l'intera infrastruttura dei campi modulo: GetFormFieldTabSequence restituisce ogni widget visibile in ordine di tabulazione stabile, GetFormFieldEditorKind determina il tipo di editor usato da un campo, ActivateFormField inoltra l'azione di rilascio del mouse del campo's all'host, inclusi pulsanti e widget firma anche senza un'azione, EditingFieldIndex / FocusedFormFieldIndex indicano lo stato dell'editor sul posto e OnFormFieldAction notifica l'host ogni volta che viene generata un'azione del campo