Teknik Makale

PDFium Component Dynamic XFA: sayfa sayısı bir farktır

Bir Delphi görüntüleyicideki dinamik bir XFA formu sayfa eklediğinde ya da çıkardığında PDFium Component, yeni toplamı TPdf.PageCount ve TPdf.OnXfaPageCountChanged üzerinden bildirir ve onu tamamlanmış layout'tan okur; çünkü yerel page event, toplam değil eklenen/çıkarılan bir delta taşır. Windows V8 kütüphaneleri ayrıca yer değiştiren field'larla birlikte giriş vuruş alanlarını da taşır ve TPdfView, layout callback'i döndükten sonra sayfa handle'larını yeniden yükler. Bir masraf beyan formu düşünün: Add Row'ya iki kez tıklayın ve form iki sayfaya büyür. Olay argümanına güvenen bir görüntüleyici gururla 1 of 1 okur; layout öncesi widget geometrisini tutan biri ise 2. sayfaya taşınmış bir field'a yazılmak istenen tuş vuruşlarını görünmez bir yere gönderir. Herkesin ilk önce test ettiği sabit uzunluklu örnek formlarda bunların hiçbiri görünmez; nedenlerini bilmek, bir form görüntüleyici gömüyorsanız değer

Dinamik bir XFA formu yeniden sayfalandığında ne olur?

Dinamik bir XFA formunun sabit bir sayfa listesi yoktur; dolayısıyla sayfa sayısı layout'un bir çıktısıdır ve kullanıcı veri düzenlediği her seferde değişebilir. XFA 3.3, formu bir subform ağacı olarak tanımlar; yinelenen bir subform bir instanceManager tarafından denetlenir ve _Row.addInstance() gibi bir script bir satır daha klonlar. Layout işlemcisi sonra içeriği sayfa alanlarına yeniden akıtır; bu bir sayfa ekleyebilir, bir sayfa düşürebilir ya da var olan field'ları başka bir sayfaya itebilir. ISO 32000-1 §12.7.8 yalnızca XFA paketlerinin PDF içinde nasıl seyahat ettiğini tanımlar; ondan sonra olan her şey XFA motoruna aittir, PDFium Component'te bu da ana sürecin içinde koşan PDFium'un kendi XFA layout'udur. Bir Delphi görüntüleyici bu yüzden sayfa sayısı, sayfa boyutları ve widget konumları canlı durum olan bir belgeyle uğraşır. Ana süreç aksini varsaydığında üç şey ters gider:

  • Ana sürecin navigation, kaydırma aralıkları ve sayfa spinner'ları için cache'lediği sayfa sayısı bayatlar; daha kötüsü yanlış sayıyla güncellenir
  • Yer değiştiren field'lar kenarlıklarını yeni konumda gösterirken editor ile fare vuruş alanı eski koordinatlarda kalır
  • Görüntüleyici, layout'un yerini aldığı bir sayfa handle'ını tutmaya devam eder; dolayısıyla tıklamalar ve boyamalar o formda artık var olmayan bir sayfaya gider

Satır düzenlemelerini kaydetme ve yeniden açma boyunca kalıcı kılmak kendi kuralları olan ayrı bir sorundur; bu yazı, görüntüleyicinin içinde çalışma zamanında olanlarla kalır

Dinamik XFA hangi PDFium runtime'ına gerek duyar?

PDFium Component'te dinamik XFA, yerel kütüphanenin V8/XFA derlemesini gerektirir; ilk belge yüklenmeden PDFium unit'indeki global EnableV8Engine değişkeniyle seçilir. Süreç, herhangi bir TPdf kütüphaneyi ilk yüklediğinde tek bir DLL'ye bağlanır ve sade bir PDFium derlemesi XFA motorunu hiç çalıştıramaz. Bir belge açıldığında TPdf dosyada XFA işaretlerine göz atar ve V8 derlemesine otomatik geçer; ama yalnızca o süreçte henüz sade bir kütüphane yüklenmemişse. Bağlılık yanlış yöne gitmişse TPdf.OnXfaRuntimeMissing bir kez ateşlenir; ana süreç böylece kullanıcıya yeniden başlatmayı söyleyebilir. Bayrağı başlangıçta açıkça set etmek tahmini ortadan kaldırır. XFA olaylarını taşıyan FPDF_FORMFILLINFO callback yapısının da DLL ile eşleşmesi gerekir; arka planı FPDF_FORMFILLINFO sürüm 2 ve XFA callback ABI'si yazısında, form tiplerini görüntüleyici açmadan ayırt etme ise XFA formlarını saptama ve paketlerini okuma yazısında

uses
  PDFium;

procedure TClaimForm.FormCreate(Sender: TObject);
begin
  // İlk TPdf yerel kütüphaneyi yüklemeden önce karar verin:
  // süreç, pdfium.dll'den pdfium.v8.dll'ye sonra geçemez
  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;

PageCount iki sayfalık bir form için neden 1 bildirir?

Yerel page event'in page_count argümanını belge toplamı diye saklayan bir wrapper yanıltır; çünkü o argüman aslında yeni ile eski sayfa sayıları arasındaki mutlak farktır. PDFium, bir layout geçişi page eklendi ya da page çıkarıldı olay tipiyle bittiğinde FFI_PageEvent yükseltir; içeride önce sakladığı sayfa sayısını günceller, sonra abs(new - old) geçirir. İlk layout'ta eski sayı sıfırdır; dolayısıyla delta toplama eşittir ve üç sayfalık statik bir örnek, beklendiği gibi üç sayfa bildirir. Sabit uzunluklu test formlarının bu hatayı hiç açığa vurmamasının nedeni tam olarak budur. Dinamik bir form ilk kez bir sayfadan ikiye büyüdüğünde delta 1'dir ve böyle bir wrapper, sayfa sayısı olarak 1 bildirir. Üç sayfalık bir formdan satır çıkarmak da benzer saçmalığı öbür yönde üretir

Delta'yı önceki değerin üstüne biriktirmek de güvenli bir tamir değildir. Başlatma ile layout callback'lerinin sırası, wrapper'ın önceki sayısına daima taban gibi güvenememesi demektir; böylece koşan bir toplam sapanabilir. PDFium Component'in callback'i bu yüzden argümanı sayı olarak yok sayar ve belge üzerinde FPDF_GetPageCount çağırır; o da toplamı, henüz tamamlanmış layout'tan okur. Sonra cache'lenmiş sayfa sahnelerini temizler, o toplamı TPdf.PageCount'in ardındaki XFA sayfa sayısı override'u olarak saklar ve ancak ondan sonra OnXfaPageCountChanged yükseltir. Handler'ınız koştuğunda NewCount ile FPdf.PageCount anlaşmıştır

PDFium Component dinamik XFA şeması: bir satır eklemek tek sayfalık bir formu iki sayfaya yeniden sayfalandırır ve FFI_PageEvent, abs(new minus old)'ı delta olarak geçirir; toplam diye okumak 1 sayfa bildirirken PDFium Component FPDF_GetPageCount okur ve doğru toplamı bildirir
Yerel page event, toplam değil eklenen-çıkarılan bir delta bildirir; dolayısıyla PDFium Component argümanı yok sayar ve OnXfaPageCountChanged'i yükseltmeden önce tamamlanmış layout'u okur
procedure TClaimForm.PdfXfaPageCountChanged(Sender: TObject; NewCount: Integer);
begin
  // NewCount tamamlanmış layout'un toplamıdır, asla delta değil.
  // Bu, PDFium'un layout callback'i içinde koşar: yalnızca ana süreç UI durumunu
  // güncelleyin; belgeyi kapatmayın ya da sayfaları buradan yüklemeyin
  UpdatePageRange(NewCount);
end;

procedure TClaimForm.PdfViewPageChange(Sender: TObject);
begin
  // Ertelenmiş XFA yenilemesi dâhil her sayfa yeniden yüklemesinden sonra ateşlenir
  PageSpin.Value := PdfView1.PageNumber;
end;

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

Olay yalnızca layout'u çalışma zamanında değişen Full XFA formları için ateşlenir. Static XFA ve AcroForm belgeleri onu hiç yükseltmez; dolayısıyla ikisini de işleyen bir görüntüleyici aynı handler'ı atanmış bırakabilir. Atanmamış bırakmak da güvenlidir; TPdf.PageCount'in ardındaki override her hâlde uygulanır ve olay, ana sürecin cache'lediği her şeyi yenileyebilmesi için vardır

Bir field taşındığında giriş kutusu neden eski sayfada kalır?

Kenarlık taşınır, editor taşınmaz; çünkü yerel XFA notifier'ı bir dikdörtgeni kendisiyle karşılaştırır. Layout, çoktan yüklenmiş bir widget'ın geometrisini değiştirdiğinde PDFium'un yeni dikdörtgeni fark edip widget üzerinde PerformLayout çağırması gerekir; o da metin editor'ünü ve vuruş alanını yeniden konumlandırır. GetWidgetRect()'i RecacheWidgetRect() ile karşılaştıran bir kontrol asla ateşlenemez: iki fonksiyon da aynı üyeye bir const referans döndürür ve recache o üyeyi yerinde üzerine yazar; dolayısıyla karşılaştırma daima iki özdeş değer görür ve yüklenmiş widget'lar relayout'larını atlar

Belirti, bir subform yüksekliği değişip var olan field'ları sonraki sayfaya taşıdığında ortaya çıkar: field kenarlığı yeni konumunda çizilirken yazılan metin ile fare vuruş alanı önceki Y koordinatında kalır. Açık bir relayout düzeltmez; sayfayı yeniden yüklemek de düzeltmez, çünkü widget geometrisinin güncel olduğuna hâlâ inanır. PDFium Component ile gelen Windows V8 kütüphaneleri, recache'ten önce eski dikdörtgeni değere göre kopyalar ve o kopyayı karşılaştırır; böylece taşınan widget'lar relayout eder ve düzenlenen değer tam olarak kenarlığın olduğu yerde görünür. Kontrol yerel kodda yaşar ve DLL'lerle seyahat eder; dolayısıyla pdfium.v8.dll'yi Pascal unit'leriyle birlikte dağıtın. Kendiniz test edecekseniz önce hayatta kalan bir satırı varsayılan olmayan bir değere düzenleyin ve sonra o değeri field'ın yeni konumunda arayın; yoksa varsayılan değerlerle yeniden kurulan bir satır geçmiş gibi görünür

PDFium Component widget relayout şeması: GetWidgetRect ile RecacheWidgetRect tek bir paylaşımlı üye döndürdüğü ve taşınan widget'ların PerformLayout'u atladığı kendisiyle-karşılaştırmayı, editor ile fare vuruş alanını yeniden çizilen kenarlığın üzerine taşıyan Windows V8 değere-göre-kopya kontrolüyle karşıt koyar
Bir dikdörtgeni kendisiyle karşılaştırmak asla bir değişiklik saptamaz; kontrol değere göre bir kopyayı önce kaydetmediği sürece kenarlık taşınırken yazılan metin ile tıklamalar geride kalır

TPdfView sayfaları, PDFium'un altından handle çekmeden nasıl yeniden yükler?

TPdfView, bir XFA layout değişikliğini izleyen sayfa yeniden yüklemesini, yerel çağrı yığını açılana dek erteler. Page event çoğunlukla PDFium hâlâ girdiyi işlerken ateşlenir: kullanıcı bir Add Row düğmesine tıkladı, tıklama bir script koşturdu, script instance sayısını değiştirdi ve layout aynı yerel çağrının içinde bitti. O anda sayfa handle'ını kapatıp yeniden açmak, çağıranın hâlâ kullandığı bir object'i serbest bırakırdı. O anda yalnızca kendini geçersiz kılan bir görüntüleyici, layout öncesi duruma işaret eden bir sayfa handle'ı tutmaya devam eder ve kullanıcı o sayfa kaybolduğunda son sayfadaysa seçili sayfa numarası aralık dışına düşer

Ertelenmiş yenileme birkaç küçük adımda işler ve bunlar ana süreçten gördüğünüz davranışı açıklar:

  1. Page-event callback'i, görüntülemeyi bekleyen bir XFA layout yenilemesi taşıyor diye işaretler ve özel bir pencere iletisi postalar; ileti gelmeden önceki yinelenen olaylar tek bir yenilemede birleşir
  2. Henüz pencere handle'ı olmayan bir görünüm bekleyen bayrağını tutar ve iletiyi CreateWnd'den postalar; belge değiştirmek, görünümü pasifleştirmek ya da yok etmek ise bayrağı temizler
  3. İleti geldiğinde görünüm, metin seçimini, arama vurgusunu ve odaklı-field indeksini temizler; çünkü üçü de eski layout'u gösteriyordu
  4. Seçili sayfa yeni PageCount'a kıskandırılır; değişen bir sayfa numarası normal sayfa geçişinden geçer, aksi hâlde geçerli sayfa yeniden yüklenir ve fit modu yeniden uygulanır
  5. Layout hiç sayfa bırakmadıysa görünüm, artık var olmayan bir sayfayı boyamak yerine eski sayfa handle'ını boşaltır
PDFium Component TPdfView ertelenmiş XFA yenilemesi şeması: yerel layout çağrı yığınının içindeki bir page event yalnızca bekleyen bir yenileme işaretler ve bir pencere iletisi postalar; ileti sonra bayat seçim durumunu temizler, sayfayı yeni PageCount'a kıskandırır ve sayfa handle'ını yeniden yükler ya da boşaltır
Yeniden yükleme, yerel çağrı yığını açılana dek bekler: postalanmış bir ileti yinelenen olayları birleştirir, sonra görünüm sayfayı kıskandırır, yeniden yükler ve OnPageChange yükseltir

Aynı kısıt kendi kodunuz için de geçerlidir. OnXfaPageCountChanged o yerel layout callback'inin içinde koşar; onu bir bildirim gibi ele alın: etiketleri, spinner aralıklarını ve araç çubuğu durumunu orada güncelleyin; belgeyi kapatmak ya da başkasını açmak gibi daha ağır her şeyi, callback döndükten sonra koşması için postalanan bir iletiyle kuyruğa alın. TPdfView.OnPageChange sonra, görünüm sayfayı gerçekten yeniden yüklediğinde haber verir ve o anda PdfView1.PageNumber okumak size kıskanılmış değeri verir. Tab tuşuyla gezinme ile form görüntüleyicinin açılışta koşturduğu FormType kontrolleri PDFium Component ile PDF form field navigasyonu yazısında

Görüntüleyici, metin katmanı olmayan Full XFA sayfalarını nasıl ele alır?

Full XFA sayfalarının PDF text page'i yoktur; böyle bir sayfada bir tane isteyen her şey Cannot open text page hatasıyla başarısız olur. Bir görüntüleyicinin varsayılan metin seçimi ile bağlantı saptaması ikisi de o katmana bakar: TPdfView.AllowUserTextSelection varsayılanı True'dayken üzerine gelmek, metin katmanından farenin altındaki bir karakteri sorar ve bir mouse-up tıklaması sayfa metni üzerinde otomatik bir URL sondası koşturur. TPdfView'de her iki iç yol da, TPdf.FormType ftXfaFull olduğunda ve XFA runtime kullanılabilirken sonuç yok döndürür; böylece varsayılan ayarlar çalışır ve field girişi kullanılabilir kalır

Full XFA belgeleri için AllowUserTextSelection'i kapatmak makul bir UI seçimidir; çünkü seçilecek sayfa metni yoktur ve sürükleme jestleri bir seçim modu başlatmamalıdır

procedure TClaimForm.ConfigureViewerForForm;
begin
  // FormType açık belgeyi okur; bunu FPdf.Active := True'dan sonra çağırın
  if FPdf.XFA and (FPdf.FormType = ftXfaFull) and FPdf.XfaRuntimeAvailable then
  begin
    // Full XFA sayfalarında PDF metin katmanı yoktur; field'lar düzenlenebilir kalır
    PdfView1.AllowUserTextSelection := False;
    StatusBar1.SimpleText := Format('Dynamic XFA form, %d page(s)',
      [FPdf.PageCount]);
  end
  else
    PdfView1.AllowUserTextSelection := True;
end;

Seçimin üstüne yazmak kendi işlemesini ister. Yerel XFA metin editor'ü bir karakter aldığında seçimi değiştirmez: FORM_OnChar imlece ekler ve Backspace tek karakter siler; dolayısıyla tuş vuruşlarını olduğu gibi geçirmek eski ile yeni metni yan yana koyar. PDFium Component, tıklamanın bir XFA metin field'ına düştüğünü hatırlar ve seçim var olduğu ve belge form-doldurma ya da değiştirme izni verdiği her anda yazılan karakterleri, Backspace ile Delete'i FORM_ReplaceSelection üzerinden yönlendirir. Salt okunur bir XFA field'ının değişip değişemeyeceğine yerel editor karar verir; dolayısıyla formda salt okunur işaretli bir field, aksi hâlde doldurmaya izin veren bir belgede bile değerini korur. TPdfView.AllowFormEvents'i False'a set etmek de bu klavye yönlendirmesini durdurur; bu da salt okunur bir görüntüleyiciyi salt okunur tutar

Hızlı başvuru: bir Delphi görüntüleyicide dinamik XFA

BelirtiNedenNasıl halledilir
Form iki sayfaya büyüdükten sonra sayfa sayısı 1 gösterirYerel page event, toplam değil eklenen/çıkarılan bir delta geçirirTPdf.PageCount tamamlanmış layout'u okur
Field kenarlığı taşınır, yazılan metin ile vuruş alanı geride kalırYüklenen widget, kendisiyle karşılaştırma sonrası relayout'u atlarWindows V8 kütüphanelerindeki değere-göre-kopya kontrolü
Görüntüleyici boyar ya da girdiyi layout öncesi sayfa durumuna yönlendirirYeniden sayfalamadan sonra sayfa handle'ı yeniden yüklenmediTPdfView'deki ertelenmiş yenileme
Bir field'a tıklamak var olmayan bir text page isterMetin katmanı olmayan sayfalarda metin seçimi ve URL sondasıMetin yolları ftXfaFull sayfalarda sonuç yok döndürür
Seçili bir değerin üstüne yazmak değiştirmek yerine eklerYerel XFA editor'ü imlece eklerTuş vuruşları FORM_ReplaceSelection üzerinden yönlendirilir
  • Herhangi bir belge yüklenmeden EnableV8Engine'i True'ya set edin ve sade kütüphanenin önce yüklendiği durum için OnXfaRuntimeMissing'i işleyin
  • Toplamı TPdf.PageCount'ten ya da OnXfaPageCountChanged'in NewCount parametresinden okuyun; sayfa sayılarını asla kendiniz toplamayın ya da çıkarmayın
  • OnXfaPageCountChanged handler'ını hafif tutun; çünkü yerel layout callback'inin içinde koşar
  • Geçerli sayfa göstergesini TPdfView.OnPageChange'de eşleyin; ertelenmiş yeniden yükleme sayfa numarasını kıskandırdıktan sonra ateşlenir
  • Windows V8 DLL'lerini unit'lerle birlikte dağıtın; widget relayout kontrolü yerel kodda yaşar
  • Sayfa sayısını gerçekten değiştiren ve düzenlenmiş bir field'ı sayfa kırılması üzerinden taşıyan bir formla test edin; sabit uzunluklu örnekler bu listedeki her sorunu saklar

Dinamik XFA, sayfa sayısını ve field geometrisini canlı değerlere çevirir; bir görüntüleyici yalnızca onları tamamlanmış layout'tan aldığında ve sayfaları güvenli bir anda yeniden yüklediğinde doğru kalır. PDFium Component ikisini de TPdf ile TPdfView içinde halleder; ana sürecin yapması gereken tek şey dinlemektir. Ayrıntılar ve indirmeler Delphi için PDFium Component ürün sayfasında