Technisch artikel

Excel-filltekens (*) in PDF-export en afdruk

Exporteer een werkblad in het accounting-formaat 44 van Excel met een zelfgebouwde formatter en de PDF toont $1,234.50 opeengepast, of $* 1,234.50 met een verdwaalde asterisk. Die opening is een *-fill die meetelt met kolombreedte en font, en zijn positie in de tekst — door HotXLS teruggegeven vanuit TXLSXCell.GetFormattedTextFill — is alles wat een renderer nodig heeft om de herhalingen te tellen

Hoe werken * en _ in een Excel-getalnotatie?

ECMA-376 Part 1 §18.8.30 definieert beide tekens in zijn tabel met format-code-symbolen. * herhaalt het volgende teken "enough times to fill the column to its current width"; een sectie mag één asterisk bevatten, en staan er meerdere, dan worden alle op de laatste na genegeerd. _ "skips the width of the next character", dus _) laat een blanco zo breed als een sluithaakje achter en positieve bedragen sluiten aan bij negativen die als (1,234.50) worden getoond. De voorbeelden van de standaard zijn kort. 0*- zet streepjes na een getal tot aan de celrand, *0 vóór een formaat geeft voorloopnullen, en 0*x toont 3 als 3xxxxxx in een kolom van één specifieke breedte. De formaten die beide tekens combineren zijn de ingebouwde accounting-formaten van Excel, IDs 41 tot 44. Die nummers zijn van Excel zelf: de ingebouwde tabel in §18.8.30 springt van 40 direct naar 45, en HotXLS registreert de vier codes hieronder onder de nummering van Excel

Excel-IDFormaatcodeSymboolDecimalen
41_(* #,##0_);_(* (#,##0);_(* "-"_);_(@_)geen0
42_("$"* #,##0_);_("$"* (#,##0);_("$"* "-"_);_(@_)$0
43_(* #,##0.00_);_(* (#,##0.00);_(* "-"??_);_(@_)geen2
44_("$"* #,##0.00_);_("$"* (#,##0.00);_("$"* "-"??_);_(@_)$2

Lees de positieve sectie van 44, _("$"* #,##0.00_), van links naar rechts: een blanco zo breed als (, een dollarteken, een spatie herhaald tot de kolom gevuld is, het getal, en een blanco zo breed als ). De negatieve sectie wisselt die sluitende blanco in voor echte haakjes. De nulsectie drukt een streepje af gevolgd door ?? — twee blanco's zo breed als een cijfer, die het streepje in de kolom van de decimale punt zetten. Welke van de vier secties een waarde kiest, en wat een lege sectie doet, volgt de regels voor Excel-getalnotatiesecties. Haal de fill weg en het dollarteken komt op de cijfers terecht. Druk de asterisk af en de lezer kijkt naar formatsyntaxis

Anatomie van de positieve sectie van Excel-accountingformaat 44 in HotXLS voor Delphi: haakjesbreedte-blanco's, dollarteken, herhaalde spatie-fill en het getal
één asterisk laat het volgende teken herhalen tot de kolombreedte, en elke blanco in een accountingsectie komt van een underscore

Waarom kan een formatter de herhalingen niet zelf invoegen?

Hij kent het aantal niet. Het aantal herhalingen is de kolombreedte minus de breedte van al het andere, gedeeld door de breedte van één fill-teken. Elke term hangt af van font, grootte, zoom en uitvoerapparaat. Een formatter die een gewone string teruggeeft zou een getal moeten kiezen, en elk vast getal is fout zodra iemand de kolom verbreedt. HotXLS splitst de klus. TXLSXCell.FormattedText geeft de displaytekst terug zonder één exemplaar van het fill-teken, en GetFormattedTextFill geeft dezelfde tekst plus het fill-teken en een index terug: het aantal tekens vóór het punt waar de herhalingen horen. De methode geeft False terug als het formaat geen fill heeft en voor een rich-text-cel, waarvan de runs getekend worden zoals ze zijn

Het automatische minteken komt vóór de fill. Met het formaat **0 en de waarde -5 is de tekst -5, het fill-teken is * en de index is 1. Een brede cel toont daarom -****5, dezelfde string die de Range.Text van Excel voor die cel geeft. Een aanroeper zonder kolom krijgt helemaal geen fill. De werkbladfunctie TEXT is zo'n aanroeper, dus evalueert in de rekenengine van HotXLS TEXT(A1, "$* #,##0") met 1234 in A1 tot $1,234. De code hieronder zet drie formaten en drukt af wat een renderer voor elk ontvangt

Contract van GetFormattedTextFill in HotXLS voor Delphi: prefixtekst, fill-teken en splitsindex waarmee een renderer de herhalingen telt voor elke kolombreedte
de cel meldt het splitspunt in plaats van een aantal herhalingen, want alleen de teken-canvas kent de echte kolombreedte
uses
  SysUtils, lxHandleX;

procedure InspectFills;
const
  Formats: array[0..2] of WideString = (
    // dezelfde code als het ingebouwde formaat 44 van Excel
    '_("$"* #,##0.00_);_("$"* (#,##0.00);_("$"* "-"??_);_(@_)',
    '0*-',     // streepjes na het getal
    '**0');    // sterretjes vóór het getal
  Values: array[0..2] of Double = (1234.5, 42, -5);
  // Elke regel hoort af te drukken:
  //   [ $] 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');   // de PDF-export legt de fill per kolom uit
  finally
    Book.Free;
  end;
end;

Elke regel toont de prefix, het fill-teken en de suffix tussen haakjes. Let op de blanco's: in de eerste rij is de prefix een spatie en een dollarteken, en eindigt de suffix met een spatie, beide geproduceerd door de _-paren. SaveAsPDF werkt vanuit dezelfde drie delen en rekent het aantal herhalingen uit op basis van de echte kolombreedte. In fills.pdf hoort het dollarteken op de linkerpadding van de eerste cel te staan, en horen de streepjes na 42 door te lopen tot de rechterrand van de tweede. Pagina-instelling, marges en fonts voor dat bestand regelt de gewone werkblad-PDF-export

Welke kant krijgt de overgebleven fractie van een teken?

Bij General en links uitgelijnde cellen: de ruimte tussen de fill en de suffix. Het aantal herhalingen is een geheel getal, dus er blijft bijna altijd een fractie van een teken over, en §18.8.30 zegt niets over waar die terechtkomt. De eigen PDF-uitvoer van Excel en zijn Range.Text tonen de volgende plaatsing, die afhangt van de horizontale uitlijning:

Matrix van plaatsing van de restfractie voor fill-tekens in HotXLS voor Delphi, van general- en linksuitlijning tot center, rechts en shrink to fit
general- en linksuitlijning zetten de restfractie tussen de fill en de suffix, wat een kolom dollartekens rustig houdt
  • General en links: de prefix plakt tegen de linkerpadding, de suffix tegen de rechterpadding, en de rest zit tussen de fill en de suffix (aan het eind van de regel als er geen suffix is)
  • Center: prefix en fill schuiven rechts op met de helft van de rest; rechtsuitlijning schuift ze met alles op
  • Fill, justify, distributed en omwikkeld tekst: de drie delen lopen vanaf links door, met de rest aan het eind van de regel
  • Inspringing versmalt de beschikbare breedte als gewoonlijk, en een "shrink to fit"-cel krijgt geen fill

General-uitlijning is waar zelfgebouwde renderers de mist in gaan. Getallen onder General staan normaal rechts. Een gevulde cel niet. Houdt u de regel "getallen gaan rechts" aan, dan landt de rest vóór de fill en duwt die het dollarteken tot een spatiebreedte van de linkerpadding af. In een kolom met bedragen in formaat 44 wiegen de dollartekens dan van rij tot rij. Minder gebruikelijke indelingen volgen hetzelfde model:

  • Geroteerde tekst: de fill-lengte komt uit de langste regel die, eenmaal gedraaid, nog in de cel past
  • Rich text: het herhaalde teken neemt zijn stijl van het teken net vóór de fill-positie
  • Center across selection: de fill beslaat de hele span
  • Meerregelige tekst: alleen de regel die de fill-positie bevat krijgt herhalingen

Rechts-naar-links-bladen zijn het geval dat HotXLS niet kopieert van de PDF-export van Excel. Die export laat de fill en de prefixglyphs vallen, al bevat Range.Text voor dezelfde cellen ze nog wel. HotXLS indeelt zulke cellen zoals het raster ze toont, met de fill op zijn plek

De fill tekenen op een VCL-canvas

Meet met de canvas waarop u gaat tekenen. Dat geldt voor een eigen grid, een rapportband en een thumbnail evenzeer. De VCL-canvas kiest bij het schalen een geheel fontgrootte, dus een breedte berekend uit fontmetrieken op de fractiegrootte komt iets smaller uit dan wat GDI verft. De fout per teken is minimaal. Over een reeks herhalingen telt hij op. Rekent u vanaf de smallere breedte, dan loopt het linkerdeel zijn rechthoek voorbij; met DT_END_ELLIPSIS tussen de tekenvlaggen zet GDI er dan een ellipsis bovenop de suffix. De routine hieronder pakt het gebruikelijke eenregelgeval met General- of linksuitlijning op en stuurt al het restant de gewone TextRect-route op:

uses
  Windows, Types, Graphics, lxHandleX;

procedure DrawFilledCell(Canvas: TCanvas; const R: TRect; Cell: TXLSXCell);
const
  Pad = 2;                                   // interne celpadding, 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);

  // Meet met dezelfde canvas, font en grootte die de tekst gaat tekenen
  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;   // alleen hele tekens

  // General / links: prefix + fill links, suffix rechts,
  // de restfractie blijft tussen de fill en de 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;

De twee helften met aparte aanroepen tekenen houdt het bedrag aan de rechterrand vast, hoe de deling met gehele getallen ook rondt. Voor gecentreerde of rechts uitgelijnde cellen schuift u de eerste TextOut op met de helft of alles van Avail - Used - Count * FillWidth. Gedraaide en meerregelige cellen pak je handiger anders aan: voeg de getelde herhalingen op FillIndex in de tekst in en teken het resultaat als één string met uw gebruikelijke rotatie- of wrap-code. In een handgebouwd grid zoals deze eigen spreadsheetgrid in Delphi hoort dezelfde canvas ook rijhoogtes en samengevoegde ranges te sturen

Fill en underscore in tekst met vaste breedte en CSV

Plain-text-uitvoer heeft geen pixels, maar kan wel een breedte hebben. TXLSXCell.FormattedText schrijft elke _x als één gewone spatie, dus de positieve sectie van formaat 44 komt terug als $1,234.50 met aan elk uiteinde een blanco. In een proportioneel font is een spatie meestal iets smaller dan een haakje, goed genoeg voor een preview. In een monospaced textrapport heeft elk teken dezelfde opmars, dus is de spatie een exacte vervanger en is het fill-aantal zuivere rekenkunde: de kolombreedte in tekens minus de lengte van de tekst. CSV is anders. Een spreadsheet of database die het bestand leest wil een getal, dus schrijf daar de Value van de cel weg en houd de opgevulde tekst voor rapporten die mensen lezen:

uses
  lxHandleX;

// Rapportkolom met vaste breedte: formaat 44, waarde 1234.5 en Width 14
// geeft ' $   1,234.50 ' (drie herhaalde spaties na het dollarteken)
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;                    // tekst breder dan de kolom: geen herhalingen
  Result := Copy(Text, 1, FillIndex) + StringOfChar(Fill, Count) +
    Copy(Text, FillIndex + 1, MaxInt);
end;

Begin met één cel: formaat 44, de waarde 1234.5, en een GetFormattedTextFill-aanroep die een spatie op index 2 hoort te melden. Verklein of verbreed de kolom twee keer en controleer dat het dollarteken op de linkerpadding blijft terwijl 1,234.50 op de rechterrand blijft. Zodra uw renderer dat haalt, zijn de andere uitlijningen offsets van de eerste TextOut, en is een SaveAsPDF-pagina vanuit de HotXLS Delphi Excel-component de referentie om ze mee te vergelijken