Article technique

XFA dynamique PDFium : le nombre de pages est un delta

Quand un formulaire XFA dynamique ajoute ou retire des pages dans un visualiseur Delphi, PDFium Component signale le nouveau total via TPdf.PageCount et TPdf.OnXfaPageCountChanged, lu depuis la mise en page terminée car l'événement de page natif porte un delta ajouté/supprimé plutôt qu'un total. Les bibliothèques Windows V8 déplacent aussi les zones de clic avec les champs relocalisés, et TPdfView recharge les handles de page après le retour du callback de mise en page. Imaginez un formulaire de note de frais : cliquez deux fois sur Add Row et le formulaire passe à deux pages. Un visualiseur qui se fie à l'argument de l'événement affiche fièrement 1 sur 1, et un qui garde la géométrie de widgets d'avant mise en page envoie les frappes d'un champ déplacé en page 2 vers un endroit invisible. Rien de tout cela n'apparaît avec les formulaires d'exemple de longueur fixe que tout le monde teste en premier, et les raisons valent la peine d'être connues si vous intégrez un visualiseur de formulaires

Que se passe-t-il quand un formulaire XFA dynamique se repagine ?

Un formulaire XFA dynamique n’a pas de liste de pages fixe, donc son nombre de pages est une sortie du layout et peut changer à chaque édition de données par l’utilisateur. XFA 3.3 décrit le formulaire comme un arbre de subforms ; un subform répété est piloté par un instanceManager, et un script tel que _Row.addInstance() clone une ligne de plus. Le processeur de layout refait alors couler le contenu dans les zones de page, ce qui peut ajouter une page, retirer une page ou pousser des champs existants sur une autre page. ISO 32000-1 §12.7.8 ne définit que la façon dont les paquets XFA voyagent dans le PDF ; tout ce qui se passe ensuite appartient au moteur XFA, qui dans PDFium Component est le layout XFA de PDFium lui-même tournant dans le processus hôte. Un visualiseur Delphi a donc affaire à un document dont le nombre de pages, les tailles de page et les positions de widgets sont tous de l’état vivant. Trois choses tournent mal quand l’hôte suppose le contraire :

  • Le nombre de pages que l’hôte met en cache pour la navigation, les plages de défilement et les spinners de page se périme, ou pire, se met à jour avec le mauvais nombre
  • Les champs relocalisés montrent leur bordure à la nouvelle position pendant que l’éditeur et la zone de frappe souris restent aux anciennes coordonnées
  • Le visualiseur garde un handle de page que le layout a remplacé, donc les clics et les dessins vont vers une page qui n’existe plus dans ce formulaire

Persister les éditions de lignes à travers sauvegarde et réouverture est un problème séparé avec ses propres règles ; cet article reste sur ce qui se passe à l’exécution à l’intérieur du visualiseur

Quel runtime PDFium le XFA dynamique exige-t-il ?

Le XFA dynamique dans PDFium Component exige le build V8/XFA de la bibliothèque native, sélectionné par la variable globale EnableV8Engine de l’unité PDFium avant le chargement du premier document. Le processus s’engage sur une seule DLL la première fois qu’un TPdf charge la bibliothèque, et un build PDFium ordinaire ne peut pas du tout exécuter le moteur XFA. À l’ouverture d’un document, TPdf jette bien un œil au fichier à la recherche de marqueurs XFA et bascule automatiquement sur le build V8, mais seulement si aucune bibliothèque ordinaire n’a encore été chargée dans ce processus. Quand l’engagement est déjà parti du mauvais côté, TPdf.OnXfaRuntimeMissing se déclenche une fois pour que l’hôte puisse dire à l’utilisateur de redémarrer. Régler le drapeau explicitement au démarrage supprime le jeu de devinettes. La structure de callbacks FPDF_FORMFILLINFO qui porte les événements XFA doit aussi correspondre à la DLL ; le fond est dans FPDF_FORMFILLINFO version 2 et l’ABI des callbacks XFA, et la détection des formulaires XFA et la lecture de leurs paquets couvre la distinction des types de formulaires avant d’ouvrir un visualiseur

uses
  PDFium;

procedure TClaimForm.FormCreate(Sender: TObject);
begin
  // Décidez avant que le premier TPdf ne charge la bibliothèque native :
  // le processus ne peut pas passer de pdfium.dll à pdfium.v8.dll ensuite
  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;

Pourquoi PageCount rapporterait 1 pour un formulaire de deux pages ?

Un wrapper qui stocke l'argument page_count de l'événement de page natif comme total du document se trompe, car cet argument est en réalité la différence absolue entre le nouveau et l'ancien nombre de pages. PDFium déclenche FFI_PageEvent à la fin d'une passe de mise en page avec un type d'événement page ajoutée ou page supprimée ; en interne il met d'abord à jour son nombre de pages stocké puis passe abs(new - old). Sur la mise en page initiale l'ancien compte vaut zéro, donc le delta égale le total, et un exemple statique de trois pages rapporte trois pages comme prévu. C'est exactement pourquoi les formulaires de test de longueur fixe n'exposent jamais l'erreur. La première fois qu'un formulaire dynamique passe d'une page à deux, le delta vaut 1, et un tel wrapper rapporte un nombre de pages de 1. Retirer une ligne d'un formulaire de trois pages produit le même genre d'absurdité dans l'autre sens

Accumuler le delta sur la valeur précédente n'est pas une réparation sûre non plus. L'ordre des callbacks d'initialisation et de mise en page fait que le wrapper ne peut pas toujours se fier à son compte antérieur comme base, une somme courante peut donc dériver. Le callback de PDFium Component ignore donc l'argument comme compte et appelle FPDF_GetPageCount sur le document, qui lit le total depuis la mise en page qui vient de s'achever. Il vide ensuite les scènes de pages en cache, stocke ce total comme override de nombre de pages XFA derrière TPdf.PageCount, et ce n'est qu'ensuite qu'il déclenche OnXfaPageCountChanged. Au moment où votre handler s'exécute, NewCount et Fpdf.PageCount concordent

Diagramme XFA dynamique de PDFium Component où l'ajout d'une ligne repagine un formulaire d'une page vers deux pages et FFI_PageEvent passe abs(nouveau moins ancien) comme delta, donc le traiter comme un total rapporterait un nombre de pages de 1, tandis que PDFium Component lit FPDF_GetPageCount et rapporte le total correct
L'événement de page natif rapporte un delta ajouté-ou-supprimé, pas un total, si bien que PDFium Component ignore l'argument et lit la mise en page terminée avant de déclencher OnXfaPageCountChanged
procedure TClaimForm.PdfXfaPageCountChanged(Sender: TObject; NewCount: Integer);
begin
  // NewCount est le total de la mise en page terminée, jamais un delta.
  // Ceci s'exécute dans le callback de mise en page de PDFium : ne mettez à jour
  // que l'état d'UI de l'hôte, sans fermer le document ni recharger des pages ici
  UpdatePageRange(NewCount);
end;

procedure TClaimForm.PdfViewPageChange(Sender: TObject);
begin
  // Se déclenche après chaque rechargement de page, y compris le rafraîchissement XFA différé
  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’événement ne se déclenche que pour les formulaires Full XFA dont le layout change à l’exécution. Les documents Static XFA et AcroForm ne le lèvent jamais, donc un visualiseur qui gère les deux peut garder le même handler affecté. Le laisser non affecté est sûr aussi ; l’override derrière TPdf.PageCount s’applique de toute façon, et l’événement existe pour que l’hôte puisse rafraîchir ce qu’il a mis en cache

Pourquoi la zone de saisie reste-t-elle sur l’ancienne page quand un champ bouge ?

La bordure bouge et l'éditeur non quand le notificateur XFA natif compare un rectangle avec lui-même. Quand la mise en page change la géométrie d'un widget déjà chargé, PDFium est censé remarquer le nouveau rectangle et appeler PerformLayout sur le widget, ce qui repositionne l'éditeur de texte et sa zone de clic. Un contrôle qui compare GetWidgetRect() avec RecacheWidgetRect() ne peut jamais se déclencher : les deux fonctions renvoient une référence const vers le même membre, et le recache écrase ce membre sur place, si bien que la comparaison voit toujours deux valeurs identiques et les widgets chargés sautent leur remise en page

Le symptôme apparaît quand la hauteur d'un sous-formulaire change au point que des champs existants basculent sur la page suivante : la bordure du champ est dessinée à sa nouvelle position tandis que le texte tapé et la zone de clic de la souris restent à l'ordonnée précédente. Une remise en page explicite n'aide pas, recharger la page non plus, car le widget croit toujours sa géométrie à jour. Les bibliothèques Windows V8 livrées avec PDFium Component copient l'ancien rectangle par valeur avant le recache et comparent cette copie, si bien que les widgets déplacés se remettent en page et la valeur éditée apparaît exactement là où est la bordure. Le contrôle vit dans le code natif et voyage avec les DLL, déployez donc pdfium.v8.dll avec les unités Pascal. Pour le tester vous-même, éditez d'abord une ligne survivante avec une valeur non par défaut puis cherchez cette valeur à la nouvelle position du champ, car une ligne reconstruite avec des valeurs par défaut sinon ressemblerait à un succès

Diagramme de remise en page de widgets PDFium Component contrastant une auto-comparaison où GetWidgetRect et RecacheWidgetRect renvoient un même membre partagé si bien que les widgets déplacés sautent PerformLayout, avec le contrôle par copie de valeur des bibliothèques Windows V8 qui repositionne l'éditeur et la zone de clic de la souris sur la bordure redessinée
Comparer un rectangle avec lui-même ne détecte jamais un changement, donc la bordure bouge pendant que le texte tapé et les clics restent derrière, sauf si le contrôle sauve d'abord une copie par valeur

Comment TPdfView recharge-t-il les pages sans arracher un handle sous les pieds de PDFium ?

TPdfView diffère le rechargement de page qui suit un changement de mise en page XFA jusqu'à ce que la pile d'appels native se soit déroulée. L'événement de page se déclenche habituellement pendant que PDFium traite encore l'entrée : l'utilisateur a cliqué sur un bouton Add Row, le clic a exécuté un script, le script a changé le nombre d'instances, et la mise en page s'est achevée dans ce même appel natif. Fermer et rouvrir le handle de page à cet instant libérerait un objet que l'appelant utilise encore. Un visualiseur qui ne s'invalide que sur ce point garde un handle de page qui pointe vers un état d'avant mise en page, et si l'utilisateur était sur la dernière page quand elle a disparu, le numéro de page sélectionné est hors limites

Le rafraîchissement différé marche en quelques petites étapes, et elles expliquent le comportement que vous observez depuis l’hôte :

  1. Le callback d’événement de page marque la vue comme ayant un rafraîchissement de layout XFA en attente et poste un message de fenêtre privé ; les événements répétés avant l’arrivée du message fusionnent en un seul rafraîchissement
  2. Une vue sans handle de fenêtre encore garde le drapeau en attente et poste le message depuis CreateWnd, tandis que changer de document, désactiver la vue ou la détruire efface le drapeau
  3. Quand le message arrive, la vue efface la sélection de texte, le surlignage de recherche et l’index du champ focalisé, parce que les trois se référaient à l’ancien layout
  4. La page sélectionnée est bornée au nouveau PageCount ; un numéro de page changé passe par la commutation de page normale, sinon la page courante est rechargée, et le mode d’ajustement est réappliqué
  5. Si le layout ne laisse aucune page du tout, la vue décharge son ancien handle de page au lieu de dessiner une page qui n’existe plus
Schéma du rafraîchissement XFA différé de TPdfView PDFium Component où un événement de page dans la pile d’appels native du layout se contente de marquer un rafraîchissement en attente et de poster un message de fenêtre, qui efface ensuite l’état de sélection périmé, borne la page au nouveau PageCount et recharge ou décharge le handle de page
Le rechargement attend que la pile d’appels native se déroule : un message posté fusionne les événements répétés, puis la vue borne la page, la recharge et lève OnPageChange

La même contrainte vaut pour votre propre code. OnXfaPageCountChanged tourne dans ce callback de layout natif, donc traitez-le comme une notification : mettez à jour libellés, plages de spinners et état de barre d’outils sur place, et mettez en file tout ce qui est plus lourd, comme fermer le document ou en ouvrir un autre, via un message posté pour que cela tourne après le retour du callback. TPdfView.OnPageChange vous dit alors quand la vue a réellement rechargé la page, et lire PdfView1.PageNumber à ce moment vous donne la valeur bornée. Le parcours par touche Tab et les vérifications FormType qu’un visualiseur de formulaires exécute à l’ouverture sont couverts dans la navigation dans les champs de formulaires PDF avec PDFium Component

Comment le visualiseur traite-t-il les pages Full XFA sans couche de texte ?

Les pages Full XFA n'ont pas de page de texte PDF, donc tout ce qui en demande une sur une telle page échoue avec une erreur Cannot open text page. La sélection de texte par défaut et la détection de liens d'un visualiseur consultent toutes deux cette couche : avec TPdfView.AllowUserTextSelection à son défaut True, le survol demande à la couche de texte un caractère sous la souris, et un clic de relâchement lance une sonde URL automatique sur le texte de la page. Dans TPdfView, les deux chemins internes ne rendent aucun résultat quand TPdf.FormType vaut ftXfaFull et que le runtime XFA est disponible, si bien que les réglages par défaut fonctionnent et la saisie dans les champs reste disponible

Désactiver AllowUserTextSelection pour les documents Full XFA est un choix d'interface raisonnable, puisqu'il n'y a pas de texte de page à sélectionner et que les gestes de glisser ne devraient pas démarrer un mode de sélection

procedure TClaimForm.ConfigureViewerForForm;
begin
  // FormType lit le document ouvert, appelez donc ceci après FPdf.Active := True
  if FPdf.XFA and (FPdf.FormType = ftXfaFull) and FPdf.XfaRuntimeAvailable then
  begin
    // Aucune couche de texte PDF n’existe sur les pages Full XFA ; les champs restent éditables
    PdfView1.AllowUserTextSelection := False;
    StatusBar1.SimpleText := Format('Dynamic XFA form, %d page(s)',
      [FPdf.PageCount]);
  end
  else
    PdfView1.AllowUserTextSelection := True;
end;

Taper par-dessus une sélection demande son propre traitement. L'éditeur de texte XFA natif ne remplace pas une sélection quand il reçoit un caractère : FORM_OnChar insère au curseur, et Retour arrière supprime un seul caractère, donc laisser passer les frappes telles quelles mettrait l'ancien et le nouveau texte côte à côte. PDFium Component se souvient que le clic a atterri sur un champ de texte XFA et route les caractères tapés, Retour arrière et Suppression via FORM_ReplaceSelection chaque fois qu'une sélection existe et que le document accorde la permission de remplir ou modifier. C'est l'éditeur natif qui décide si un champ XFA en lecture seule peut changer, donc un champ marqué lecture seule dans le formulaire garde sa valeur même dans un document qui autorise par ailleurs le remplissage. Mettre TPdfView.AllowFormEvents à False arrête aussi ce routage clavier, ce qui garde un visualiseur en lecture seule lecture seule

Aide-mémoire : le XFA dynamique dans un visualiseur Delphi

SymptômeCauseTraité par
Le nombre de pages affiche 1 après que le formulaire est passé à deux pagesL'événement de page natif passe un delta ajouté/supprimé, pas un totalTPdf.PageCount lit la mise en page terminée
La bordure du champ bouge, le texte tapé et la zone de clic restent derrièreLe widget chargé saute sa remise en page après une auto-comparaisonContrôle par copie de valeur dans les bibliothèques Windows V8
Le visualiseur peint ou route l'entrée vers un état de page d'avant mise en pageHandle de page non rechargé après repaginationRafraîchissement différé dans TPdfView
Un clic dans un champ demande une page de texte inexistanteSélection de texte et sonde URL sur des pages sans couche de texteLes chemins de texte ne rendent aucun résultat sur les pages ftXfaFull
Taper par-dessus une valeur sélectionnée ajoute au lieu de remplacerL'éditeur XFA natif insère au curseurFrappes routées via FORM_ReplaceSelection
  • Mettez EnableV8Engine à True avant tout chargement de document, et traitez OnXfaRuntimeMissing pour le cas où la bibliothèque simple aurait été chargée en premier
  • Lisez le total depuis TPdf.PageCount ou le paramètre NewCount de OnXfaPageCountChanged ; n'additionnez ni ne soustrayez jamais des nombres de pages vous-même
  • Gardez le handler OnXfaPageCountChanged léger, car il s'exécute dans le callback de mise en page natif
  • Synchronisez l'indicateur de page courante dans TPdfView.OnPageChange, qui se déclenche après que le rechargement différé a borné le numéro de page
  • Déployez les DLL V8 Windows avec les unités ; le contrôle de remise en page des widgets vit dans le code natif
  • Testez avec un formulaire qui change réellement de nombre de pages et déplace un champ édité à travers un saut de page, car les exemples de longueur fixe cachent tous les problèmes de cette liste

Le XFA dynamique transforme le nombre de pages et la géométrie des champs en valeurs vivantes, et un visualiseur ne reste correct que s’il les prend au layout achevé et recharge les pages à un moment sûr. PDFium Component gère les deux à l’intérieur de TPdf et TPdfView, si bien que l’hôte n’a qu’à écouter. Détails et téléchargements sont sur la page produit PDFium Component for Delphi