Artículo técnico

Caracteres de relleno (*) de Excel en PDF e impresión

Exporte una hoja en el formato contable 44 de Excel con un formateador casero y el PDF muestra $1,234.50 apretado, o $* 1,234.50 con un asterisco suelto. Ese hueco es un relleno * dimensionado por el ancho de columna y la fuente, y su posición en el texto, que HotXLS devuelve desde TXLSXCell.GetFormattedTextFill, es todo lo que un renderer necesita para contar las repeticiones

¿Cómo funcionan * y _ en un formato numérico de Excel?

ECMA-376 Part 1 §18.8.30 define ambos caracteres en su tabla de símbolos de código de formato. * repite el siguiente carácter "enough times to fill the column to its current width"; una sección puede cargar un asterisco, y si aparecen varios, todos menos el último se ignoran. _ "skips the width of the next character", así que _) deja un espacio tan ancho como un paréntesis de cierre y los montos positivos se alinean con los negativos mostrados como (1,234.50). Los ejemplos del estándar son cortos. 0*- pone guiones después de un número hasta el borde de la celda, *0 delante de un formato da ceros a la izquierda, y 0*x muestra 3 como 3xxxxxx en una columna de un ancho en particular. Los formatos que combinan ambos caracteres son los formatos contables integrados de Excel, los IDs 41 a 44. Esos números son cosa de Excel: la tabla integrada de §18.8.30 salta de 40 directo a 45, y HotXLS registra los cuatro códigos de abajo bajo la numeración de Excel

ID de ExcelCódigo de formatoSímboloDecimales
41_(* #,##0_);_(* (#,##0);_(* "-"_);_(@_)ninguno0
42_("$"* #,##0_);_("$"* (#,##0);_("$"* "-"_);_(@_)$0
43_(* #,##0.00_);_(* (#,##0.00);_(* "-"??_);_(@_)ninguno2
44_("$"* #,##0.00_);_("$"* (#,##0.00);_("$"* "-"??_);_(@_)$2

Lea la sección positiva del 44, _("$"* #,##0.00_), de izquierda a derecha: un espacio del ancho de (, un signo de dólar, un espacio repetido hasta llenar la columna, el número, y un espacio del ancho de ). La sección negativa cambia ese espacio final por paréntesis de verdad. La sección del cero imprime un guion seguido de ??, dos espacios del ancho de un dígito que ponen el guion en la columna del punto decimal. Qué sección de las cuatro elige un valor, y qué hace una sección vacía, sigue las reglas de las secciones del formato numérico de Excel. Quite el relleno y el signo de dólar aterriza sobre los dígitos. Imprima el asterisco y el lector está viendo sintaxis de formato

Anatomía de la sección positiva del formato contable 44 de Excel en HotXLS para Delphi: espacios del ancho del paréntesis, signo de dólar, relleno de espacios repetidos y el número
un asterisco hace que el siguiente carácter se repita hasta el ancho de la columna, y cada espacio en una sección contable sale de un underscore

¿Por qué un formateador no puede insertar las repeticiones por su cuenta?

No conoce el conteo. El número de repeticiones es el ancho de columna menos el ancho de todo lo demás, dividido entre el ancho de un carácter de relleno. Cada término depende de la fuente, el tamaño, el zoom y el dispositivo de salida. Un formateador que devuelve un string simple tendría que elegir un número, y cualquier número fijo está mal en cuanto alguien cambia el tamaño de la columna. HotXLS parte el trabajo. TXLSXCell.FormattedText devuelve el texto de display sin ninguna copia del carácter de relleno, y GetFormattedTextFill devuelve ese mismo texto más el carácter de relleno y un índice: el número de caracteres previos al punto donde van las repeticiones. El método devuelve False cuando el formato no tiene relleno y para una celda de rich-text, cuyos runs se dibujan tal como son

El signo menos automático va antes del relleno. Con el formato **0 y el valor -5, el texto es -5, el carácter de relleno es * y el índice es 1. Una celda ancha muestra entonces -****5, el mismo string que el Range.Text de Excel da para esa celda. Un llamador sin columna no recibe relleno alguno. La función de hoja de cálculo TEXT es un llamador así, así que en el motor de cálculo de HotXLS TEXT(A1, "$* #,##0") con 1234 en A1 evalúa a $1,234. El código de abajo configura tres formatos e imprime lo que un renderer recibe para cada uno

Contrato de GetFormattedTextFill en HotXLS para Delphi: texto de prefijo, carácter de relleno e índice de corte que le permiten a un renderer contar las repeticiones para cualquier ancho de columna
la celda reporta el punto de corte en lugar de un conteo de repeticiones, porque solo el canvas de dibujo conoce el ancho real de la columna
uses
  SysUtils, lxHandleX;

procedure InspectFills;
const
  Formats: array[0..2] of WideString = (
    // el mismo código que el formato integrado 44 de Excel
    '_("$"* #,##0.00_);_("$"* (#,##0.00);_("$"* "-"??_);_(@_)',
    '0*-',     // guiones después del número
    '**0');    // estrellas delante del número
  Values: array[0..2] of Double = (1234.5, 42, -5);
  // Cada fila debe 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');   // la exportación PDF acomoda el relleno por columna
  finally
    Book.Free;
  end;
end;

Cada línea muestra el prefijo, el carácter de relleno y el sufijo entre corchetes. Note los espacios: en la primera fila el prefijo es un espacio y un signo de dólar, y el sufijo termina en espacio, ambos producidos por los pares _. SaveAsPDF trabaja desde las mismas tres partes y calcula el conteo de repeticiones desde el ancho real de la columna. En fills.pdf el signo de dólar debe quedar sobre el margen izquierdo de la primera celda, y los guiones después del 42 deben correr hasta el borde derecho de la segunda. La configuración de página, márgenes y fuentes de ese archivo los maneja la configuración normal de la exportación PDF de hojas de cálculo

¿Qué lado se queda con la fracción de carácter sobrante?

Para celdas General y alineadas a la izquierda, el espacio entre el relleno y el sufijo. El conteo de repeticiones es un número entero, así que casi siempre sobra una fracción de carácter, y §18.8.30 no dice nada sobre dónde va. La salida PDF del propio Excel y su Range.Text muestran la siguiente colocación, que depende de la alineación horizontal:

Matriz de colocación de la fracción sobrante para caracteres de relleno en HotXLS para Delphi, desde la alineación general e izquierda hasta centrada, derecha y reducir hasta caber
la alineación general e izquierda ponen la fracción sobrante entre el relleno y el sufijo, lo que mantiene quieta una columna de signos de dólar
  • General e izquierda: el prefijo pegado al margen izquierdo, el sufijo pegado al margen derecho, y lo sobrante queda entre el relleno y el sufijo (al final de la línea cuando no hay sufijo)
  • Centrada: el prefijo y el relleno se corren a la derecha la mitad de lo sobrante; la alineación derecha los corre todo
  • Fill, justificado, distribuido y texto con ajuste de línea: las tres partes corren desde la izquierda, con lo sobrante al final de la línea
  • La sangría reduce el ancho disponible como siempre, y una celda "shrink to fit" no recibe relleno

La alineación General es donde los renderers caseros se equivocan. Los números bajo General normalmente se alinean a la derecha. Una celda con relleno no. Conserve la regla de "los números van a la derecha" y lo sobrante cae delante del relleno, empujando el signo de dólar fuera del margen izquierdo hasta un ancho de espacio. Bajando por una columna de montos en formato 44, los signos de dólar entonces se tambalean de fila en fila. Los layouts menos comunes siguen el mismo modelo:

  • Texto rotado: la longitud del relleno sale de la línea más larga que todavía cabe dentro de la celda una vez rotada
  • Rich text: el carácter repetido toma su estilo del carácter justo antes de la posición del relleno
  • Centrar en la selección: el relleno cubre todo el tramo
  • Texto multilínea: solo la línea que contiene la posición del relleno recibe repeticiones

Las hojas de derecha a izquierda son el caso que HotXLS no copia de la exportación PDF de Excel. Esa exportación suelta los glifos del relleno y del prefijo, aunque el Range.Text de las mismas celdas todavía los contiene. HotXLS acomoda esas celdas como las muestra la retícula, con el relleno en su lugar

Dibujar el relleno en un canvas VCL

Mida con el canvas sobre el que va a dibujar. Eso vale por igual para una retícula personalizada, una banda de reporte y una miniatura. El canvas VCL selecciona un tamaño de fuente entero cuando escala, así que un ancho calculado de las métricas de fuente al tamaño fraccionario sale un poco más angosto que lo que GDI pinta. El error por carácter es diminuto. A lo largo de una corrida de repeticiones se acumula. Cuente desde el ancho más angosto y la parte izquierda se sale de su rectángulo; con DT_END_ELLIPSIS entre los flags de dibujo, GDI entonces pone puntos suspensivos encima del sufijo. La rutina de abajo maneja el caso común de una sola línea con alineación General o izquierda y manda todo lo demás por el camino simple de TextRect:

uses
  Windows, Types, Graphics, lxHandleX;

procedure DrawFilledCell(Canvas: TCanvas; const R: TRect; Cell: TXLSXCell);
const
  Pad = 2;                                   // padding interno de la celda, en píxeles
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);

  // Mida con el mismo canvas, fuente y tamaño que dibujarán el 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;   // solo caracteres enteros

  // General / izquierda: prefijo + relleno a la izquierda, sufijo a la derecha,
  // la fracción sobrante se queda entre el relleno y el sufijo
  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;

Dibujar las dos mitades con llamadas separadas mantiene el monto clavado al borde derecho sin importar cómo redondee la división entera. Para celdas centradas o alineadas a la derecha, corra el primer TextOut la mitad o todo Avail - Used - Count * FillWidth. Las celdas rotadas y multilínea se manejan más fácil de otra forma: inserte las repeticiones contadas en el texto en FillIndex y dibuje el resultado como un solo string con su código de rotación o ajuste de línea de siempre. En una retícula hecha a mano como esta retícula de hoja de cálculo personalizada en Delphi, el mismo canvas debe gobernar también las alturas de fila y los rangos combinados

Relleno y underscore en texto de ancho fijo y CSV

La salida de texto plano no tiene píxeles, pero puede tener un ancho. TXLSXCell.FormattedText escribe cada _x como un espacio ordinario, así que la sección positiva del formato 44 regresa como $1,234.50 con un espacio en cada extremo. En una fuente proporcional un espacio suele ser un poco más angosto que un paréntesis, suficiente para una vista previa. En un reporte de texto monoespaciado cada carácter tiene el mismo avance, así que el espacio es un sustituto exacto y el conteo del relleno es aritmética simple: el ancho de la columna en caracteres menos la longitud del texto. El CSV es distinto. Una hoja de cálculo o base de datos que lee el archivo quiere un número, así que escriba ahí el Value de la celda y reserve el texto con relleno para los reportes que la gente lee:

uses
  lxHandleX;

// Columna de reporte de ancho fijo: formato 44, valor 1234.5 y Width 14
// dan ' $   1,234.50 ' (tres espacios repetidos después del signo de dólar)
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 más ancho que la columna: sin repeticiones
  Result := Copy(Text, 1, FillIndex) + StringOfChar(Fill, Count) +
    Copy(Text, FillIndex + 1, MaxInt);
end;

Empiece con una celda: formato 44, el valor 1234.5, y una llamada a GetFormattedTextFill que debe reportar un espacio en el índice 2. Cambie el ancho de la columna dos veces y verifique que el signo de dólar se quede en el margen izquierdo mientras 1,234.50 se queda en el borde derecho. Cuando su renderer pase esa prueba, las demás alineaciones son desfases del primer TextOut, y una página de SaveAsPDF del componente Excel HotXLS para Delphi es la referencia con la que compararlas