Article technique

Césure et colonnes équilibrées en PDF depuis Delphi

Pour un produit allemand dans trois colonnes de 148 points, deux choses tournent mal en même temps. La ligne devant un mot comme Rechnungsprüfungsausschuss peut se terminer au tiers vide, parce que l'espace avant ce composé de 26 lettres était le seul endroit où couper. Et sur la dernière page le texte restant remplit une colonne, une partie d'une deuxième, et laisse la troisième vide. Un coupeur de lignes qui ne connaît que les espaces, et ne compte jamais ce qui reste, produit exactement cette page

Le correctif a deux moitiés : couper à l'intérieur des mots selon les règles de la langue du texte, et dimensionner les colonnes finales d'après le nombre de lignes restant à placer. Les deux moitiés ne marchent que si le compte de lignes utilisé pour la décision vient des mêmes coupures que celles qui sont dessinées, césures comprises, à une largeur de colonne de 148 points plutôt qu'à la région de 480 points

Un flux à trois colonnes avec césure dans PDF Library for Delphi

PDF Library for Delphi garde un passage comme un flux de texte : NewTextFlow renvoie un handle, SetTextFlowLanguage et SetTextFlowHyphenation contrôlent où les mots peuvent se couper, et DrawTextFlowColumns verse autant du texte restant que possible dans une à 64 colonnes de largeur égale et avance le flux. La largeur de colonne est la largeur de la région moins les gouttières, divisée par le nombre de colonnes, donc une région de 480 points avec trois colonnes et des gouttières de 18 points donne (480 − 2 × 18) / 3 = 148 points par colonne

L'appel renvoie le nombre total de lignes qu'il a dessinées. Zéro signifie que rien n'est entré, et dans ce cas le flux reste où il était, donc aucun texte ne se perd ; le piège est une boucle de pages qui continue d'appeler NewPage pendant que l'appel continue de renvoyer zéro. Cela arrive quand la région est plus courte qu'une ligne, ou quand un réglage de lignes minimales ne peut pas être satisfait dans l'espace offert. La boucle ci-dessous traite zéro comme une erreur au lieu de tourner en boucle

var
  Lib: TPDFlib;
  FontID, Flow, Drawn: Integer;
begin
  Lib := TPDFlib.Create;
  try
    Lib.SetDocumentLanguage('de-DE');      // avant NewTextFlow, voir plus bas
    FontID := Lib.AddTrueTypeFont('Georgia', 1);
    Lib.SetTextSize(10.5);

    Flow := Lib.NewTextFlow(ArticleBody);
    try
      Lib.SetTextFlowHyphenation(Flow, 1, 3, 3);
      Lib.SetTextFlowMinLines(Flow, 2);   // aucune ligne isolée au pied d'une colonne

      repeat
        // Left 66, Top 72, région 480 x 620 pt, 3 colonnes, gouttières de 18 pt, équilibré
        Drawn := Lib.DrawTextFlowColumns(Flow, 66, 72, 480, 620, 3, 18, 1);
        if Lib.TextFlowFinished(Flow) = 1 then
          Break;
        if Drawn = 0 then
          raise Exception.Create('Column region cannot take the next lines');
        Lib.NewPage;
        Lib.SelectFont(FontID);
        Lib.SetTextSize(10.5);            // NewPage ramène la police à 12 pt
      until False;
    finally
      Lib.ReleaseTextFlow(Flow);
    end;

    Lib.SaveToFile('newsletter.pdf');
  finally
    Lib.Free;
  end;
end;

Les coordonnées se mesurent depuis le coin supérieur gauche de la page quelle que soit l'origine que vous avez posée, parce que l'appel de colonnes dispose ses lignes vers le bas depuis Top. Avec l'alignement à gauche par défaut, chaque ligne démarre au bord gauche de sa colonne, si bien que le relâchement d'une coupure ratée apparaît en bord droit déchiqueté ; en texte justifié le même relâchement devient des rivières

Comparaison PDF Library for Delphi de colonnes étroites justifiées avec et sans césure, montrant comment activer la césure coupe le mot long et supprime les rivières d'espace blanc
La césure consciente de la langue place la coupure à l'intérieur du mot, si bien que le relâchement de la justification ne s'accumule jamais en rivières

D'où vient la langue de la césure ?

Un flux neuf prend sa langue de l'entrée /Lang du Catalog du document au moment où NewTextFlow tourne. C'est la même valeur que lisent les lecteurs d'écran et les indexeurs de recherche, donc un document qui déclare déjà sa langue, comme le fait la sortie balisée de le balisage automatique pour des PDF accessibles, obtient la césure gratuitement. Le moment compte pourtant. Appelez SetDocumentLanguage après que le flux existe et ce flux ne le voit jamais ; le premier exemple pose la langue d'abord exactement pour cette raison

Quand l'étiquette nomme une langue prise en charge, la césure automatique s'allume toute seule. Les règles couvrent l'anglais, l'allemand, le néerlandais, le français, l'espagnol, l'italien, le portugais, le russe, le turc, le danois, le suédois, le finnois, le polonais, le tchèque et le hongrois. Les sous-étiquettes de région sont retirées avant la recherche, donc de-CH, de-AT et de césurent tous comme de l'allemand. Une étiquette que les règles ne couvrent pas, comme ja, est acceptée, et la coupure automatique s'éteint simplement pour ce flux

Trois valeurs de retour vous disent ce qui s'est passé, et elles valent d'être vérifiées dans du code qui reçoit la langue depuis des données utilisateur :

  • SetTextFlowLanguage renvoie 0 seulement pour une étiquette malformée ; une étiquette bien formée pour une langue non couverte renvoie 1 et laisse la césure automatique éteinte
  • SetTextFlowHyphenation avec Enable = 1 renvoie 0 quand la langue du flux n'a pas de règles, donc un coupeur ne peut pas inventer des points de coupure sans langue derrière
  • GetTextFlowHyphenation rapporte si la coupure automatique est allumée en ce moment, la valeur à journaliser quand une mise en page semble fausse

L'ordre compte ici aussi. SetTextFlowLanguage recalcule l'état on/off depuis la nouvelle langue, donc l'appeler après SetTextFlowHyphenation(Flow, 0, …) rallume la césure pour une langue prise en charge. Posez la langue, puis les options de césure

MinPrefix et MinSuffix sont un réglage de charte typographique

Les deux entiers après le drapeau d'activation sont le nombre minimal de lettres qui doivent rester sur la ligne avant une coupure et passer à la ligne suivante après elle. Tous deux acceptent 1 à 16. Quand la césure s'allume par la seule langue, les deux valent 2, et un mot n'est envisagé pour la coupure que s'il a au moins MinPrefix + MinSuffix + 1 lettres

Deux et deux est le réglage que nous changerions dans presque chaque document. Il produit plus d'occasions de coupure, mais un fragment de deux lettres en fin de ligne se lit comme une faute de frappe, et en allemand ou en néerlandais il détache des choses comme un préfixe de deux lettres que le lecteur doit ensuite recoller. Trois et trois coûte quelques lignes déchiquetées de plus et ressemble à de la composition. Montez les minimums pour les grands corps, où chaque fragment est proéminent ; descendez à deux seulement pour une colonne réellement étroite où vous avez décidé qu'une justification serrée bat une justification propre

Quels mots peuvent se couper, et que devient une URL

Les lignes se coupent aux espaces et tabulations, et un saut de ligne force une nouvelle ligne. À l'intérieur d'un mot, la césure automatique ne regarde que les mots faits entièrement de lettres (latin, plages latines étendues avec accents comprises, et cyrillique), ponctuation de tête et de queue mise à part. Les règles sont des combinaisons prudentes de voyelles, de grappes de consonnes légales et d'affixes courants, donc elles placent moins de points de coupure qu'un césuriste à dictionnaire. Les mots avec chiffres ou ponctuation interne, comme ISO-32000 ou v2Beta, et les mots de plus de 128 lettres n'obtiennent aucun point automatique

Les traits d'union conditionnels (U+00AD) sont le dépassement. Si un mot en contient, ces positions deviennent ses seuls points de coupure : les règles automatiques sont sautées pour ce mot, et les traits d'union conditionnels marchent même quand la césure automatique est éteinte ou que la langue n'a pas de règles. Utilisez-les pour les noms de marque, les codes produits et les termes que les règles coupent mal ; dans l'exemple suivant, Rechnungs et prüfungs sont les deux seuls endroits où le composé peut se couper

var
  Flow: Integer;
  Body, Rest: WideString;
begin
  // U+00AD marque les seuls endroits où ce composé peut se couper
  Body := 'Die Pr' + #$00FC + 'fung erfolgt durch den Rechnungs' + #$00AD +
    'pr' + #$00FC + 'fungs' + #$00AD + 'ausschuss der Gesellschaft';
  Flow := Lib.NewTextFlow(Body);
  try
    if Lib.SetTextFlowLanguage(Flow, CustomerLanguageTag) = 0 then
      raise Exception.Create('Malformed language tag: ' + CustomerLanguageTag);
    if Lib.SetTextFlowHyphenation(Flow, 1, 3, 3) = 0 then
      LogWarning('No hyphenation rules; only soft hyphens will break words');
      // LogWarning est votre propre routine de journalisation

    Lib.DrawTextFlow(Flow, 72, 72, 148, 240);

    // Ce qui n'est pas entré revient exactement tel que passé,
    // traits d'union conditionnels compris
    Rest := Lib.GetTextFlowRemaining(Flow);
  finally
    Lib.ReleaseTextFlow(Flow);
  end;
end;

Un trait d'union (hyphen-minus) n'est dessiné qu'à la coupure effectivement choisie. Les traits d'union conditionnels non choisis sont invisibles en mesure comme en dessin, et la coupure est enregistrée contre le texte original, et c'est pourquoi GetTextFlowRemaining rend les traits d'union conditionnels intacts. Le design naïf se trompe d'une manière reconnaissable : il écrit le trait dans la chaîne pendant qu'il essaie un candidat, la coupure bouge ensuite, et un trait égaré finit au milieu d'une ligne

Un jeton qui n'entre dans aucune ligne, une longue URL ou un numéro d'accession sans coupure légale, est coupé au plus long préfixe qui entre, sans trait d'union ajouté. La coupe ne tombe jamais entre les deux moitiés d'une paire de substitution ni devant un signe combinant, donc un emoji ou une lettre accentuée n'est jamais coupé entre deux lignes

Ce que Balance=1 change sur la dernière page

L'argument Balance ne compte que quand tout ce qui reste tient dans la région. Dans ce cas DrawTextFlowColumns divise le nombre de lignes restant par le nombre de colonnes, arrondit au-dessus, et s'en sert comme hauteur de chaque colonne. Vingt-deux lignes restantes en trois colonnes sortent en 8, 8 et 6. Quand le reste n'entre pas, chaque colonne garde sa pleine hauteur pour que la page transporte autant qu'elle peut et que la suite continue à la page suivante

Un réglage de lignes minimales peut monter la hauteur équilibrée. Avec SetTextFlowMinLines(Flow, 3) et quatre lignes restantes, la hauteur équilibrée de deux est sous le minimum, donc les colonnes se remplissent dans l'ordre : trois lignes dans la première colonne, une dans la deuxième, la troisième vide. Une queue courte tout à la fin du passage est toujours placée, puisqu'elle n'a nulle part où aller. Pour garder au moins deux lignes ensemble en tête de la colonne suivante aussi, SetTextFlowPaginationLines prend les minimums d'orphelines et de veuves en un appel

Diagramme PDF Library for Delphi du paramètre Balance gardant les régions de colonnes antérieures pleines tout en raccourcissant la région finale à un nombre de lignes égal dans chaque colonne
L'équilibrage ne s'applique qu'à la fin d'un passage, où il ajuste chaque colonne au même nombre de lignes

Pour les articles continus, passez 1 à chaque fois. En milieu de passage cela ne change rien. Les colonnes sont pleines de toute façon. Nous ne passerions 0 que quand la région de colonnes est une boîte fixe dans une mise en page de type formulaire, où un reste de 52 lignes dans des colonnes de 43 lignes doit atterrir en 43, 9 et 0 plutôt qu'en 18, 18 et 16

Quand la mise en page elle-même dépend de la longueur du passage, mesurez avant de dessiner. MeasureTextFlow renvoie combien de lignes le reste du flux demande à une largeur donnée, avec les mêmes coupures, césure comprise, sans bouger le flux

var
  Flow, Needed, LinesPerColumn: Integer;
  LinePitch: Double;
begin
  Flow := Lib.NewTextFlow(ArticleBody);
  try
    Lib.SetTextFlowLanguage(Flow, 'fr');
    Lib.SetTextFlowHyphenation(Flow, 1, 3, 3);

    Lib.SelectFont(FontID);
    Lib.SetTextSize(10.5);
    // Interligne que l'appel de colonnes utilise : 1.2 x la hauteur de texte sélectionnée
    LinePitch := Lib.GetTextHeight * 1.2;
    LinesPerColumn := Trunc(620 / LinePitch);

    Needed := Lib.MeasureTextFlow(Flow, (480 - 2 * 18) / 3);
    if Needed > 3 * LinesPerColumn then
      UseTwoPageSpread      // votre propre choix de mise en page
    else
      UseSinglePage;        // Balance=1 égalisera les colonnes

    Lib.DrawTextFlowColumns(Flow, 66, 72, 480, 620, 3, 18, 1);
    if Lib.TextFlowFinished(Flow) <> 1 then
      CarryOver(Lib.GetTextFlowRemaining(Flow));   // également le vôtre
  finally
    Lib.ReleaseTextFlow(Flow);
  end;
end;

Gardez la police et la taille identiques d'une boîte à l'autre

DrawTextFlow, DrawTextFlowColumns et MeasureTextFlow coupent tous les lignes avec la police et la taille sélectionnées au moment où ils sont appelés. Changez l'une entre deux boîtes du même flux et la seconde boîte coupe différemment de ce que la première a mesuré. L'interligne bouge avec, puisqu'il vaut 1.2 fois la hauteur de texte sélectionnée. Supposez que GetTextHeight rapporte 12 points pour votre police : l'interligne est de 14.4 points et une colonne de 620 points contient 43 lignes

La façon facile de trébucher là-dessus est une nouvelle page. NewPage resélectionne la police courante, mais à 12 points, et SelectFont fait pareil. Un flux réglé à 10.5 points en page un tourne donc à 12 points dès la page deux à moins que la boucle n'appelle SetTextSize à nouveau : mots plus larges, interligne plus haut, moins de lignes par colonne, et un résultat de MeasureTextFlow de la page un qui ne correspond plus. Le symptôme semble intermittent parce que la page un a toujours raison. Resélectionnez la police puis la taille après chaque NewPage, dans cet ordre, comme le fait le premier exemple

PDF Library for Delphi : diagramme d'avertissement sur la dérive des coupures de lignes après un changement de police entre boîtes, contrastant avec la boucle stable de re-sélection de la police après chaque nouvelle page
Les trois méthodes de flux coupent les lignes avec la police actuellement sélectionnée, si bien que la police doit rester inchangée d'une page à l'autre

Les passages qui mélangent des écritures passent par le même chemin de police sélectionnée en mesure comme en dessin, donc les polices de substitution choisies par le repli automatique de police pour le texte CJK et emoji n'ouvrent pas d'écart entre les deux. Dans les mises en page de rapport où le flux partage la page avec en-têtes, pieds de page et blocs pilotés par les données, l'ordre de le moteur de rapports par jeu de données s'applique : mesurez d'abord, placez les éléments fixes, puis remettez au flux la région qui reste

Les appels de flux de texte couverts ici, de la création et de la mesure au rembobinage et à la libération, font partie de PDF Library for Delphi pour Delphi, C++Builder et Lazarus. La référence des fonctions et le téléchargement sont sur la page produit PDF Library for Delphi