From 055342523333e359ece8dca6d3b502c1e7e5c191 Mon Sep 17 00:00:00 2001 From: wp_xxyyzz Date: Mon, 23 Jun 2014 15:16:30 +0000 Subject: [PATCH] fpspreadsheet: Complete doc-o-matic comments in fpspreadsheet.pas, now also with reader/writer. git-svn-id: https://svn.code.sf.net/p/lazarus-ccr/svn@3227 8e941d3f-bd1b-0410-a28a-d453659cc2b4 --- components/fpspreadsheet/fpspreadsheet.pas | 141 +++++++++++++++++---- 1 file changed, 119 insertions(+), 22 deletions(-) diff --git a/components/fpspreadsheet/fpspreadsheet.pas b/components/fpspreadsheet/fpspreadsheet.pas index a4c6a2c8a..3674ac441 100755 --- a/components/fpspreadsheet/fpspreadsheet.pas +++ b/components/fpspreadsheet/fpspreadsheet.pas @@ -674,6 +674,9 @@ type procedure RemoveWorksheetsCallback(data, arg: pointer); public + {@@ A copy of SysUtil's DefaultFormatSettings to provide some kind of + localization to some formatting strings. Can be modified before + loading/writing files } FormatSettings: TFormatSettings; { Base methods } @@ -821,8 +824,11 @@ type TsCustomSpreadReader = class protected + {@@ A copy of the workbook's FormatSetting to extract some localized number format information } FWorkbook: TsWorkbook; + {@@ Instance of the worksheet which is currently being read. } FWorksheet: TsWorksheet; + {@@ List of number formats found in the file } FNumFormatList: TsCustomNumFormatList; procedure CreateNumFormatList; virtual; { Record reading methods } @@ -4557,24 +4563,36 @@ end; { TsCustomSpreadReader } +{@@ + Constructor of the reader. Has the workbook to be read as a parameter to + apply the localization information found in its FormatSettings. + Creates an internal instance of the number format list according to the + file format being read. + + @param AWorkbook Workbook into which the file is being read. This parameter + is passed from the workbook which creates the reader. } constructor TsCustomSpreadReader.Create(AWorkbook: TsWorkbook); begin inherited Create; FWorkbook := AWorkbook; CreateNumFormatList; -// FNumFormatList.FWorkbook := AWorkbook; end; +{@@ + Destructor of the reader. Destroys the internal number format list. } destructor TsCustomSpreadReader.Destroy; begin FNumFormatList.Free; inherited Destroy; end; +{@@ + This method creates an instance of the number format list according to the + file format being read. The method has to be overridden because the + descendants know the special requirements of the file format. } procedure TsCustomSpreadReader.CreateNumFormatList; begin - { The format list needs to be created by descendants who know about the - special requirements of the file format. } + // nothing to do here end; {@@ @@ -4584,7 +4602,6 @@ end; @param AFileName The input file name. @param AData The Workbook to be filled with information from the file. - @see TsWorkbook } procedure TsCustomSpreadReader.ReadFromFile(AFileName: string; AData: TsWorkbook); @@ -4600,7 +4617,15 @@ begin end; {@@ - This routine should be overriden in descendent classes. + This routine has the purpose to read the workbook data from the stream. + It should be overriden in descendent classes. + + Its basic implementation here assumes that the stream is a TStringStream and + the data are provided by calling ReadFromStrings. This mechanism is valid + for wikitables. + + @param AStream Stream containing the workbook data + @param AData Workbook which is filled by the data from the stream. } procedure TsCustomSpreadReader.ReadFromStream(AStream: TStream; AData: TsWorkbook); var @@ -4620,6 +4645,10 @@ begin end; end; +{@@ + Reads workbook data from a string list. This abstract implementation does + nothing and raises an exception. Must be overridden, like for wikitables. +} procedure TsCustomSpreadReader.ReadFromStrings(AStrings: TStrings; AData: TsWorkbook); begin @@ -4629,6 +4658,15 @@ end; { TsCustomSpreadWriter } +{@@ Constructor of the writer. Has the workbook to be written as a parameter to + apply the localization information found in its FormatSettings. + Creates an internal number format list to collect unique samples of all the + number formats found in the workbook. + + @param AWorkbook Workbook which is to be written to file/stream. + This parameter is passed from the workbook which creates the + writer. +} constructor TsCustomSpreadWriter.Create(AWorkbook: TsWorkbook); begin inherited Create; @@ -4637,6 +4675,7 @@ begin // FNumFormatList.FWorkbook := AWorkbook; end; +{@@ Destructor of the writer. Destroys the internal number format list. } destructor TsCustomSpreadWriter.Destroy; begin FNumFormatList.Free; @@ -4644,8 +4683,11 @@ begin end; {@@ - Checks if the style of a cell is in the list of manually added FFormattingStyles - and returns the index or -1 if it isn't + Checks if the formatting style of a cell is in the list of manually added + FFormattingStyles and returns its index, or -1 if it isn't + + @param AFormat Cell containing the formatting styles which are seeked in the + FFormattingStyles array. } function TsCustomSpreadWriter.FindFormattingInList(AFormat: PCell): Integer; var @@ -4702,27 +4744,42 @@ begin end; end; -{ If formatting features of a cell are not supported by the destination file +{@@ + If formatting features of a cell are not supported by the destination file format of the writer, here is the place to apply replacements. - Must be overridden by descendants. See BIFF2 } + Must be overridden by descendants, nothin happens here. See BIFF2. + + @param ACell Pointer to the cell being investigated. Note that this cell + does not belong to the workbook, but is a cell of the + FFormattingStyles array. +} procedure TsCustomSpreadWriter.FixFormat(ACell: PCell); begin Unused(ACell); // to be overridden end; -{ Each descendent should define its own default formats, if any. - Always add the normal, unformatted style first to speed things up. } +{@@ + Each descendent should define its own default formats, if any. + Always add the normal, unformatted style first to speed things up. + + To be overridden by descendants. +} procedure TsCustomSpreadWriter.AddDefaultFormats(); begin SetLength(FFormattingStyles, 0); NextXFIndex := 0; end; +{@@ + Creates an instance of the number format list which collects prototypes of + all number formats found in the workbook. + + Create here a descendant who knows about the details how to write the + formats correctly to the destination file. } procedure TsCustomSpreadWriter.CreateNumFormatList; begin - { The format list needs to be created by descendants who know about the - special requirements of the file format. } + // nothing to do here end; procedure TsCustomSpreadWriter.ListAllFormattingStylesCallback(ACell: PCell; AStream: TStream); @@ -4843,7 +4900,12 @@ begin end; {@@ - Helper function for the spreadsheet writers. + Helper function for the spreadsheet writers. Writes the cell value to the + stream. Calls the WriteNumber method of the worksheet for writing a number, + the WriteDateTime method for writing a date/time etc. + + @param ACell Pointer to the worksheet cell being written + @param AStream Stream to which data are written @see TsCustomSpreadWriter.WriteCellsToStream } @@ -4876,9 +4938,10 @@ end; A generic method to iterate through all cells in a worksheet and call a callback routine for each cell. - @param AStream The output stream, passed to the callback routine. - @param ACells List of cells to be iterated - @param ACallback The callback routine + @param AStream The output stream, passed to the callback routine. + @param ACells List of cells to be iterated + @param ACallback Callback routine; it requires as arguments a pointer to the + cell as well as the destination stream. } procedure TsCustomSpreadWriter.IterateThroughCells(AStream: TStream; ACells: TAVLTree; ACallback: TCellsCallback); var @@ -4898,8 +4961,8 @@ end; Opens the file and calls WriteToStream The workbook written is the one specified in the constructor of the writer. - @param AFileName The output file name. - If the file already exists it will be replaced. + @param AFileName The output file name. + @param AOverwriteExisting If the file already exists it will be replaced. @see TsWorkbook } @@ -4921,7 +4984,12 @@ begin end; {@@ - This routine should be overriden in descendent classes. + This routine has the purpose to write the workbook to a stream. + Present implementation writes to a stringlists by means of WriteToStrings; + this behavior is required for wikitables. + Must be overriden in descendent classes for all other cases. + + @param AStream Stream to which the workbook is written } procedure TsCustomSpreadWriter.WriteToStream(AStream: TStream); var @@ -4936,21 +5004,48 @@ begin end; end; +{@@ + Writes the worksheet to a list of strings. Not implemented here, needs to + be overridden by descendants. See wikitables. +} procedure TsCustomSpreadWriter.WriteToStrings(AStrings: TStrings); begin Unused(AStrings); raise Exception.Create(lpUnsupportedWriteFormat); end; +{@@ + Basic method which is called when writing a string formula to a stream. + Present implementation does nothing. Needs to be overridden by descendants. + + @param AStream Stream to be written + @param ARow Row index of the cell containing the formula + @param ACol Column index of the cell containing the formula + @param AFormula String formula given as an Excel-like string, such as '=A1+B1' + @param ACell Pointer to the cell containing the formula and being written + to the stream +} procedure TsCustomSpreadWriter.WriteFormula(AStream: TStream; const ARow, ACol: Cardinal; const AFormula: TsFormula; ACell: PCell); begin Unused(AStream, ARow, ACol); Unused(AFormula, ACell); - // Silently dump the formula; child classes should implement their own support end; +{@@ + Basic method which is called when writing an RPN formula to a stream. + Present implementation does nothing. Needs to be overridden by descendants. + + RPN formula are used by the BIFF file format. + + @param AStream Stream to be written + @param ARow Row index of the cell containing the formula + @param ACol Column index of the cell containing the formula + @param AFormula RPN formula given as an array of RPN tokens + @param ACell Pointer to the cell containing the formula and being written + to the stream +} procedure TsCustomSpreadWriter.WriteRPNFormula(AStream: TStream; const ARow, ACol: Cardinal; const AFormula: TsRPNFormula; ACell: PCell); begin @@ -4960,7 +5055,9 @@ begin end; -{ Simplified creation of RPN formulas } +{******************************************************************************} +{ Simplified creation of RPN formulas } +{******************************************************************************} {@@ Creates a pointer to a new RPN item. This represents an element in the array