Gdy dynamiczny formularz XFA w viewerze Delphi dodaje albo usuwa strony, PDFium Component zgłasza nową sumę przez TPdf.PageCount i TPdf.OnXfaPageCountChanged, czytając ją z ukończonego layoutu, bo natywne zdarzenie strony niesie deltę dodano/usunięto, a nie sumę. Biblioteki Windows V8 przeprowadzają też obszary trafień wejścia razem z przeprowadzonymi polami, a TPdfView wczytuje uchwyty stron ponownie po powrocie callbacka layoutu. Wyobraź sobie formularz wniosku o zwrot wydatków: kliknij Dodaj wiersz dwa razy i formularz urośnie do dwóch stron. Viewer, który ufa argumentowi zdarzenia, dumnie czyta 1 z 1, a taki, który trzyma geometrię widgetów sprzed layoutu, wysyła klawisze dla pola, które przeprowadziło się na stronę 2, gdzieś niewidocznie. Nic z tego nie wychodzi na przykładowych formularzach o stałej długości, od których każdy zaczyna testy, a powody warto znać, gdy osadzasz viewer formularzy
Co się dzieje, gdy dynamiczny formularz XFA się repaginuje?
Dynamiczny formularz XFA nie ma sztywnej listy stron, więc jego liczba stron jest wynikiem layoutu i może się zmieniać przy każdej edycji danych przez użytkownika. XFA 3.3 opisuje formularz jako drzewo subformów; powtarzalnym subformem steruje instanceManager, a skrypt typu _Row.addInstance() klonuje kolejny wiersz. Procesor layoutu przelewa potem treść do obszarów stron od nowa, co może dodać stronę, zabrać stronę albo wepchnąć istniejące pola na inną stronę. ISO 32000-1 §12.7.8 definiuje wyłącznie to, jak pakiety XFA jadą wewnątrz PDF; wszystko, co dzieje się potem, należy do silnika XFA, którym w PDFium Component jest własny layout XFA PDFiuma działający w procesie gospodarza. Viewer w Delphi ma więc do czynienia z dokumentem, którego liczba stron, rozmiary stron i pozycje widgetów to żywy stan. Trzy rzeczy idą źle, gdy gospodarz zakłada inaczej:
- liczba stron cache'owana przez gospodarza do nawigacji, zakresów przewijania i spinerów stron robi się nieaktualna albo, gorzej, zostaje zaktualizowana złą liczbą
- pola, które się przeprowadzają, pokazują obramowanie na nowym miejscu, podczas gdy edytor i obszar trafień myszy siedzą na starych współrzędnych
- viewer trzyma uchwyt strony, który layout podmienił, więc kliki i rysowanie idą do strony, która w tym formularzu już nie istnieje
Utrwalanie edycji wierszy przez zapis i ponowne otwarcie to osobny problem z własnymi regułami; ten artykuł zostaje przy tym, co dzieje się w trakcie działania wewnątrz viewera
Jakiego runtime'u PDFium potrzebuje dynamiczne XFA?
Dynamiczne XFA w PDFium Component wymaga builda V8/XFA biblioteki natywnej, wybieranego globalną zmienną EnableV8Engine z modułu PDFium przed wczytaniem pierwszego dokumentu. Proces wiąże się z jedną biblioteką DLL przy pierwszym wczytaniu biblioteki przez dowolny TPdf, a zwykły build PDFium nie uruchomi silnika XFA w ogóle. Przy otwarciu dokumentu TPdf zajrzyje do pliku pod kątem znaczników XFA i przełączy się na build V8 automatycznie, ale tylko jeśli żaden zwykły nie został jeszcze wczytany w tym procesie. Gdy związanie poszło już złą stroną, TPdf.OnXfaRuntimeMissing odpala się raz, żeby gospodarz mógł kazać użytkownikowi zrestartować aplikację. Jawne ustawienie flagi na starcie usuwa zgadywanie. Struktura callbacków FPDF_FORMFILLINFO niosąca zdarzenia XFA też musi pasować do biblioteki DLL; tło opisuje FPDF_FORMFILLINFO wersja 2 i ABI callbacków XFA, a wykrywanie formularzy XFA i czytanie ich pakietów pokazuje, jak odróżnić typy formularzy, zanim otworzysz viewer
uses
PDFium;
procedure TClaimForm.FormCreate(Sender: TObject);
begin
// Zdecyduj, zanim pierwszy TPdf wczyta bibliotekę natywną:
// proces nie może później przejść z pdfium.dll na pdfium.v8.dll
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;
Dlaczego PageCount raportuje 1 dla formularza o dwóch stronach?
Wrapper, który zapisuje argument page_count natywnego zdarzenia strony jako sumę dokumentu, myli się, bo ten argument to w rzeczywistości bezwzględna różnica między nową a starą liczbą stron. PDFium podnosi FFI_PageEvent po zakończeniu przebiegu layoutu z typem zdarzenia strona dodana albo strona usunięta; wewnętrznie najpierw aktualizuje swoją zapamiętaną liczbę stron, a potem przekazuje abs(new - old). Przy początkowym layoutcie stara liczba to zero, więc delta równa się sumie, i trójstronicowy statyczny przykład zgłasza trzy strony, jak trzeba. Dokładnie dlatego formularze testowe o stałej długości nigdy nie obnażają tego błędu. Gdy dynamiczny formularz pierwszy raz urośnie z jednej strony do dwóch, delta wynosi 1, i taki wrapper raportuje liczbę stron 1. Usunięcie wiersza z trójstronicowego formularza produkuje ten sam rodzaj bezsensu w drugą stronę
Sumowanie delty na poprzednią wartość to też nie jest bezpieczna łata. Kolejność callbacków inicjalizacji i layoutu oznacza, że wrapper nie zawsze może ufać swojej wcześniejszej liczbie jako bazy, więc biegnąca suma może dryfować. Callback PDFium Component dlatego ignoruje argument jako liczbę i woła FPDF_GetPageCount na dokumencie, który czyta sumę z layoutu, właśnie co ukończonego. Potem czyści cache'owane sceny stron, zapisuje tę sumę jako nadpisanie liczby stron XFA za TPdf.PageCount i dopiero po tym podnosi OnXfaPageCountChanged. Kiedy twój handler się wykonuje, NewCount i FPdf.PageCount się zgadzają
procedure TClaimForm.PdfXfaPageCountChanged(Sender: TObject; NewCount: Integer);
begin
// NewCount to suma ukończonego layoutu, nigdy delta.
// To wykonuje się wewnątrz callbacka layoutu PDFium: aktualizuj tylko stan UI gospodarza,
// nie zamykaj dokumentu ani nie wczytuj stron stąd
UpdatePageRange(NewCount);
end;
procedure TClaimForm.PdfViewPageChange(Sender: TObject);
begin
// Odpala się po każdym ponownym wczytaniu strony, łącznie z odroczonym odświeżeniem XFA
PageSpin.Value := PdfView1.PageNumber;
end;
procedure TClaimForm.UpdatePageRange(Count: Integer);
begin
PageSpin.MinValue := 1;
PageSpin.MaxValue := Count;
PageLabel.Caption := Format('of %d', [Count]);
end;
Zdarzenie odpala się wyłącznie dla formularzy Full XFA, których layout zmienia się w trakcie działania. Statyczne XFA i dokumenty AcroForm nigdy go nie podnoszą, więc viewer obsługujący oba może zostawić ten sam handler podpięty. Pozostawienie go niepodpiętym też jest bezpieczne; nadpisanie za TPdf.PageCount działa tak czy inaczej, a zdarzenie istnieje po to, żeby gospodarz odświeżył to, co cache'ował
Dlaczego pole wprowadzania zostaje na starej stronie, gdy pole się przeprowadza?
Obramowanie się przeprowadza, a edytor nie, gdy natywny notyfikator XFA porównuje prostokąt z nim samym. Gdy layout zmienia geometrię widgeta już wczytanego, PDFium powinien zauważyć nowy prostokąt i zawołać PerformLayout na widgetcie, co przestawia edytor tekstu i jego obszar trafień. Sprawdzenie porównujące GetWidgetRect() z RecacheWidgetRect() nie może nigdy odpalić: obie funkcje zwracają const referencję do tego samego pola, a recache nadpisuje to pole w miejscu, więc porównanie zawsze widzi dwie identyczne wartości i wczytane widgety pomijają swój relayout
Objaw wychodzi na jaw, gdy zmiana wysokości subformu sprawia, że istniejące pola przeskakują na następną stronę: obramowanie pola jest rysowane na nowym miejscu, podczas gdy wpisany tekst i obszar trafień myszy siedzą na poprzedniej współrzędnej Y. Jawne wymuszenie relayoutu nie pomaga, i ponowne wczytanie strony też nie, bo widget nadal wierzy, że jego geometria jest aktualna. Biblioteki Windows V8 rozprowadzane z PDFium Component kopiują stary prostokąt przez wartość przed recachowaniem i porównują tę kopię, więc przeprowadzone widgety robią relayout, a edytowana wartość pojawia się dokładnie tam, gdzie jest obramowanie. Sprawdzenie mieszka w kodzie natywnym i podróżuje z bibliotekami DLL, więc rozprowadzaj pdfium.v8.dll razem z modułami Pascala. Żeby przetestować samodzielnie, najpierw ustaw w przeżywającym wierszu wartość inną niż domyślna, a potem szukaj tej wartości w nowym położeniu pola, bo wiersz przebudowany z wartościami domyślnymi wyglądałby inaczej na zaliczony
Jak TPdfView wczytuje strony ponownie, nie wyrywając uchwytu sprzed PDFium?
TPdfView odracza ponowne wczytanie strony następujące po zmianie layoutu XFA, aż natywny stos wywołań się rozwinie. Zdarzenie strony zwykle odpala się, gdy PDFium wciąż przetwarza wejście: użytkownik kliknął przycisk Dodaj wiersz, klik wykonał skrypt, skrypt zmienił liczbę instancji, a layout skończył się wewnątrz tego samego natywnego wywołania. Zamknięcie i ponowne otwarcie uchwytu strony w tym momencie uwolniłoby obiekt, którego wołający wciąż używa. Viewer, który w tym punkcie tylko unieważnia siebie, trzyma uchwyt strony wskazujący na stan sprzed layoutu, a jeśli użytkownik był na ostatniej stronie, gdy ta zniknęła, wybrany numer strony jest poza zakresem
Odroczone odświeżanie działa w kilku małych krokach, które tłumaczą zachowanie widziane od strony gospodarza:
- callback zdarzenia strony oznacza widok jako mający oczekujące odświeżenie layoutu XFA i wysyła prywatny komunikat okienkowy; powtórzone zdarzenia przed dotarciem komunikatu scaliłyby się w jedno odświeżenie
- widok bez uchwytu okna trzyma na razie flagę oczekującą i wysyła komunikat z
CreateWnd, a zmiana dokumentu, deaktywacja widoku albo jego zniszczenie czyszczą flagę - gdy komunikat dociera, widok czyści zaznaczenie tekstu, podświetlenie wyszukiwania i indeks pola z fokusem, bo wszystkie trzy odnosiły się do starego layoutu
- wybrana strona jest przycinana do nowego
PageCount; zmieniony numer strony idzie przez normalne przełączenie strony, w przeciwnym razie bieżąca strona jest wczytywana ponownie, a tryb dopasowania stosuje się jeszcze raz - jeśli layout nie zostawia żadnych stron, widok wyładowuje stary uchwyt strony, zamiast rysować stronę, która już nie istnieje
To samo ograniczenie dotyczy twojego własnego kodu. OnXfaPageCountChanged wykonuje się wewnątrz natywnego callbacka layoutu, więc traktuj go jak powiadomienie: aktualizuj tam etykiety, zakresy spinerów i stan paska narzędzi, a wszystko cięższe, jak zamknięcie dokumentu albo otwarcie innego, kolejkuj wysłanym komunikatem, żeby wykonało się po powrocie callbacka. TPdfView.OnPageChange mówi ci potem, kiedy widok faktycznie wczytał stronę ponownie, a odczyt PdfView1.PageNumber w tym momencie daje wartość przyciętą. Nawigowanie Tabem i sprawdzenia FormType, które viewer formularzy robi przy otwarciu, opisuje nawigacja po polach formularzy PDF z PDFium Component
Jak viewer traktuje strony Full XFA, które nie mają warstwy tekstu?
Strony Full XFA nie mają tekstowej strony PDF, więc cokolwiek, co o taką stronę prosi, zawodzi z błędem Cannot open text page. Domyślne zaznaczanie tekstu i wykrywanie linków w viewerze oba sięgają do tej warstwy: przy TPdfView.AllowUserTextSelection na domyślnym True najechanie proszi warstwę tekstu o znak pod myszą, a kliknięcie puszczenia myszy uruchamia automatyczną sondę URL po tekście strony. W TPdfView obie wewnętrzne ścieżki zwracają brak wyniku, gdy TPdf.FormType to ftXfaFull, a runtime XFA jest dostępny, więc ustawienia domyślne działają, a wprowadzanie w pola zostaje dostępne
Wyłączenie AllowUserTextSelection dla dokumentów Full XFA to rozsądny wybór w UI, bo nie ma tekstu strony do zaznaczenia, a gesty przeciągania nie powinny startować trybu zaznaczania
procedure TClaimForm.ConfigureViewerForForm;
begin
// FormType czyta otwarty dokument, więc wołaj to po FPdf.Active := True
if FPdf.XFA and (FPdf.FormType = ftXfaFull) and FPdf.XfaRuntimeAvailable then
begin
// Na stronach Full XFA nie ma warstwy tekstu PDF; pola zostają edytowalne
PdfView1.AllowUserTextSelection := False;
StatusBar1.SimpleText := Format('Dynamic XFA form, %d page(s)',
[FPdf.PageCount]);
end
else
PdfView1.AllowUserTextSelection := True;
end;
Pisanie po zaznaczeniu potrzebuje własnej obsługi. Natywny edytor tekstu XFA nie zastępuje zaznaczenia, gdy dostaje znak: FORM_OnChar wstawia przy kursorze, a Backspace kasuje pojedynczy znak, więc przepuszczenie klawiszy wprost postawiłoby stary i nowy tekst obok siebie. PDFium Component pamięta, że klik wylądował na polu tekstowym XFA, i kieruje wpisane znaki, Backspace oraz Delete przez FORM_ReplaceSelection zawsze, gdy zaznaczenie istnieje, a dokument daje prawo wypełniania formularzy albo modyfikacji. O tym, czy pole XFA tylko do odczytu może się zmienić, decyduje edytor natywny, więc pole oznaczone w formularzu jako read-only trzyma swoją wartość nawet w dokumencie, który poza tym pozwala wypełniać. Ustawienie TPdfView.AllowFormEvents na False też zatrzymuje to kierowanie klawiatury, co sprawia, że viewer przeznaczony tylko do odczytu taki pozostaje
Ściąga: dynamiczne XFA w viewerze Delphi
| Objaw | Przyczyna | Obsługiwane przez |
|---|---|---|
| Liczba stron pokazuje 1, gdy formularz urośnie do dwóch stron | Natywne zdarzenie strony przekazuje deltę dodano/usunięto, nie sumę | TPdf.PageCount czyta ukończony layout |
| Obramowanie pola się przeprowadza, wpisany tekst i obszar trafień zostają | Wczytany widget pomija relayout po porównaniu samego siebie | Kontrola z kopią przez wartość w bibliotekach Windows V8 |
| Viewer rysuje albo kieruje wejście do stanu strony sprzed layoutu | Uchwyt strony niewczytany ponownie po repaginacji | Odroczone odświeżanie w TPdfView |
| Klik w pole prosi o tekstową stronę, która nie istnieje | Zaznaczanie tekstu i sonda URL na stronach bez warstwy tekstu | Ścieżki tekstu zwracają brak wyniku na stronach ftXfaFull |
| Pisanie po zaznaczonej wartości dokleja zamiast zastępować | Natywny edytor XFA wstawia przy kursorze | Klawisze kierowane przez FORM_ReplaceSelection |
- Ustaw
EnableV8EnginenaTrue, zanim jakikolwiek dokument się wczyta, i obsłużOnXfaRuntimeMissingna wypadek, gdy najpierw wczytano bibliotekę zwykłą - Czytaj sumę z
TPdf.PageCountalbo z parametruNewCountOnXfaPageCountChanged; nigdy nie dodawaj ani nie odejmuj liczb stron samodzielnie - Trzymaj handler
OnXfaPageCountChangedlekki, bo wykonuje się wewnątrz natywnego callbacka layoutu - Synchronizuj wskaźnik bieżącej strony w
TPdfView.OnPageChange, które odpala się po tym, jak odroczone ponowne wczytanie przycina numer strony - Rozprowadzaj biblioteki DLL Windows V8 razem z modułami; kontrola relayoutu widgetów mieszka w kodzie natywnym
- Testuj na formularzu, który faktycznie zmienia liczbę stron i przenosi edytowane pole przez łamanie strony, bo próbki o stałej długości ukrywają każdy problem z tej listy
Dynamiczne XFA zamienia liczbę stron i geometrię pól w wartości żywe, a viewer pozostaje poprawny tylko wtedy, gdy bierze je z ukończonego layoutu i wczytuje strony ponownie w bezpiecznym momencie. PDFium Component załatwia jedno i drugie wewnątrz TPdf i TPdfView, więc gospodarz musi tylko słuchać. Szczegóły i pobieranie są na stronie produktu PDFium Component for Delphi