Artigo Técnico

Caractere de preenchimento * do Excel em PDF e impressão

Exporte uma planilha no formato contábil 44 do Excel com um formatter caseiro e o PDF mostra $1,234.50 colado, ou $* 1,234.50 com um asterisco perdido. Esse espaço é um fill * dimensionado pela largura da coluna e pela fonte, e a posição dele no texto, que o HotXLS retorna de TXLSXCell.GetFormattedTextFill, é tudo de que um renderer precisa para contar as repetições

Como * e _ funcionam num formato de número do Excel?

A ECMA-376 Part 1 §18.8.30 define os dois caracteres na tabela de símbolos de código de formato dela. O * repete o caractere seguinte "tantas vezes quantas bastem para preencher a coluna até a largura atual"; uma seção pode ter um asterisco, e se vários aparecerem, todos menos o último são ignorados. O _ "salta a largura do caractere seguinte", então o _) deixa um branco tão largo quanto um parêntese de fechamento e valores positivos se alinham com negativos exibidos como (1,234.50). Os exemplos do padrão são curtos. O 0*- põe traços depois do número até a borda da célula, o *0 na frente de um formato dá zeros à esquerda, e o 0*x mostra 3 como 3xxxxxx numa coluna de uma largura específica. Os formatos que combinam os dois caracteres são os formatos contábeis embutidos do Excel, IDs 41 a 44. Esses números são do próprio Excel: a tabela embutida na §18.8.30 salta de 40 direto para 45, e o HotXLS registra os quatro códigos abaixo na numeração do Excel

Excel IDCódigo de formatoSímboloDecimais
41_(* #,##0_);_(* (#,##0);_(* "-"_);_(@_)nenhum0
42_("$"* #,##0_);_("$"* (#,##0);_("$"* "-"_);_(@_)$0
43_(* #,##0.00_);_(* (#,##0.00);_(* "-"??_);_(@_)nenhum2
44_("$"* #,##0.00_);_("$"* (#,##0.00);_("$"* "-"??_);_(@_)$2

Leia a seção positiva do 44, _("$"* #,##0.00_), da esquerda para a direita: um branco da largura de (, um sinal de cifrão, um espaço repetido para preencher a coluna, o número, e um branco da largura de ). A seção negativa troca esse branco final por parênteses de verdade. A seção zero imprime um traço seguido de ?? — dois brancos da largura de um dígito que põem o traço na coluna do ponto decimal. Qual das quatro seções um valor escolhe, e o que uma seção vazia faz, segue as regras das seções de formato de número do Excel. Tire o fill e o cifrão cai em cima dos dígitos. Imprima o asterisco e o leitor está olhando para sintaxe de formato

Anatomia da seção positiva do formato contábil 44 do Excel no HotXLS para Delphi: brancos da largura de parêntese, sinal de cifrão, fill de espaço repetido e o número
um asterisco faz o caractere seguinte repetir até a largura da coluna, e todo branco numa seção contábil vem de um underscore

Por que um formatter não pode inserir as repetições sozinho?

Ele não conhece a contagem. O número de repetições é a largura da coluna menos a largura de todo o resto, dividido pela largura de um caractere de fill. Cada termo depende da fonte, do tamanho, do zoom e do device de saída. Um formatter que retorna uma string plain teria que escolher um número, e qualquer número fixo está errado assim que alguém redimensiona a coluna. O HotXLS divide o trabalho. O TXLSXCell.FormattedText retorna o texto de exibição sem cópia do caractere de fill, e o GetFormattedTextFill retorna esse mesmo texto mais o caractere de fill e um índice: o número de caracteres antes do ponto onde as repetições pertencem. O método retorna False quando o formato não tem fill e para uma célula de rich text, cujos runs são desenhados como estão

O sinal de menos automático vem antes do fill. Com o formato **0 e o valor -5, o texto é -5, o caractere de fill é * e o índice é 1. Uma célula larga portanto exibe -****5, a mesma string que o Range.Text do Excel dá para aquela célula. Um chamador sem coluna não ganha fill nenhum. A função de planilha TEXT é um chamador assim, então no motor de cálculo do HotXLS TEXT(A1, "$* #,##0") com 1234 em A1 avalia para $1,234. O código abaixo define três formatos e imprime o que um renderer recebe para cada

Contrato do GetFormattedTextFill no HotXLS para Delphi: texto de prefixo, caractere de fill e índice de corte que permitem a um renderer contar as repetições para qualquer largura de coluna
a célula informa o ponto de corte em vez de uma contagem de repetições, porque só o canvas de desenho conhece a largura real da coluna
uses
  SysUtils, lxHandleX;

procedure InspectFills;
const
  Formats: array[0..2] of WideString = (
    // o mesmo código do formato embutido 44 do Excel
    '_("$"* #,##0.00_);_("$"* (#,##0.00);_("$"* "-"??_);_(@_)',
    '0*-',     // traços depois do número
    '**0');    // estrelas na frente do número
  Values: array[0..2] of Double = (1234.5, 42, -5);
  // Cada linha deve imprimir:
  //   [ $] fill " " [1,234.50 ]
  //   [42] fill "-" []
  //   [-] fill "*" [5]
var
  Book: TXLSXWorkbook;
  Sheet: TXLSXWorksheet;
  Text: WideString;
  Fill: WideChar;
  FillIndex, I: Integer;
begin
  Book := TXLSXWorkbook.Create;
  try
    Sheet := Book.Sheets.Add('Fills');
    for I := 0 to High(Formats) do
    begin
      Sheet.Cells[I + 1, 1].NumberFormat := Formats[I];
      Sheet.Cells[I + 1, 1].Value := Values[I];
      if Sheet.Cells[I + 1, 1].GetFormattedTextFill(Text, Fill, FillIndex) then
        Writeln(Format('[%s] fill "%s" [%s]', [
          Copy(Text, 1, FillIndex), string(Fill),
          Copy(Text, FillIndex + 1, MaxInt)]))
      else
        Writeln('no fill: ', string(Sheet.Cells[I + 1, 1].FormattedText));
    end;
    Sheet.SaveAsPDF('fills.pdf');   // o export PDF dispõe o fill por coluna
  finally
    Book.Free;
  end;
end;

Cada linha mostra o prefixo, o caractere de fill e o sufixo entre colchetes. Repare nos brancos: na primeira linha o prefixo é um espaço e um cifrão, e o sufixo termina com um espaço, ambos produzidos pelos pares _. O SaveAsPDF trabalha a partir das mesmas três partes e calcula a contagem de repetições pela largura real da coluna. Em fills.pdf o cifrão deve ficar no padding esquerdo da primeira célula, e os traços depois do 42 devem correr até a borda direita da segunda. Page setup, margens e fontes desse arquivo ficam por conta das configurações regulares do export PDF de planilha

De que lado fica a fração de caractere que sobra?

Para células General e alinhadas à esquerda, o espaço entre o fill e o sufixo. A contagem de repetições é um número inteiro, então uma fração de caractere quase sempre sobra, e a §18.8.30 não diz nada sobre onde ela vai. A própria saída PDF do Excel e o Range.Text dela mostram o posicionamento seguinte, que depende do alinhamento horizontal:

Matriz de posicionamento da fração que sobra para caracteres de fill no HotXLS para Delphi, do alinhamento general e esquerda até centro, direita e shrink to fit
os alinhamentos general e esquerda põem a fração que sobra entre o fill e o sufixo, o que mantém uma coluna de cifrões parada
  • General e esquerda: o prefixo encosta no padding esquerdo, o sufixo encosta no padding direito, e a sobra fica entre o fill e o sufixo (no fim da linha quando não há sufixo)
  • Centro: prefixo e fill se movem para a direita pela metade da sobra; alinhamento à direita os move por ela inteira
  • Fill, justify, distributed e texto quebrado: as três partes correm da esquerda, com a sobra no fim da linha
  • Indentação estreita a largura disponível como de costume, e uma célula "shrink to fit" não ganha fill

O alinhamento General é onde renderers caseiros erram. Números sob General são normalmente alinhados à direita. Uma célula com fill não é. Mantenha a regra "números vão para a direita" e a sobra cai na frente do fill, empurrando o cifrão para fora do padding esquerdo por até uma largura de espaço. Ao longo de uma coluna de valores no formato 44, os cifrões então balançam de linha em linha. Layouts menos comuns seguem o mesmo modelo:

  • Texto rotacionado: o comprimento do fill vem da linha mais longa que ainda cabe dentro da célula depois de rotacionada
  • Rich text: o caractere repetido toma o estilo do caractere logo antes da posição do fill
  • Center across selection: o fill cobre todo o vão
  • Texto de múltiplas linhas: só a linha que contém a posição do fill ganha repetições

Planilhas da direita para a esquerda são o caso que o HotXLS não copia do export PDF do Excel. Esse export descarta o fill e os glifos do prefixo, embora o Range.Text para as mesmas células ainda os contenha. O HotXLS dispõe essas células do jeito que a grade as mostra, com o fill no lugar

Desenhando o fill num canvas VCL

Meça com o canvas em que você vai desenhar. Isso vale para um grid customizado, uma banda de relatório e uma miniatura igualmente. O canvas VCL seleciona um tamanho de fonte inteiro quando escala, então uma largura calculada das métricas de fonte no tamanho fracionário sai um pouco mais estreita que o que o GDI pinta. O erro por caractere é minúsculo. Ao longo de uma sequência de repetições ele soma. Conte pela largura mais estreita e a parte esquerda transborda o retângulo; com DT_END_ELLIPSIS entre as flags de desenho, o GDI então põe reticências em cima do sufixo. A rotina abaixo cuida do caso comum de linha única com alinhamento General ou esquerda e manda todo o resto pelo caminho plain do TextRect:

uses
  Windows, Types, Graphics, lxHandleX;

procedure DrawFilledCell(Canvas: TCanvas; const R: TRect; Cell: TXLSXCell);
const
  Pad = 2;                                   // padding interno da célula, pixels
var
  Text: WideString;
  Fill: WideChar;
  FillIndex, Avail, Used, FillWidth, Count: Integer;
  Prefix, Suffix: string;
begin
  if not Cell.GetFormattedTextFill(Text, Fill, FillIndex) then
  begin
    Canvas.TextRect(R, R.Left + Pad, R.Top + Pad, Cell.FormattedText);
    Exit;
  end;
  Prefix := Copy(Text, 1, FillIndex);
  Suffix := Copy(Text, FillIndex + 1, MaxInt);

  // Meça com o mesmo canvas, fonte e tamanho que vão desenhar o texto
  Avail := (R.Right - R.Left) - 2 * Pad;
  Used := Canvas.TextWidth(Prefix) + Canvas.TextWidth(Suffix);
  FillWidth := Canvas.TextWidth(string(Fill));
  Count := 0;
  if (FillWidth > 0) and (Used < Avail) then
    Count := (Avail - Used) div FillWidth;   // só caracteres inteiros

  // General / esquerda: prefixo + fill à esquerda, sufixo à direita,
  // a fração que sobra fica entre o fill e o sufixo
  Canvas.TextOut(R.Left + Pad, R.Top + Pad, Prefix + StringOfChar(Fill, Count));
  Canvas.TextOut(R.Right - Pad - Canvas.TextWidth(Suffix), R.Top + Pad, Suffix);
end;

Desenhar as duas metades com chamadas separadas mantém o valor preso à borda direita, como quer que a divisão inteira arredonde. Para células centralizadas ou alinhadas à direita, desloque o primeiro TextOut por metade ou pela totalidade de Avail - Used - Count * FillWidth. Células rotacionadas e de múltiplas linhas são mais simples de tratar de outro jeito: insira as repetições contadas no texto em FillIndex e desenhe o resultado como uma string com o seu código habitual de rotação ou quebra. Num grid feito à mão como esta grade de planilha customizada em Delphi, o mesmo canvas deve comandar alturas de linha e ranges mesclados também

Fill e underscore em texto de largura fixa e CSV

Saída de texto plain não tem pixels, mas ainda pode ter largura. O TXLSXCell.FormattedText escreve cada _x como um espaço comum, então a seção positiva do formato 44 volta como $1,234.50 com um branco em cada extremidade. Numa fonte proporcional um espaço costuma ser um pouco mais estreito que um parêntese, perto o bastante para uma prévia. Num relatório de texto monoespaçado todo caractere tem o mesmo avanço, então o espaço é um substituto exato e a contagem de fill é aritmética plain: a largura da coluna em caracteres menos o comprimento do texto. CSV é diferente. Uma planilha ou banco de dados que lê o arquivo quer um número, então escreva o Value da célula ali e guarde o texto com padding para relatórios que pessoas leem:

uses
  lxHandleX;

// Coluna de relatório de largura fixa: formato 44, valor 1234.5 e Width 14
// dão ' $   1,234.50 ' (três espaços repetidos depois do cifrão)
function PadToWidth(Cell: TXLSXCell; Width: Integer): WideString;
var
  Text: WideString;
  Fill: WideChar;
  FillIndex, Count: Integer;
begin
  if not Cell.GetFormattedTextFill(Text, Fill, FillIndex) then
    Exit(Cell.FormattedText);
  Count := Width - Length(Text);
  if Count < 0 then
    Count := 0;                    // texto mais largo que a coluna: sem repetições
  Result := Copy(Text, 1, FillIndex) + StringOfChar(Fill, Count) +
    Copy(Text, FillIndex + 1, MaxInt);
end;

Comece com uma célula: formato 44, o valor 1234.5, e uma chamada GetFormattedTextFill que deve informar um espaço no índice 2. Redimensione a coluna duas vezes e confira que o cifrão fica no padding esquerdo enquanto o 1,234.50 fica na borda direita. Depois que o seu renderer passar nisso, os outros alinhamentos são deslocamentos do primeiro TextOut, e uma página SaveAsPDF do componente Excel HotXLS Delphi é a referência com que compará-los