Technisch artikel

Afbreken en gebalanceerde tekstkolommen in Delphi

Giet een Duits productblad in drie kolommen van 148 punten en er gaan tegelijk twee dingen mis. De regel vóór een woord als Rechnungsprüfungsausschuss kan voor een derde leeg eindigen, want de spatie vóór die samenstelling van 26 letters was de enige plek om te breken. En op de laatste pagina vult de resttekst één kolom, een deel van een tweede, en laat de derde leeg. Een regeleinde-mechanisme dat alleen spaties kent en nooit telt wat er overblijft, produceert precies die pagina

De oplossing heeft twee helften: binnen woorden breken met regels voor de taal van de tekst, en de laatste kolommen op maat maken op basis van het aantal regels dat nog geplaatst moet worden. Beide helften werken alleen als het regelgetal dat voor de beslissing dient uit dezelfde breuken komt die getekend worden, afbreekstrepen inbegrepen, bij een kolombreedte van 148 punten in plaats van de regio van 480 punten

Een afgebroken tekststroom in drie kolommen in PDF Library for Delphi

PDF Library for Delphi houdt een passage vast als tekststroom: NewTextFlow geeft een handle terug, SetTextFlowLanguage en SetTextFlowHyphenation sturen waar woorden mogen breken, en DrawTextFlowColumns giet zoveel van de resterende tekst als past in één tot 64 kolommen van gelijke breedte en schuift de stroom op. De kolombreedte is de regiobreedte min de gutters, gedeeld door het kolomaantal, dus een regio van 480 punten met drie kolommen en gutters van 18 punten geeft (480 − 2 × 18) / 3 = 148 punten per kolom

De aanroep geeft het totaal aantal getekende regels terug. Nul betekent dat niets paste, en in dat geval blijft de stroom waar hij was, dus er gaat geen tekst verloren; de val is een paginalus die NewPage blijft aanroepen terwijl de aanroep nul blijft teruggeven. Dat gebeurt wanneer de regio korter is dan één regel, of wanneer een minimum-aantal-regels-instelling in de geboden ruimte niet kan worden gehaald. De loop hieronder behandelt nul als fout in plaats van te blijven draaien

var
  Lib: TPDFlib;
  FontID, Flow, Drawn: Integer;
begin
  Lib := TPDFlib.Create;
  try
    Lib.SetDocumentLanguage('de-DE');      // vóór NewTextFlow, zie hieronder
    FontID := Lib.AddTrueTypeFont('Georgia', 1);
    Lib.SetTextSize(10.5);

    Flow := Lib.NewTextFlow(ArticleBody);
    try
      Lib.SetTextFlowHyphenation(Flow, 1, 3, 3);
      Lib.SetTextFlowMinLines(Flow, 2);   // geen enkele regel achtergelaten aan de voet van een kolom

      repeat
        // Links 66, Boven 72, regio 480 x 620 pt, 3 kolommen, gutters 18 pt, gebalanceerd
        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 brengt het font terug op 12 pt
      until False;
    finally
      Lib.ReleaseTextFlow(Flow);
    end;

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

De coördinaten worden gemeten vanaf de linkerbovenhoek van de pagina welke oorsprong je ook hebt gezet, want de kolomaanroep zet zijn regels van boven naar beneden vanaf Top. Met de standaard links-uitlijning begint elke regel aan de linkerrand van zijn kolom, dus speling door een slechte breuk toont zich als een oneffen rechterrand; bij uitgevulde tekst verandert dezelfde speling in rivieren

Vergelijking van PDF Library for Delphi tussen uitgevulde smalle kolommen met en zonder afbreking, die toont hoe afbreking inschakelen het lange woord breekt en rivieren van witruimte verwijdert
Taalbewuste woordafbreking zet de breuk binnen het woord, zodat de speling bij uitvullen nooit uitgroeit tot witte rivieren

Waar komt de afbreektaal vandaan?

Een nieuwe stroom neemt zijn taal over uit de Catalog-/Lang-entry van het document op het moment dat NewTextFlow draait. Dat is dezelfde waarde die screenreaders en zoekindexeerders lezen, dus een document dat zijn taal al verklaart, zoals getagde uitvoer van automatische tagging voor toegankelijke PDF's, krijgt afbreking gratis. De timing weegt wel. Roep SetDocumentLanguage aan nadat de stroom bestaat en die stroom ziet hem nooit; het eerste voorbeeld zet de taal eerst voor precies die reden

Noemt de tag een ondersteunde taal, dan schakelt automatische afbreking zichzelf in. De regels dekken Engels, Duits, Nederlands, Frans, Spaans, Italiaans, Portugees, Russisch, Turks, Deens, Zweeds, Fins, Pools, Tsjechisch en Hongaars. Regio-subtags worden vóór de opzoeking weggegooid, dus de-CH, de-AT en de breken alle drie als Duits. Een tag die de regels niet dekken, zoals ja, wordt geaccepteerd, en het automatische breken zet zich voor die stroom simpelweg uit

Drie retourwaarden vertellen je wat er gebeurde, en ze zijn het controleren waard in code die de taal uit gebruikersdata ontvangt:

  • SetTextFlowLanguage geeft alleen 0 terug voor een misvormde tag; een goed gevormde tag voor een niet-gedekte taal geeft 1 terug en laat automatische afbreking uit
  • SetTextFlowHyphenation met Enable = 1 geeft 0 terug wanneer de taal van de stroom geen regels heeft, zodat een breker geen breukpunten kan verzinnen zonder taal erachter
  • GetTextFlowHyphenation meldt of het automatische breken op dit moment aan staat, en dat is de waarde om te loggen wanneer een layout er verkeerd uitziet

Ook hier weegt de volgorde. SetTextFlowLanguage berekent de aan/uit-toestand opnieuw vanuit de nieuwe taal, dus hem aanroepen na SetTextFlowHyphenation(Flow, 0, …) zet afbreking weer aan voor een ondersteunde taal. Stel eerst de taal in, daarna de afbreekopties

MinPrefix en MinSuffix zijn een huisstijl-instelling

De twee gehele getallen na de enable-vlag zijn het minimum aantal letters dat vóór de breuk op de regel moet blijven en erna naar de volgende regel moet overgaan. Beide accepteren 1 tot 16. Schakelt afbreking aan alleen door de taal, dan staan beide op 2, en een woord komt alleen voor breuk in aanmerking als het ten minste MinPrefix + MinSuffix + 1 letters heeft

Twee en twee is de instelling die we in bijna elk document zouden aanpassen. Ze levert meer breukmogelijkheden op, maar een fragment van twee letters aan het einde van een regel leest als een typefout, en in het Duits of Nederlands splijt ze dingen af als een voorvoegsel van twee letters dat de lezer dan weer moet aanplakken. Drie en drie kost een paar oneffenere regels en oogt als zetwerk. Verhoog de minimums verder bij grote letters, waar elk fragment prominent is; ga alleen naar twee bij een echt smalle kolom waar je hebt beslist dat een korte maat een schone maat verslaat

Welke woorden mogen breken, en wat er met een URL gebeurt

Regels breken op spaties en tabs, en een line feed dwingt een nieuwe regel af. Binnen een woord kijkt automatische afbreking alleen naar woorden die volledig uit letters bestaan (Latijn, inclusief de geaccentueerde ranges van Latin Extended, en Cyrillisch), met eventuele voorafgaande of navolgende interpunctie opzij gezet. De regels zijn conservatieve combinaties van klinkers, toegestane medeklinkerclusters en gangbare affixen, dus ze plaatsen minder breukpunten dan een woordenboek-hyphenator zou doen. Woorden met cijfers of interne interpunctie, zoals ISO-32000 of v2Beta, en woorden langer dan 128 letters krijgen geen automatische punten

Zachte afbreekstrepen (U+00AD) zijn de override. Bevat een woord er één of meer, dan worden die posities zijn enige breukpunten: de automatische regels worden voor dat woord overgeslagen, en de zachte afbreekstrepen werken zelfs wanneer automatische afbreking uit staat of de taal geen regels heeft. Gebruik ze voor merknamen, productcodes en termen die de regels slecht splijten; in het volgende voorbeeld zijn Rechnungs en prüfungs de enige twee plekken waar de samenstelling kan breken

var
  Flow: Integer;
  Body, Rest: WideString;
begin
  // U+00AD markeert de enige plekken waar deze samenstelling mag breken
  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 is je eigen logroutine

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

    // Wat niet paste komt precies zoals ingevoerd terug,
    // zachte afbreekstrepen inbegrepen
    Rest := Lib.GetTextFlowRemaining(Flow);
  finally
    Lib.ReleaseTextFlow(Flow);
  end;
end;

Een afbreekstreepje wordt alleen getekend bij de breuk die werkelijk wordt gekozen. Niet-gekozen zachte afbreekstrepen zijn onzichtbaar in zowel meting als tekening, en de breuk wordt geregistreerd tegen de originele tekst, wat de reden is dat GetTextFlowRemaining de zachte afbreekstrepen onaangeroerd teruggeeft. Het naïeve ontwerp gaat hier verkeerd op een herkenbare manier: hij schrijft het streepje in de string terwijl hij een kandidaat probeert, de breuk schuift later op, en een verdwaald streepje belandt midden in een regel

Een token dat in geen enkele regel past, een lange URL of een toegangsnummer zonder legale breuk, wordt afgekapt op het langste voorvoegsel dat past, zonder afbreekstreepje. De kap valt nooit tussen de twee helften van een surrogaatpaar of vóór een combinerend diakritisch teken, dus een emoji of een letter met accent wordt nooit over regels heen gesplitst

Wat Balance=1 op de laatste pagina verandert

Het argument Balance weegt alleen wanneer alles wat overblijft in de regio past. In dat geval deelt DrawTextFlowColumns het resterende regelgetal door het kolomaantal, rondt naar boven af, en gebruikt dat als hoogte van elke kolom. Tweeëntwintig resterende regels in drie kolommen komen naar buiten als 8, 8 en 6. Past de rest niet, dan houdt elke kolom zijn volle hoogte zodat de pagina zo veel mogelijk draagt en de rest op de volgende pagina verdergaat

Een minimum-aantal-regels-instelling kan de gebalanceerde hoogte verhogen. Met SetTextFlowMinLines(Flow, 3) en vier regels over zit de gebalanceerde hoogte van twee onder het minimum, dus de kolommen vullen op volgorde: drie regels in de eerste kolom, één in de tweede, de derde leeg. Een korte staart aan het allerlaatste einde van de passage wordt altijd geplaatst, want er is geen andere plek voor hem. Om ook bovenaan de volgende kolom ten minste twee regels samen te houden neemt SetTextFlowPaginationLines wees- en weduwenminimums in één aanroep

Diagram van PDF Library for Delphi met de Balance-parameter die eerdere kolomregio's vol houdt terwijl de laatste regio wordt ingekort tot een gelijk regelaantal in elke kolom
Balancering geldt alleen aan het einde van een passage, waar ze elke kolom bijsnijdt naar hetzelfde regelaantal

Geef voor doorlopende artikelen elke keer 1 door. Halverwege een passage verandert het niets. De kolommen zitten toch al vol. We zouden alleen 0 doorgeven wanneer de kolomregio een vaste box is in een formulier-achtige layout, waar een rest van 52 regels in kolommen van 43 regels zou moeten belanden als 43, 9 en 0 in plaats van 18, 18 en 16

Wanneer de layout zelf afhangt van hoe lang de passage is, meet voordat je tekent. MeasureTextFlow geeft terug hoeveel regels de rest van de stroom nodig heeft bij een gegeven breedte, met hetzelfde breken, afbreking inbegrepen, zonder de stroom te verplaatsen

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);
    // Regelpitch die de kolomaanroep gebruikt: 1.2 x de gekozen texthoogte
    LinePitch := Lib.GetTextHeight * 1.2;
    LinesPerColumn := Trunc(620 / LinePitch);

    Needed := Lib.MeasureTextFlow(Flow, (480 - 2 * 18) / 3);
    if Needed > 3 * LinesPerColumn then
      UseTwoPageSpread      // je eigen layoutkeuze
    else
      UseSinglePage;        // Balance=1 maakt de kolommen gelijk

    Lib.DrawTextFlowColumns(Flow, 66, 72, 480, 620, 3, 18, 1);
    if Lib.TextFlowFinished(Flow) <> 1 then
      CarryOver(Lib.GetTextFlowRemaining(Flow));   // ook je eigen
  finally
    Lib.ReleaseTextFlow(Flow);
  end;
end;

Houd font en grootte identiek van box tot box

DrawTextFlow, DrawTextFlowColumns en MeasureTextFlow breken allemaal regels met het font en de grootte die op het moment van aanroep zijn geselecteerd. Verander één van beide tussen twee boxen van dezelfde stroom en de tweede box breekt anders dan wat de eerste mat. De regelpitch schuift mee, want hij is 1.2 keer de geselecteerde texthoogte. Stel dat GetTextHeight voor je font 12 punten meldt: de pitch is 14.4 punten en een kolom van 620 punten herbergt 43 regels

De makkelijke manier om hierover te struikelen is een nieuwe pagina. NewPage kiest het huidige font opnieuw, maar op 12 punten, en SelectFont doet hetzelfde. Een stroom die op pagina één op 10.5 punten staat draait vanaf pagina twee dus op 12 punten tenzij de loop opnieuw SetTextSize aanroept: bredere woorden, een hogere pitch, minder regels per kolom, en een MeasureTextFlow-resultaat van pagina één dat niet meer matcht. Het symptoom lijkt intermitterend omdat pagina één altijd klopt. Kies na elke NewPage het font opnieuw en daarna de grootte, in die volgorde, zoals het eerste voorbeeld doet

PDF Library for Delphi: Waarschuwingsdiagram van regelafbrekingen die afdwalen na een fontwissel tussen boxen, afgezet tegen de stabiele lus van het opnieuw kiezen van het font na elke nieuwe pagina
Alle drie de flow-methoden breken regels met het momenteel geselecteerde lettertype, dus het lettertype moet ongewijzigd pagina's overleven

Passages die scripts mengen gaan bij meting en tekening door hetzelfde pad met geselecteerd font, dus de vervangende lettertypen die automatische fontfallback voor CJK- en emoji-tekst kiest openen geen gat tussen beide. In rapportlayouts waar de stroom de pagina deelt met koppen, voetteksten en datagedreven blokken geldt de volgorde uit de dataset-report-engine: meet eerst, plaats de vaste elementen, en geef de stroom daarna wat er aan regio overblijft

De hier behandelde tekststroom-aanroepen, van aanmaken en meten tot terugspoelen en vrijgeven, maken deel uit van PDF Library for Delphi voor Delphi, C++Builder en Lazarus. De functiereferentie en de download staan op de productpagina van PDF Library for Delphi