Artículo técnico

Caracteres de relleno de Excel en PDF e impresión

Exporta 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?

El ECMA-376 Parte 1 §18.8.30 define ambos caracteres en su tabla de símbolos de código de formato. * repite el siguiente carácter «las veces suficientes para llenar la columna hasta su ancho actual»; una sección puede llevar un asterisco, y si aparecen varios, todos menos el último se ignoran. _ «salta el ancho del siguiente carácter», así que _) deja un blanco tan ancho como un paréntesis de cierre y los importes positivos se alinean con los negativos mostrados como (1,234.50). Los ejemplos de la norma 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 concreto. Los formatos que combinan ambos caracteres son los formatos contables integrados de Excel, IDs 41 a 44. Esos números son de la cuenta propia de Excel: la tabla integrada del §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

Lee la sección positiva del 44, _("$"* #,##0.00_), de izquierda a derecha: un blanco del ancho de (, un signo de dólar, un espacio repetido para llenar la columna, el número, y un blanco del ancho de ). La sección negativa cambia ese blanco final por paréntesis de verdad. La sección cero imprime un guion seguido de ?? —dos blancos del ancho de un dígito que colocan 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. Quita el relleno y el signo de dólar cae sobre los dígitos. Imprime el asterisco y el lector está mirando sintaxis de formato

Anatomía de la sección positiva del formato contable 44 de Excel en HotXLS para Delphi: blancos 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 columna, y cada blanco de una sección contable sale de un guion bajo

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

Porque no conoce el recuento. El número de repeticiones es el ancho de columna menos el ancho de todo lo demás, dividido por 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 una cadena plana tendría que elegir un número, y cualquier número fijo está mal en cuanto alguien cambia el ancho de la columna. HotXLS reparte el trabajo. TXLSXCell.FormattedText devuelve el texto de vista sin 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 antes del punto donde las repeticiones pertenecen. 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 delante 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 por tanto muestra -****5, la misma cadena que el Range.Text de Excel da para esa celda. Un llamador sin columna no recibe relleno alguno. La función de hoja TEXT es tal llamador, 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 fija 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 división que permiten a un renderer contar las repeticiones para cualquier ancho de columna
la celda informa del punto de división en vez de un recuento de repeticiones, porque solo el lienzo 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');    // asteriscos delante del número
  Values: array[0..2] of Double = (1234.5, 42, -5);
  // Cada fila debería 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 dispone 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. Fíjate en los blancos: en la primera fila el prefijo es un espacio y un signo de dólar, y el sufijo termina en espacio, ambos producidos por las parejas _. SaveAsPDF trabaja desde las mismas tres partes y calcula el recuento de repeticiones a partir del ancho real de columna. En fills.pdf el signo de dólar debería sentarse en el padding izquierdo de la primera celda, y los guiones tras 42 deberían correr hasta el borde derecho de la segunda. La configuración de página, márgenes y fuentes de ese archivo los lleva la configuración habitual de la exportación PDF de hojas de cálculo

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

Para General y celdas alineadas a la izquierda, el espacio entre el relleno y el sufijo. El recuento de repeticiones es un número entero, así que casi siempre sobra una fracción de carácter, y el §18.8.30 no dice nada de dónde va. La propia salida PDF de 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 centro, derecha y shrink to fit
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 se pega al padding izquierdo, el sufijo se pega al padding derecho, y la sobrante se sienta entre el relleno y el sufijo (al final de la línea cuando no hay sufijo)
  • Centro: prefijo y relleno se mueven a la derecha media sobrante; la alineación derecha los mueve toda
  • Fill, justify, distributed y texto con ajuste de línea: las tres partes corren desde la izquierda, con la sobrante al final de la línea
  • La indentación estrecha 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 se alinean normalmente a la derecha. Una celda con relleno no. Mantén la regla «los números van a la derecha» y la sobrante aterriza delante del relleno, empujando el signo de dólar fuera del padding izquierdo hasta el ancho de un espacio. En una columna de importes con formato 44, los signos de dólar titubean entonces de fila en fila. Las maquetaciones 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
  • Center across selection: el relleno cubre todo el intervalo
  • 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 el relleno y los glifos del prefijo, aunque el Range.Text de las mismas celdas todavía los contiene. HotXLS maqueta tales celdas como las muestra la rejilla, con el relleno en su sitio

Dibujar el relleno en un canvas VCL

Mide con el canvas sobre el que vas a dibujar. Eso vale para una rejilla personalizada, una banda de informe y una miniatura por igual. 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 ligeramente más estrecho que lo que GDI pinta. El error por carácter es minúsculo. A lo largo de una tanda de repeticiones se acumula. Cuenta desde el ancho más estrecho y la parte izquierda desborda su rectángulo; con DT_END_ELLIPSIS entre los flags de dibujo, GDI pone entonces una elipsis encima del sufijo. La rutina de abajo se encarga del caso habitual de una sola línea con alineación General o izquierda y manda todo lo demás por el camino plano de TextRect:

uses
  Windows, Types, Graphics, lxHandleX;

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

  // Mide con el mismo canvas, fuente y tamaño que dibujará 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 importe clavado al borde derecho, redondee como redondee la división entera. Para celdas centradas o alineadas a la derecha, desplaza el primer TextOut media o toda la Avail - Used - Count * FillWidth. Las celdas rotadas y multilínea se manejan más fácil de otra manera: inserta las repeticiones contadas en el texto en FillIndex y dibuja el resultado como una sola cadena con tu código habitual de rotación o ajuste de línea. En una rejilla hecha a mano como esta rejilla de hoja de cálculo personalizada en Delphi, el mismo canvas debería llevar también las alturas de fila y los rangos combinados

Relleno y guion bajo en texto de ancho fijo y CSV

La salida de texto plano no tiene píxeles, pero puede tener ancho. TXLSXCell.FormattedText escribe cada _x como un espacio ordinario, así que la sección positiva del formato 44 vuelve como $1,234.50 con un blanco en cada extremo. En una fuente proporcional un espacio suele ser un poco más estrecho que un paréntesis, suficiente para una vista previa. En un informe de texto monoespaciado cada carácter tiene el mismo avance, así que el espacio es un sustituto exacto y el recuento de relleno es aritmética plana: el ancho de 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 escribe ahí el Value de la celda y reserva el texto rellenado para informes que lee gente:

uses
  lxHandleX;

// Columna de informe de ancho fijo: formato 44, valor 1234.5 y Width 14
// dan ' $   1,234.50 ' (tres espacios repetidos tras el 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;

Empieza por una celda: formato 44, el valor 1234.5, y una llamada a GetFormattedTextFill que debería informar un espacio en el índice 2. Cambia el ancho de la columna dos veces y comprueba que el signo de dólar se queda en el padding izquierdo mientras 1,234.50 se queda en el borde derecho. Cuando tu renderer pase eso, las demás alineaciones son offsets del primer TextOut, y una página de SaveAsPDF del componente Excel de HotXLS para Delphi es la referencia con la que compararlas