Artigo Técnico

Hifenização e colunas de texto balanceadas em PDF

Despeje uma ficha de produto alemã em três colunas de 148 points e duas coisas dão errado ao mesmo tempo. A linha antes de uma palavra como Rechnungsprüfungsausschuss pode terminar um terço vazia, porque o espaço antes desse composto de 26 letras era o único lugar para quebrar. E na última página o texto restante preenche uma coluna, parte de uma segunda e deixa a terceira em branco. Um quebrador de linhas que só conhece espaços, e nunca conta o que resta, produz exatamente essa página

O conserto tem duas metades: quebrar dentro das palavras usando regras para a língua do texto, e dimensionar as colunas finais a partir do número de linhas que ainda faltam colocar. As duas metades só funcionam se a contagem de linhas usada na decisão vier das mesmas quebras que serão desenhadas, hífens incluídos, numa largura de coluna de 148 points em vez da região de 480 points

Um fluxo de três colunas com hifenização na PDF Library for Delphi

A PDF Library for Delphi mantém um trecho como um fluxo de texto: o NewTextFlow retorna um handle, o SetTextFlowLanguage e o SetTextFlowHyphenation controlam onde as palavras podem quebrar, e o DrawTextFlowColumns despeja o máximo do texto restante que couber em uma a 64 colunas de largura igual e avança o fluxo. A largura da coluna é a largura da região menos as calhas, dividida pelo número de colunas, então uma região de 480 points com três colunas e calhas de 18 points dá (480 − 2 × 18) / 3 = 148 points por coluna

A chamada retorna o número total de linhas que desenhou. Zero significa que nada coube, e nesse caso o fluxo fica onde estava, então nenhum texto se perde; a armadilha é um laço de páginas que fica chamando NewPage enquanto a chamada continua retornando zero. Isso acontece quando a região é mais curta que uma linha, ou quando uma definição de linhas mínimas não pode ser satisfeita no espaço oferecido. O laço abaixo trata zero como erro em vez de girar

var
  Lib: TPDFlib;
  FontID, Flow, Drawn: Integer;
begin
  Lib := TPDFlib.Create;
  try
    Lib.SetDocumentLanguage('de-DE');      // antes do NewTextFlow, veja abaixo
    FontID := Lib.AddTrueTypeFont('Georgia', 1);
    Lib.SetTextSize(10.5);

    Flow := Lib.NewTextFlow(ArticleBody);
    try
      Lib.SetTextFlowHyphenation(Flow, 1, 3, 3);
      Lib.SetTextFlowMinLines(Flow, 2);   // nenhuma linha única abandonada no pé de uma coluna

      repeat
        // Esquerda 66, Topo 72, região de 480 x 620 pt, 3 colunas, calhas de 18 pt, balanceado
        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 traz a fonte de volta a 12 pt
      until False;
    finally
      Lib.ReleaseTextFlow(Flow);
    end;

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

As coordenadas são medidas do canto superior esquerdo da página, qualquer que seja a origem que você tenha definido, porque a chamada de colunas dispõe as linhas para baixo a partir de Top. Com o alinhamento à esquerda padrão, cada linha começa na borda esquerda da coluna dela, então a folga de uma quebra ruim aparece como uma borda direita irregular; em texto justificado a mesma folga vira rios

Comparação do PDF Library for Delphi de colunas estreitas justificadas com e sem hifenização, mostrando como habilitar a hifenização quebra a palavra longa e remove rios de espaço em branco
A hifenização consciente do idioma coloca a quebra dentro da palavra, de modo que a folga da justificação nunca se acumula em rios

De onde vem a língua da hifenização?

Um fluxo novo recebe a língua dele da entrada /Lang do Catalog do documento no momento em que o NewTextFlow roda. Esse é o mesmo valor que leitores de tela e indexadores de busca leem, então um documento que já declara a língua dele, como a saída com tags do tagueamento automático para PDFs acessíveis, ganha hifenização de graça. O momento importa, porém. Chame o SetDocumentLanguage depois de o fluxo existir e aquele fluxo nunca o verá; o primeiro exemplo define a língua primeiro por exatamente essa razão

Quando a tag nomeia uma língua suportada, a hifenização automática liga sozinha. As regras cobrem inglês, alemão, holandês, francês, espanhol, italiano, português, russo, turco, dinamarquês, sueco, finlandês, polonês, tcheco e húngaro. Subtags de região são descartadas antes da consulta, então de-CH, de-AT e de hifenizam todos como alemão. Uma tag que as regras não cobrem, como ja, é aceita, e a quebra automática simplesmente desliga para aquele fluxo

Três valores de retorno dizem o que aconteceu, e valem a checagem em código que recebe a língua de dados de usuário:

  • O SetTextFlowLanguage retorna 0 só para uma tag malformada; uma tag bem formada para uma língua sem cobertura retorna 1 e deixa a hifenização automática desligada
  • O SetTextFlowHyphenation com Enable = 1 retorna 0 quando a língua do fluxo não tem regras, para que um quebrador não invente pontos de quebra sem língua por trás
  • O GetTextFlowHyphenation reporta se a quebra automática está ligada agora, que é o valor a registrar no log quando um layout parece errado

A ordem também importa aqui. O SetTextFlowLanguage recalcula o estado ligado/desligado a partir da língua nova, então chamá-lo depois de SetTextFlowHyphenation(Flow, 0, …) religa a hifenização para uma língua suportada. Defina a língua, depois as opções de hifenização

MinPrefix e MinSuffix são uma definição de estilo da casa

Os dois inteiros depois da flag de ativação são o número mínimo de letras que precisa ficar na linha antes de uma quebra e passar para a linha seguinte depois dela. Ambos aceitam 1 a 16. Quando a hifenização liga por causa da língua apenas, ambos valem 2, e uma palavra só é considerada para quebra quando tem pelo menos MinPrefix + MinSuffix + 1 letras

Dois e dois é a definição que mudaríamos em quase todo documento. Ela produz mais oportunidades de quebra, mas um fragmento de duas letras no fim de uma linha lê como um typo, e em alemão ou holandês ele destacaria coisas como um prefixo de duas letras que o leitor precisa remontar. Três e três custa algumas linhas irregulares a mais e parece diagramação. Eleve os mínimos para corpos grandes, em que cada fragmento é proeminente; baixe para dois apenas numa coluna genuinamente estreita, em que você decidiu que uma medida apertada vence uma limpa

Quais palavras podem quebrar, e o que acontece com uma URL

As linhas quebram em espaços e tabs, e um line feed força uma linha nova. Dentro de uma palavra, a hifenização automática olha só para palavras feitas inteiramente de letras (latinas, incluindo as faixas Latin Extended acentuadas, e cirílicas), com qualquer pontuação inicial ou final posta de lado. As regras são combinações conservadoras de vogais, clusters legais de consoantes e afixos comuns, então colocam menos pontos de quebra do que colocaria um hifenizador de dicionário. Palavras com dígitos ou pontuação interna, como ISO-32000 ou v2Beta, e palavras com mais de 128 letras não recebem pontos automáticos

Hífens suaves (U+00AD) são a sobrescrita. Se uma palavra contém algum, essas posições viram os únicos pontos de quebra dela: as regras automáticas são puladas para aquela palavra, e os hífens suaves funcionam mesmo com a hifenização automática desligada ou quando a língua não tem regras. Use-os para nomes de marca, códigos de produto e termos que as regras separam mal; no próximo exemplo, Rechnungs e prüfungs são os únicos dois lugares em que o composto pode quebrar

var
  Flow: Integer;
  Body, Rest: WideString;
begin
  // U+00AD marca os únicos lugares em que esse composto pode quebrar
  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 é a sua própria rotina de log

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

    // O que não coube volta exatamente como foi passado,
    // hífens suaves incluídos
    Rest := Lib.GetTextFlowRemaining(Flow);
  finally
    Lib.ReleaseTextFlow(Flow);
  end;
end;

Um hífen-menos é desenhado apenas na quebra de fato escolhida. Hífens suaves não escolhidos ficam invisíveis tanto na medição quanto no desenho, e a quebra é registrada contra o texto original, razão pela qual o GetTextFlowRemaining devolve os hífens suaves intocados. O design ingênuo erra isso de forma reconhecível: ele grava o hífen na string enquanto testa uma candidata, a quebra mais tarde se move, e um hífen perdido acaba no meio de uma linha

Um token que não cabe em linha nenhuma, uma URL longa ou um número de acesso sem quebra legal, é cortado no prefixo mais longo que couber, sem hífen adicionado. O corte nunca cai entre as duas metades de um par substituto nem antes de um sinal combinável, então um emoji ou uma letra acentuada nunca é dividido entre linhas

O que Balance=1 muda na última página

O argumento Balance só importa quando tudo o que resta cabe dentro da região. Nesse caso o DrawTextFlowColumns divide a contagem de linhas restante pela contagem de colunas, arredonda para cima e usa isso como a altura de cada coluna. Vinte e duas linhas restantes em três colunas saem como 8, 8 e 6. Quando o restante não cabe, cada coluna mantém a altura cheia para que a página carregue o máximo possível e o resto continue na próxima página

Uma definição de linhas mínimas pode elevar a altura balanceada. Com SetTextFlowMinLines(Flow, 3) e quatro linhas restantes, a altura balanceada de dois fica abaixo do mínimo, então as colunas enchem em ordem: três linhas na primeira coluna, uma na segunda, a terceira vazia. Uma cauda curta bem no fim do trecho é sempre colocada, já que não há outro lugar para ela. Para manter ao menos duas linhas juntas no topo da próxima coluna também, o SetTextFlowPaginationLines recebe mínimos de órfã e viúva em uma única chamada

Diagrama do PDF Library for Delphi do parâmetro Balance mantendo as regiões de coluna anteriores cheias enquanto encurta a região final para uma contagem de linhas igual em todas as colunas
O balanceamento se aplica apenas ao fim de um trecho, onde reduz todas as colunas à mesma contagem de linhas

Para artigos contínuos, passe 1 toda vez. No meio do trecho não muda nada. As colunas estão cheias de qualquer forma. Passaríamos 0 só quando a região de colunas é uma caixa fixa em um layout de tipo formulário, em que um restante de 52 linhas em colunas de 43 linhas deve cair como 43, 9 e 0 em vez de 18, 18 e 16

Quando o layout em si depende de quão longo o trecho é, meça antes de desenhar. O MeasureTextFlow retorna quantas linhas o resto do fluxo precisa em uma dada largura, usando a mesma quebra, hifenização incluída, sem mover o fluxo

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);
    // Entrelinha que a chamada de colunas usa: 1,2 x a altura de texto selecionada
    LinePitch := Lib.GetTextHeight * 1.2;
    LinesPerColumn := Trunc(620 / LinePitch);

    Needed := Lib.MeasureTextFlow(Flow, (480 - 2 * 18) / 3);
    if Needed > 3 * LinesPerColumn then
      UseTwoPageSpread      // sua própria escolha de layout
    else
      UseSinglePage;        // Balance=1 vai nivelar as colunas

    Lib.DrawTextFlowColumns(Flow, 66, 72, 480, 620, 3, 18, 1);
    if Lib.TextFlowFinished(Flow) <> 1 then
      CarryOver(Lib.GetTextFlowRemaining(Flow));   // também sua
  finally
    Lib.ReleaseTextFlow(Flow);
  end;
end;

Mantenha a fonte e o tamanho idênticos de caixa em caixa

O DrawTextFlow, o DrawTextFlowColumns e o MeasureTextFlow quebram todos as linhas com a fonte e o tamanho selecionados no momento em que são chamados. Mude qualquer um entre duas caixas do mesmo fluxo e a segunda caixa quebra diferente do que a primeira mediu. A entrelinha se move junto, já que ela é 1,2 vezes a altura do texto selecionado. Suponha que o GetTextHeight reporta 12 points para a sua face: a entrelinha é 14,4 points e uma coluna de 620 points comporta 43 linhas

O jeito fácil de tropeçar nisso é uma página nova. O NewPage reseleciona a fonte atual, mas a 12 points, e o SelectFont faz o mesmo. Um fluxo definido a 10,5 points na página um, portanto, roda a 12 points da página dois em diante, a menos que o laço chame o SetTextSize de novo: palavras mais largas, entrelinha mais alta, menos linhas por coluna, e um resultado do MeasureTextFlow da página um que não bate mais. O sintoma parece intermitente porque a página um está sempre certa. Reselecione a fonte e depois o tamanho após cada NewPage, nessa ordem, como o primeiro exemplo faz

PDF Library for Delphi: diagrama de alerta de quebras de linha derivando após uma troca de fonte entre caixas, contrastado com o loop estável de reselecionar a fonte a cada nova página
Os três métodos de fluxo quebram linhas com a fonte atualmente selecionada, então a face precisa permanecer inalterada entre páginas

Trechos que misturam escritas passam pelo mesmo caminho de fonte selecionada na medição e no desenho, então as faces substitutas escolhidas pelo fallback automático de fonte para texto CJK e emojis não abrem uma brecha entre os dois. Em layouts de relatório em que o fluxo divide a página com cabeçalhos, rodapés e blocos orientados a dados, a ordem do motor de relatórios de dataset se aplica: meça primeiro, posicione os elementos fixos, depois entregue ao fluxo a região que sobrar

As chamadas de fluxo de texto cobertas aqui, da criação e medição ao rebobinar e liberar, fazem parte da PDF Library for Delphi para Delphi, C++Builder e Lazarus. A referência de funções e o download estão na página do produto PDF Library for Delphi