Articolo tecnico

XFA dinamico in PDFium Component: il conteggio è un delta

Quando un form XFA dinamico in un viewer Delphi aggiunge o toglie pagine, PDFium Component riporta il nuovo totale tramite TPdf.PageCount e TPdf.OnXfaPageCountChanged, leggendolo dal layout completato perché l'evento pagina nativo porta un delta aggiunte/rimozioni anziché un totale. Le librerie V8 Windows spostano anche le aree di hit degli input insieme ai campi rilocati, e TPdfView ricarica gli handle di pagina dopo che il callback di layout è tornato. Immaginate un modulo di richiesta spese: clic su Add Row due volte e il form cresce fino a due pagine. Un viewer che si fida dell'argomento dell'evento legge fiero 1 di 1, e uno che conserva la geometria dei widget pre-layout manda i tasti di un campo spostato a pagina 2 chissà dove, invisibili. Niente di tutto questo compare con i form campione a lunghezza fissa con cui tutti provano per primi, e i motivi valgono la pena di essere conosciuti se incorporate un viewer di form

Che cosa succede quando un form XFA dinamico si ripagina?

Un form XFA dinamico non ha una lista di pagine fissa, quindi il suo conteggio pagine è un output del layout e può cambiare ogni volta che l'utente modifica i dati. XFA 3.3 descrive il form come un albero di subform; un subform ripetuto è governato da un instanceManager, e uno script come _Row.addInstance() clona un'altra riga. Il processore di layout poi riversa di nuovo il contenuto nelle aree di pagina, il che può aggiungere una pagina, toglierne una o spingere campi esistenti su un'altra pagina. ISO 32000-1 §12.7.8 definisce solo come i pacchetti XFA viaggiano dentro il PDF; tutto ciò che succede dopo appartiene al motore XFA, che in PDFium Component è il layout XFA di PDFium stesso in esecuzione nel processo host. Un viewer Delphi quindi ha a che fare con un documento il cui conteggio pagine, le cui dimensioni di pagina e le cui posizioni dei widget sono tutti stato vivo. Tre cose vanno storte quando l'host presume il contrario:

  • Il conteggio pagine che l'host tiene in cache per navigazione, intervalli di scroll e spinner di pagina diventa stantio, o peggio, viene aggiornato con il numero sbagliato
  • I campi che si rilocano mostrano il bordo nella nuova posizione mentre l'editor e l'area di hit del mouse restano alle vecchie coordinate
  • Il viewer conserva un handle di pagina che il layout ha sostituito, così clic e disegnate vanno a una pagina che in quel form non esiste più

Fare sopravvivere le modifiche delle righe attraverso salvataggio e riapertura è un problema a parte con le sue regole; questo articolo resta su ciò che succede a runtime dentro il viewer

Quale runtime PDFium serve a XFA dinamico?

XFA dinamico in PDFium Component richiede la build V8/XFA della libreria nativa, selezionata dalla variabile globale EnableV8Engine nell'unità PDFium prima che il primo documento si carichi. Il processo si impegna su una DLL la prima volta che un qualsiasi TPdf carica la libreria, e una build PDFium semplice non può far girare per niente il motore XFA. Quando un documento si apre, TPdf sbircia nel file in cerca di marker XFA e passa alla build V8 da solo, ma solo se nel processo non è ancora stata caricata alcuna libreria semplice. Quando l'impegno è già andato nel verso sbagliato, TPdf.OnXfaRuntimeMissing scatta una volta sola così l'host può dire all'utente di riavviare. Impostare il flag esplicitamente all'avvio toglie ogni congettura. Anche la struttura di callback FPDF_FORMFILLINFO che porta gli eventi XFA deve combaciare con la DLL; il contesto è in FPDF_FORMFILLINFO versione 2 e l'ABI dei callback XFA, e rilevare i form XFA e leggere i loro pacchetti copre come distinguere i tipi di form prima di aprire un viewer

uses
  PDFium;

procedure TClaimForm.FormCreate(Sender: TObject);
begin
  // Decidi prima che il primo TPdf carichi la libreria nativa:
  // il processo non può passare da pdfium.dll a pdfium.v8.dll più tardi
  EnableV8Engine := True;

  FPdf := TPdf.Create(nil);
  FPdf.OnXfaRuntimeMissing := PdfXfaRuntimeMissing;
  FPdf.OnXfaPageCountChanged := PdfXfaPageCountChanged;
  FPdf.FileName := 'C:\Forms\expense-claim.pdf';
  FPdf.Active := True;

  PdfView1.Pdf := FPdf;
  PdfView1.OnPageChange := PdfViewPageChange;
  PdfView1.Active := True;

  UpdatePageRange(FPdf.PageCount);
end;

procedure TClaimForm.PdfXfaRuntimeMissing(Sender: TObject);
begin
  StatusBar1.SimpleText :=
    'This XFA form needs the V8 runtime; restart the application to enable it';
end;

Perché PageCount riporterebbe 1 per un form di due pagine?

Un wrapper che memorizza l'argomento page_count dell'evento pagina nativo come totale del documento sbaglia, perché quell'argomento in realtà è la differenza assoluta tra il nuovo e il vecchio conteggio pagine. PDFium solleva FFI_PageEvent dopo che un passaggio di layout è finito, con un tipo di evento pagina aggiunta o pagina rimossa; internamente aggiorna prima il proprio conteggio pagine memorizzato e poi passa abs(new - old). Sul layout iniziale il vecchio conteggio è zero, quindi il delta eguaglia il totale, e un campione statico di tre pagine riporta tre pagine come previsto. È esattamente per questo che i form di test a lunghezza fissa non espongono mai l'errore. La prima volta che un form dinamico cresce da una pagina a due, il delta è 1, e un wrapper simile riporta un conteggio pagine di 1. Togliere una riga a un form di tre pagine produce lo stesso tipo di assurdo nell'altra direzione

Accumulare il delta sul valore precedente non è una riparazione sicura neanche quella. L'ordine dei callback di inizializzazione e layout fa sì che il wrapper non possa sempre fidarsi del proprio conteggio precedente come baseline, quindi una somma progressiva può divergere. Per questo il callback di PDFium Component ignora l'argomento come conteggio e chiama FPDF_GetPageCount sul documento, che legge il totale dal layout appena completato. Poi pulisce le scene di pagina in cache, memorizza quel totale come override del conteggio pagine XFA dietro a TPdf.PageCount, e solo dopo solleva OnXfaPageCountChanged. Per il momento in cui il vostro handler gira, NewCount e FPdf.PageCount sono d'accordo

Diagramma XFA dinamico PDFium Component in cui aggiungere una riga ripagina un form di una pagina in due pagine e FFI_PageEvent passa abs(nuovo meno vecchio) come delta, così trattarlo come totale riporterebbe un conteggio pagine di 1, mentre PDFium Component legge FPDF_GetPageCount e riporta il totale corretto
L'evento pagina nativo riporta un delta aggiunto-o-rimosso, non un totale, quindi PDFium Component ignora l'argomento e legge il layout completato prima di sollevare OnXfaPageCountChanged
procedure TClaimForm.PdfXfaPageCountChanged(Sender: TObject; NewCount: Integer);
begin
  // NewCount è il totale del layout completato, mai un delta.
  // Questo gira dentro il callback di layout di PDFium: aggiornate solo lo stato
  // UI dell'host, non chiudere il documento né ricaricare pagine da qui
  UpdatePageRange(NewCount);
end;

procedure TClaimForm.PdfViewPageChange(Sender: TObject);
begin
  // Scatta dopo ogni ricaricamento di pagina, compreso il refresh XFA differito
  PageSpin.Value := PdfView1.PageNumber;
end;

procedure TClaimForm.UpdatePageRange(Count: Integer);
begin
  PageSpin.MinValue := 1;
  PageSpin.MaxValue := Count;
  PageLabel.Caption := Format('of %d', [Count]);
end;

L'evento scatta solo per i form Full XFA il cui layout cambia a runtime. I documenti Static XFA e AcroForm non lo sollevano mai, quindi un viewer che gestisce entrambi può lasciare assegnato lo stesso handler. Lasciarlo non assegnato è sicuro a sua volta; l'override dietro a TPdf.PageCount viene applicato comunque, e l'evento esiste perché l'host possa rinfrescare ciò che aveva in cache

Perché la casella di input resta sulla vecchia pagina quando un campo si sposta?

Il bordo si sposta e l'editor no quando il notifier XFA nativo confronta un rettangolo con sé stesso. Quando il layout cambia la geometria di un widget già caricato, PDFium dovrebbe accorgersene e chiamare PerformLayout sul widget, che riposiziona l'editor di testo e la sua area di hit. Un controllo che confronti GetWidgetRect() con RecacheWidgetRect() non può mai scattare: entrambe le funzioni restituiscono un riferimento const allo stesso membro, e il ricache sovrascrive quel membro sul posto, così il confronto vede sempre due valori identici e i widget caricati saltano il loro relayout

Il sintomo compare quando l'altezza di un subform cambia così che i campi esistenti attraversino la pagina successiva: il bordo del campo viene disegnato nella nuova posizione mentre il testo digitato e l'area di hit del mouse restano alla coordinata Y precedente. Un relayout esplicito non aiuta, e nemmeno ricaricare la pagina, perché il widget continua a credere che la sua geometria sia aggiornata. Le librerie V8 Windows che viaggiano con PDFium Component copiano il vecchio rettangolo per valore prima del ricache e confrontano quella copia, così i widget spostati fanno relayout e il valore modificato appare esattamente dove sta il bordo. Il controllo vive nel codice nativo e viaggia con le DLL, quindi spedite pdfium.v8.dll insieme alle unità Pascal. Per provarlo per conto vostro, modificate prima una riga superstite con un valore non predefinito e poi cercate quel valore nella nuova posizione del campo, perché una riga ricostruita coi valori predefiniti sembrerebbe altrimenti un passaggio

Diagramma di relayout widget PDFium Component che contrappone un'auto-confrontazione in cui GetWidgetRect e RecacheWidgetRect restituiscono un membro condiviso così i widget spostati saltano PerformLayout, con il controllo copy-by-value Windows V8 che riposiziona l'editor e l'area di hit del mouse sul bordo ridisegnato
Confrontare un rettangolo con sé stesso non rileva mai un cambiamento, così il bordo si sposta mentre testo digitato e clic restano indietro a meno che il controllo non salvi prima una copia per valore

Come ricarica le pagine TPdfView senza tirare via un handle dall'interno di PDFium?

TPdfView differisce il ricaricamento di pagina che segue un cambio di layout XFA finché lo stack di chiamate nativo non si è scaricato. L'evento pagina di solito scatta mentre PDFium sta ancora processando l'input: l'utente ha cliccato un pulsante Add Row, il click ha fatto girare uno script, lo script ha cambiato il conteggio delle istanze, e il layout è finito dentro quella stessa chiamata nativa. Chiudere e riaprire l'handle di pagina in quel momento libererebbe un oggetto che il chiamante sta ancora usando. Un viewer che in quel punto si limita a invalidarsi conserva un handle di pagina che punta allo stato pre-layout, e se l'utente era sull'ultima pagina quando questa è sparita, il numero di pagina selezionato è fuori intervallo

Il refresh differito funziona in pochi piccoli passi, e spiegano il comportamento che vedi dall'host:

  1. Il callback dell'evento pagina marca la vista come in attesa di un refresh del layout XFA e posta un messaggio di finestra privato; gli eventi ripetuti prima che il messaggio arrivi si fondono in un unico refresh
  2. Una vista senza ancora un handle di finestra conserva il flag in attesa e posta il messaggio da CreateWnd, mentre cambiare documento, disattivare la vista o distruggerla pulisce il flag
  3. Quando il messaggio arriva, la vista pulisce la selezione di testo, l'evidenziazione di ricerca e l'indice del campo con focus, perché tutti e tre si riferivano al vecchio layout
  4. La pagina selezionata viene limitata al nuovo PageCount; un numero di pagina cambiato passa per il normale cambio di pagina, altrimenti la pagina corrente viene ricaricata, e la modalità di adattamento viene riapplicata
  5. Se il layout non lascia proprio nessuna pagina, la vista scarica il suo vecchio handle di pagina invece di disegnare una pagina che non esiste più
Diagramma del refresh XFA differito di TPdfView in PDFium Component in cui un evento pagina dentro lo stack di chiamate del layout nativo marca soltanto un refresh in attesa e posta un messaggio di finestra, che più tardi pulisce lo stato di selezione stantio, limita la pagina al nuovo PageCount e ricarica o scarica l'handle di pagina
Il ricaricamento aspetta che lo stack di chiamate nativo si scarichi: un messaggio postato fonde gli eventi ripetuti, poi la vista limita la pagina, la ricarica e solleva OnPageChange

Lo stesso vincolo vale per il tuo codice. OnXfaPageCountChanged gira dentro quel callback di layout nativo, quindi trattalo come una notifica: aggiorna etichette, intervalli dello spinner e stato della toolbar lì, e metti in coda tutto ciò che è più pesante, come chiudere il documento o aprirne un altro, con un messaggio postato così gira dopo che il callback è tornato. TPdfView.OnPageChange poi ti dice quando la vista ha davvero ricaricato la pagina, e leggere PdfView1.PageNumber in quel punto ti dà il valore limitato. L'attraversamento col tasto Tab e i controlli FormType che un viewer di form esegue all'apertura sono coperti in navigazione dei campi form PDF con PDFium Component

Come tratta il viewer le pagine Full XFA che non hanno layer di testo?

Le pagine Full XFA non hanno una pagina di testo PDF, quindi qualsiasi cosa chieda una di quelle pagine fallisce con un errore Cannot open text page. La selezione testuale predefinita di un viewer e il rilevamento dei link consultano entrambi quel layer: con TPdfView.AllowUserTextSelection al suo default di True, il passaggio del mouse chiede al layer di testo il carattere sotto il cursore, e un click con rilascio del mouse fa una sonda URL automatica sul testo di pagina. In TPdfView entrambi i percorsi interni restituiscono nessun risultato quando TPdf.FormType è ftXfaFull e il runtime XFA è disponibile, così le impostazioni predefinite funzionano e l'input nei campi resta disponibile

Spegnere AllowUserTextSelection per i documenti Full XFA è una scelta di UI ragionevole, perché non c'è testo di pagina da selezionare e i gesti di trascinamento non dovrebbero avviare una modalità di selezione

procedure TClaimForm.ConfigureViewerForForm;
begin
  // FormType legge il documento aperto, quindi chiama questo dopo FPdf.Active := True
  if FPdf.XFA and (FPdf.FormType = ftXfaFull) and FPdf.XfaRuntimeAvailable then
  begin
    // Nessun layer di testo PDF esiste sulle pagine Full XFA; i campi restano modificabili
    PdfView1.AllowUserTextSelection := False;
    StatusBar1.SimpleText := Format('Dynamic XFA form, %d page(s)',
      [FPdf.PageCount]);
  end
  else
    PdfView1.AllowUserTextSelection := True;
end;

La digitazione sopra una selezione richiede una gestione propria. L'editor di testo XFA nativo non sostituisce una selezione quando riceve un carattere: FORM_OnChar inserisce al cursore, e Backspace cancella un solo carattere, quindi passare i tasti dritti metterebbe il vecchio e il nuovo testo fianco a fianco. PDFium Component ricorda che il click è caduto su un campo testuale XFA e instrada i caratteri digitati, Backspace e Delete attraverso FORM_ReplaceSelection ogni volta che esiste una selezione e il documento concede il permesso di compilare o modificare. Se un campo XFA a sola lettura possa cambiare lo decide l'editor nativo, quindi un campo marcato a sola lettura nel form conserva il suo valore anche in un documento che altrimenti consente la compilazione. Impostare TPdfView.AllowFormEvents a False ferma anche questo instradamento della tastiera, il che mantiene un viewer a sola lettura a sola lettura

Riferimento rapido: XFA dinamico in un viewer Delphi

SintomoCausaGestito da
Il conteggio pagine mostra 1 dopo che il form è cresciuto a due pagineL'evento pagina nativo passa un delta aggiunte/rimozioni, non un totaleTPdf.PageCount legge il layout completato
Il bordo del campo si sposta, testo digitato e area di hit restano indietroIl widget caricato salta il relayout dopo un'auto-confrontazioneControllo copy-by-value nelle librerie Windows V8
Il viewer disegna o instrada l'input allo stato di pagina pre-layoutHandle di pagina non ricaricato dopo la ripaginazioneRefresh differito in TPdfView
Il click in un campo chiede una pagina di testo che non esisteSelezione testuale e sonda URL su pagine senza layer di testoI percorsi di testo non restituiscono risultato sulle pagine ftXfaFull
Digitare sopra un valore selezionato accoda anziché sostituireL'editor XFA nativo inserisce al cursoreTasti instradati attraverso FORM_ReplaceSelection
  • Imposta EnableV8Engine a True prima che qualsiasi documento si carichi, e gestisci OnXfaRuntimeMissing per il caso in cui la libreria semplice sia stata caricata per prima
  • Leggi il totale da TPdf.PageCount o dal parametro NewCount di OnXfaPageCountChanged; non aggiungere o sottrarre mai conteggi di pagina da te
  • Tieni leggero l'handler di OnXfaPageCountChanged, perché gira dentro il callback di layout nativo
  • Sincronizza l'indicatore della pagina corrente in TPdfView.OnPageChange, che scatta dopo che il ricaricamento differito ha limitato il numero di pagina
  • Distribuite le DLL Windows V8 insieme alle unità; il controllo del relayout dei widget vive nel codice nativo
  • Prova con un form che cambia davvero il proprio conteggio pagine e sposta un campo modificato attraverso un'interruzione di pagina, perché i campioni a lunghezza fissa nascondono ogni problema di questa lista

XFA dinamico trasforma conteggio pagine e geometria dei campi in valori vivi, e un viewer resta corretto solo quando li prende dal layout completato e ricarica le pagine in un momento sicuro. PDFium Component gestisce entrambe le cose dentro TPdf e TPdfView, quindi all'host resta solo da ascoltare. Dettagli e download sono sulla pagina prodotto di PDFium Component for Delphi