FPSpreadsheet/fr

From Lazarus wiki

Deutsch (de) English (en) español (es) français (fr) polski (pl) русский (ru)


La bibliothèque fpSpreadsheet offre un moyen pratique de générer et de lire des feuilles de calcul dans différents formats. La bibliothèque est écrite d'une manière très flexible, capable d'être étendue pour prendre en charge facilement un certain nombre de formats.

Capture d'écran du programme de démonstration spready fourni avec fpspreadsheet montrant un fichier XLS :



fpsgrid.png

Contents

Documentation

Cette page wiki couvre la dernière version de développement/tronc de FPSpreadsheet disponible via subversion. Merci de consulter Stable releases pour la documentation sur la version stable que vous pouvez télécharger.

API Documentation

API Reference

Un fichier d'aide au format CHM se trouve dans le dossier d'installation de FPSpreadsheet docs. Si vous n'avez pas encore installé le paquet, suivez http://lazarus-ccr.svn.sourceforge.net/viewvc/lazarus-ccr/components/fpspreadsheet/docs/fpspreadsheet-api.chm

Le deuxième fichier CHM disponible dans le dossier "docs", "fpspreadsheet-wiki.chm", est un instantané des pages wiki relatives à FPSpreadsheet regroupées en un seul fichier d'aide.

Basics

Notions de base Les plus petites entités d'une feuille de calcul sont les cellules qui contiennent les données. Les cellules peuvent contenir différents types de données, comme des chaînes de caractères, des chiffres, des dates, des heures, des valeurs booléennes ou des formules. En outre, les cellules peuvent contenir des informations sur la mise en forme, c'est-à-dire le style de police, la couleur de fond, l'alignement du texte, etc... Les cellules sont disposées dans une structure en forme de grille, appelée feuille de travail, ou feuille de calcul, constituée de lignes et de colonnes. Chaque cellule a une adresse unique donnée par l'index de la ligne et de la colonne. Les feuilles de travail sont liées entre elles pour former un classeur qui représente le document du tableur. Le classeur stocke également les informations nécessaires à toutes les feuilles de travail, c'est-à-dire la liste des polices, les listes de formats de cellules et de numéros, etc. FPSpreadsheet suit cette même structure - il y a un TCell, un TsWorksheet, et un TsWorkbook.

Workbook

La classe TsWorkbook (Classeur) est la classe principale visible par l'utilisateur. Il fournit des méthodes pour lire et écrire des données dans des fichiers. La structure polyvalente de la bibliothèque permet d'accéder à divers formats de fichiers populaires, comme Excel .xls ou .xlsx, ou OpenOffice/LibreOffice .ods.

Le format du fichier est spécifié par le type TsSpreadsheetFormat défini dans l'unité fpstypes.

type
  TsSpreadsheetFormat = (sfExcel2, sfExcel5, sfExcel8, sfExcelXML, sfOOXML, 
    sfOpenDocument, sfCSV, sfHTML, sfWikiTable_Pipes, sfWikiTable_WikiMedia, sfUser);

  • sfExcel2, sfExcel5, sfExcel8 désigne des versions du format xls binaire utilisé par Excel ("BIFF" = "Binary Interchange File Format"), sfExcel8 étant le plus moderne.
  • sfOOXML correspond au nouveau format xlsx introduit par Excel2007 .
  • sfExcelXML est le format xml qui a été introduit par Microsoft pour Office XP et 2003. Pas très populaire.
  • sfOpenDocument est le format de feuille de calcul utilisé par OpenOffice/LibreOffice ; par défaut, les fichiers ont l'extension .ods.
  • sfCSV fait référence aux fichiers texte délimités par des virgules (extension par défaut .csv) ; ils peuvent être compris par n'importe quel éditeur de texte et tous les tableurs, mais ne contiennent pas d'informations de formatage.
  • sfHTML désigne le format HTML standard tel qu'il est utilisé dans les navigateurs web.
  • sfWikiTable_Pipes et sfWikiTable_WikiMedia est le format utilisé par les tables dans les sites wiki.
  • sfUser est nécessaire pour enregistrer un format défini par l'utilisateur. Il n'est pas prévu de mettre en œuvre des formats de fichiers "anciens" comme Excel3.0/4.0 ou Lotus. Il est toutefois possible de fournir vos propres classes de lecture et d'écriture pour étendre les fonctionnalités de FPSpreadsheet - voir la section ci-dessous sur Ajouter de nouveaux formats de fichiers.

Lorsque vous utilisez fpspreadsheet, la première tâche consiste à créer une instance du classeur :

var
  MyWorkbook: TsWorkbook;
begin
  MyWorkbook := TsWorkbook.Create;
  ...

La lecture des fichiers de tableur est accomplie (entre autres) par les méthodes du classeur.

  • procedure ReadFromFile(AFileName: string):
    Lit le fichier portant le nom donné et détermine automatiquement le format correct du fichier.
  • procedure ReadFromFile(AFileName: string; AFormat: TsSpreadsheetFormat):
    Lit le fichier, mais suppose que le format du fichier est celui spécifié par AFormat..

Les méthodes suivantes peuvent être utilisées pour enregistrer le classeur dans un fichier :

  • procedure WriteToFile(const AFileName: string; const AFormat: TsSpreadsheetFormat; const AOverwriteExisting: Boolean = False):
    Écrit le classeur dans le fichier donné en utilisant le format de feuille de calcul voulu. Si le fichier existe déjà, il est automatiquement écrasé si AOverwriteExisting est true :
  • procedure WriteToFile(const AFileName: String; const AOverwriteExisting: Boolean = False):
    idem, mais le format du fichier est déterminé à partir de l'extension de fichier fournie (dans le cas du xls d'Excel, on utilise la version la plus récente, sfExcel8).

Après avoir appelé ces méthodes, il est avantageux de regarder la propriété ErrorMsg dans laquelle sont collectés les messages dus aux erreurs ou aux avertissements qui auraient pu se produire lors de la lecture/écriture. Cette propriété renvoie une chaîne de caractères multi-lignes qui s'affiche au mieux dans un composant mémo ; si tout va bien, c'est une chaîne vide.

Note: FPSpreadsheets fournit des unités spécialisées pour la lecture et l'écriture de chaque format de fichier. Ces unités ne sont pas disponibles automatiquement, vous devez les ajouter explicitement à la clause uses. FPSpreadsheet signalera que le format de fichier n'est pas supporté si l'unité de lecture/écriture demandée n'est pas trouvée. Voici une liste des noms des unités :

  • xlsbiff2, xlsbiff5 et xlsbiff8 pour les formats de fichiers binaires xls sfExcel2, sfExcel5 et sfExcel8, respectivement, .
  • xlsxOOXML pour le format de fichier xlsx sfOOXML d'Excel 2007 et plus, .
  • xlsXML pour le format xml d'Excel XP et 2003,
  • fpsopendocument pour le format de fichier sfOpenDocument d'OpenOffice/LibreOffice, .
  • fpsCSV pour les fichiers texte avec des valeurs séparées par des virgules (csv),
  • fpsHTML pour les fichiers HTML,
  • wikitables pour sfWikiTable_Pipes et sfWikiTable_WikiMedia, .
  • ou, ajoutez simplement fpsallformats pour obtenir un support de lecture/écriture pour tous les formats de fichiers supportés.

Worksheet

Worksheet (Feuille de travail)

Le classeur contient une liste d'instances TsWorksheet. Elles correspondent aux onglets que vous voyez dans Excel ou Open/LibreOffice. Lors de la lecture d'un fichier de feuille de calcul, les feuilles de calcul sont créées automatiquement en fonction du contenu du fichier. Lorsqu'une feuille de calcul est créée manuellement pour être stockée dans un fichier, une feuille de travail doit être créée en l'ajoutant au classeur :

var
  MyWorkbook: TsWorkbook;
  MyWorksheet: TsWorksheet;
begin
  MyWorkbook := TsWorkbook.Create;
  MyWorksheet := MyWorkbook.AddWorksheet('My_Table');  
    // 'My_Table' is the "name" of the worksheet
  ...

On peut accéder aux feuilles de calcul déjà existantes en utilisant les TsWorkbookméthodes .

  • function GetFirstWorksheet : TsWorksheet : récupère la première feuille de calcul du classeur.
  • function GetWorksheetByIndex(AIndex : Cardinal) : TsWorksheet : renvoie la feuille de travail avec l'indice donné (en commençant par 0).
  • function GetWorksheetByName(AName : String) : TsWorksheet : renvoie la feuille de travail avec le nom donné qui a été utilisé lorsque la feuille de travail a été ajoutée.

The count of already existing worksheets can be queried by calling GetWorksheetCount.

Cell

Cell (cellule) The worksheet, finally, gives access to the cells. Une feuille de calcul nouvellement créée, comme dans l'exemple ci-dessus, est vide et ne contient aucune cellule. Les cellules sont ajoutées en leur attribuant des données ou des attributs par l'une des WriteXXXX méthodes de la feuille de calcul. Comme déjà mentionné, une cellule est adressée par l'index de la ligne et de la colonne auxquels elle appartient. Comme d'habitude, les index des lignes et des colonnes commencent à 0. Par conséquent, la cellule "A1" appartient à la ligne 0 et à la colonne 0. Il faut noter que l'indice de ligne et de colonne sont toujours spécifiés dans cet ordre, ceci est différent de la convention de TStringGrid. L'exemple suivant crée une cellule à l'adresse A1 et y place le nombre 1,0.

var
  MyWorkbook: TsWorkbook;
  MyWorksheet: TsWorksheet;
begin
  MyWorkbook := TsWorkbook.Create;
  MyWorksheet := MyWorkbook.AddWorksheet('My_Table');
  MyWorksheet.WriteNumber(0, 0, 1.0);  // "A1" a row=0 et col=0
  ...

Il est également possible d'accéder directement aux cellules au moyen des méthodes FindCell(ARow, ACol) ou GetCell(ARow, ACol) du classeur. Ces deux fonctions existent également dans une version surchargée à laquelle l'adresse de la cellule peut être passée en notation Excel : FindCell(ACellStr : String) ou GetCell(ACellStr : String). Sachez que ces fonctions renvoient un pointeur aux données de la cellule (type PCell). N'oubliez pas de déréférencer les pointeurs ! La différence entre FindCell et GetCell est que le premier retourne nil, si une cellule n'existe pas encore, alors que le second crée une cellule vide dans ce cas.

if MyWorksheet.FindCell('A1') = nil then
  WriteLn('Cell A1 does not exist.');
Le record TCell de base

Il s'agit de la déclaration du type de données de la cellule :

type
  TCell = record
    { L'emplacement de la cellule }
    Worksheet : TsWorksheet;
    Col: Cardinal; // zero-based
    Row: Cardinal; // zero-based

    { Index of format record }
    FormatIndex: Integer;

    { Drapeaux de l'état }
    Flags: TsCellFlags; // (cfHasComment, cfMerged, cfHyperlink, ...)

    { Contenu de la cellule }
    UTF8StringValue : String ; // les chaînes de caractères ne peuvent pas faire partie d'un enregistrement de variant.
    case ContentType : TCellContentType of /// doit être à la fin de la déclaration
      cctEmpty  : () ;// n'a pas de données du tout
      cctFormula : (); // UTF8StringValue est en dehors the variant record
      cctNumber : (Numbervalue: Double);
      cctUTF8String : (); // FormulaValue est en dehors the variant record
      cctDateTime : (DateTimevalue: TDateTime);
      cctBool : (BoolValue: boolean);
      cctError : (ErrorValue: TsErrorValue);
  end;
  PCell = ^TCell;

Le champ ContentType indique quel type de données est stocké dans la cellule :

type
  TCellContentType = (cctEmpty, cctFormula, cctNumber, cctUTF8String, cctDateTime, cctBool, cctError);

Selon ce champ, les données correspondantes peuvent être trouvées dans les champs

  • NumberValue (for ContentType=cctNumber), or
  • UTF8StringValue (for ContentType=cctUTF8String), or
  • DateTimeValue (for ContentType=cctDateTime), or
  • BoolValue (for ContentType=cctBool), i.e. TRUE or FALSE, or
  • ErrorValue (for ContentType=cctError).

En raison de l'utilisation d'un record variant, la plupart de ces valeurs se chevauchent, c'est-à-dire que la modification de NumberValue affecte également les autres valeurs. Par conséquent, il faut toujours respecter le ContentType lorsqu'on accède directement à l'enregistrement TCell (les méthodes de feuille de calcul discutées ci-dessous en tiennent compte automatiquement).

Le champ Flags indique si des données supplémentaires sont associées à la cellule qui ne sont pas incluses dans l'enregistrement de la cellule généralement pour économiser de la mémoire :

type
  TsCellFlag = (cfHasComment, cfHyperlink, cfMerged, cfHasFormula, cf3dFormula);
  TsCellFlags = set of TsCellFlag;
  • cfHasComment : Un commentaire du record peut être trouvé dans le Commentaires de la feuille de calcul.
  • cfHyperlink: La cellule contient un hyperlink stocké dans les Hyperlinks de la feuille de calcul.
  • cfMerged : La cellule appartient à un bloc fusionné et s'étend sur plusieurs cellules.
  • cfHasFormula : La cellule est associée à une formule qui est stockée dans les Formules de la feuille de calcul.
  • cf3dFormule : La formule associée à la cellule contient des éléments faisant référence à d'autres feuilles du même classeur.
<a href="/File:fpsgrid.png view-source:<a class="external free" href="https://wiki.freepascal.org/File:fpsgrid.png">https://wiki.freepascal.org/File:fpsgrid.png</a>" class="image"><img alt="Note-icon.png" src="/images/0/02/fpsgrid.png view-source:<a class="external free" href="https://wiki.freepascal.org/images/0/02/fpsgrid.png">https://wiki.freepascal.org/images/0/02/fpsgrid.png</a>" width="24" height="29" /></a>
{{Note:Après calcul d'une formule ou après lecture d'un fichier, le ContentType de la cellule de formule est converti en celui du résultat. Ensuite, la présence d'une formule ne peut être détectée qu'en appelant la fonction HasFormula(cell) pour la cellule à interroger (cell : PCell) dans l'unité fpsUtils ; cette fonction vérifie la présence de l'élément cfHasFormula dans les flags de la cellule.}}
How to add and read data to/from a cell
Comment ajouter et lire des données dans une cellule

L'ajout de valeurs à une cellule s'effectue le plus facilement en utilisant l'une des WriteXXXX de la feuille de calcul. Les plus importantes sont :

type
  TsWorksheet = class
    &lt;span class="o"&gt;...&lt;/span&gt;
    {Ecriture des valeurs monétaires}
    function WriteCurrency(ARow, ACol: Cardinal; AValue: Double;
      ANumFormat: TsNumberFormat = nfCurrency; ADecimals: Integer = 2;
      ACurrencySymbol: String = '?'; APosCurrFormat: Integer = -1;
      ANegCurrFormat: Integer = -1): PCell; overload;
    procedure WriteCurrency(ACell: PCell; AValue: Double;
      ANumFormat: TsNumberFormat = nfCurrency; ADecimals: Integer = -1;
      ACurrencySymbol: String = '?'; APosCurrFormat: Integer = -1;
      ANegCurrFormat: Integer = -1); overload;
    function WriteCurrency(ARow, ACol: Cardinal; AValue: Double;
      ANumFormat: TsNumberFormat; ANumFormatString: String): PCell; overload;
    procedure WriteCurrency(ACell: PCell; AValue: Double;
      ANumFormat: TsNumberFormat; ANumFormatString: String); overload;

    {Écriture de valeurs de date/heure }
    function WriteDateTime(ARow, ACol: Cardinal; AValue: TDateTime): PCell; overload;
    procedure WriteDateTime(ACell: PCell; AValue: TDateTime); overload;
    function WriteDateTime(ARow, ACol: Cardinal; AValue: TDateTime;
      ANumFormat: TsNumberFormat; ANumFormatStr: String = ''): PCell; overload;
    procedure WriteDateTime(ACell: PCell; AValue: TDateTime;
      ANumFormat: TsNumberFormat; ANumFormatStr: String = ''); overload;
    function WriteDateTime(ARow, ACol: Cardinal; AValue: TDateTime;
      ANumFormatStr: String): PCell; overload;
    procedure WriteDateTime(ACell: PCell; AValue: TDateTime;
      ANumFormatStr: String); overload;

    {Écriture de valeurs numériques}
    function WriteNumber(ARow, ACol: Cardinal; ANumber: double): PCell; overload;
    procedure WriteNumber(ACell: PCell; ANumber: Double); overload;
    function WriteNumber(ARow, ACol: Cardinal; ANumber: double;
      ANumFormat: TsNumberFormat; ADecimals: Byte = 2): PCell; overload;
    procedure WriteNumber(ACell: PCell; ANumber: Double;
      ANumFormat: TsNumberFormat; ADecimals: Byte = 2); overload;
    function WriteNumber(ARow, ACol: Cardinal; ANumber: double;
      ANumFormat: TsNumberFormat; ANumFormatString: String): PCell; overload;
    procedure WriteNumber(ACell: PCell; ANumber: Double;
      ANumFormat: TsNumberFormat; ANumFormatString: String); overload;

    {Écriture de chaîne de caractères }
    function WriteText(ARow, ACol: Cardinal; AText: ansistring;
      ARichTextParams: TsRichTextParams = nil): PCell; overload;
    procedure WriteText(ACell: PCell; AText: String;
      ARichTextparams: TsRichTextParams = nil); overload;

    // les anciennes méthodes de chaîne "WriteUTF8Text" sont désormais obsolètes.

Certaines de ces méthodes existent dans des versions surchargées dans lesquelles les paramètres de formatage de la cellule peuvent être ajoutés avec la valeur de la cellule. De manière correspondante à l'écriture, il existe également un certain nombre de worksheet méthodes de lecture des valeurs des cellules :

type
  TsWorksheet = class
    &lt;span class="o"&gt;...&lt;/span&gt;
    {Lecture du contenu d'une cellule qui contient une valeur string }
    function ReadAsText(ARow, ACol: Cardinal): string; overload;
    function ReadAsText(ACell: PCell): string; overload;
    function ReadAsText(ACell: PCell; AFormatSettings: TFormatSettings): string; overload;

    {Lecture du contenu d'une cellule qui contient une valeur nombre }
    function ReadAsNumber(ARow, ACol: Cardinal): Double; overload;
    function ReadAsNumber(ACell: PCell): Double; overload;
    function ReadNumericValue(ACell: PCell; out AValue: Double): Boolean;

    {Lecture du contenu d'une cellule qui contient une valeur date/heure }
    function ReadAsDateTime(ARow, ACol: Cardinal; out AResult: TDateTime): Boolean; overload;
    function ReadAsDateTime(ACell: PCell; out AResult: TDateTime): Boolean; overload;
    &lt;span class="o"&gt;...&lt;/span&gt;
Index du format de la cellule

FormatIndex est l'index de l'enregistrement du format de cellule. Il décrit les attributs de mise en forme d'une cellule. Ces enregistrements sont collectés par une liste interne du classeur et sont définis comme suit :

type
  TsCellFormat = record
    FontIndex: Integer;
    TextRotation: TsTextRotation;
    HorAlignment: TsHorAlignment;
    VertAlignment: TsVertAlignment;
    Border: TsCellBorders;
    BorderStyles: TsCellBorderStyles;
    Background: TsFillPattern;
    NumberFormatIndex: Integer;
    NumberFormat: TsNumberFormat;
    NumberFormatStr: String;
    BiDiMode&#160;: TsBiDiMode&#160;; // bdDefault, bdLTR {gauche à droite}, bdRTL {droite à gauche)
    Protection: TsCellProtection; // cpLockCell, cpHideFormulas
    UsedFormattingFields: TsUsedFormattingFields;
      //uffTextRotation, uffFont, uffBold, uffBorder, uffBackground, uffNumberFormat, uffWordWrap, uffHorAlign, uffVertAlign, uffBiDi
  end;
  • FontIndex : police de texte en spécifiant l'index dans la liste des polices du classeur .
  • TextRotation : spécifie si le texte de la cellule est écrit horizontalement ou verticalement .
  • HorAlignment : texte aligné à gauche, centré horizontalement ou aligné à droite .
  • VertAlignment : texte en haut, en bas ou centré verticalement .
  • Border : un ensemble de drapeaux indiquant que - s'ils sont définis - une ligne de bordure est dessinée sur le bord gauche, haut, droit ou bas de la cellule. Les lignes sont dessinées selon les BorderStyles qui définissent le style de ligne et la couleur de la bordure.
  • Fond : un record définissant le remplissage de fond d'une cellule (style de motif, couleur de motif et couleur de fond - voir le chapitre sur l'arrière-plan de cellule ci-dessous).
  • NumberFormat et NumberFormatStr spécifient comment les valeurs de nombre ou de date/heure sont formatées (par exemple, le nombre de décimales, le format de date long ou court, etc.)
  • Seuls les attributs de format pour lesquels un drapeau est défini dans le UsedFormattingFields sont pris en compte lors du formatage d'une cellule. Si un drapeau n'est pas inclus alors l'attribut correspondant est ignoré et remplacé par sa valeur par défaut.

Pour spécifier un format pour une cellule donnée, appelez la méthode correspondante de la feuille de calcul WriteXXXX, pour récupérer un format appelez ReadXX. Ces méthodes reçoivent généralement un pointeur sur la cellule comme paramètre, mais il existe également des versions surchargées qui acceptent l'index de la ligne et de la colonne. De plus, les styles de mise en forme peuvent également être appliqués directement à la cellule en utilisant une aide d'enregistrement implémentée dans l'unité fpsCell.

Voir formatage des cellules ci-dessous pour une description plus détaillée.

Colonnes et lignes

Des records de colonnes et de lignes sont ajoutés pour chaque colonne et ligne ayant des propriétés autres que celles par défaut :

type
  TCol = record
    Col: Cardinal;
    Width: Single;
    ColWidthType: TsColWidthType; // = (cwtDefault, cwtCustom)
    FormatIndex: Integer;
    Options: TsColRowOptions; // set of [croHidden, croPageBreak]
  end;
  PCol = ^TCol;

  TRow = record
    Row: Cardinal;
    Height: Single;
    RowHeightType: TsRowHeightType; // = (rhtDefault, rhtCustom, rhtAuto)
    FormatIndex: Integer;
    Options: TsColRowOptions; // set of [croHidden, croPageBreak]
    Hidden: Boolean;
    PageBreak: Boolean;
  end;
  PRow = ^TRow;
Largeur de colonne / hauteur de ligne

La largeur des colonnes et la hauteur des lignes peuvent être spécifiées dans différentes unités définies par leur type TsSizeUnits = (suChars, suLines, suMillimeters, suCentimeters, suPoints, suInches). ursuChars fait référence au nombre de 0 caractères entrant dans la largeur de la colonne - c'est ainsi qu'Excel définit les largeurs de colonne. suLines est le nombre de lignes s'adaptant à la hauteur de la ligne. Les deux unités sont basées sur la taille des caractères de la police par défaut du classeur. Les autres unités sont des unités de longueur physique conventionnelle (1 cm = 10 mm, 1 pouce = 25,4 mm = 72 pts). Les valeurs fractionnaires sont acceptées. Le classeur et les feuilles de calcul stockent les longueurs en interne en millimètres (MonWorkbook.Units).

Les applications Office ajustent généralement les hauteurs de ligne automatiquement en fonction de la police ou de la rotation du texte du contenu de la cellule. Ce cas est identifié par RowHeightType ayant la valeur rhtAuto. Comme la feuille de calcul ne peut pas calculer très précisément la taille du texte, les hauteurs de ligne automatiques ne sont pas écrites par FPSpreadsheet ; elles sont remplacées par la hauteur de ligne par défaut. La hauteur de ligne par défaut est également utilisée si une ligne est vide, c'est-à-dire si elle ne contient aucune cellule de données. Sa valeur peut être modifiée en appelant la WriteDefaultRowHeight() ou en utilisant la propriété de la feuille de calcul DefaultRowHeight. Dans WriteDefaultRowHeight, les unités doivent être spécifiées alors que dans DefaultRowHeight, elles sont supposées être des lignes. De même, la largeur de colonne par défaut peut être spécifiée par WriteDefaultColWidth() ou la propriété DefaultColWidth (en caractères).

Pour outrepasser les hauteurs de ligne automatiques et par défaut, appelez la méthode de la feuille de calcul WriteRowHeight(). Ces records de lignes sont identifiés par RowHeightType ayant la valeur rhtCustom. De même, la largeur des colonnes peut être fixée à une valeur spécifique en appelant WriteColWidth(). ColWidthType de ces colonnes est cwtCustom.

La hauteur/largeur d'une ligne/colonne particulière peut être récupérée au moyen des méthodes GetRowHeight ou GetColWidth. Notez que ces méthodes renvoient les hauteurs de ligne/largeurs de colonne par défaut s'il n'y a pas de TRow/TCol records.

type 
  TsWorksheet = class
  &lt;span class="o"&gt;...&lt;/span&gt;
  {Définir la hauteur de la ligne}
  procedure WriteRowHeight(ARowIndex: Cardinal; AHeight: Single; AUnits: TsSizeUnits);
  { Définir la largeur de la colonne }
  procedure WriteColWidth(AColIndex: Cardinal; AWidth: Single; AUnits: TsSizeUnits);
  {Définir la hauteur de ligne par défaut }
  procedure WriteDefaultRowHeight(AHeight: Single; AUnits: TsSizeUnits);
  {Définir la largeur par défaut de la colonne }
  procedure WriteDefaultColWidth(AWidth: Single; AUnits: TsSizeUnits);

  { Retourner la hauteur de la ligne}
  function GetRowHeight(ARowIndex: Cardinal; AUnits: TsSizeUnits): Single;
  { Retourner la largeur de la colonne }
  function GetColWidth(AColIndex: Cardinal; AUnits: TsSizeUnits): Single;
  { Retourner la hauteur de ligne par défaut }
  function ReadDefaultRowHeight(AUnits: TsSizeUnits): Single;
  { Retourner la largeur de colonne par défaut }
  function ReadDefaultColWidth(AUnits: TsSizeUnits): Single;

  property DefaultRowHeight: Single; // en lignes
  property DefaultColWidht: Single; // en caractères

Il existe également des versions surchargées de ces méthodes qui ne nécessitent pas le paramètre AUnits. Dans ce cas, la hauteur des lignes est définie en fonction du nombre de lignes et la largeur des colonnes est définie en fonction du nombre de caractères. Notez que ces variantes sont issues de versions antérieures et sont désormais obsolètes.

Formats des colonnes et des lignes

L'élément FormatIndex de la ligne et de la colonne enregistre le format appliqué à la ligne ou à la colonne entière. Avec les cellules, ces formats sont stockés comme TsCellFormat records dans une liste interne du classeur, FormatIndex est l'index des propriétés du format dans cette liste. Voir les détails dans la section Formatage des cellules. Les formats de ligne et de colonne sont principalement appliqués aux cellules vides, mais si une nouvelle cellule est ajoutée, elle obtiendra automatiquement le format de la ligne ou de la colonne. (Si la ligne et la colonne ont des formats différents, le format de la ligne sera utilisé).

Voici une liste des méthodes de feuille de calcul disponibles pour le formatage des colonnes et des lignes :

<syntaxhighlight lang="pascal"> type

 TsWorksheet = class
 // Attribue un format à une colonne ou à une ligne
 procedure WriteColFormatIndex(ACol: Cardinal; AFormatIndex: Integer);
 procedure WriteRowFormatIndex(ARow: Cardinal; AFormatIndex: Integer);
 // récupère le format d'une colonne ou d'une ligne
 function GetColFormatIndex(ACol: Cardinal): Integer;
 function GetRowFormatIndex(ARow: Cardinal): Integer;
 // Renvoie la police affectée à une colonne ou à une ligne.
 function ReadColFont(ACol: PCol): TsFont;
 function ReadRowFont(ARow: PRow): TsFont;
 // Vérifie si une colonne ou une ligne utilise un format spécial.
 function HasRowFormats: Boolean;
 function HasColFormats: Boolean;

</syntaxhighlight lang="pascal">

Colonnes / lignes cachées

Ajouter l'indicateur croHidden à l'Options cache la ligne ou la colonne dans l'application Office (ou dans TsWorksheetGrid). Les méthodes de feuille de calcul suivantes sont des aides pour gérer la visibilité des lignes/colonnes :

<span></span>type TsWorksheet = class
  <span class="o">...</span>
  { Masquer la colonne/ligne }
  procedure HideCol(ACol: Cardinal);
  procedure HideRow(ARow: Cardinal);

  { Afficher une colonne/ligne précédemment cachée }
  procedure ShowCol(ACol: Cardinal);
  procedure ShowRow(ARow: Cardinal);

  { Vérifier si la colonne/ligne} est cachée }
  function ColHidden(ACol: Cardinal): Boolean;
  function RowHidden(ARow: Cardinal): Boolean;
Sauts de page

L'indicateur croPageBreak peut être ajouté à l'Options de la ligne ou de la colonne afin de forcer un saut de page avant la ligne ou la colonne correspondante lorsque la feuille de calcul est imprimée par les applications Office. Notez que FPSpreadsheet lui-même ne prend pas en charge l'impression. Les méthodes de feuille de calcul suivantes aident à gérer les sauts de page :

<span></span>type TsWorksheet = class
  <span class="o">...</span>
  {Forcer un saut de page avant la colonne/ligne spécifiée }
  procedure AddPageBreakToCol(ACol: Cardinal);
  procedure AddPageBreakToRow(ARow: Cardinal);

  {Supprime un saut de page précédemment ajouté à une colonne/ligne }
  procedure RemovePageBreakFromCol(ACol: Cardinal);
  procedure RemovePageBreakFromRow(ARow: Cardinal);

  {Vérifie si un saut de page est forcé avant la colonne/ligne spécifiée }
  function IsPageBreakCol(ACol: Cardinal): Boolean;
  function IsPageBreakRow(ARow: Cardinal): Boolean;

Événements

Les feuilles de calcul et les classeurs déclenchent une série d'événements tels que OnChangeCell, OnChangeFont, etc. Les événements sont généralement destinés à l'interaction avec les commandes visuelles du tableur. Si vous devez joindre vos propres gestionnaires, vous devez vous assurer que le gestionnaire d'origine est appelé, au moins dans un programme gui utilisant les contrôles de feuille de calcul. Ou vous utilisez les événements fournis par les contrôles visuels eux-mêmes, par exemple WorksheetGrid.OnEditingDone au lieu de WorksheetGrid.Worksheet.OnChangeCell.

Formules

Deux types de formules sont pris en charge par FPSpreadsheet :

  • Formules à textes : Elles sont écrites en chaînes de caractères comme dans les applications bureautiques, par exemple "=ROUND(A1+B1,0)". Ils sont utilisés en interne dans les fichiers d'Open/LibreOffice et d'Excel .xlsx.
  • Les formules RPN sont utilisées en interne par les fichiers binaires .xls Excel. Ils sont écrits en notation polonaise inversée (RPN), par exemple : A1, B1, Add, 0, ROUND. Si une feuille de calcul contenant des formules doit être enregistrée dans un format Excel binaire, les formules RPN requises sont générées automatiquement.

FPSpreadsheet peut convertir les formules de type chaîne et rpn. Les formules des deux types peuvent être calculées.

Dans les anciennes versions de FPSpreadsheet, les formules étaient stockées directement dans le record de la cellule. On y a renoncé pour avoir des formules analysées disponibles pour un calcul plus rapide. Les formules sont stockées dans l'arbre Formules de la feuille de calcul. Le record de la formule contient l'indice de ligne et de colonne de la cellule à laquelle appartient la formule, la représentation de la chaîne de caractères de la formule, ainsi que l'arbre d'analyse syntaxique pour une évaluation rapide.

FPSpreadsheet prend en charge la majorité des formules fournies par les tableurs courants. Toutefois, lors de la lecture d'un fichier créé par ces applications, il est toujours possible qu'une formule non prise en charge soit contenue. Pour éviter le plantage de fpspreadsheet, la lecture des formules est désactivée par défaut ; la cellule affiche uniquement le résultat de la formule écrite par l'application Office. Pour activer la lecture des formules, ajoutez l'élément boReadformulas aux Options du classeur avant d'ouvrir le fichier. Si une erreur se produit dans ce cas, le lecteur capture normalement l'exception, écrit le message d'exception dans le journal des erreurs du classeur et continue la lecture. Si vous voulez que la lecture s'arrête, vous devez ajouter le boAbortReadingOnFormulaError au classeur Options.

Les formules peuvent être liées aux données d'autres feuilles du même classeur ("formules 3d") en appliquant la syntaxe Excel (voir ci-dessous). Les liens externes vers des feuilles de calcul dans d'autres fichiers ne sont pas pris en charge.

Le calcul des formules n'est normalement pas nécessaire lorsqu'un fichier est écrit par FPSpreadsheet pour être ouvert dans une application Office car celle-ci calcule automatiquement les résultats des formules. Cependant, si le même fichier est ouvert par une application basée sur FPSpreadsheet, les cellules calculées seront vides car les formules ne sont pas calculées automatiquement par défaut. Pour activer le calcul des formules avant d'écrire une feuille de calcul dans un fichier, vous devez ajouter l'option boCalcBeforeSaving aux Options.

Si FPSpreadshet est utilisé dans une application interactive (telle que la spready démo trouvée dans le dossierexamples de l'installation de FPSpreadsheet), il est souhaitable de calculer les formules automatiquement chaque fois que les chaînes de formules ou les valeurs des cellules sont modifiées par l'utilisateur. Cela peut être réalisé par l'option boAutoCalc dans les Options du classeur.

Le cadre le plus général concernant les formules est donc le suivant

<span></span>  MyWorkbook.Options := MyWorkbook.Options + [boReadFormulas, boCalcBeforeSaving, boAutoCalc];

Le calcul des formules peut être déclenché manuellement en appelant la méthode CalcFormulas de la feuille de calcul ou du classeur. Cette dernière est absolument nécessaire lorsque le classeur contient des formules 3D où le résultat d'une cellule peut affecter les cellules d'autres feuilles. S'il n'y a que des formules internes à la feuille de calcul, le CalcFormulas de la feuille de calcul est suffisant.

Formules de chaîne de texte

Les formules de chaînes de caractères sont écrites de la même manière que dans les applications Office. La méthode de feuille de calcul pour créer une formule de chaîne est WriteFormula :

<span></span><span class="k">var</span>
  MyWorksheet: TsWorksheet;
  MyWorksheet.WriteFormula(0, 1, '=ROUND(A1+B2+1.215,0)');
  // Par défaut, utiliser le point comme décimal et la virgule comme séparateur de liste !

Quelques notes sur la syntaxe :

  • Le caractère en tête = qui identifie les formules dans les applications Office n'est pas absolument nécessaire ici et peut être abandonné. La formule est stockée dans le record de la cellule sans elle.
  • La casse du nom de la formule est ignorée.
  • Des espaces peuvent être ajoutés pour une meilleure lisibilité, mais ils seront perdus lors de la sauvegarde.
  • Les chaînes de caractères doivent être placées entre guillemets.
  • Les points d'angle d'une plage de cellules doivent être séparés par un deux-points (" :"), par exemple A1:C3. Les plages non ordonnées seront réorganisées lorsque la formule sera analysée, c'est-à-dire que C3:A1 devient A1:C3.
  • Les liens vers d'autres feuilles de calcul doivent respecter la syntaxe Excel qui sépare le nom de la feuille et l'adresse de la cellule par un " !". Une seule cellule, par exemple, peut être liée par Sheet1!A1. Une plage de feuilles doit être placée avant la cellule ou la plage de cellules, par exemple Feuille1:Feuille2!A1:C3. Notez que la syntaxe Open/LibreOffice avec un point de séparation et une référence aux points d'angle de la boîte 3d (c'est-à-dire Sheet1.A1:Sheet2.C3) n'est pas prise en charge. Notez également que la ou les feuilles de calcul vers lesquelles la formule établit un lien doivent exister au moment où la formule est ajoutée, sinon le lien sera remplacé par le code d'erreur #REF!, et la formule ne sera pas utilisable même si la feuille manquante est ajoutée ultérieurement.
  • Normalement, les nombres à virgule flottante doivent être saisis avec un point comme séparateur décimal, et une virgule doit être utilisée pour séparer les arguments de fonction.
  • Mettre le paramètre optionnel ALocalized des méthodes de feuille de calcul WriteFormula à TRUE, permet toutefois d'utiliser les séparateurs décimaux et de liste localisés pris dans le FormatSettings - voir la démo spready.
<span></span><span class="k">var</span>
  MyWorksheet: TsWorksheet;
  MyWorksheet.WriteFormula(0, 1, '=ROUND(A1+B2+1.215,0)');
  // En raison du "true", l'analyseur de formule accepte la virgule comme décimale et la
  // le point-virgule comme séparateur de liste si les paramètres de format du classeur sont configurés comme ceci.

Utilisez les méthodes de feuille de calcul ReadFormula ou ReadFormulaAsString pour récupérer la chaîne de caractères de la formule affectée à la cellule. Le pointeur de la cellule doit être donné en paramètre. Cette dernière fonction accepte un paramètre supplémentaire (booléen) ALocalized pour utiliser les séparateurs décimaux et de liste du FormatSettings du classeur pour la création de la chaîne de formule.

<span></span><span class="k">var</span>
  MyWorksheet: TsWorksheet;
  cell: PCell;
  if MyWorksheet.FindCell('A1') = nil then
  WriteLn('Le format interne de la formule est : ', MyworkSheet.ReadFormula(cell));
  // Pour l'exemple précédent, cela donnera la sortie suivante

Formules RPN

Au niveau des applications, les formules de type chaîne de caractères sont principalement utilisées, et les formules RPN ont peu d'importance pratique. Par conséquent, la documentation des formules RPN a été retirée de ce wiki principal de FPSpreadsheet et peut être trouvée dans l'article "Formules RPN dans FPSpreadsheet".

Formules partagées et formules de tableau

  • Les formules partagées ne sont prises en charge que pour la lecture (à partir de fichiers Excel).
  • Les formules de tableaux ne sont pas prises en charge, actuellement.

Liste des formules intégrées

FPSpreadsheet prend en charge plus de 80 formules intégrées. Afin de ne pas trop gonfler cette page wiki, la documentation de ces formules a été déplacée vers le document séparé "Liste des formules".

Pour en savoir plus sur les fonctions disponibles, consultez le fichier testcases_calcrpnformula.inc dans le dossier tests de l'installation de FPSpreadsheet où chaque fonction est incluse avec au moins un exemple.

Extension de FPSpreadsheet par des formules définies par l'utilisateur

Bien que les formules intégrées couvrent la plupart des applications, il peut être nécessaire d'accéder à une formule disponible dans l'application Office, mais pas dans FPSpreadsheet Pour cette raison, la bibliothèque prend en charge un mécanisme d'enregistrement qui permet d'ajouter des fonctions, définies par l'utilisateur, aux feuilles de calcul. Cela peut être fait en appelant la procédure RegisterFunction depuis l'unité fpsExprParser :

<span></span>procedure RegisterFunction(const AName: ShortString; const AResultType: Char;
  const AParamTypes: String; const AExcelCode: Integer; ACallBack: TsExprFunctionCallBack); overload;
  const AParamTypes: String; const AExcelCode: Integer; ACallBack: TsExprEventCallBack); overload;
  • AName spécifie le nom par lequel la fonction sera appelée dans la feuille de calcul. Il doit correspondre au nom de la formule dans l'application Office.
  • AResultType est un caractère qui identifie le type de données du résultat de la fonction :
    • 'F' - nombre à virgule flottante .
    • 'I' - nombre entier
    • 'D' - date/time
    • 'B' - boolean
    • 'S' - string
    • 'C' - adresse de la cellule, par exemple 'A1' .
    • 'R' - adresse de la plage de cellules, par exemple 'A1:C3'.
  • AParamTypes est une chaîne de caractères dans laquelle chaque caractère identifie le type de données de l'argument correspondant. En plus de la liste présentée ci-dessus, les symboles suivants peuvent être utilisés :
    • '?' - tout type .
    • '+' - doit être le dernier caractère. Cela signifie que le caractère précédent est répété indéfiniment. Cela permet un nombre d'arguments arbitraire. Veuillez noter, toutefois, qu'Excel ne prend en charge que 30 arguments au maximum.
    • minuscules 'f', 'i', 'd', 'b', 's' indiquent des paramètres facultatifs du type expliqué ci-dessus. Bien sûr, les symboles en majuscules ne peuvent pas suivre les symboles en minuscules.
  • AExcelCode est l'identifiant de la fonction dans les fichiers xls. Voir "Documentation OpenOffice du format de fichier Microsoft Excel", section 3.11, pour une liste.
  • ACallback identifie la fonction qui est appelée par FPSpreadsheet pour le calcul de la formule. Il peut s'agir d'une procédure ou d'un gestionnaire d'événements.
<span></span><span class="k">type</span>
  TsExprFunctionCallBack = procedure (var Result: TsExpressionResult; const Args: TsExprParameterArray);
  TsExprFunctionEvent = procedure (var Result: TsExpressionResult; const Args: TsExprParameterArray) of object;

Le TsExpressionResult est un record de variant contenant des données de résultat ou d'argument de plusieurs types :

<span></span><span class="k">type</span>
  TsResultType = (rtEmpty, rtBoolean, rtInteger, rtFloat, rtDateTime, rtString,
    rtCell, rtCellRange, rtError, rtAny);

  TsExpressionResult = record
    Worksheet : TsWorksheet;
    ResString : String;
    case ResultType : TsResultType of
      rtEmpty : ();
      rtError : (ResError : TsErrorValue);
      rtBoolean : (ResBoolean : Boolean);
      rtInteger : (ResInteger : Int64);
      rtFloat : (ResFloat : TsExprFloat);
      rtDateTime : (ResDateTime : TDatetime);
      rtCell : (ResRow, ResCol : Cardinal);
      rtCellRange : (ResCellRange : TsCellRange);
      rtString : ();
  end;

  TsExprParameterArray = array of TsExpressionResult;

À titre d'exemple, nous montrons ici le code de la CONCATENATE() formule qui joint deux ou plusieurs chaînes de caractères :

<span></span>const
  INT_EXCEL_SHEET_FUNC_CONCATENATE = 336;
  procedure fpsCONCATENATE(var Result: TsExpressionResult; const Args: TsExprParameterArray);
  s: String;
  i: Integer;
  s := '';
  for i:=0 to Length(Args)-1 do
  begin
    if Args[i].ResultType = rtError then
    begin
      Result := ErrorResult(Args[i].ResError);
      exit;
    end;
    s := s + ArgToString(Args[i]);
    // "ArgToString" simplifie l'obtention de la chaîne de caractères d'un TsExpressionResult en tant que
    // chaîne de caractères, peut être contenue dans le champ ResString et dans le champ ResCell.
    // Il existe une telle fonction pour chaque type de données de base.
  end;
  Result := StringResult(s);
  // "StringResult" stocke la chaîne s dans le champ ResString de l'objet
  // TsExpressionResult et définit le ResultType à rtString.
  // Il existe une telle fonction pour chaque type de données de base.

Il existe un exemple travaillé (demo_formula_func.pas) dans le dossier examples/other de l'installation de FPSpreadsheet. Dans cette démo, quatre fonctions financières (FV(), PV(), PMT(), RATE()) sont ajoutées à FPSpreadsheet.

Formules non prises en charge

Il est parfois nécessaire de créer des fichiers pour les applications Office avec des formules non prises en charge par fpspreadsheet. Cela est possible dans une certaine mesure lorsque l'option du classeur boIgnoreFormulas est active. Il est alors possible d'écrire n'importe quelle formule arbitraire dans une cellule, et la formule n'est ni vérifiée ni évaluée. Le classeur peut être écrit dans un fichier .ods ou .xlsx. L'ancien format de fichier xls ne peut être utilisé car la formule devrait être analysée pour créer la formule rpn nécessaire.

Dans le dossier exemples/autres vous trouverez le projet d'exemple demo_ignore_formula qui crée un fichier ods avec des références à un autre fichier de données - les références externes ne sont normalement pas supportées par fpspreadsheet, et donc la solution de contournement ignore-formules doit être utilisée. Notez que cet exemple ne fonctionne pas avec xlsx car Excel écrit les informations sur les liens externes dans des fichiers xml séparés à l'intérieur du conteneur xlsx.

Mise en forme des cellules

Formats de nombres et de dates/heures

Les nombres et les valeurs de date/heure peuvent être affichés dans différents formats. Dans FPSpreadsheet, cela peut être réalisé de deux manières :

  • en utilisant des formats de nombres intégrés en spécifiant une valeur pour le NumberFormat de la cellule .
  • en utilisant une chaîne de format personnalisée.

Les formats des nombres peuvent être spécifiés par ces méthodes de feuille de calcul :

<span></span><span class="k">type</span>
  TsWorksheet = class
  public
    // Définir seulement les formats des nombres
    function WriteNumberFormat(ARow, ACol: Cardinal; ANumberFormat: TsNumberFormat;
      const AFormatString: String = ''): PCell; overload;
    procedure WriteNumberFormat(ACell: PCell; ANumberFormat: TsNumberFormat;
      const AFormatString: String = ''); overload;

    function WriteNumberFormat(ARow, ACol: Cardinal; ANumFormat: TsNumberFormat;
      ADecimals: Integer; ACurrencySymbol: String = ''; APosCurrFormat: Integer = -1;
      ANegCurrFormat: Integer = -1): PCell; overload;
    procedure WriteNumberFormat(ACell: PCell; ANumFormat: TsNumberFormat;
      ADecimals: Integer; ACurrencySymbol: String = '';
      APosCurrFormat: Integer = -1; ANegCurrFormat: Integer = -1); overload;

    function WriteFractionFormat(ARow, ACol: Cardinal; AMixedFraction: Boolean;
      ANumeratorDigits, ADenominatorDigits: Integer): PCell; overload;
    procedure WriteFractionFormat(ACell: PCell; AMixedFraction: Boolean;
      ANumeratorDigits, ADenominatorDigits: Integer); overload;

    // Définir uniquement les formats de date et d'heure
    function WriteDateTimeFormat(ARow, ACol: Cardinal; ANumberFormat: TsNumberFormat;
      const AFormatString: String = ''): PCell; overload;
    procedure WriteDateTimeFormat(ACell: PCell; ANumberFormat: TsNumberFormat;
      const AFormatString: String = ''); overload;


    // Définissez les valeurs des cellules et les formats des nombres en un seul appel.

    // valeurs numériques
    function WriteNumber(ARow, ACol: Cardinal; ANumber: double;
      AFormat: TsNumberFormat = nfGeneral; ADecimals: Byte = 2;
      ACurrencySymbol: String = ''): PCell; overload;
    procedure WriteNumber(ACell: PCell; ANumber: Double; AFormat: TsNumberFormat = nfGeneral;
      ADecimals: Byte = 2; ACurrencySymbol: String = ''); overload;
    function WriteNumber(ARow, ACol: Cardinal; ANumber: double;
      AFormat: TsNumberFormat; AFormatString: String): PCell; overload;
    procedure WriteNumber(ACell: PCell; ANumber: Double;
      AFormat: TsNumberFormat; AFormatString: String); overload;

    // valeurs de date/heure
    function WriteDateTime(ARow, ACol: Cardinal; AValue: TDateTime;
      AFormat: TsNumberFormat = nfShortDateTime; AFormatStr: String = ''): PCell; overload;
    procedure WriteDateTime(ACell: PCell; AValue: TDateTime;
      AFormat: TsNumberFormat = nfShortDateTime; AFormatStr: String = ''); overload;
    function WriteDateTime(ARow, ACol: Cardinal; AValue: TDateTime;
      AFormatStr: String): PCell; overload;
    procedure WriteDateTime(ACell: PCell; AValue: TDateTime;
      AFormatStr: String); overload;

    // valeurs monétaires
    function WriteCurrency(ARow, ACol: Cardinal; AValue: Double;
      AFormat: TsNumberFormat = nfCurrency; ADecimals: Integer = 2;
      ACurrencySymbol: String = '?'; APosCurrFormat: Integer = -1;
      ANegCurrFormat: Integer = -1): PCell; overload;
    procedure WriteCurrency(ACell: PCell; AValue: Double;
      AFormat: TsNumberFormat = nfCurrency; ADecimals: Integer = -1;
      ACurrencySymbol: String = '?'; APosCurrFormat: Integer = -1;
      ANegCurrFormat: Integer = -1); overload;
    function WriteCurrency(ARow, ACol: Cardinal; AValue: Double;
      AFormat: TsNumberFormat; AFormatString: String): PCell; overload;
    procedure WriteCurrency(ACell: PCell; AValue: Double;
      AFormat: TsNumberFormat; AFormatString: String); overload;
  <span class="o">...</span>
Formats numériques intégrés

Les formats intégrés sont définis par l'énumération TsNumberFormat. Malgré son nom, les éléments couvrent à la fois les valeurs numériques et les valeurs de date/heure :

<span></span><span class="k">type</span>
  TsNumberFormat = (
    // polyvalent pour tous les nombres
    nfGeneral,
    // nombres
    nfFixed, nfFixedTh, nfExp, nfPercentage, nfFraction,
    // monnaitaire
    nfCurrency, nfCurrencyRed,
    // dates et heures
    nfShortDateTime, nfShortDate, nfLongDate, nfShortTime, nfLongTime,
    nfShortTimeAM, nfLongTimeAM, nfDayMonth, nfMonthYear, nfTimeInterval,
    // autre (en utilisant la chaîne de caractères du format).
    nfCustom);
  • nfGeneral correspond à la mise en forme par défaut faisant apparaître le plus de décimales possible (le nombre 3.141592654 serait inchangé) .
  • nfFixed limite les décimales. Le nombre de décimales doit être spécifié dans l'appel à WriteNumber. Exemple : avec 2 décimales, le nombre 3,141592654 devient 3,14.
  • nfFixedTh : similaire à nfFixed, mais ajoute un séparateur de milliers lorsque le nombre est affiché sous forme de chaîne : Le nombre 3,141592654 resterait comme dans l'exemple précédent car il est trop petit pour afficher des séparateurs de milliers. Mais le nombre 314159,2654 deviendrait 314 159,26, pour 2 décimales.
  • nfExp sélectionne la présentation exponentielle, c'est-à-dire qu'elle sépare l'exposant. Le paramètre ADecimals dans WriteNumber détermine le nombre de décimales utilisées. (Le nombre 3,141592654 devient 3,14E+00 en cas de deux décimales).
  • nfPercentage affiche le nombre sous forme de pourcentage. Cela signifie que la valeur est multipliée par 100 et qu'un signe de pourcentage est ajouté. Là encore, précisez dans ADecimals combien de décimales doivent être affichées. (Le nombre 3,141592654 s'affiche comme 314,92%, en cas de 2 décimales).
  • nfFraction présente un nombre sous forme de fraction. Les détails (fraction mixte, nombre maximal de chiffres pour le numérateur ou le dénominateur) peuvent être spécifiés dans la méthode de la feuille de calcul WriteFractionFormat.
  • nfCurrency affiche le nombre avec un symbole monétaire, et il existe des règles spéciales sur la façon d'afficher les valeurs négatives (entre parenthèses, ou signe moins avant ou après le nombre). Les FormatSettings du classeur sont utilisés pour définir le signe de la monnaie et la façon dont les nombres sont affichés (FormatSettings. CurrencyString pour le symbole de la devise, FormatSettings.CurrencyFormat pour les valeurs positives, FormatSettings.NegCurrFormat pour les valeurs négatives). Ces paramètres peuvent être remplacés en les spécifiant dans l'appel à WriteCurrency directement.
  • nfCurrendyRed comme nfCurrency, en plus les valeurs négatives sont affichées en rouge.
  • nfShortDateTime présente la valeur DateTime de la cellule en "format court de date/heure", c'est-à-dire jours + mois à deux chiffres + année à deux chiffres + heures + minutes, pas de secondes. L'ordre des parties de la date est repris du FormatSettings du classeur. Cela s'applique également aux autres formats de date et d'heure.
  • nfShortDate crée une chaîne de date indiquant le jour + le mois à deux chiffres + l'année à deux chiffres.
  • nfShortTime crée une chaîne de temps indiquant les heures + les minutes.
  • nfLongTime, similaire, mais inclut également les secondes.
  • nfShortTimeAM, similaire à nfShortTime, mais utilise le format de temps AM/PM, c'est-à-dire que les heures vont jusqu'à 12, et AM ou PM est ajouté pour spécifier le matin ou le soir/après-midi.
  • nfLongTimeAM, comme nfShortTimeAM, mais inclut les secondes .
  • nfTimeInterval, comme nfLongTime, mais il peut y avoir plus de 24 heures. L'intervalle peut également être exprimé en minutes ou en secondes, si les chaînes de format [n]:ss, ou [s], respectivement, sont utilisées.
  • nfCustom permet de spécifier une chaîne de formatage dédiée.

Comme déjà noté, le classeur possède une propriété FormatSettings qui fournit des informations supplémentaires pour contrôler le formatage résultant. Il s'agit essentiellement d'une copie de l'élément DefaultFormatSettings déclaré dans l'unité sysutils (les éléments LongDateFormat et ShortDateFormat sont légèrement modifiés pour mieux correspondre aux paramètres par défaut des principales applications de tableur). L'objectif principal du FormatSettings est d'ajouter une manière simple de localisation aux formats de nombres.

Chaînes de format des nombres

En plus de ces formats prédéfinis, un formatage plus spécialisé peut être réalisé en utilisant la constante de format nfCustom ainsi qu'une chaîne de format dédiée. La chaîne de format est construite selon la syntaxe Excel qui est proche de la syntaxe des commandes FormatFloat et FormatDateTime (acceptées également, voir l'aide en ligne de ces fonctions).

Voici une liste de base des symboles utilisés :

<tbody>

</tbody>

<tbody></tbody>
Symbol Meaning Format string: Number -- Output string
General Affiche toutes les décimales du nombre 'General':
1.2345678 -- '1.2345678'
0 Affiche des zéros non significatifs si un nombre a moins de chiffres qu'il n'y a de zéros dans le format. S'il est utilisé pour les décimales, le nombre est arrondi à autant de décimales que de 0 sont trouvés. '000': 1 -- '001'
'0.0': 1 -- '1.0'
'0.0': 1.2345678 -- '1.2'
* Comme "0" ci-dessus, mais n'affiche pas les zéros non significatifs. '0.*': 1 -- '1.'
'0.*': 1.2345678 -- '1.2'
? Comme "0" ci-dessus, mais les zéros non significatifs sont remplacés par des caractères d'espacement. Bon pour aligner les points décimaux et les fractions

'??0': 1 -- ' 1'
'0.0??': 1 -- '1.0 '

. Séparateur décimal ; sera remplacé par la valeur utilisée dans le DecimalSeparator du FormatSettings du classeur. '0.00': 8.9 -- '8.90'
, Le séparateur de milliers ; sera remplacé par la valeur utilisée dans le ThousandSeparator du FormatSettings du classeur. Si à la fin d'une séquence de formatage de nombres, la valeur affichée est divisée par 1000. '#,##0.00': 1200 -- '1,200.00'
'0.00,': 1200 -- '1.20'
E+, e+ Affiche un nombre au format exponentiel. Les chiffres utilisés pour l'exposant sont définis par le nombre de zéros ajoutés à ce symbole. Le signe de l'exposant est indiqué pour les exposants positifs et négatifs. '0.00E+00': 1200 -- 1.20E+03
E+, e+ Affiche un nombre au format exponentiel. Les chiffres utilisés pour l'exposant sont définis par le nombre de zéros ajoutés à ce symbole. Le signe de l'exposant n'est indiqué que pour les exposants négatifs. '0.00e-000': 1200 -- 1.20e003
% Affiche le nombre sous forme de "pourcentage", c'est-à-dire que le nombre est multiplié par 100 et un signe % est ajouté. '0.0%': 0.75 -- 75.0%
/ Ce symbole a deux significations : si la cellule représente un "nombre", la barre oblique indique le formatage en tant que fraction, les caractères de remplacement pour le numérateur et le dénominateur doivent suivre. Si la cellule représente une "date/heure" alors la barre oblique indique le séparateur de date qui sera remplacé par le DateSeparator du FormatSettings du classeur. '#/#': 1.5 -- '3/2'
'# #/#': 1.5 -- '1 1/2'
'# #/16': 1.5 -- '1 8/16'
également : voir les exemples de date/heure ci-dessous
: Séparateur entre les heures, les minutes et les secondes d'une valeur de date/heure. Sera remplacé par le TimeSeparator du FormatSettings du classeur. voir les exemples ci-dessous
yyyy Emplacement pour l'année d'une valeur de date/heure. L'année est affichée sous la forme d'un nombre à quatre chiffres. 'yyyy/mm/dd':
Jan 3, 2012 -- '2012-01-03'Dans cet exemple, le DateSeparator est un caractère tiret (-).
yy Emplacement pour l'année d'une valeur de date/heure. L'année est affichée sous la forme d'un nombre à deux chiffres. 'yy/mm/dd':
Jan 3, 2012 -- '2012-01-03'
m Emplacement pour le mois d'une valeur de date/heure. Le mois est affiché comme un nombre sans chiffres supplémentaires.
Veuillez noter que le code m peut également être interprété comme les "minutes" d'une valeur temporelle (voir ci-dessous).
'yyyy/m/dd':
Jan 3, 2012 -- '2012-01-03'
mm Emplacement pour le mois d'une valeur de date/heure. Le mois est indiqué sous la forme d'un nombre à deux chiffres, c'est-à-dire qu'un zéro initial est ajouté pour les mois de janvier à septembre.
Veuillez noter que le code mm peut également être interprété comme les "minutes" d'une valeur temporelle (voir ci-dessous).
'yyyy/mm/dd':
Jan 3, 2012 -- '2012-01-03'
mmm Emplacement pour le mois d'une valeur de date/heure. Le mois est affiché par son nom abrégé. 'yyyy/mmm/dd':
Jan 3, 2012 -- '2012-Jan-03'
mmmm Emplacement pour le mois d'une valeur de date/heure. Le mois est affiché par son nom complet.
'yyyy/mmm/dd':
Jan 3, 2012 -- '2012-January-03'
d Emplacement pour le jour d'une valeur de date/heure à afficher sous forme de nombre. Le jour est affiché sous la forme d'un simple chiffre, sans ajout d'un zéro initial. 'yyyy/mm/d':
Jan 3, 2012 -- '2012-01-03'
dd Emplacement pour le jour d'une valeur de date/heure à afficher sous forme de nombre. dd ajoute un zéro de tête aux numéros de jour à un chiffre. 'yyyy/mm/dd':
Jan 3, 2012 -- '2012-01-03'
ddd Support pour le jour d'une valeur de date/heure. Le jour est affiché sous son nom abrégé. 'dddd, yyyy/mm/ddd':
Jan 03, 2012 -- 'Tue 2012-01-03'
dddd Support pour le jour d'une valeur de date/heure. Le jour est affiché sous son nom complet. 'dddd, yyyy/mmmm/dd':
Jan 03, 2012 -- 'Tuesday 2012-01-03'
h Support de la partie horaire d'une valeur de date/heure. L'heure est affichée sous la forme d'un simple chiffre, sans ajout d'un zéro initial. 'h:mm':
0.25 -- '6:00'
hh Support de la partie horaire d'une valeur de date/heure. L'heure est affichée avec un zéro en tête si l'heure est inférieure à 10. 'hh:mm':
0.25 -- '06:00'
[hh], ou [h] Affiche le temps écoulé de manière à ce que la partie des heures puisse devenir supérieure à 23. '[h]:mm':
1.25 -- '30:00'
m Support de la partie minutes d'une valeur de date/heure. Les minutes sont indiquées sous la forme d'un nombre simple sans ajout d'un zéro initial. Notez que si les codes m sont entourés de symboles de date (y, d), ils sont interprétés comme "mois". 'h:m':
0.25 -- '6:0'
mm Support de la partie minutes d'une valeur de date/heure. Les minutes à un chiffre sont affichées avec un zéro en tête. Notez que si le code mm est entouré de symboles de date (y, d), il est interprété comme "mois". 'h:mm':
0.25 -- '6:00'
[mm], ou [m] Affiche le temps écoulé de telle sorte que la partie minutes peut devenir supérieure à 59 '[mm]:ss':
1.25 -- '1800:00'
s Support de la partie secondes d'une valeur de date/heure. Les secondes sont affichées sous la forme d'un simple nombre, sans ajout de zéro. 'hh:mm:s':
0.25 -- '06:00:0'
ss Support de la partie secondes d'une valeur de date/heure. Les secondes à un chiffre sont affichées avec un zéro en tête. 'hh:mm:ss':
0.25 -- '06:00:00'
[ss], ou [s] Affiche le temps écoulé de telle sorte que la partie secondes peut devenir supérieure à 59 '[ss]':
1.25 -- '108000'
AM/PM, am/pm, A/P, ou a/p Affiche l'heure au format 12 heures. 'hh:mm:ss AM/PM':
0.25 -- '6:00:00 AM'
" Le texte entre guillemets est inséré dans les chaînes formatées de manière littérale. 'yyyy"/"mm"/"dd':
3 janvier 2012 -- '2012/01/03' (c'est-à-dire que le / n'est pas remplacé par le DateSeparator du classeur).
\ Le caractère suivant de la chaîne de format apparaît littéralement dans la chaîne de résultat. Le lui-même n'apparaît pas.

'yyyy/mm/dd':
Jan 3, 2012 -- '2012-01-03'

; Une chaîne de caractères de format peut contenir jusqu'à trois sections séparées par un point-virgule. La première section est utilisée pour les nombres positifs, la deuxième section pour les nombres négatifs, et la troisième section pour les nombres zéro. Si la troisième section est manquante, une valeur nulle est formatée comme indiqué dans la première section. Si la deuxième section est également manquante, toutes les valeurs sont formatées selon la première section. '"#,##0"$"';-#,##0"$";"-"':
1200 -- '1,200$'
-1200 -- '1,200$'
0 -- '-'
(, et ) Parfois utilisé pour les valeurs monétaires afin d'indiquer les nombres négatifs, au lieu du signe moins. '#,##0"$";(#,##0)"$"':
-1200 -- '(1200)$'
[red] La chaîne de caractères formatée est affichée dans la couleur spécifiée. Au lieu de [red],vous pouvez utiliser en conséquence [black], [white], [green], [blue], [magenta], [yellow], or [cyan]. Souvent utilisé pour mettre en évidence des valeurs monétaires négatives. '"$" #,##0.00;[red]("$" #,##0.00)':
-1200 -- '($ 1200.00)'
Une note sur les dates Excel

Il existe une divergence entre la présentation des dates dans FPSpreadsheet et dans Excel : Excel suppose à tort que l'année 1900 était une année bissextile et autorise donc la date du 29 février 1900. FPSpreadsheet fait le calcul de la date correctement. En conséquence, les dates antérieures au 1er mars 1900 sont décalées d'une unité ! Par ailleurs, FPSpreadsheet traite ce problème de la même manière que LibreOffice Calc.

Couleurs

FPSpreadsheet prend en charge les couleurs pour le texte, l'arrière-plan des cellules et les bordures des cellules. Les couleurs de base de l'EGA sont déclarées dans l'unité fpstypes comme des constantes :

<a href="/File:fpsgrid.png view-source:<a class="external free" href="https://wiki.freepascal.org/File:fpsgrid.png">https://wiki.freepascal.org/File:fpsgrid.png</a>" class="image" title="Couleurs prédéfinies"><img alt="Couleurs prédéfinies" src="/images/0/02/fpsgrid.png view-source:<a class="external free" href="https://wiki.freepascal.org/images/0/02/fpsgrid.png">https://wiki.freepascal.org/images/0/02/fpsgrid.png</a>" width="137" height="339" /></a>
<span></span><span class="k">type</span>
  TsColor = DWORD;
  scBlack = $00000000;
  scWhite = $00FFFFFF;
  scRed = $000000FF;
  scGreen = $0000FF00;
  scBlue = $00FF0000;
  scYellow = $0000FFFF;
  scMagenta = $00FF00FF;
  scCyan = $00FFFF00;
  scDarkRed = $00000080;
  scDarkGreen = $00008000;
  scDarkBlue = $00800000;
  scOlive = $00008080;
  scPurple = $00800080;
  scTeal = $00808000;
  scSilver = $00C0C0C0;
  scGray = $00808080;
  scGrey = scGray; // redefine to allow different spelling

  // Identifiant pour une couleur non définie
  scNotDefined = $40000000;

  // Identificateur de la couleur transparente
  scTransparent = $20000000;

Le TsColor représente la valeur rgb d'une couleur, un seul octet étant utilisé pour les composantes rouge, verte et bleu. Le nombre résultant est en notation little endian, c'est-à-dire que la valeur rouge vient en premier en mémoire : $00BBGGRR. (Ceci est directement compatible avec les valeurs de couleur telles que définies dans l'unité graphique).

L'octet de poids fort est généralement égal à zéro, mais il est utilisé en interne pour identifier des valeurs de couleur spéciales, comme pour les couleurs indéfinies ou transparentes.

<a href="/File:fpsgrid.png view-source:<a class="external free" href="https://wiki.freepascal.org/File:fpsgrid.png">https://wiki.freepascal.org/File:fpsgrid.png</a>" class="image"><img alt="Note-icon.png" src="/images/0/02/fpsgrid.png view-source:<a class="external free" href="https://wiki.freepascal.org/images/0/02/fpsgrid.png">https://wiki.freepascal.org/images/0/02/fpsgrid.png</a>" width="24" height="29" /></a>

Note: Dans les anciennes versions de la bibliothèque, les couleurs étaient définies comme des index dans une palette de couleurs. Ceci ne fonctionne plus.

L'unité fpsutils contient quelques fonctions utiles pour la modification des couleurs :

  • function GetColorName(AColor: TsColor): String; renvoie le nom des couleurs définies ci-dessus, ou une chaîne indiquant les composantes rgb pour les autres couleurs.
  • function HighContrastColor(AColor: TsColor): TsColor renvoie scBlack pour une couleur d'entrée "claire", scWhite pour une couleur d'entrée "sombre".
  • function TintedColor(AColor: TsColor; tint: Double): TsColor; éclaircit ou assombrit une couleur en appliquant un facteur tint = -1...+1, où -1 signifie "assombrir à 100%", +1 signifie "éclaircir à 100%", et 0 signifie "aucun changement". La teinte de la couleur est préservée.

Arrière-plan de la cellule

L'arrière-plan des cellules peut être rempli par des motifs prédéfinis qui sont identifiés par l'enregistrement TsFillPattern :

<span></span><span class="k">type</span>
  TsFillPattern = record
    Style : TsFillStyle ; /// modèle de style de remplissage tel que défini ci-dessous.
    FgColor : TsColor ; /// couleur d'arrière-plan du motif de remplissage.
    BgColor : TsColor ; /// couleur du motif de remplissage.
  end;

  TsFillStyle = (fsNoFill, fsSolidFill, fsGray75, fsGray50, fsGray25, fsGray12, fsGray6,
    fsStripeHor, fsStripeVert, fsStripeDiagUp, fsStripeDiagDown,
    fsThinStripeHor, fsThinStripeVert, fsThinStripeDiagUp, fsThinStripeDiagDown,
    fsHatchDiag, fsThinHatchDiag, fsThickHatchDiag, fsThinHatchHor);
  • Utilisez la méthode de feuille de calcul WriteBackground pour affecter un motif de remplissage à une cellule spécifique. Outre l'adresse de la cellule, cette méthode requiert le type du motif de remplissage (TsFillStyle), ainsi que les couleurs d'avant-plan et d'arrière-plan telles que spécifiées par leurs valeurs TsColor.
  • Le motif de remplissage d'une cellule particulière peut être récupéré en appelant la méthode du classeur ReadBackground.
  • La méthode simplifiée WriteBackgroundColor peut être utilisée pour obtenir une couleur d'arrière-plan uniforme.
  • Limitations:
    • Les fichiers OpenDocument ne prennent en charge que les remplissages uniformes. La couleur d'arrière-plan est un mélange des composantes rgb de premier plan et d'arrière-plan dans un rapport défini par le motif de remplissage.
    • Les fichiers BIFF2 ne prennent en charge qu'un motif ombré noir et blanc de 12,5 %.
<span></span><span class="k">type</span>
  TsWorksheet = class
  public
    function WriteBackground(ARow, ACol: Cardinal; AStyle: TsFillStyle; APatternColor, ABackgroundColor: TsColor): PCell; overload;
    procedure WriteBackground(ACell: PCell; AStyle: TsFillStyle; APatternColor, ABackgroundColor: TsColor); overload;

    function WriteBackgroundColor(ARow, ACol: Cardinal; AColor: TsColor): PCell; overload;
    procedure WriteBackgroundColor(ACell: PCell; AColor: TsColor); overload;

    function ReadBackground(ACell: PCell): TsFillPattern;
    function ReadBackgroundColor(ACell: PCell): TsColor; overload;
    <span class="c1">// ...</span>
  end;
  cell: PCell;
  // Exemple 1 : Attribue un motif de fines rayures horizontales jaunes sur l'arrière-plan bleu de la cellule vide A1 (ligne 0, colonne 0).
  MyWorksheet.WriteBackground(0, 0, fsThinStripeHor, scYellow, scBlue);

  // Exemple 2 : Couleur d'arrière-plan gris uniforme de la cellule B1 (ligne 0, colonne 1) contenant le nombre 3,14.
  if MyWorksheet.FindCell('A1') = nil then
  MyWorksheet.WriteBackgroundColor(cell, clSilver);

Bordures des cellules

Les cellules peuvent être mises en valeur en dessinant des lignes de bordure le long de leurs bords ou des lignes diagonales. Il existe quatre bordures plus deux diagonales énumérées dans le type de données TsCellBorder :

<span></span><span class="k">type</span>
  TsCellBorder = (cbNorth, cbWest, cbEast, cbSouth, cbDiagUp, cbDiagDown);
  TsCellBorders = set of TsCellBorder;

Pour afficher une ligne de bordure, ajoutez la bordure correspondante à l'ensemble Borders de la cellule (type TsCellBorders, voir ci-dessus). De cette façon, chaque bord de cellule peut être traité séparément. Utilisez la méthode de la feuille de calcul WriteBorders à cet effet. Cet exemple ajoute des bordures supérieure et inférieure aux bords A1 et B1 :

<span></span>  MyWorksheet.WriteBorders(0, 0, [cbNorth, cbSouth]) ; /// A1 : ligne 0, colonne 0
  MyWorksheet.WriteBorders(0, 0, [cbNorth, cbSouth]) ; /// A1 : ligne 0, colonne 0

Les lignes sont généralement dessinées comme des lignes fines, solides et noires. Mais il est possible de modifier le style de ligne et la couleur de chaque ligne. À cette fin, la cellule fournit un tableau de records TsCellBorderStyle :

<span></span><span class="k">type</span>
  TsLineStyle = (lsThin, lsMedium, lsDashed, lsDotted, lsThick, lsDouble, lsHair,
    lsMediumDash, lsDashDot, lsMediumDashDot, lsDashDotDot, lsMediumDashDotDot, lsSlantDashDot);

  TsCellBorderStyle = record
    LineStyle: TsLineStyle;
    Color: TsColor;
  end;

  TsCellBorderStyles = array[TsCellBorder] of TsCellBorderStyle;

  TsWorksheet = class
  public
    function WriteBorderStyle(ARow, ACol: Cardinal; ABorder: TsCellBorder; AStyle: TsCellBorderStyle): PCell; overload;
    procedure WriteBorderStyle(ACell: PCell; ABorder: TsCellBorder; AStyle: TsCellBorderStyle); overload;

    function WriteBorderStyle(ARow, ACol: Cardinal; ABorder: TsCellBorder; ALineStyle: TsLineStyle; AColor: TsColor): PCell; overload;
    procedure WriteBorderStyle(ACell: PCell; ABorder: TsCellBorder; ALineStyle: TsLineStyle; AColor: TsColor); overload;

    function WriteBorderColor(ARow, ACol: Cardinal; ABorder: TsCellBorder; AColor: TsColor): PCell; overload;
    procedure WriteBorderColor(ACell: PCell; ABorder: TsCellBorder; AColor: TsColor): PCell; overload;

    function WriteBorderLineStyle(ARow, ACol: Cardinal; ABorder: TsCellBorder; ALineStyle: TsLineStyle): PCell; overload;
    procedure WriteBorderLineStyle(ACell: PCell; ABorder: TsCellBorder; ALineStyle: TsLineStyle): PCell; overload;

    function WriteBorderStyles(ARow, ACol: Cardinal; const AStyles: TsCellBorderStyles): PCell; overload;
    procedure WriteBorderStyles(ACell: PCell; const AStyles: TsCellBorderStyles); overload;

    function WriteBorders(ARow, ACol: Cardinal; ABorders: TsCellBorders): PCell; overload
    procedure WriteBorders(ACell: PCell; ABorders: TsCellBorders); overload

    function ReadCellBorders(ACell: PCell): TsCellBorders;
    function ReadCellBorderStyle(ACell: PCell; ABorder: TsCellBorder): TsCellBorderStyle;
    function ReadCellBorderStyles(ACell: PCell): TsCellBorderStyles;
    <span class="o">...</span>
  end;

Le style de la bordure d'une cellule donnée peut être spécifié par les méthodes suivantes fournies par la feuille de calcul :

  • WriteBorderStyleaffecte un record de style de bordure de cellule à une bordure de la cellule. Il existe deux versions surchargées de cette méthode : l'une prend un TsCellBorderStyle entier, l'autre prend les éléments individuels du record.
  • WriteBorderColor change la couleur d'une bordure donnée sans affecter le style de ligne de cette bordure.
  • WriteBorderLineStyle définit le style de ligne de la bordure uniquement, mais laisse la couleur inchangée.
  • WriteBorderStyles définit le style de bordure de toutes les bordures d'une cellule donnée en une seule fois. Utile pour copier les styles de bordure d'une cellule à d'autres cellules.

Cet exemple ajoute une fine bordure noire en haut et une épaisse bordure bleue en bas des cellules A1 et B1 :

<span></span><span class="k">var</span>
  cellA1, cellB1: PCell;
  MyWorksheet.WriteBorders(0, 0, [cbNorth, cbSouth]) ; /// A1 : ligne 0, colonne 0
  MyWorksheet.WriteBorderStyle(cellA1, cbNorth, lsThin, scBlack);
  MyWorksheet.WriteBorderStyle(cellA1, cbSouth, lsThick, scBlue);

  MyWorksheet.WriteBorders(0, 0, [cbNorth, cbSouth]) ; /// A1 : ligne 0, colonne 0
  MyWorksheet.WriteBorderStyles(cellB1, cellA1^.BorderStyles); // copier tous les styles de bordure de la cellule A1 à B1
<a href="/File:fpsgrid.png view-source:<a class="external free" href="https://wiki.freepascal.org/File:fpsgrid.png">https://wiki.freepascal.org/File:fpsgrid.png</a>" class="image"><img alt="Note-icon.png" src="/images/0/02/fpsgrid.png view-source:<a class="external free" href="https://wiki.freepascal.org/images/0/02/fpsgrid.png">https://wiki.freepascal.org/images/0/02/fpsgrid.png</a>" width="24" height="29" /></a>

Note: Les lignes diagonales ne sont pas supportées par sfExcel2 et sfExcel5 - elles sont simplement omises. sfExcel8 et sfOOXML utilisent le même style de ligne et la même couleur pour les deux diagonales ; lors de l'écriture, le style de bordure de la ligne en diagonale haute est supposé être également valable pour la ligne en diagonale basse. Certains auteurs ne prennent pas en charge tous les styles de ligne de l'énumération TsLineStyle. Dans ce cas, les styles de ligne de remplacement appropriés sont utilisés.

Polices de caractères

Le texte de la cellule peut s'afficher dans différentes polices. À cette fin, le classeur fournit une liste d'éléments TsFont :

<span></span><span class="k">type</span>
  TsFont = class
    FontName: String;
    Size: Single;
    Style: TsFontStyles;
    Color: TsColor;
    Position: TsFontPosition;
  end;
  • Le FontName correspond au nom de la police tel qu'il est utilisé par le système opérationnel. Dans Windows, un exemple serait "Times New Roman".
  • La FontSize est donnée en "points", c'est-à-dire en unités 1/72 de pouce qui sont couramment utilisées dans les applications Office.
  • Le FontStyle est un ensemble des éléments fssBold, fssItalic, fssStrikeout, et fssUnderline qui forment le type énumération TsFontStyle. La police "normale" correspond à un ensemble vide.
  • Le Color détermine la couleur d'avant-plan des caractères du texte donnée en présentation rgb comme indiqué ci-dessus.
  • La Position est soit fpNormal, fpSuperscript, ou fpSubscript et indique si la taille de la police doit être diminuée d'environ 1/3 et si les caractères doivent être déplacés vers le haut (superscript) ou vers le bas (subscript).

Chaque cellule est dotée d'un index dans la liste des polices.

Pour attribuer une police particulière à une cellule, utilisez l'une des méthodes suivantes de TsSpreadsheet :

<span></span><span class="k">type</span>
  TsSpreadsheet = class
  public
    function WriteFont(ARow, ACol: Cardinal; const AFontName: String;
      AFontSize: Single; AFontStyle: TsFontStyles; AFontColor: TsColor): Integer; overload;
    procedure WriteFont(ARow, ACol: Cardinal; AFontIndex: Integer); overload;
    function WriteFontColor(ARow, ACol: Cardinal; AFontColor: TsColor): Integer;
    function WriteFontSize(ARow, ACol: Cardinal; ASize: Integer): Integer;
    function WriteFontStyle(ARow, ACol: Cardinal; AStyle: TsFontStyles): Integer;
    // plus : versions surchargées acceptant un pointeur vers un enregistrement de cellule au lieu de l'index de ligne et de colonne comme paramètre.
    <span class="c1">// ...</span>
  end;
  • WriteFont attribue une police à la cellule. Si la police n'existe pas encore dans la liste des polices, une nouvelle entrée est créée. La fonction renvoie l'index de la police dans la liste des polices. En outre, il existe une version surchargée qui ne prend que l'indice de la police comme paramètre.
  • WriteFontColor remplace la couleur de la police actuellement affectée à la cellule par une nouvelle. Là encore, un nouvel élément de liste de polices est créé si la police avec la nouvelle couleur n'existe pas encore. La fonction renvoie l'index de la police dans la liste.
  • WriteFontSize remplace la taille de la police actuellement utilisée de la cellule.
  • WriteFontStyle remplace le style (normal, gras, italique, etc.) de la police de cellule actuellement utilisée.

La liste des polices du classeur contient au moins un élément qui est la police par défaut pour les cellules dont les polices ne sont pas modifiées. Par défaut, il s'agit de la police "Arial" de 10 points. Utilisez la méthode du classeur SetDefaultFont pour affecter une police différente au premier élément de la liste.

La police à un indice donné de la liste des polices peut être recherchée en appelant la fonction du classeur GetFont. Le compte des polices disponibles est renvoyé par GetFontCount.

Voici un exemple qui diminue la taille de toutes les polices "Arial" de 10 points à 9 points :

<span></span><span class="k">var</span>
  i: Integer;
  font: TsFont;
  for i := 0 to MyWorkbook.GetFontCount-1 do
  begin
    font := MyWorkbook.GetFont(i);
    if (font.FontName = 'Arial') and (font.Size = 10.0) then
      font: TsFont;
  end;

Mise en forme de texte enrichi

Outre l'utilisation d'une police spécifique pour chaque cellule, il est également possible de spécifier des attributs de police particuliers pour des caractères individuels ou des groupes de caractères dans le texte de chaque cellule. Suivant la notation Excel, nous appelons cette fonction Formatage en Rich-text (bien qu'elle n'ait rien à voir avec le format de fichier "Rich-text").

For this purpose, unit fpstypes declares the type TsRichTextParams which is an array of TsRichTextParam records:

<span></span><span class="k">type</span>
  TsRichTextParam = record
    FontIndex: Integer;
    FirstIndex: Integer;
  end;

  TsRichTextParams = array of TsRichTextParam;

FontIndex fait référence à l'index de la police dans la FontList du classeur à utiliser pour le formatage des caractères commençant à l'index FirstIndex. Étant un indice de caractères de chaîne, le FirstIndex est basé sur 1.

Il existe deux façons d'ajouter un formatage "Rich-text" au texte d'une cellule :

  • Intégrer les codes de format HTML correspondants dans le texte de la cellule. Cela peut être fait en utilisant la méthode WriteTextAsHTML de la feuille de calcul. Pour ajouter le texte "Aire (m2)" à la cellule A1, passez la chaîne codée HTML suivante à cette fonction.
<span></span>  MyWorksheet.WriteTextAsHTML(0, 0, 'Area (m<sup>2</sup>');
  • Alternativement, la méthode standard d'écriture de texte, WriteText peut être appelée avec un paramètre supplémentaire spécifiant les paramètres de formatage du Rich-text à utiliser directement:.
<span></span><span class="k">var</span>
  richTextParams: TsRichTextParams;
  fnt: TsFont;
  cell: PCell;
  SetLength(rtp, 2);
  if MyWorksheet.FindCell('A1') = nil then
  fnt := MyWorksheet.ReadCellFont(cell);
  richTextParams[0].FirstIndex := 8 ; // Les groupes en exposant commencent par "2", qui est le caractère n° 8 (basé sur 1) du texte de la cellule.
  <span class="n">richTextParams</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span><span class="o">.</span><span class="n">FontIndex</span> <span class="o">:=</span> <span class="n">MyWorkbook</span><span class="o">.</span><span class="n">AddFont</span><span class="p">(</span><span class="n">fnt</span><span class="o">.</span><span class="n">FontName</span><span class="o">,</span> <span class="n">fnt</span><span class="o">.</span><span class="n">Size</span><span class="o">,</span> <span class="n">fnt</span><span class="o">.</span><span class="n">Style</span><span class="o">,</span> <span class="n">fnt</span><span class="o">.</span><span class="n">Color</span><span class="o">,</span> <span class="n">fpSuperscript</span><span class="p">)</span><span class="o">;</span>
  richTextParams[1].FirstIndex := 9 ; // La police normale recommence à partir du caractère n° 9.
  richTextParams[1].FontIndex := MyWorksheet.ReadCellFontIndex(0, 0);
  MyWorksheet.WriteUTF8Text(cell, 'Area (m2)', richTextParams);

Utilisez la méthode de feuille de calcul DeleteRichTextParams pour supprimer le formatage du Rich-text d'une cellule précédemment formatée.

<a href="/File:fpsgrid.png view-source:<a class="external free" href="https://wiki.freepascal.org/File:fpsgrid.png">https://wiki.freepascal.org/File:fpsgrid.png</a>" class="image"><img alt="Note-icon.png" src="/images/0/02/fpsgrid.png view-source:<a class="external free" href="https://wiki.freepascal.org/images/0/02/fpsgrid.png">https://wiki.freepascal.org/images/0/02/fpsgrid.png</a>" width="24" height="29" /></a>

Note: Si la cellule est censée avoir une police différente de la police par défaut de la feuille de calcul, alors cette police doit être écrite dans la cellule avant d'écrire le texte formaté en Rich-text. Sinon, la police dans les régions non formatées ne sera pas à jour.

Rotation de texte

En général, le texte s'affiche horizontalement dans les cellules. Toutefois, il est également possible de le faire pivoter de 90 degrés dans le sens des aiguilles d'une montre ou dans le sens inverse. En outre, il est également possible d'empiler des caractères horizontaux verticalement les uns au-dessus des autres.

Si vous avez besoin de cette fonctionnalité, utilisez la méthode de feuille de calcul WriteTextRotation et spécifiez la direction du texte par un élément du type énumération TsTextRotation :

<span></span><span class="k">type</span>
  TsTextRotation = (trHorizontal, rt90DegreeClockwiseRotation,
    rt90DegreeCounterClockwiseRotation, rtStacked);

  TsWorksheet = class
  public
    function WriteTextRotation(ARow, ACol: Cardinal; ARotation: TsTextRotation): PCell; overload;
    procedure WriteTextRotation(ACell: PCell; ARotation: TsTextRotation); overload;

    function ReadTextRotation(ACell: PCell): TsTextRotation;
    <span class="c1">// ...</span>
  end;

  // exemple de texte tourné dans le sens inverse des aiguilles d'une montre dans la cellule A1 :
  WriteTextRotation(0, 0, rt90DegreeCounterClockwiseRotation);
<a href="/File:fpsgrid.png view-source:<a class="external free" href="https://wiki.freepascal.org/File:fpsgrid.png">https://wiki.freepascal.org/File:fpsgrid.png</a>" class="image"><img alt="Warning-icon.png" src="/images/0/02/fpsgrid.png view-source:<a class="external free" href="https://wiki.freepascal.org/images/0/02/fpsgrid.png">https://wiki.freepascal.org/images/0/02/fpsgrid.png</a>" width="24" height="24" /></a>

Avertissement: Les degrés de rotation plus fins qui peuvent être pris en charge par certains formats de fichiers de tableur sont ignorés.

Alignement du texte

Par défaut, les textes des cellules sont alignés sur les bords gauche et inférieur de la cellule, sauf pour les nombres qui sont alignés à droite. Ce comportement peut être modifié en utilisant les méthodes de feuille de calcul WriteHorAlignment et WriteVertAlignment :

<span></span><span class="k">type</span>
  TsHorAlignment = (haDefault, haLeft, haCenter, haRight);
  TsVertAlignment = (vaDefault, vaTop, vaCenter, vaBottom);

  TsWorkbook = class
  public
    function WriteHorAlignment(ARow, ACol: Cardinal; AValue: TsHorAlignment): PCell; overload;
    procedure WriteHorAlignment(ACell: PCell; AValue: TsHorAlignment); overload;
    function ReadHorAlignment(ACell: PCell): TsHorAlignment;

    function WriteVertAlignment(ARow, ACol: Cardinal; AValue: TsVertAlignment): PCell; overload;
    procedure WriteVertAlignment(ACell: PCell; AValue: TsVertAlignment); overload;
    function ReadVertAlignment(ACell: PCell): TsVertAlignment;
    <span class="c1">// ...</span>
  end;

  // Exemple : Centrer le texte de la cellule A1 à la fois horizontalement et verticalement.
  MyWorkbook.WriteHorAlignment(0, 0, haCenter);
  MyWorkbook.WriteHorAlignment(0, 0, haCenter);

Retour à la ligne

Le texte qui est plus long que la largeur d'une cellule peut s'étendre sur plusieurs lignes en appelant la méthode WriteWordwrap du tableur :

<span></span><span class="k">type</span>
  TsWorksheet = class
  public
    function WriteWordwrap(ARow, ACol: Cardinal; AValue: Boolean): PCell; overload;
    procedure WriteWordwrap(ACell: PCell; AValue: Boolean); overload;
    function ReadWordwrap(ACell: PCell): Boolean;
    <span class="c1">//...</span>
  end;

  // Exemple : activer le retour à la ligne dans la cellule A1
  MyWorksheet.WriteFormula(0, 1, '=ROUND(A1+B2+1.215,0)');

Fusion de cellules

Comme les applications Office, FPSpreadsheet prend également en charge la fonction de fusion des cellules en une seule grande cellule qui est souvent utilisée comme en-tête commun au-dessus de colonnes simlaires. Il suffit d'appeler MergeCells et de passer un paramètre pour spécifier la plage de cellules à fusionner, soit une chaîne de plage Excel (comme A1:D5), soit les première et dernière lignes et colonnes :

<span></span>  MyWorksheet: TsWorksheet;
  // ou : MyWorksheet.MergeCells(0, 0, 4, 3) ; /// première ligne, première colonne, dernière ligne, dernière colonne

Le contenu et le format affichés pour une plage fusionnée sont pris dans le coin supérieur gauche de la plage, cellule A1 dans l'exemple ci-dessus. Cette cellule est appelée la MergeBase dans la bibliothèque. À l'exception de cette cellule d'angle, il ne doit pas y avoir d'autres cellules dans la plage. S'il y en a, leur contenu et leur format seront cachés.

Pour décomposer à nouveau une plage fusionnée en cellules individuelles, utilisez la commande Unmerge et passez toute cellule qui se trouve dans la plage fusionnée :

<span></span>  MyWorksheet: TsWorksheet;
  // ou : MyWorksheet.UnmergeCells(0, 1) ; /// ligne, colonne de n'importe quelle cellule de la plage.

Les cellules fusionnées peuvent être lues/écrites dans tous les formats de fichiers, à l'exception de sfCSV, sfExcel2 et sfExcel5 qui ne supportent pas cette fonctionnalité de manière native.

L'information selon laquelle les cellules sont fusionnées est stockée dans une liste interne. Contrairement aux versions précédentes, il n'est plus possible d'accéder directement à la MergeBase depuis la cellule. Utilisez les fonctions suivantes pour extraire des informations sur les cellules fusionnées :

<span></span><span class="k">var</span>
  cell, base: PCell;
  r1,c1,r2,c2: Cardinal;
  if MyWorksheet.FindCell('A1') = nil then
  fnt := MyWorksheet.ReadCellFont(cell);
  begin
    WriteLn('Cell B1 is merged.');

    fnt := MyWorksheet.ReadCellFont(cell);
    WriteLn('The merged range is ' + GetCellRangeString(r1, c1, r2, c2));

    fnt := MyWorksheet.ReadCellFont(cell);
    WriteLn('The merge base is cell ' + GetCellString(base^.Row, base^.Col));
  end;

Protection des cellules

Ceci est décrit dans une section distincte ci-dessous.

Données supplémentaires

Commentaires des cellules

Les commentaires peuvent être attachés à n'importe quelle cellule en appelant

<span></span>  MyWorksheet.WriteComment(0, 0, 'This is a comment for cell A1');

Ils sont stockés dans une liste interne de la feuille de calcul. Utilisez les méthodes des feuilles de calcul correspondantes pour accéder aux commentaires :

  • Si vous voulez savoir si une cellule particulière contient un commentaire, appelez la méthode de feuille de calcul HasComment(cell).
  • Pour récupérer un commentaire de cellule, utilisez la méthode ReadComment(cell), ou son compagnon surchargé ReadComment(ARow, ACol).
  • Le nombre total de commentaires peut être récupéré à partir de worksheet.Comments.Count..

Hyperliens

Des hyperliens peuvent être attachés aux cellules afin de les relier à d'autres documents ou à d'autres cellules du même classeur. La syntaxe générale pour créer des hyperliens est la suivante

<span></span>  procedure TWorksheet.WriteHyperlink(ARow, ACol: Cardinal; ATarget: String; ATooltip: String = '');
  • La cible de l'hyperlien, passée en paramètre ATarget, doit être un URI (Uniform resource identifier) entièrement qualifié composé d'une phrase de protocole (par exemple, http://, file:///, mailto:, etc.) suivie d'informations spécifiques telles que l'URL du web, le nom du fichier ou l'adresse électronique et une identification facultative du signet séparée par le caractère '#'. Traduit avec www.DeepL.com/Translator (version gratuite) Une exception est constituée par les hyperliens internes qui permettent de sauter à une cellule du classeur actuel ; ils sont constitués du nom de la feuille de calcul facultatif et de l'adresse de la cellule, séparés par le caractère '!'.
  • Le paramètre optionnel Tooltip est évalué par Excel pour l'afficher dans une fenêtre d'aide si la souris se trouve au-dessus du lien hypertexte.
<a href="/File:fpsgrid.png view-source:<a class="external free" href="https://wiki.freepascal.org/File:fpsgrid.png">https://wiki.freepascal.org/File:fpsgrid.png</a>" class="image"><img alt="Note-icon.png" src="/images/0/02/fpsgrid.png view-source:<a class="external free" href="https://wiki.freepascal.org/images/0/02/fpsgrid.png">https://wiki.freepascal.org/images/0/02/fpsgrid.png</a>" width="24" height="29" /></a>

Note: Les hyperliens peuvent être ajoutés à des cellules vides ou à des cellules avec du contenu. Dans ce dernier cas, le contenu affiché n'est pas modifié par le lien hypertexte ; dans le premier cas, la cellule est convertie en cellule d'étiquette affichant la cible du lien hypertexte. Sachez qu'OpenOffice/LibreOffice n'accepte que les hyperliens avec des cellules non textuelles.

Exemples:

<span></span>  // Ouvrir le site web www.google.com
  MyWorksheet.WriteText(0, 0, 'Open google');
  MyWorksheet.WriteHyperlink(0, 0, 'http://www.google.com');

  // Ouvrez le fichier local avec le chemin absolu "C:\readme.txt" (avec Windows).
  MyWorksheet.WriteHyperlink(1, 0, 'file:///c:\readme.txt');

  // Ouvrir le client de messagerie pour envoyer un courrier
  MyWorksheet.WriteText('Send mail');
  MyWorksheet.WriteHyperlink(3, 0, 'mailto:somebody@gmail.com?subject=Test');

  // Sauter à une cellule particulière
  MyWorksheet.WriteText(5, 0, 'Jump to cell A10 on sheet2');
  MyWorksheet.WriteHyperlink(0, 0, 'http://www.google.com');

  // Sauter à la cellule A10 de la feuille courante et afficher une info-bulle.
  MyWorksheet.WriteHyperlink(5, 0, '#A10', 'Go to cell A10');
<a href="/File:fpsgrid.png view-source:<a class="external free" href="https://wiki.freepascal.org/File:fpsgrid.png">https://wiki.freepascal.org/File:fpsgrid.png</a>" class="image"><img alt="Note-icon.png" src="/images/0/02/fpsgrid.png view-source:<a class="external free" href="https://wiki.freepascal.org/images/0/02/fpsgrid.png">https://wiki.freepascal.org/images/0/02/fpsgrid.png</a>" width="24" height="29" /></a>

Note: FPSpreadsheet ne "suit" pas les liens, il fournit seulement un mécanisme permettant d'accéder aux données des liens. TsWorksheetGrid du package laz_fpspreadsheet_visual, cependant, déclenche l'événement OnClickHyperlink si une cellule avec un hyperlien externe est cliquée pendant des fractions de seconde. Dans le gestionnaire d'événement correspondant, vous pouvez, par exemple, charger une feuille de calcul cible ou ouvrir un navigateur Web pour afficher le site Web lié. Si le lien est un lien interne vers une autre cellule du même classeur, la grille saute à la cellule concernée.

Images

FPSpreadsheet prend en charge l'intégration d'images dans les feuilles de calcul. Utilisez une des méthodes de la feuille de calcul WriteImage() pour ajouter une image à la feuille de calcul :

<span></span>  MyWorksheet.WriteImage(row, col, filename, offsetX, offsetY, scaleX, scaleY);
  MyWorksheet.WriteImage(row, col, filename, offsetX, offsetY, scaleX, scaleY);
  MyWorksheet.WriteImage(row, col, filename, offsetX, offsetY, scaleX, scaleY);

Le coin supérieur/gauche de l'image est placé au coin supérieur/gauche de la cellule dans la ligne et la colonne spécifiées. Les paramètres à virgule flottante offsetX, offsetY, scaleX et scaleY sont facultatifs : ils définissent un décalage de ce point d'ancrage de l'image par rapport au coin de la cellule et un facteur d'agrandissement. Le chemin du fichier image est donné comme paramètre filename. Il est également possible d'utiliser des versions surchargées qui acceptent un flux à la place du nom de fichier ou un index d'image dans la liste EmbeddedObj du classeur - utilisez MyWorkbook.FindEmbeddedObj(filename) pour obtenir cet index pour un fichier image précédemment chargé.

Notez que FPSpreadsheet doit connaître le type d'image pour réussir l'importation d'une image. Actuellement, les types png, jpg, tiff, bmp, gif, svg, wmf, emf, et pcx sont prises en charge (Excel2007 ne peut pas lire les images svg et pcx importées). D'autres formats peuvent être enregistrés en écrivant une fonction qui détermine la taille de l'image et la densité des pixels, et en enregistrant le nouveau format à l'aide de la procédure RegisterImageType - voir l'unité fpsImages pour des exemples :

<span></span><span class="k">type</span>
  TsImageType = integer;
  TGetImageSizeFunc = function (AStream: TStream; out AWidth, AHeight: DWord; out dpiX, dpiY: Double): Boolean;

En raison des différences de calcul de la hauteur des lignes et de la largeur des colonnes entre FPSpreadsheet et les applications Office, il n'est pas possible de positionner correctement les images. Si la position exacte des images est importante, vous devez suivre ces règles :

  • Prédéfinir les largeurs de toutes les colonnes au moins jusqu'à celles qui contiennent le bord droit de l'image.
  • Prédéfinir les hauteurs de toutes les lignes au moins jusqu'à celles contenant le bord inférieur de l'image.
  • Si le classeur doit être enregistré au format OpenDocument, ajoutez l'image après avoir modifié la largeur des colonnes et la hauteur des lignes, car ods ancre l'image dans la feuille et non dans la cellule (comme Excel et FPSpreadsheet).
  • Si la taille exacte de l'image est importante, veillez à ce qu'elle tienne dans une seule cellule.

Tri

Les cellules d'une feuille de calcul peuvent être triées selon divers critères en appelant la méthode Sort de la feuille de calcul. Cette méthode prend un record TsSortParams et les bords du rectangle de cellules à trier comme paramètres ; dans une version surchargée, le rectangle de cellules peut également être spécifié au moyen d'une chaîne de plage de type Excel (par exemple 'A1:G10') :

<span></span><span class="k">type</span>
  TsWorksheet = class
    <span class="c1">// ...</span>
    procedure Sort(const ASortParams: TsSortParams;
      ARowFrom, AColFrom, ARowTo, AColTo: Cardinal); overload;
    procedure Sort(ASortParams: TsSortParams; ARange: String); overload;
    <span class="c1">// ...</span>
  end;

Les critères de tri sont définis par un record de type TsSortParams :

<span></span><span class="k">type</span>
  TsSortParams = record
    SortByCols: Boolean;
    Priority : TsSortPriority ; // spNumAlpha ("d'abord les nombres"), ou spAlphaNum ("d'abord le texte").
    Keys: TsSortKeys;
  end;

  TsSortKey = record
    ColRowIndex: Integer;
    Options: TsSortOptions; // set of [spDescending, spCaseInsensitive]
  end;
  • La valeur booléenne SortByCols détermine si le tri se fait selon les colonnes (true) ou les lignes (false). Le ColRowIndex spécifié dans les clés de tri, en conséquence, correspond à un indice de colonne ou de ligne, respectivement (voir ci-dessous).
  • Priorité détermine dans les plages de cellules à contenu mixte si un tri ascendant place les valeurs numériques devant les valeurs textuelles ou non. Les cellules vides sont toujours déplacées à la fin de la colonne ou de la ligne triée. Dans Excel, la priorité est "les chiffres d'abord" (spNumAlpha).
  • Le tableau Keys spécifie plusieurs paramètres de tri. Ils se composent de l'indice de la colonne ou de la ligne à trier (ColRowIndex) et d'un ensemble de Options. pour la direction du tri (spoDescending) et la casse des caractères (spCaseInsensitive). Si Options est vide, la comparaison des cellules est sensible à la casse et les cellules sont classées par ordre croissant. Si deux cellules se révèlent "égales" sur la base de la première clé (sortParams.Keys[0]), la comparaison se poursuit avec les conditions suivantes dans le tableau Keys jusqu'à ce qu'une différence soit trouvée ou que toutes les conditions soient épuisées.

InitSortParams est un utilitaire pratique pour initialiser les paramètres de tri :

<span></span>function InitSortParams(ASortByCols: Boolean = true; ANumSortKeys: Integer = 1;
  ASortPriority: TsSortPriority = spNumAlpha): TsSortParams;

Le fragment de code suivant montre un appel de tri typique :

<span></span><span class="k">var</span>
  sortParams: TsSortParams;
  sortParams := InitSortParams(true, 2); // sorting along columns, 2 sorting keys

  // clé de tri primaire : colonne 3, ascendante, insensible à la casse
  sortParams.Keys[0].ColRowIndex := 3;
  sortParams.Keys[0].Options := [ssoCaseInsensitive];

  // clé de tri secondaire : colum 1, descendant
  sortParams.Keys[0].ColRowIndex := 3;
  sortParams.Keys[0].Options := [ssoCaseInsensitive];

  // Le bloc trié s'étend entre les cellules A1 (row=0, col=0) et F10 (row=9, col=5)
  MyWorksheet.Sort(sortParams, 0, 0, 9, 5);
  // ou: MyWorksheet.Sort(sortParams, 'A1:F10');


Rechercher et remplacer

L'unité fpsSearch met en œuvre un moteur de recherche qui peut être utilisé pour rechercher un contenu de cellule spécifique dans un classeur, ou pour remplacer le contenu de cellule trouvé par une autre chaîne.

Exemple:

<span></span>uses
  fpsTypes, fpSpreadsheet, fpsUtils, fpsSearch, fpsAllFormats;
  <span class="n">MyWorkbook</span><span class="o">:</span> <span class="n">TsWorkbook</span><span class="o">;</span>
  foundWorksheet: TsWorksheet;
  foundRow, foundCol: Cardinal;
  MySearchParams: TsSearchParams;
  <span class="o">MyWorkbook</span> <span class="n">:=</span> <span class="o">TsWorkbook</span><span class="n">.</span><span class="o">Create</span><span class="k">;</span>
  try
    procedure ReadFromFile(AFileName: string) ;

    // Spécifier les critères de recherche
    MySearchParams.SearchText := 'Hallo';
    sortParams.Keys[0].Options := [ssoCaseInsensitive];
    MySearchParams.SearchText := 'Hallo';

    // ou: MySearchParaams := InitSearchParams('Hallo', [soEntireDocument], swWorkbook);

    // Créer un moteur de recherche et exécuter la recherche
    with TsSearchEngine.Create(MyWorkbook) do begin
      if FindFirst(MySearchParams, foundWorksheet, foundRow, foundCol) then begin
        WriteLn('First "', MySearchparams.SearchText, '" found in cell ', GetCellString(foundRow, foundCol), ' of worksheet ', foundWorksheet.Name);
        while FindNext(MySeachParams, foundWorksheet, foundRow, foundCol) do
          WriteLn('First "', MySearchparams.SearchText, '" found in cell ', GetCellString(foundRow, foundCol), ' of worksheet ', foundWorksheet.Name);
      end;
      Free;
    end;
  finally
    Free;
  end;

Le moteur de recherche fournit deux méthodes de recherche : FindFirst et FindNext. Ils sont très similaires, ils ne diffèrent que par le point de départ de la recherche. En cas de FindFirst, la cellule de départ est déterminée à partir des Options décrites ci-dessous. Dans le cas de FindNext la recherche commence à la cellule adjacente à la cellule précédemment trouvée. Les deux méthodes renvoient la feuille de calcul et les indices de ligne et de colonne de la cellule dans laquelle se trouve le texte recherché. Si la recherche n'aboutit pas, le résultat de la fonction est FALSE, et la FoundWorksheet est nulle. Il est clair que la feuille de travail trouvée ne peut pas être utilisée pour autre chose pendant que la recherche est en cours.

Le record TsSearchParams spécifie les critères utilisés pour la recherche : .

<span></span><span class="k">type</span>
  TsSearchParams = record
    SearchText: String;
    Options: TsSearchOptions;
    Within: TsSearchWithin;
  end;

En plus du texte à rechercher (SearchText), il fournit un ensemble d'options pour affiner la recherche :

  • soCompareEntireCell : Compare le SearchText avec le contenu entier de la cellule. S'il n'est pas contenu dans l'Options alors le texte de la cellule n'est comparé que partiellement.
  • soMatchCase : Effectuer une recherche sensible à la casse .
  • soRegularExpr : Le SearchText est considéré comme une expression régulière .
  • soAlongRows : Le moteur de recherche procède d'abord le long des lignes. Si elle n'est pas contenue dans l'Options alors la recherche se poursuit le long des colonnes.
  • soBackward : La recherche commence à la fin du document, ou s'effectue en arrière à partir de la cellule active. Si elle n'est pas contenue dans le Options alors la recherche commence au début du document, ou avance à partir de la cellule active.
  • soWrapDocument : Si une recherche a atteint la fin du document, la recherche est reprise à son début (ou vice versa, si soBackward est utilisé).
  • soEntireDocument : la recherche commence à la première cellule (ou à la dernière cellule si soBackward est utilisé). Si elle n'est pas contenue dans les Options alors la recherche commence à la cellule active de la feuille de calcul. Ignoré par FindNext.

Le champ record Within identifie la partie de la feuille de calcul à rechercher :

  • swWorkbook : La recherche porte sur l'ensemble du classeur. Si l'expression recherchée n'est pas trouvée sur la première feuille de calcul (ou la dernière feuille de calcul si soBackward est utilisé), la recherche continue avec la feuille suivante (précédente).
  • swWorksheet : La recherche est limitée à la feuille de calcul actuellement active .
  • swColumn : La recherche est limitée à la colonne de la cellule active .
  • swRow : La recherche est limitée à la ligne de la cellule active.

L'enregistrement des paramètres de recherche peut être initialisé en appelant InitSearchParams (dans l'unité fpsutils) avec les éléments du record comme paramètres facultatifs. Utilisez les méthodes Workbook.ActiveWorksheet et Worksheet.SelectCell(ARow, ACol) pour définir respectivement la feuille de travail active et la position de la cellule active, si la recherche le nécessite.

En plus de la recherche, le moteur de recherche peut également être utilisé pour remplacer le texte trouvé par une autre chaîne de caractères. Appelez les fonctions ReplaceFirst ou ReplaceNext à cette fin. Ils agissent comme leurs FindXXXX homologues, ils nécessitent donc un TsSearchParams record pour spécifier les critères de recherche. Mais en plus de la recherche, ces fonctions effectuent également le remplacement du texte selon la spécification dans un TsReplaceParams record :

<span></span><span class="k">type</span>
  TsReplaceParams = record
    ReplaceText: String;
    Options: TsReplaceOptions;
  end;

Le ReplaceText identifie la chaîne qui remplacera le motif de texte trouvé. Les Options est un ensemble de critères qui définissent comment le remplacement est effectué :

  • roReplaceEntirecell : Remplace le texte entier de la cellule par le ReplaceText. Si elle n'est pas contenue dans les Options, seule la partie correspondant au SearchText est remplacée.
  • roReplaceAll : Effectue le remplacement dans toutes les cellules trouvées (c'est-à-dire qu'il suffit d'appeler ReplaceFirst pour tout remplacer automatiquement).
  • roConfirm : Appelle un gestionnaire d'événement pour l'événement OnConfirmReplacement dans lequel l'utilisateur doit préciser si le remplacement doit être effectué ou non. Notez que ce gestionnaire d'événement est obligatoire si roConfirm est défini.

Utilisez la fonction InitReplaceParams (dans l'unité fpsutils) pour initialiser le record des paramètres de remplacement avec les valeurs fournies (mais facultatives).

Opérations sur les colonnes et les lignes

La feuille de calcul fournit ces méthodes pour insérer, supprimer, masquer ou démasquer des colonnes et des lignes :

<span></span><span class="k">type</span>
  TsWorksheet = class
  <span class="o">...</span>
    procedure DeleteCol(ACol: Cardinal);
    procedure DeleteRow(ARow: Cardinal);

    procedure InsertCol(ACol: Cardinal);
    procedure InsertRow(ARow: Cardinal);

    procedure RemoveCol(ACol: Cardinal);
    procedure RemoveRow(ARow: Cardinal);

    procedure RemoveAllCols;
    procedure RemoveAllRows

    procedure HideCol(ACol: Cardinal);
    procedure HideRow(ARow: Cardinal);

    procedure ShowCol(ACol: Cardinal);
    procedure ShowRow(ARow: Cardinal);

    function ColHidden(ACol: Cardinal): Boolean;
    function RowHidden(ARow: Cardinal): Boolean;
  • Lorsqu'une colonne ou une ligne est supprimée par DeleteCol ou DeleteRow, toute donnée affectée à cette colonne ou ligne est supprimée, c'est-à-dire les cellules, les commentaires, les hyperliens, les enregistrements TCol ou TRow. Les données situées à droite ou en dessous de la colonne/ligne supprimée se déplacent vers la gauche ou vers le haut.
  • RemoveCol et RemoveRow, en contrat, remove uniquement le record de colonne ou de ligne, c'est-à-dire réinitialise la largeur de la colonne et la hauteur de la ligne à leurs valeurs par défaut. Les données des cellules, des commentaires et des hyperliens ne sont pas affectées.
  • RemoveAllCols Elimine tousles records de colonnes, c'est-à-dire réinitialise toutes les largeurs de colonnes ; RemoveAllRows fait de même avec les records de lignes et les hauteurs de lignes.
  • Une colonne ou une ligne est insérée avant l'indice spécifié en paramètre de la méthode InsertXXX.

Mise en page

General

Pour l'instant, FPSpreadsheet ne prend pas en charge l'impression des feuilles de calcul, mais les applications Office le font, et elles fournissent une section d'information dans leurs fichiers à cet effet. Dans FPSpreadsheets, ces informations sont disponibles dans la classe TsPageLayout qui appartient à la structure de données TsWorksheet. Ses propriétés et méthodes combinent les caractéristiques les plus importantes des mondes Excel et OpenDocument.

<span></span><span class="k">type</span>
  TsPageOrientation = (spoPortrait, spoLandscape);

  TsPrintOption = (poPrintGridLines, poPrintHeaders, poPrintPagesByRows,
    poMonochrome, poDraftQuality, poPrintCellComments, poDefaultOrientation,
    poUseStartPageNumber, poCommentsAtEnd, poHorCentered, poVertCentered,
    poDifferentOddEven, poDifferentFirst, poFitPages);

  TsPrintOptions = set of TsPrintOption;

  TsHeaderFooterSectionIndex = (hfsLeft, hfsCenter, hfsRight);

  TsCellRange = record
    Row1, Col1, Row2, Col2: Cardinal;
  end;

  TsPageLayout = class
  <span class="o">...</span>
  public
    <span class="o">...</span>
    { Methods }
    // images d'en-tête et de pied de page intégrées
    procedure AddHeaderImage(AHeaderIndex: Integer;
      ASection: TsHeaderFooterSectionIndex; const AFilename: String);
    procedure AddFooterImage(AFooterIndex: Integer;
      ASection: TsHeaderFooterSectionIndex; const AFilename: String);
    procedure GetImageSections(out AHeaderTags, AFooterTags: String);
    function HasHeaderFooterImages: Boolean;

    // Lignes et colonnes répétées
    function HasRepeatedCols: Boolean;
    function HasRepeatedRows: Boolean;
    procedure SetRepeatedCols(AFirstCol, ALastCol: Cardinal);
    procedure SetRepeatedRows(AFirstRow, ALastRow: Cardinal);

    // imprimer les plages
    function AddPrintRange(ARow1, ACol1, ARow2, ACol2: Cardinal): Integer; overload;
    function AddPrintRange(const ARange: TsCellRange): Integer; overload;
    function GetPrintRange(AIndex: Integer): TsCellRange;
    function NumPrintRanges: Integer;
    procedure RemovePrintRange(AIndex: Integer);

    { Propriétés }
    property Orientation: TsPageOrientation read FOrientation write FOrientation;
    property PageWidth: Double read FPageWidth write FPageWidth;
    property PageHeight: Double read FPageHeight write FPageHeight;
    property LeftMargin: Double read FLeftMargin write FLeftMargin;
    property RightMargin: Double read FRightMargin write FRightMargin;
    property TopMargin: Double read FTopMargin write FTopMargin;
    property BottomMargin: Double read FBottomMargin write FBottomMargin;
    property HeaderMargin: Double read FHeaderMargin write FHeaderMargin;
    property FooterMargin: Double read FFooterMargin write FFooterMargin;
    property StartPageNumber: Integer read FStartPageNumber write SetStartPageNumber;
    property ScalingFactor: Integer read FScalingFactor write SetScalingFactor;
    property FitHeightToPages: Integer read FFitHeightToPages write SetFitHeightToPages;
    property FitWidthToPages: Integer read FFitWidthToPages write SetFitWidthToPages;
    property Copies: Integer read FCopies write FCopies;
    property Options: TsPrintOptions read FOptions write FOptions;
    property Headers[AIndex: Integer]: String read GetHeaders write SetHeaders;
    property Footers[AIndex: Integer]: String read GetFooters write SetFooters;
    property RepeatedCols: TsRowColRange read FRepeatedCols;
    property RepeatedRows: TsRowColRange read FRepeatedRows;
    property PrintRange[AIndex: Integer]: TsCellRange read GetPrintRange;
    property FooterImages[ASection: TsHeaderFooterSectionIndex]: TsHeaderFooterImage read GetFooterImages;
    property HeaderImages[ASection: TsHeaderFooterSectionIndex]: TsHeaderFooterImage read GetHeaderImages;
  end;

  TsWorksheet = class
  <span class="o">...</span>
  public
    property PageLayout: TsPageLayout;
    <span class="o">...</span>
  end;
<a href="/File:fpsgrid.png view-source:<a class="external free" href="https://wiki.freepascal.org/File:fpsgrid.png">https://wiki.freepascal.org/File:fpsgrid.png</a>" class="image"><img alt="Note-icon.png" src="/images/0/02/fpsgrid.png view-source:<a class="external free" href="https://wiki.freepascal.org/images/0/02/fpsgrid.png">https://wiki.freepascal.org/images/0/02/fpsgrid.png</a>" width="24" height="29" /></a>

Note: Le fait que le PageLayout appartienne à la feuille de calcul indique qu'il peut y avoir plusieurs mises en page dans le même classeur, une pour chaque feuille de calcul.

  • Orientation définit l'orientation du papier imprimé, soit portrait, soit paysage.
  • La largeur de la page et la hauteur de la page font référence à l'orientation standard du papier, généralement l'orientation portrait.
  • Les marges gauche, haut, droite et bas sont explicites et sont données en millimètres.
  • HeaderMargin s'entend - comme dans Excel - comme la distance entre le bord supérieur du papier et le haut de l'en-tête, et TopMargin correspond à la distance entre le bord supérieur du papier et le haut de la première ligne du tableau, c'est-à-dire que si l'en-tête contient plusieurs sauts de ligne, il peut atteindre la partie tableau de l'impression. C'est différent des fichiers OpenDocument où l'en-tête peut s'agrandir en conséquence.
  • StartPageNumber doit être modifié si l'impression ne doit pas commencer par la page 1. Ce paramètre nécessite d'ajouter l'option poUseStartPageNumber aux Options du PageLayout - mais cela est normalement fait automatiquement.
  • Le ScalingFactor est donné en pourcentage et peut être utilisé pour réduire le nombre de pages imprimées. La modification de cette propriété efface l'option poFitToPages des Options.
  • Au lieu de ScalingFactor, vous pouvez également utiliser FitHeightToPages ou FitWidthToPages. L'option poFitToPages doit être active afin de remplacer le ScalingFactorsetting. FitHeightToPages spécifie le nombre de pages sur lesquelles toute la hauteur de la feuille de calcul à imprimer doit tenir. En conséquence, FitWidthToPages peut être utilisé pour définir le nombre de pages sur lesquelles toute la largeur de la feuille de calcul doit tenir. La valeur 0 a la signification spéciale de "utiliser autant de pages que nécessaire". De cette façon, le paramètre "Adapter toutes les colonnes sur une page" d'Excel, par exemple, peut être réalisé par ce code:.
<span></span>  Ce paramètre nécessite d'ajouter l'option poUseStartPageNumber aux Options du PageLayout - mais cela est normalement fait automatiquement.
  MyWorksheet.PageLayout.FitWidthToPages := 1 ; /// toutes les colonnes sur une largeur de page
  MyWorksheet.PageLayout.FitHeightToPages := 0 ; ///utiliser autant de pages que nécessaire
  • Les lignes et colonnes d'en-tête répétées sur chaque page imprimée peuvent être définies par les records RepeatedCols et RepeatedRows ; leurs éléments FirstIndex et LastIndex font référence aux index de la première et de la dernière colonne ou ligne, respectivement, à répéter. Traduit avec www.DeepL.com/Translator (version gratuite) Utilisez les méthodes SetRepeatedCols et SetRepeatedRows pour définir ces nombres. Notez que le deuxième paramètre pour le dernier indice peut être omis pour n'utiliser qu'une seule ligne ou colonne d'en-tête.
  • Les plages d'impression ou les zones d'impression (selon la terminologie Excel) peuvent être utilisées pour restreindre l'impression uniquement à une plage de cellules. Utilisez les méthodes AddPrintRange pour définir une plage de cellules à imprimer : indiquez les indices de la colonne de gauche, de la ligne supérieure, de la colonne de droite et de la ligne inférieure de la plage à imprimer. Une feuille de calcul peut contenir plusieurs plages d'impression.
  • Copies spécifie combien de fois la feuille de calcul sera imprimée.
  • Les Options définissent d'autres propriétés d'impression, leurs noms s'expliquent d'eux-mêmes. Ils ont été définis en fonction des fichiers Excel, certains d'entre eux n'existent pas dans les fichiers ODS et y sont ignorés.

En-têtes et pieds de page

Les textes d'en-tête et de pied de page peuvent être composés de chaînes de caractères alignés à gauche, centrés ou alignés à droite. Ajoutez le symbole &L pour indiquer que la chaîne suivante doit être imprimée en tant que partie alignée à gauche ; utilisez &C en conséquence pour les parties centrées et &R pour les parties alignées à droite. Il existe d'autres symboles qui seront remplacés par leurs homologues lors de l'impression :

  • &L : commence la section alignée à gauche d'une définition de texte d'en-tête ou de pied de page .
  • &C : commence la section centrée d'une définition de texte d'en-tête ou de pied de page .
  • &R : commence la section alignée à droite d'une définition de texte d'en-tête ou de pied de page .
  • &P : numéro de page.
  • &N : nombre de pages.
  • &D : date actuelle date d'impression .
  • &T : heure actuelle d'impression .
  • &A : nom de la feuille de travail.
  • &F : Nom du fichier sans chemin d'accès.
  • &P : chemin du fichier sans nom de fichier .
  • &G : image intégré - utilisez les méthodes AddHeaderImage ou AddFooterImage pour spécifier le fichier image ; cela ajoute également le &G aux autres codes de la section en-tête/pied de page actuelle. Notez que tous les types d'images connus par l'application Office ne sont pas forcément acceptés. Actuellement, l'image peut être jpeg, png, gif, bmp, tiff, pcx, svg, wmf ou emf.
  • &B : grason/off .
  • &I : italiqueon/off .
  • &U : soulignement on/off .
  • &E : double soulignementon/off .
  • &S : barré on/off .
  • &H : ombré on/off
  • &O : contour on/off
  • &X: exposant on/off
  • &Y: indice on/off
  • &"font" : commence l'utilisation de la font avec le nom spécifié, par exemple &"Arial".
  • &number : commence à utiliser la taille de police (en points), par exemple &16.
  • &Krrggbb : passer à la couleur de police spécifiée par la valeur binaire de la couleur spécifiée, par exemple utiliser &KFF0000 pour le rouge.

Les tableaux Headers[]/Footers[] offrent un espace pour l'utilisation de trois en-têtes ou pieds de page différents :

  • Headers[0] fait référence à l'en-tête utilisé sur la première page uniquement, de même pour Footers[0]. Au lieu de l'indice 0, vous pouvez utiliser la constante HEADER_FOOTER_INDEX_FIRST. Laissez cette chaîne vide s'il n'y a pas d'en-tête/pied de page spécial.
  • Headers[1] fait référence à l'en-tête des pages comportant des numéros de page impairs, de même pour Footers[1]. Au lieu de l'indice 1, vous pouvez utiliser la constante HEADER_FOOTER_INDEX_ODD.
  • Headers[2] désigne l'en-tête sur les pages avec numeros de pages pairs, de même pour Footers[2]. Au lieu de l'indice 2 vous pouvez utiliser la constante HEADER_FOOTER_INDEX_EVEN.

Laissez les chaînes aux indices 0 et 2 vides si l'impression doit toujours avoir le même en-tête/pied de page. Vous pouvez utiliser la constante HEADER_FOOTER_INDEX_ALL pour plus de clarté. Exemple:

<span></span>  MyWorksheet.PageLayout.Headers[HEADER_FOOTER_INDEX_ALL] := '&C&D &T'; // centré "date heure" sur toutes les pages comme en-tête
  MyWorksheet.PageLayout.Footers[HEADER_FOOTER_INDEX_ODD] := '&RPage &P of &N'; // aligné à droite "Page ... de ..." sur les pages impaires comme pied de page
  MyWorksheet.PageLayout.Footers[HEADER_FOOTER_INDEX_EVEN] := '&LPage &P of &N'; // dto, mais aligné à gauche sur les pages paires

Protection

Dans les applications Office, les classeurs peuvent être protégés contre toute modification involontaire par l'utilisateur. fpspreadsheet est capable de lire et d'écrire les structures de données liées à la protection, mais ne les applique pas. Cela signifie, par exemple, que les cellules peuvent être modifiées par l'utilisateur bien que la feuille de calcul soit spécifiée comme étant verrouillée.

La protection est gérée à trois niveaux : protection du classeur, protection de la feuille de calcul et protection des cellules.

Protection du classeur

TsWorkbook contient un ensemble d'options de protection du classeur ou du document :

  • bpLockRevision : spécifie que le classeur est verrouillé pour les révisions .
  • bpLockStructure : si cette option est définie, les feuilles de calcul du classeur ne peuvent pas être déplacées, supprimées, cachées, affichées ou renommées, et de nouvelles feuilles de calcul ne peuvent pas être insérées.
  • bpLockWindows : indique que les fenêtres du classeur dans l'application Office sont verrouillées. Les fenêtres ont la même taille et la même position chaque fois que le classeur est ouvert par l'application Office.

En relation avec la protection du classeur, il y a l'option de feuille de travail soPanesProtection qui empêche les volets d'une feuille de travail d'être modifiés si le classeur est protégé.

Selon le format du fichier, seules certaines de ces options peuvent être prises en charge. Dans ces cas, les options non prises en charge sont des valeurs par défaut communément acceptées.

Protection des feuilles de travail

TsWorksheet abrite un ensemble similaire d'options de protection. Chaque fois qu'une option est incluse dans l'ensemble Protection du classeur, l'action correspondante n'est pas autorisée et verrouillée :

  • spCells : les cellules de la feuille sont protégées. Le fait qu'une cellule particulière puisse être modifiée ou non dépend du niveau de protection de la cellule. Par défaut, aucune cellule ne peut être modifiée.
  • spDeleteColumns : la suppression de colonnes n'est pas autorisée .
  • spDeleteRows : il n'est pas possible de supprimer des lignes .
  • spFormatCells : le formatage des cellules n'est pas autorisé .
  • spFormatColumns : les colonnes ne peuvent pas être formatées.
  • spFormatRows : les lignes ne peuvent pas être formatées .
  • spInsertColumns : il n'est pas autorisé d'insérer des colonnes .
  • spInsertRows : les lignes ne peuvent pas être insérées .
  • spInsertHyperlinks : il n'est pas possible d'insérer de nouveaux hyperliens .
  • spSort : la feuille de calcul n'est pas autorisée à être triée.
  • spSelectLockedCells : Les cellules qui sont verrouillées ne peuvent plus être sélectionnées.
  • spSelectUnlockedCells : Même les cellules qui sont déverrouillées ne peuvent pas être sélectionnées. Avec spSelectLockedCells, cela signifie que la sélection dans la feuille de calcul est gelée..

Ces niveaux de protection deviennent actifs si l'option soProtected est ajoutée aux Options, ou en appelant la méthode Protect(true).

Protection des cellules

La protection des cellules devient active lorsque la protection de la feuille de calcul est activée. Il est contrôlé par un ensemble d'éléments TsCellProtection qui appartient au format de la cellule record :

  • cpLockCell : Cette option détermine si le contenu des cellules peut être modifié par l'utilisateur. Comme elle est activée par défaut, les cellules d'une feuille de calcul protégée ne peuvent normalement pas être modifiées. Afin de déverrouiller certaines cellules pour la saisie par l'utilisateur, l'option cpLockCell doit être retirée de la protection de ces cellules.
  • cpHideFormulas : empêche l'affichage des formules dans l'application Office.

La protection des cellules peut être modifiée en appelant la méthode de feuille de calcul WriteCellProtection. A l'inverse, ReadCellProtection peut être utilisé pour récupérer l'état de protection d'une cellule particulière :

<span></span>// interroge et modifie l'état de protection de la cellule A1 (row=0, col=0)
  cell: PCell;
  cellprot: TsCellProtections;
  // Chercher la cellule
  if MyWorksheet.FindCell('A1') = nil then
  // interroge la protection de la cellule.
  cellprot := worksheet.ReadCellProtection(cell);
  // Déverrouille la cellule pour l'édition, ne modifie pas la visibilité des formules.
  worksheet.WriteCellProtection(cell, cellprot - [cpLockCell]);
  // Masque la formule et déverrouille la cellule.
  worksheet.WriteCellProtection(cell, cellprot - [cpLockCell]);

Mots de passe

La protection des classeurs et des feuilles de calcul peut être sécurisée par des mots de passe. Notez que ces mots de passe ne chiffrent pas le fichier (sauf pour la protection des classeurs dans Excel 2007). Dans les applications Office, l'utilisateur doit saisir ce mot de passe pour désactiver la protection ou pour modifier les éléments de protection. Le mot de passe crypté est stocké dans le CryptoInfo record du classeur et des feuilles de calcul, respectivement :

<span></span><span class="k">type</span>
  TsCryptoInfo = record
    PasswordHash: String;
    Algorithm: TsCryptoAlgorithm; // caExcel, caSHA1, caSHA256, etc.
    SaltValue: String;
    SpinCount: Integer;
  end;
<a href="/File:fpsgrid.png view-source:<a class="external free" href="https://wiki.freepascal.org/File:fpsgrid.png">https://wiki.freepascal.org/File:fpsgrid.png</a>" class="image"><img alt="Warning-icon.png" src="/images/0/02/fpsgrid.png view-source:<a class="external free" href="https://wiki.freepascal.org/images/0/02/fpsgrid.png">https://wiki.freepascal.org/images/0/02/fpsgrid.png</a>" width="24" height="24" /></a>

Avertissement: FPSpreadsheet n'effectue aucun calcul de hachage, le CryptoInfo record est juste passé de la lecture à l'écriture. Cela pose des problèmes lorsque des formats de fichiers différents sont impliqués dans la lecture et l'écriture. On tente de détecter les combinaisons incompatibles. Dans ces cas, la protection par mot de passe est supprimée, et une erreur est enregistrée par le classeur.

Charger et sauvegarder

Ajout de nouveaux formats de fichiers

FPSpreadsheet est ouvert à tout format de fichier de tableur. En plus des formats de fichiers intégrés qui sont spécifiés par l'une des sfXXXX déclarations, il est possible de fournir des unités de lecture et d'écriture dédiées pour accéder à des formats de fichiers spéciaux.

  • Écrire une unité mettant en œuvre un lecteur et un editeur pour le nouveau format de fichier. Ils doivent hériter des basiques TsCustomSpreadReader et TsCustomWriter, respectivement, - les deux sont implémentés dans l'unité fpsReaderWriter -, ou de l'un des plus avancés appartenant aux formats de fichiers intégrés.
  • Enregistrer le nouveau lecteur/écrivain en appelant la fonction RegisterSpreadFileFormat dans la section initialisation de cette unité (implémentée dans l'unité fpsRegFileFormats:.
<span></span>function RegisterSpreadFormat(AFormat: TsSpreadsheetFormat; AReaderClass: TsSpreadReaderClass; AWriterClass: TsSpreadWriterClass;
  AFormatName, ATechnicalName: String; const AFileExtensions: array of String): TsSpreadFormatID;
  • AFormat doit avoir la valeur sfUser pour enregistrer un format de fichier externe.
  • AReaderClass est la classe du lecteur (ou nil, si la fonctionnalité de lecture n'est pas implémentée).
  • AWriterClass est la classe de l'éditeur (ou nil, si la fonctionnalité d'écriture n'est pas implémentée).
  • AFormatName définit le nom du format tel qu'il est utilisé par exemple dans la liste de filtres des dialogues d'ouverture de fichiers.
  • ATechnicalName définit un nom de format plus court.
  • AFileExtensions est un tableau des extensions de fichiers utilisées dans les fichiers. Le premier élément du tableau indique l'extension par défaut. Les extensions doivent commencer par un point comme dans .xls.
  • La fonction d'enregistrement renvoie une valeur numérique (TsSpreadFormatID) qui peut être utilisée comme identifiant de format dans les fonctions de lecture et d'écriture du classeur qui existent en version surchargées acceptant une valeur numérique pour le spécificateur de format. En accord avec les formats intégrés, le FormatID est négatif.
  • Finalement, dans votre application, ajoutez la nouvelle unité à la clause uses. Cela appellera la fonction d'enregistrement lors du chargement de l'appareil et mettra le nouveau format de fichier à la disposition de FPSpreadsheet.

Stream selection

Les classeurs sont chargés et enregistrés au moyen des méthodes ReadFromFile et WriteToFile, respectivement (ou par leurs équivalents de flux, ReadFromStream et WriteToStream).

Par défaut, on accède aux fichiers de données au moyen de memory streams, ce qui donne l'accès le plus rapide aux fichiers. Toutefois, dans le cas de fichiers très volumineux (par exemple, des dizaines de milliers de lignes), le système peut manquer de mémoire. Il existe deux méthodes pour différer dans une certaine mesure le débordement de la mémoire.

  • Ajouter l'élément boBufStream au Options. Dans ce cas, un flux "tamponné" est utilisé pour accéder aux données. Ce type de flux contient une mémoire tampon d'une taille donnée et transfère les données vers un fichier si la mémoire tampon devient trop petite.
  • Ajouter l'élément boFileStream au Options. Cette option évite complètement les flux de mémoire et crée des fichiers temporaires si nécessaire. Il s'agit toutefois de la méthode d'accès aux données la plus lente.
  • Si les deux options sont définies, alors boBufStream est ignoré.
  • En pratique, cependant, l'effet des flux sélectionnés n'est pas très important si l'on veut économiser de la mémoire.

Mode virtuel

Au-delà de l'utilisation transitoire de la mémoire pendant la lecture et l'écriture, la principale consommation de mémoire provient de la structure interne de FPSpreadsheet qui conserve toutes les données en mémoire. Pour surmonter cette limitation, un "mode virtuel" a été introduit. Dans ce mode, les données sont reçues d'une source de données (telle qu'une table de base de données) et sont transmises à l'éditeur sans être collectées dans la feuille de calcul. Il est clair que les données chargées en mode virtuel ne peuvent pas être affichées dans les contrôles visuels. Le mode virtuel est bon pour la conversion entre différents formats de données.

Voici les étapes à suivre pour utiliser ce mode :

  • Activer le mode virtuel en ajoutant l'option boVirtualMode au Options du classeur.
  • Dire au tableur combien de lignes et de colonnes doivent être écrites. Les propriétés de feuille de calcul correspondantes sont VirtualRowCount et VirtualColCount.
  • Écrire un gestionnaire d'événement pour l'événement OnWriteCellData de la feuille de calcul. Ce gestionnaire obtient l'index de la ligne et de la colonne de la cellule en cours d'enregistrement. Vous devez retourner la valeur qui sera enregistrée dans cette cellule. Vous pouvez également spécifier une cellule modèle qui existe physiquement dans le classeur et à partir de laquelle le style de mise en forme est copié dans la cellule de destination. Sachez que lorsque vous exportez une base de données, vous êtes responsable de l'avancement du pointeur de l'ensemble de données vers le prochain enregistrement de la base de données lorsque l'écriture d'une ligne est terminée.
  • Appelle la méthode WriteToFile du classeur.

Le mode virtuel fonctionne également pour la lecture des fichiers de tableur.

Le dossier exemple/autre contient un projet d'exemple travaillé démontrant le mode virtuel en utilisant des données aléatoires. Des exemples de bases de données plus réalistes se trouvent dans exemple/db_import_export et dans le chapitre sur la conversion d'une grande table de base de données en utilisant le mode virtuel.

Exportation des données

FPC contient un ensemble d'unités qui vous permettent d'exporter des ensembles de données vers différents formats (XML, instructions SQL, fichiers DBF, ...). Il existe un paquet maître qui vous permet de choisir un format d'exportation au moment de la conception ou de l'exécution (paquet Lazarus lazdbexport).

FPSpreadsheet possède TFPSExport qui se branche sur ce système. Il permet d'exporter le contenu d'un ensemble de données vers un nouveau fichier de type tableur (.xls, .xlsx, .ods, format wikitable) dans un tableau sur la première feuille par défaut. En outre, si MultipleSheets est défini sur TRUE, il est possible de combiner plusieurs feuilles en feuilles de travail individuelles dans le même fichier. Vous pouvez éventuellement inclure les noms des champs en tant que cellules d'en-tête sur la première ligne en utilisant les propriétés HeaderRow dans les paramètres d'exportation. Le composant d'exportation tente de trouver le format de numérotation des cellules en fonction des types de champs de l'ensemble de données.

Pour les exportations plus compliquées, vous devez coder manuellement une solution (voir les exemples ci-dessous) mais pour les simples transferts de données/exportations dynamiques à la demande de l'utilisateur, cette unité sera probablement suffisante.

Un exemple simple de ce fonctionnement :

<span></span>end;
  Exp: TFPSExport;
  ExpSettings: TFPSExportFormatSettings;
  TheDate: TDateTime;
  FDataset.First ; //supposons que nous ayons un ensemble de données appelé FDataset
  Exp := TFPSExport.Create(nil);
  ExpSettings := TFPSExportFormatSettings.Create(true);
  try
    ExpSettings.ExportFormat := efXLS ; // choisir le format de fichier
    ExpSettings.HeaderRow := true ; // inclure la ligne d'en-tête avec les noms des champs
    Exp.FormatSettings := ExpSettings ; // appliquer les paramètres à l'objet d'exportation
    Exp.Dataset:=FDataset ; // spécifier la source
    Exp.FileName := 'c:\temp\datadump.xls';
    Exp.Execute ; // exécute l'exportation
  finally
    Free;
    Free;
  end;

Exporter en DBF

Vous pouvez sauvegarder les informations d'Excel vers dbf assez facilement. Voici un exemple tiré du forum. Veuillez noter que cet exemple est censé fonctionner avec l'encodage Win1251 par défaut. Pour obtenir plus d'informations, veuillez vous reporter à ce fil de discussion [1].

<span></span>procedure TForm1.ExportToDBF(AWorksheet: TsWorksheet; AFileName: String);
  i: Integer;
  f: TField;
  r, c: Cardinal;
  cell: PCell;
  DbfGlobals.DefaultCreateCodePage := 1251 ; //codage par défaut du dbf
  DbfGlobals.DefaultCreateCodePage := 1251 ; //codage par défaut du dbf
  if Dbf1.Active then Dbf1.Close;
  if FileExists(AFileName) then DeleteFile(AFileName);

  Dbf1.FilePathFull := ExtractFilePath(AFileName);
  Dbf1.TableName := ExtractFileName(AFileName);
  Dbf1.TableLevel := 25 ; // DBase IV : 4 - le plus utilisé ; ou 25 = FoxPro supporte nfCurrency
  Dbf1.LanguageID := $C9 ; //langue russe par défaut
  <span class="n">Dbf1</span><span class="o">.</span><span class="n">FieldDefs</span><span class="o">.</span><span class="n">Clear</span><span class="o">;</span>
  //ci-dessous se trouvent les champs en excel
  Dbf1.FieldDefs.Add('fam', ftString);
  //ajoutez les autres champs que vous voulez sauvegarder

  Dbf1.CreateTable;
  Dbf1.Open;

  for f in Dbf1.Fields do
    f.OnGetText := @DbfGetTextHandler;

  // Sauter la ligne 0 qui contient les en-têtes
  for r := 1 to AWorksheet.GetLastRowIndex do begin
    Dbf1.Append;
    for c := 0 to Dbf1.FieldDefs.Count-1 do begin
      f := Dbf1.Fields[c];
      cell := AWorksheet.FindCell(r, c);
      if cell = nil then
        f.Value := NULL
      else
        case cell^.ContentType of
          cctUTF8String: f.AsString := UTF8ToCP1251(cell^.UTF8StringValue);
          cctNumber: f.AsFloat := cell^.NumberValue;
          cctDateTime: f.AsDateTime := cell^.DateTimeValue;
          cctUTF8String: f.AsString := UTF8ToCP1251(cell^.UTF8StringValue);
        end;
    end;
    Dbf1.Post;
  //Cette procédure est appelée pour que le texte dans les cellules puisse être correctement distribué sur la WorkSheetGrid du formulaire, sinon les symboles ' ?
  if DisplayText then
    <span class="n">AText</span> <span class="o">:=</span> <span class="n">CP1251ToUTF8</span><span class="p">(</span><span class="n">Sender</span><span class="o">.</span><span class="n">AsString</span><span class="p">)</span><span class="o">;</span>
<span class="k">end</span><span class="o">;</span>

Contrôles visuels pour FPSpreadsheet

Le paquet laz_fpspreadsheet_visual implémente une série de contrôles qui simplifient la création d'applications visuelles GUI :

  • TsWorkwookSource lie les contrôles à un classeur et notifie aux contrôles les modifications du classeur.
  • TsWorksheetGrid met en œuvre un contrôle de grille avec des capacités d'édition et de formatage ; il peut être appliqué de manière similaire à TStringGrid.
  • TsWorkbookTabControl fournit une feuille d'onglet pour chaque feuille de calcul du classeur. C'est le conteneur idéal pour une TsWorksheetGrid.
  • TsWorksheetIndicator : une combobox qui liste toutes les feuilles de calcul du classeur.
  • TsCellEdit correspond à la ligne d'édition dans Excel ou Open/LibreOffice. L'édition directe dans la grille est toutefois également possible.
  • TsCellIndicator affiche le nom de la cellule actuellement sélectionnée ; il peut être utilisé à des fins de navigation en saisissant une chaîne d'adresse de cellule.
  • TsCellCombobox propose de choisir les propriétés des cellules pour une sélection d'attributs de mise en forme : nom de la police, taille de la police, couleur de la police, couleur de fond.
  • TsSpreadsheetInspector est un outil principalement destiné au débogage ; il affiche diverses propriétés du classeur, de la feuille de calcul, de la valeur et du formatage des cellules, de manière similaire à l'ObjectInspector de Lazarus. Il est cependant en lecture seule.
  • Diverses actions standard sont fournies dans l'unité fpsActions. Appliqués au menu ou à la barre d'outils, ils simplifient les tâches typiques de formatage et d'édition sans avoir à écrire une ligne de code.
  • TsWorkbookChartSource interface un classeur avec la bibliothèque <a href="/opensearch_desc.php view-source:<a class="external free" href="https://wiki.freepascal.org/opensearch_desc.php">https://wiki.freepascal.org/opensearch_desc.php</a>" title="TsWorksheetChartSource">TAChart</a>. Il définit les plages de cellules à partir desquelles une série de graphiques peut obtenir ses données. Il existe également un composant plus ancien, TsWorksheetChartSource, qui exige que toutes les cellules proviennent de la même feuille de calcul. Pour cette raison, il n'a pas été entièrement intégré à l'environnement des contrôles de FPSpreadsheet et sera retiré de la bibliothèque à l'avenir.

Voir le <a href="#Protection view-source:<a class="external free" href="https://wiki.freepascal.org/FPSpreadsheet#Protection">https://wiki.freepascal.org/FPSpreadsheet#Protection</a>">Tutoriel FPSpreadsheet : Écriture d'une mini application de tableur</a> pour plus d'informations et un tutoriel, et voir les projets de démonstration pour des exemples d'application de ces composants.

Exemples

Voir FPSpreadsheet : Exemples pour une variété d'exemples de code.

Download

Subversion

Vous pouvez télécharger FPSpreadsheet en utilisant le logiciel subversion et la ligne de commande suivante :

<span></span>svn checkout https://svn.code.sf.net/p/lazarus-ccr/svn/components/fpspreadsheet fpspreadsheet

Journal des modifications SVN

  • Mise en œuvre de formats conditionnels pour ods, xlsx et Excel xml.
  • Implémentation des métadonnées pour ods, xlsx et Excel xml.

Modifications incompatibles

  • Suppression des propriétés de feuille de calcul obsolètes DefaultRowHeight et DefaultColWidth. Utilisez plutôt les routines de lecture/écriture correspondantes (ReadDefaultColWidth(units), WriteDefaultColWidth(units)).

Versions stables

Vous pouvez trouver toutes les versions de FPSpreadsheet sur sourceforge.

Version 1.12

Journal des modifications (par rapport à la v1.10x)
  • Cacher (et afficher) les lignes et les colonnes.
  • Appliquer des Sauts de page avant les lignes et les colonnes lors de l'impression par les applications Office.
  • Support complet (lecture et écriture) du format xml ExcelXML (Excel 2003 et XP).
  • Prise en charge de la couleur des onglets des feuilles de calcul (Worksheet.TabColor) dans les formats xls biff8, xlsx et ods. Cette propriété est cependant ignorée par le WorkbookTabControl visuel.
  • Ajouter TsWorksheetIndicator aux contrôles visuels.

Version 1.10.1

Il s'agit de la dernière version stable.

Journal des modifications (par rapport à la v1.8x)
  • Protection du classeur, de la feuille de calcul et des cellules (lecture/écriture en BIFF2/BIFF5/BIFF8/OOXML/ODS, écriture en ExcelXML).
  • Nouveau paquet laz_fpspreadsheet_crypto pour déchiffrer le cryptage pour la protection des feuilles de calcul dans les fichiers xls. Nécessite DCPcrypt.
  • TsWorksheetGrid peut afficher des images intégrées.
  • Glisser-déposer dans TsWorksheetGrid
  • Nouvelles icônes de contraste élevé de la palette des composants, tenant compte de l'indice.
  • Nouvelles options de classeur boAbortReadingOnFormulaError et boIgnoreFormulas.
  • Formules avec références à d'autres feuilles, c'est-à-dire '=Feuillet1!A1+Feuillet2!A2'.
Modifications incompatibles
  • Le champ Valeur de la formule a été supprimé de l'enregistrement de la cellule. La formule de la cellule peut maintenant être récupérée en appelant Worksheet.ReadFormula(cell)..

Version 1.8

Journal des modifications (par rapport à la v1.6x)
  • "Rich-text" formatting of label cells, i.e. assignment different fonts to groups of characters within the cell text. For this purpose, HTML codes (such as ...) can be embedded in the cell text to identify the parts with different font (-- TsWorksheet.WriteTextAsHTML).
  • Searching for cells with specified content in worksheet or workbook.
  • Support for reading and writing of HTML format
  • Support for writing of the ExcelXML format (Excel XP and 2003)
  • Ability to use user-provided file reader/writer classes to extend FPSpreadsheet to new file formats.
  • Readers and writers now support all the line styles of Excel8 and OOXML.
  • xls, xlsx and ods readers/writers now support the active worksheet and selected cell.
  • Ability to write to/read from the system's clipboard for copy & paste using the visual controls.
  • Support for print ranges and repeated header rows and columns in the Office applications.
  • Support for embedded images (currently only writing to xlsx and ods, no reading).
  • Improved compatibility of TsWorksheetGrid with TStringGrid (Cells[Col,Row] property). Standalone application as an advanced StringGrid replacement.
  • Support for Right-to-left mode in TsWorksheetGrid. In addition to the system-wide RTL mode, there are also parameters BiDiMode in the Worksheet and cells allowing to controls text direction at worksheet and cell level individually, like in Excel or LibreOffice Calc.
  • Support of several units for specification of column widths and row heights.
  • The library now supports localization using po files. Translations are welcome.
  • Zoom factor read and written by the worksheet, and applied by the TsWorksheetGrid.
  • Support of column and row formats
  • Support of hidden worksheets
Modifications incompatibles
  • VirtualMode was changed in order to be able to treat worksheets of the same workbook differently. VirtualRowCount and VirtualColCount are now properties of the worksheet, and similarly, the event handler OnWriteCellData. In older versions, these properties had belonged to the workbook.
  • The worksheet methods ReadAsUTF8Text and WriteUTF8Text have been renamed to ReadAsText and WriteText, respectively. The old ones are still available and marked as deprecated; they will be removed in later versions.
  • The public properties of TsWorksheetGrid using a TRect as parameter were modified to use the Left, Top, Right, Bottom values separately.
  • The PageLayout is a class now, no longer a record. As a consequence, some array properties cannot be set directly any more, use the corresponding methods instead.
  • Most of the predefined color constants were marked as deprecated; only the basic EGA colors will remain.
  • Unit fpsNumFormatParser is integrated in fpsNumFormat. Old code which "uses" fpsNumFormatParser must "use" fpsNumFormat now.
  • The source files of the laz_fpspreadsheet, laz_fpspreadsheet_visual and laz_fpspreadsheetexport_visual packages have been moved to separate folders in order to resolve some occasional compilation issues. Projects which do not use the packages but the path to the sources must adapt the paths.

Version 1.6

Journal des modifications (par rapport à la v1.4.x)
  • TsWorkbookChartSource is a new component which facilitates creation of charts from non-contiguous spreadsheet data in various worksheets. It interfaces to a workbook via tha WorkbookSource component. In the long run, it will replace the older TsWorksheetChartSource which required contiguous x/y data blocks in the same worksheet.
  • Major reconstruction of the cell record resulting in strong reduction of memory consumption per cell (from about 160 bytes per cell down to about 50)
  • Implementation of a record helper for the TCell which simplifies cell formatting (no need to set a bit in UsedFormattingFields any more, automatic notification of visual controls)
  • Comments in cells
  • Background fill patterns
  • Hyperliens
  • Enumerators for worksheet's internal AVLTrees for faster iteration using a for-in loop.
  • Formatting of numbers as fractions.
  • Improved number format parser for better recognition of Excel-like number formats.
  • Page layout (page margins, headers, footer, used for only when printing in the Office applications - no direct print support in fpspreadsheet!)
  • Improved color management: no more palettes, but direct rgb colors. More pre-defined colors.
  • A snapshot of the wiki documentation is added to the library as chm help file.
Modifications incompatibles
  • All type declarations and constants are moved from fpspreadsheet.pas to the new unit fpstypes.pas. Therefore, most probably, this unit has to be added to the uses clause.
  • Because fpspreadsheet supports now background fill patterns the cell property BackgroundColor has been replaced by Background. Similarly, the UsedFormattingFields flag uffBackgroundColor is called uffBackground now.
  • Another UsedFormattingFields flag has been dropped: uffBold. It is from the early days of fpspreadsheet and has become obsolete since the introduction of full font support. For achieving a bold type-face, now call MyWorksheet.WriteFont(row, col, BOLD_FONTINDEX), or Myworksheet.WriteFontStyle(row, col, [fssBold]).
  • Iteration through cells using the worksheet methods GetFirstCell and GetNextCell has been removed - it failed if another iteration of this kind was called within the loop. Use the new <a href="#Iteration_through_cells view-source:<a class="external free" href="https://wiki.freepascal.org/FPSpreadsheet#Iteration_through_cells">https://wiki.freepascal.org/FPSpreadsheet#Iteration_through_cells</a>">for-in</a> syntax instead.
  • Support for shared formulas has been reduced. The field SharedFormulaBase has been deleted from the TCell record, and methods related to shared formulas have been removed from TsWorksheet. Files containing shared formulas can still be read, the shared formulas are converted to multiple normal formulas.
  • The color palettes of previous versions have been abandoned. TsColor is now a DWord representing the rgb components of a color (just like TColor does in the graphics unit), it is not an index into a color palette any more. The values of pre-defined colors, therefore, have changed, their names, however, are still existing. The workbook functions for palette access have become obsolete and were removed.

Version 1.4

Journal des modifications (par rapport à la v1.2.x)
  • Full support for string formulas; calculation of RPN and string formulas for all built-in formulas either directly or by means of registration mechanism. Calculation occurs when a workbook is saved (activate workbook option boCalcBeforeSaving) or when cell content changes (active workbook option boAutoCalc).
  • Shared formulas (reading for sfExcel5, sfExcel8, sfOOXML; writing for sfExcel2, sfExcel5, sfExcel8).
  • Significant speed-up of writing of large spreadsheets for the xml-based formats (ods and xlsx), speed up for biff2; speedtest demo program
  • VirtualMode allowing to read and write very large spreadsheet files without loading entire document representation into memory. Formatting of cells in VirtualMode.
  • Demo program for database export using virtual mode and TFPSExport.
  • Added db export unit allowing programmatic exporting datasets using TFPSExport. Similar export units are e.g. <a href="/fpdbfexport view-source:<a class="external free" href="https://wiki.freepascal.org/fpdbfexport">https://wiki.freepascal.org/fpdbfexport</a>" title="fpdbfexport">fpdbfexport</a>, <a href="/fpXMLXSDExport view-source:<a class="external free" href="https://wiki.freepascal.org/fpXMLXSDExport">https://wiki.freepascal.org/fpXMLXSDExport</a>" title="fpXMLXSDExport">fpXMLXSDExport</a>.
  • Reader for xlsx files, now fully supporting the same features as the other readers.
  • Reader/writer for CSV files based on <a href="/CsvDocument view-source:<a class="external free" href="https://wiki.freepascal.org/CsvDocument">https://wiki.freepascal.org/CsvDocument</a>" title="CsvDocument">CsvDocument</a>.
  • Wikitables writer supports now most of the fpspreadsheet formatting options (background color, font style, font color, text alignment, cell borders/line styles/line colors, merged cells, column widths, row heights); new "wikitablemaker" demo
  • Insertion and deletion of rows and columns into a worksheet containing data.
  • Implementation of sorting of a worksheet.
  • Support of diagonal "border" lines
  • Logging of non-fatal error messages during reading/writing (TsWorksheet.ErrorMsg)
  • Merged cells
  • Registration of currency strings for automatic conversion of strings to currency values
  • A set of visual controls (TsWorkbookSource, TsWorkbookTabControl, TsSpreadsheetInspector, TsCellEdit, TsCellIndicator, TsCellCombobox, in addition to the already-existing TsWorksheetGrid) and pre-defined standard actions to facilitate <a href="/File:fpsgrid.png view-source:<a class="external free" href="https://wiki.freepascal.org/File:fpsgrid.png">https://wiki.freepascal.org/File:fpsgrid.png</a>" title="Voir le Tutoriel FPSpreadsheet : Écriture d'une mini application de tableur pour plus d'informations et un tutoriel, et voir les projets de démonstration pour des exemples d'application de ces composants.">creation of GUI applications</a>.
  • Overflow cells in TsWorksheetGrid: label cells with text longer than the cell width extend into the neighboring cell(s).
Modifications incompatibles
  • The option soCalcBeforeSaving now belongs to the workbook, no longer to the worksheet, and has been renamed to boCalcBeforeSaving (it controls automatic calculation of formulas when a workbook is saved).
  • The workbook property ReadFormulas is replaced by the option flag boReadFormulas. This means that you have to add this flag to the workbook's Options in order to activate reading of formulas.
  • With full support of string formulas some features related to RPN formulas were removed:
    • The field RPNFormulaResult of TCell was dropped, as well as the element cctRPNFormula in the TsContentType set.
    • Sheet function identifiers were removed from the TsFormulaElement set, which was truncated after fekParen.
    • To identify a sheet function, its name must be passed to the function RPNFunc (instead of using the now removed fekXXXX token). In the array notation of the RPN formula, a sheet function is identified by the new token fekFunc.
    • The calling convention for registering user-defined functions was modified. It now also requires the Excel ID of the function (see "OpenOffice Documentation of Microsoft Excel Files", section 3.11, or unit xlsconst containing all token up to ID 200 and some above).
    • Code related to RPN formulas was moved to a separate unit, fpsRPN. Add this unit to the uses clause if you need RPN features.

Documentation wiki des anciennes versions

This wiki page is work in progress and updated whenever a new feature is added; therefore, its state corresponds to the svn trunk version of the package. If you work with an older stable version please use these "historic" wiki versions:

Installation

  • If you only need non-GUI components: in Lazarus: Package/Open Package File, select laz_fpspreadsheet.lpk, click Compile. Now the package is known to Lazarus (and should e.g. show up in Package/Package Links). Now you can add a dependency on laz_fpspreadsheet in your project options and fpspreadsheet to the uses clause of the project units that need to use it.
  • If you also want GUI components (<a href="/opensearch_desc.php view-source:<a class="external free" href="https://wiki.freepascal.org/opensearch_desc.php">https://wiki.freepascal.org/opensearch_desc.php</a>" title="Glisser-déposer dans TsWorksheetGrid">TsWorksheetGrid</a> and <a href="/opensearch_desc.php view-source:<a class="external free" href="https://wiki.freepascal.org/opensearch_desc.php">https://wiki.freepascal.org/opensearch_desc.php</a>" title="TsWorksheetChartSource">TsWorksheetChartSource</a>): Package/Open Package File, select laz_fpspreadsheet_visual.lpk, click Compile, then click Use, Install and follow the prompts to rebuild Lazarus with the new package. Drop needed grid/chart components on your forms as usual.
  • If you want to have a GUI component for dataset export: Package/Open Package File, select laz_fpspreadsheetexport_visual.lpk, click Compile, then click, Use, Install and follow the prompts to rebuild Lazarus with the new package. Drop needed export components from the Data Export tab on your forms as usual.
  • FPSpreadsheet is developed with the latest stable fpc version (currently fpc 3.0.2). We only occasionally check older versions.
  • The basic spreadsheet functionality works with Lazarus versions back to version 1.0. Some visual controls or demo programs, however, require newer versions. Please update your Lazarus if you have an older version and experience problems.

Options du compilateur

Here is a list of conditional defines which can be activated in order to tweak some operating modes of the packages and/or make it compilable with older Lazarus/FPC versions:

All these defines are collected in the include file fps.inc.

Support and Bug Reporting

The recommended place to discuss FPSpreadsheet and obtain support is asking in the <a class="external text" href="<a class="external free" href="http://forum.lazarus.freepascal.org/index.php?board=49.0">http://forum.lazarus.freepascal.org/index.php?board=49.0</a> view-source:<a class="external free" href="http://forum.lazarus.freepascal.org/index.php?board=49.0">http://forum.lazarus.freepascal.org/index.php?board=49.0</a>">Lazarus Forum</a>.

Bug reports should be sent to the <a class="external text" href="<a class="external free" href="http://bugs.freepascal.org/">http://bugs.freepascal.org/</a> view-source:<a class="external free" href="http://bugs.freepascal.org/">http://bugs.freepascal.org/</a>">Lazarus/Free Pascal Bug Tracker</a>; please specify the "Lazarus-CCR" project.

Current Progress

Amélioration du contenu des cellules

<tbody></tbody>

<tbody></tbody>
Format Multiple
sheets
Unicode Reader
support
Writer
support
Text Number String
Formula
RPN
Formula
3D cell
references
Date/Time Comments Hyperliens Images +++ Protection Conditional
formats
CSV files No Yes + Working ++ Working ++ Working ++ Working ++ N/A N/A N/A Working ++ N/A N/A N/A N/A N/A
Excel 2.x No No * Working ** Working Working Working Working Working *** N/A Working **** Working N/A N/A Working N/A
Excel 5.0 (Excel 5.0 and 95) Yes No * Working ** Working Working Working Working Working *** Working Working **** Working N/A N/A Working N/A
Excel 8.0 (Excel 97- 2003) Yes Yes Working ** Working Working Working Working Working *** Working Working **** Reading only Working Not working Working Not working
Excel 2003/XML Yes Yes Working ** Working Working Working Working *** Working Working Working **** Working Working N/A Working Working
Excel OOXML Yes Yes Working ** Working Working Working Working *** Working Working Working **** Working Working Writing only Working Working ++++
OpenDocument Yes Yes Working ** Working Working Working Working *** Working Working Working **** Working Working Working Working Working
HTML No Yes Working ++ Working ++ Working ++ Working ++ N/A N/A N/A Working ++ N/A Working Not working N/A N/A
Wikitable files (Mediawiki) No Yes planned Working ++ Working ++ Working ++ N/A N/A N/A Working ++ N/A N/A Not working N/A N/A

(+) Depends on file.
(++) No "true" number format support because the file does not containg number formatting information. But the number format currently used in the spreadsheet understood.
(+++) Only very basic image support: no transformations, no cropping, no image manipulation.
(++++) Extended OOXML formatting options not supported.
(*) In formats which don't support Unicode the data is stored by default as ISO 8859-1 (Latin 1). You can change the encoding in TsWorkbook.Encoding. Note that FPSpreadsheet offers UTF-8 read and write routines, but the data might be converted to ISO when reading or writing to the disk. Be careful that characters which don't fit selected encoding will be lost in those operations. The remarks here are only valid for formats which don't support Unicode.
(**) Some cell could be returned blank due to missing or non ready implemented number and text formats.
(***) This is the format in which the formulas are written to file (determined by design of the file format).
(****) Writing of all formats is supported. Some rare custom formats, however, may not be recognized correctly. BIFF2 supports only built-in formats by design.

Amélioration des options de formatage

The following formatting options are available:

<tbody>

</tbody>

<tbody></tbody>
Format Text
alignment
Text
rotation
    Font     Rich
text
  Border   Color
support
Back
ground
Word
wrap
Col&Row
size
Number
format
Merged
cells
Page
layout
Print
ranges
Header/footer
images
Column/row
format
Hide
cols/rows
Page
breaks
CSV files N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A
Excel 2.x Working * N/A Working N/A Working Working Working** N/A Working Working N/A Working N/A N/A Working N/A Working
Excel 5.0
(Excel 5.0 and 95)
Working Working Working Working Working Working Working Working Working Working N/A Working Working N/A Working Working Working
Excel 8.0
(Excel 97 - XP)
Working Working Working Working Working Working Working Working Working Working Working Working Working Not working Working Working Working
Excel 2003/XML Working Working Working Working Working Working Working Working Working Working Working Working Working N/A Working Wworking Working
Excel OOXML (xlsx) Working Working Working Working Working Working Working Working Working Working Working Working Working Writing only Working Working Working
OpenDocument Working Working Working Working Working Working Working*** Working Working Working Working Working Working Working Working Working
HTML (+) Working bugs Working Working bugs Working Working **** Writing only Writing only N/A Working N/A N/A Not working Writing only to be done N/A
Wikitable (Mediawiki) Writing only N/A Writing only Not working Writing only Writing only Writing only Writing only N/A Writing only N/A N/A Not working Writing only to be done N/A

(N/A) Feature is not available for this format intrinsically.
(*) BIFF2 supports only horizontal text alignment, vertical alignment is ignored.
(**) BIFF2 does not support a background color; a dotted black&white background is used instead.
(***) OpenDocument supports only uniform backgrounds; a fill color interpolated between foreground and background colors is written instead.
(****) Only uniform background color, no fill styles.
(+) HTML reader does not support styles. Since the writer does use styles these files are not read back correctly.

Amélioration des options de l'interface utilisateur des classeurs/feuilles de travail.

Some additional options were added to interface the file contents with the TsWorksheetGrid:

<tbody></tbody>

<tbody></tbody>
Format Hide grid lines Hide headers Frozen Panes Active sheet/cell Zooming BiDi mode Tab color
Excel 2.x Working Working not working N/A N/A N/A N/A
Excel 5.0 (Excel 5.0 and 95) Working Working Working Working Working N/A N/A
Excel 8.0 (Excel 97 - XP) Working Working Working Working Working Working Working
Excel2003/XML Working Working Working Working Working Working N/A
Excel OOXML Working Working Working Working Working Working Working
OpenDocument Working Working Working Working Working Working Working
HTML Writing only Writing only N/A N/A N/A not working N/A

To do list

Note: this list is provisional, maintained by developers and can change without notice. If you are interested in contributing, please feel free to get in touch and submit a patch - thanks!

Long-term:

  • Provide a more common user interface to fpspreadsheet (setter/getter and properties instead of Read*/Write* methods, MyWorksheet.Cells[ARow, ACol]), make TCell a class, avoid the pointers PCell.
  • Store formatting in a format list of the workbook, not in the cell, to reduce memory usage.
  • Use BIFF8 file-wide string storage instead of storing strings in cells (should reduce memory usage in case of many duplicate strings)
  • Redo ooxml and ods readers based upon SAX/TXmlReader instead of DOM to reduce memory usage of large files.
  • Add an fpspreadsheetexport unit and component on "Data Export" tab similar to <a href="/fpdbfexport view-source:<a class="external free" href="https://wiki.freepascal.org/fpdbfexport">https://wiki.freepascal.org/fpdbfexport</a>" title="fpdbfexport">fpdbfexport</a> FPSpreadsheetexport demo preferably with all export formats component. Find a way to register export format to all formats (look into how lazreport pdf export performs a similar procedure).

Changelog

Changes in the development version that have not yet been released are already documented on this page.

  • 2 June 2020:
    Version 1.12 based on revision 7479
  • 13 August 2018:
    Version 1.10.1 bug fix release, based on revision 6598.
  • 6 July 2018:
    Version 1.10 release, based on svn revision 6547.
  • 16 June 2017:
    Version 1.8.3. Fixes compilation with Lazarus 1.8. New, highDPI-aware component palette icons
  • 11 April 2017:
    Version 1.8.2, based on svn revision 5832. Fixes writing distorted images due to incorrect row height calculation.
  • 2 March 2017:
    Version 1.8, based on svn revision 5781.
  • 13 April 2016:
    Version 1.6.2 released, based on svn revision 4619. Fixes integer overflow in formulas (<a class="external text" href="<a class="external free" href="https://bugs.freepascal.org/view.php?id=29999">https://bugs.freepascal.org/view.php?id=29999</a> view-source:<a class="external free" href="https://bugs.freepascal.org/view.php?id=29999">https://bugs.freepascal.org/view.php?id=29999</a>">Issue #29999</a>).
  • 28 June 2015:
    Version 1.6 released, based on svn release 4106. Improved memory consumption, comments, hyperlinks, background fill patterns, cell enumerator, fraction number format, page layout, modified color management, offline wiki version included.
  • 13 March 2015:
    Version 1.4.3 released. Fixes formula calculation in worksheet grid.
  • 31 January 2015:
    Version 1.4.2 released. Fixes incomplete reading of ods files with repeated cells (<a class="external text" href="<a class="external free" href="https://bugs.freepascal.org/view.php?id=0027389">https://bugs.freepascal.org/view.php?id=0027389</a> view-source:<a class="external free" href="https://bugs.freepascal.org/view.php?id=0027389">https://bugs.freepascal.org/view.php?id=0027389</a>">Issue #0027389</a>)
  • 26 January 2015:
    Version 1.4.1 released. A bugfix release for 1.4 that fixes incorrect streaming of TsWorksheetGrid and reading errors of biff5 and biff8 readers.
  • 31 December 2014:
    Version 1.4 released (based on subversion revision 3856 with full formula support, xlsx reader, csv reader and writer, wikitables writer, speed enhancement, virtual mode, db export component, row and column insertion/deletion, sorting, merged cells, visual controls in addition to (improved) fpspreadsheet grid.
  • 3 September 2014:
    Version 1.2.1 released. This is a bugfix release for 1.2 that fixes a bug in spreadsheetGrid (<a class="external text" href="<a class="external free" href="https://bugs.freepascal.org/view.php?id=26521">https://bugs.freepascal.org/view.php?id=26521</a> view-source:<a class="external free" href="https://bugs.freepascal.org/view.php?id=26521">https://bugs.freepascal.org/view.php?id=26521</a>">Issue #26521</a>)
  • 26 June 2014:
    Version 1.2 released (based on subversion revision 3241) with fpsgrid improvements, date/time cell support for .xls, .ods, vastly improved cell formatting support, improved formula support, unit tests.
  • Jan 2013:
    Version 1.1 released with all improvements up to revision 2621
  • Nov 2011:
    Released version 1.0, which includes OO XML generation support with bold formatting supported and also a lot of improvements from the last years
  • Jan 2009:
    Implemented a cross-platform support for OLE file. Now Excel 5.0 files can be created in any operating system. Adds read support for Excel 2.1
  • Feb 2008:
    Initial commit to lazarus-ccr with write support for Excel 2.1, Excel 5.0 (Windows only) and experimental OOXML and OpenDocument

License

LGPL with static linking exception. This is the same license as is used in the Lazarus Component Library.

References

Liens Wiki

Liens externes

Navigation menu

<script>(window.RLQ=window.RLQ||[]).push(function(){mw.config.set({"wgPageParseReport":{"limitreport":{"cputime":"0.160","walltime":"0.161","ppvisitednodes":{"value":846,"limit":1000000},"ppgeneratednodes":{"value":2636,"limit":1000000},"postexpandincludesize":{"value":0,"limit":2097152},"templateargumentsize":{"value":0,"limit":2097152},"expansiondepth":{"value":2,"limit":40},"expensivefunctioncount":{"value":0,"limit":100},"unstrip-depth":{"value":0,"limit":20},"unstrip-size":{"value":46861,"limit":5000000},"timingprofile":["100.00% 0.000 1 -total"]},"cachereport":{"timestamp":"20210720150814","ttl":86400,"transientcontent":false}}});});</script><script>(window.RLQ=window.RLQ||[]).push(function(){mw.config.set({"wgBackendResponseTime":59});});</script></body></html>