技術記事

PDF エクスポートと印刷での Excel の Fill 文字(*)

Excel の会計書式 44 のシートを手製のフォーマッタでエクスポートすると、PDF には $1,234.50 が詰まって印字されるか、$* 1,234.50 と迷子のアスタリスク付きで現れます。あの隙間は、列幅とフォントでサイズが決まる * フィルです。そしてそのテキスト内の位置——HotXLS が TXLSXCell.GetFormattedTextFill から返すもの——があれば、レンダラーは繰り返し回数を数えられます

Excel の数値書式で * と _ はどう働くか

ECMA-376 Part 1 の §18.8.30 は、両方の文字を書式コード記号の表に定義しています。* は次の文字を「現在の列幅を満たすのに十分な回数」繰り返します。1 セクションはアスタリスクを 1 個まで持ち、複数現れた場合は最後のもの以外が無視されます。_ は「次の文字の幅を飛ばす」ので、_) は閉じ括弧と同じ幅の空白を残し、正の金額は (1,234.50) と表示される負の金額と揃います。標準の例は短いものばかりです。0*- は数の後ろにセル端までダッシュを並べ、書式の前の *0 は先行ゼロを付け、0*x は特定の幅の列で 3 を 3xxxxxx と表示します。両方の文字を組み合わせた書式が、Excel の組み込み会計書式、ID 41 から 44 です。これらの番号は Excel 自身のものです。§18.8.30 の組み込み表は 40 から 45 へ飛んでいて、HotXLS は下の 4 つのコードを Excel の番号付けで登録します

Excel ID書式コード記号小数桁
41_(* #,##0_);_(* (#,##0);_(* "-"_);_(@_)なし0
42_("$"* #,##0_);_("$"* (#,##0);_("$"* "-"_);_(@_)$0
43_(* #,##0.00_);_(* (#,##0.00);_(* "-"??_);_(@_)なし2
44_("$"* #,##0.00_);_("$"* (#,##0.00);_("$"* "-"??_);_(@_)$2

44 の正セクション _("$"* #,##0.00_) を左から右へ読みましょう。( の幅の空白、ドル記号、列を満たすまで繰り返されるスペース、数、そして ) の幅の空白です。負セクションはその末尾の空白を実の括弧に替えます。ゼロセクションはダッシュに続けて ?? を印字します。桁 2 文字分の空白 2 つで、ダッシュが小数点の桁に乗ります。値が 4 セクションのどれを選ぶか、空セクションが何をするかは、Excel 数値書式のセクションの記事の規則に従います。フィルを剥ぎ取ればドル記号は数字の上に載ります。アスタリスクを印字すれば、読み手は書式構文を見せられているわけです

Delphi 向け HotXLS における Excel 会計書式 44 の正セクションの解剖図。括弧幅の空白、ドル記号、繰り返すスペースのフィル、そして数
1 つのアスタリスクが次の文字を列幅まで繰り返させ、会計セクションのすべての空白はアンダースコアから生まれます

フォーマッタが繰り返しを自分で挿入できない理由

回数を知らないからです。繰り返し回数は、列幅から他のすべての幅を引いたものを、フィル文字 1 個の幅で割った値です。各項はフォント、サイズ、ズーム、出力デバイスに依存します。素の文字列を返すフォーマッタはどこかの数を選ぶしかなく、固定の数は誰かが列をリサイズした途端に間違えます。HotXLS は仕事を分割します。TXLSXCell.FormattedText はフィル文字のコピーなしの表示テキストを返し、GetFormattedTextFill は同じテキストに、フィル文字とインデックスを添えて返します。繰り返しが属すべき位置の前にある文字数です。書式にフィルがないときと、リッチテキストセル——その run はあるがままに描かれます——には False を返します

自動のマイナス符号はフィルの前に来ます。書式 **0 で値 -5 のとき、テキストは -5、フィル文字は *、インデックスは 1 です。広いセルはしたがって -****5 を表示します。Excel の Range.Text がそのセルについて返すのと同じ文字列です。列を持たない呼び出し側にはフィルは一切付きません。TEXT ワークシート関数はまさにその呼び出し側で、HotXLS の計算エンジンでは、A1 に 1234 が入った状態の TEXT(A1, "$* #,##0") は $1,234 と評価されます。下のコードは 3 つの書式を設定し、レンダラーがそれぞれ何を受け取るかを印字します

Delphi 向け HotXLS における GetFormattedTextFill の契約。prefix テキスト、fill 文字、分割インデックスで任意の列幅に対する繰り返し回数をレンダラーが数えられる
セルは繰り返し回数の代わりに分割点を報告します。実際の列幅を知っているのは描画キャンバスだけだからです
uses
  SysUtils, lxHandleX;

procedure InspectFills;
const
  Formats: array[0..2] of WideString = (
    // Excel の組み込み書式 44 と同じコード
    '_("$"* #,##0.00_);_("$"* (#,##0.00);_("$"* "-"??_);_(@_)',
    '0*-',     // 数の後ろにダッシュ
    '**0');    // 数の前に星印
  Values: array[0..2] of Double = (1234.5, 42, -5);
  // 各行は次を印字するはず:
  //   [ $] 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');   // PDF エクスポートは列ごとにフィルをレイアウトする
  finally
    Book.Free;
  end;
end;

各行は角括弧で、プレフィックス、フィル文字、サフィックスを示します。空白に注目してください。最初の行ではプレフィックスがスペースとドル記号、サフィックスはスペースで終わり、どちらも _ のペアが作ったものです。SaveAsPDF は同じ 3 つのパーツから動き、実際の列幅から繰り返し回数を計算します。fills.pdf ではドル記号が最初のセルの左パディングに座り、42 の後ろのダッシュは 2 つ目のセルの右端まで走るはずです。そのファイルのページ設定、余白、フォントは、通常のワークシート PDF エクスポートの設定が扱います

文字の余り端数はどちら側に行くのか

General と左寄せのセルでは、フィルとサフィックスの間のスペースです。繰り返し回数は整数なので、1 文字の端数はほぼ必ず余り、§18.8.30 はその行き先には触れません。Excel 自身の PDF 出力とその Range.Text が示す配置は以下のとおりで、水平方向の配置で変わります:

Delphi 向け HotXLS におけるフィル文字の余り端数の配置マトリクス。general と左寄せから中央、右寄せ、縮小して全体表示まで
general と左寄せは余った端数をフィルとサフィックスの間に置くので、ドル記号の列は静かに保たれます
  • General と左寄せ: プレフィックスは左パディングに張り付き、サフィックスは右パディングに張り付き、余りはフィルとサフィックスの間に座ります(サフィックスがなければ行末です)
  • 中央寄せ: プレフィックスとフィルは余りの半分だけ右へ動きます。右寄せは全部だけ動きます
  • Fill、両端揃え、均等割り付け、折り返しテキスト: 3 つのパーツは左から順に並び、余りは行末です
  • インデントは通常どおり利用可能幅を狭め、「縮小して全体を表示する」セルにはフィルは付きません

General の配置は、手製のレンダラーが踏み外れる場所です。General の数値は通常右寄せです。フィル付きのセルは違います。「数値は右」の規則を保つと、余りはフィルの前に着地し、ドル記号は最大スペース 1 個ぶん、左パディングから押し出されます。書式 44 の金額の列を下ると、ドル記号は行ごとに揺れます。あまり一般的でないレイアウトも同じモデルに従います:

  • 回転テキスト: フィルの長さは、回転したときにセル内に収まる最長の行から取られます
  • リッチテキスト: 繰り返される文字は、フィル位置の直前の文字からスタイルを受け継ぎます
  • 選択範囲内で中央: フィルは範囲全体を覆います
  • 複数行テキスト: フィル位置を含む行だけが繰り返しを得ます

右から左のシートは、HotXLS が Excel の PDF エクスポートからコピーしないケースです。あのエクスポートはフィルとプレフィックスのグリフを落とします。同じセルの Range.Text にはまだ入っているのに、です。HotXLS はそうしたセルを、グリッドの見せ方どおり、フィルをその位置に置いてレイアウトします

VCL キャンバスにフィルを描く

描くキャンバスで計測しましょう。これはカスタムグリッドにも、レポートバンドにも、サムネイルにも当たります。VCL キャンバスはスケール時に整数のフォントサイズを選ぶので、端数のサイズのフォントメトリクスから計算した幅は、GDI が描くものよりわずかに狭く出ます。1 文字あたりの誤差は小さい。繰り返しの連なりでは積み上がります。狭い方の幅から数えると、左のパーツは矩形をはみ出し、描画フラグに DT_END_ELLIPSIS があると、GDI はサフィックスの上に三点リーダーを乗せます。下のルーチンは、General または左寄せの一般的な単一行ケースを処理し、それ以外は素の TextRect 経路へ送ります

uses
  Windows, Types, Graphics, lxHandleX;

procedure DrawFilledCell(Canvas: TCanvas; const R: TRect; Cell: TXLSXCell);
const
  Pad = 2;                                   // セル内側のパディング、ピクセル
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);

  // テキストを描くのと同じキャンバス、フォント、サイズで計測する
  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;   // 整数文字のみ

  // General / 左寄せ: prefix + fill は左に、suffix は右に、
  // 余りの端数は fill と suffix の間に留まる
  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;

2 つの半分を別々の呼び出しで描くと、整数除算がどちらに丸れても、金額は右端に釘付けのままです。中央寄せや右寄せのセルでは、最初の TextOut を Avail - Used - Count * FillWidth の半分か全部だけずらします。回転と複数行のセルは別のやり方が簡単です。数えた繰り返しをテキストの FillIndex 位置に挿入し、結果をいつもの回転や折り返しのコードで 1 つの文字列として描きます。この Delphi のカスタムスプレッドシートグリッドのような手組みのグリッドでは、同じキャンバスが行の高さや結合範囲も動かすべきです

固定幅テキストと CSV でのフィルとアンダースコア

プレーンテキスト出力にピクセルはありませんが、幅は持てます。TXLSXCell.FormattedText は各 _x を 1 個の普通のスペースとして書くので、書式 44 の正セクションは両端に空白の付いた $1,234.50 として返ってきます。可変幅フォントではスペースは通常、括弧よりほんの少し狭く、プレビューには十分です。等幅のテキストレポートではすべての文字が同じ送り幅を持つので、スペースは正確な代役となり、フィル数は素朴な算数です。文字数での列幅からテキストの長さを引くだけです。CSV は違います。ファイルを読むスプレッドシートやデータベースが欲しいのは数値なので、そこにはセルの Value を書き、パディング済みのテキストは人間が読むレポート用に取っておきましょう

uses
  lxHandleX;

// 固定幅のレポート列: 書式 44、値 1234.5、Width 14
// は ' $   1,234.50 ' を得る(ドル記号の後に空白 3 個が繰り返される)
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;                    // テキストが列より広い: 繰り返しなし
  Result := Copy(Text, 1, FillIndex) + StringOfChar(Fill, Count) +
    Copy(Text, FillIndex + 1, MaxInt);
end;

まずは 1 セルから始めましょう。書式 44、値 1234.5、そしてインデックス 2 にスペースを報告するはずの GetFormattedTextFill 呼び出しです。列を 2 回リサイズし、ドル記号が左パディングに留まり、1,234.50 が右端に留まることを確かめます。レンダラーがここを通れば、他の配置は最初の TextOut のオフセットに過ぎず、HotXLS Delphi Excel component が作る SaveAsPDF のページが比較の基準になります