pascal/lazarus-ccr
1
0
Fork 0
Code Issues Releases Activity

fpspreadsheet: Update documentation.

Browse Source 
git-svn-id: https://svn.code.sf.net/p/lazarus-ccr/svn@8935 8e941d3f-bd1b-0410-a28a-d453659cc2b4
This commit is contained in:
wp_xxyyzz
2023-10-07 21:51:23 +00:00
parent 2b08e69c92
commit 67024b9786
9 changed files with 238 additions and 49 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
components/fpspreadsheet/docs/api/source-files.txt
View File

@ -6,5 +6,6 @@
../../source/common/fpsallformats.pas
../../source/common/fpsrpn.pas
../../source/common/fpscurrency.pas
../../source/common/fpsconditionalformat.pas
../../source/visual/fpspreadsheetctrls.pas
../../source/visual/fpspreadsheetgrid.pas

BIN
components/fpspreadsheet/docs/fpspreadsheet-api.chm
View File

Binary file not shown.

BIN
components/fpspreadsheet/docs/fpspreadsheet-wiki.chm
View File

Binary file not shown.

7
components/fpspreadsheet/examples/other/conditional_formatting/demo_conditional_formatting.pas
View File

@ -28,7 +28,7 @@ begin
sh.WriteText(0, 2, 'Test values');
row := 2;
for i := row to row+33 do
for i := row to row+42 do
begin
sh.WriteNumber(i, 2, 1.0);
sh.WriteNumber(i, 3, 2.0);
@ -399,6 +399,11 @@ begin
sh.WriteText(row, 1, '3 flags');
sh.WriteIconSet(Range(Row, 2, row, 12), is3Flags);
inc(row);
sh.WriteText(row, 0, 'IconSet');
sh.WriteText(row, 1, '5 quarters');
sh.WriteIconSet(Range(Row, 2, row, 12), is5Quarters);
{ ------ Save workbook to file-------------------------------------------- }
dir := ExtractFilePath(ParamStr(0));
wb.WriteToFile(dir + 'test.xlsx', true);

36
components/fpspreadsheet/source/common/fpsconditionalformat.pas
View File

@ -1,7 +1,18 @@
{@@ ----------------------------------------------------------------------------
Unit **fpsConditionalFormat** implements conditional formatting for
Excel and OpenDocument spreadsheet documents.
AUTHORS: Werner Pamler
LICENSE: See the file COPYING.modifiedLGPL.txt, included in the Lazarus
distribution, for details about the license.
-------------------------------------------------------------------------------}
unit fpsConditionalFormat;
{$mode objfpc}{$H+}
{$WARN 6058 off : Call to subroutine "$1" marked as inline is not inlined}
interface
uses
@ -13,7 +24,8 @@ type
procedure Assign(ASource: TsCFRule); virtual; abstract;
end;
{ Cell is... }
{@@ Enumeration of the available conditions to be fulfilled by a cell value
in conditional formatting }
TsCFCondition = (
cfcEqual, cfcNotEqual,
cfcGreaterThan, cfcLessThan, cfcGreaterEqual, cfcLessEqual,
@ -40,6 +52,8 @@ type
procedure Assign(ASource: TsCFRule); override;
end;
{@@ Enumeration of the criteria to be fulfilled by the values used in
"color range" and "data bar" conditional formatting. }
TsCFValueKind = (vkNone, vkMin, vkMax, vkPercent, vkPercentile, vkValue);
{ Color range }
@ -72,7 +86,7 @@ type
procedure Assign(ASource: TsCFRule); override;
end;
{ Icon sets }
{@@ Enumeration of the icon sets available for conditional formatting }
TsCFIconSet = (
is3Arrows, is3ArrowsGray, is3Flags,
is3TrafficLights1, // x14 in xlsx
@ -107,7 +121,7 @@ type
property ShowValue: Boolean read FShowValue write FShowValue;
end;
{ Rules }
{@@ Rule for a conditional format }
TsCFRules = class(TFPObjectList)
private
function GetItem(AIndex: Integer): TsCFRule;
@ -118,7 +132,7 @@ type
property Priority[AIndex: Integer]: Integer read GetPriority;
end;
{ Conditional format item }
{@@ Conditional format item. These items are stored in an instance of TsConditionalFormatList. }
TsConditionalFormat = class
private
FWorksheet: TsBasicWorksheet;
@ -140,6 +154,7 @@ type
property Worksheet: TsBasicWorksheet read FWorksheet;
end;
{@@ List of conditional formats. Maintained by the workbook. }
TsConditionalFormatList = class(TFPObjectList)
protected
function AddRule(ASheet: TsBasicWorksheet; ARange: TsCellRange;
@ -202,6 +217,13 @@ uses
Math, TypInfo,
fpSpreadsheet;
{@@ ----------------------------------------------------------------------------
Determines the count of icons available in the specified icon set for
conditional formatting.
@param AIconSet Icon set to be checked
@returns Number of icons in the icon set.
-------------------------------------------------------------------------------}
function GetCFIconCount(AIconSet: TsCFIconSet): Integer;
var
s: String;
@ -629,7 +651,7 @@ begin
Result := AddRule(ASheet, ARange, rule);
end;
{ IconSet conditional format for 3 icons, ie. 2 values }
{@@ IconSet conditional format for 3 icons, ie. 2 values }
function TsConditionalFormatList.AddIconSetRule(ASheet: TsBasicWorksheet;
ARange: TsCellRange; AIconSet: TsCFIconSet;
AValueKind1: TsCFValueKind; AValue1: Double;
@ -657,7 +679,7 @@ begin
Result := AddRule(ASheet, ARange, rule);
end;
{ IconSet conditional format for 4 icons, i.e. 3 values }
{@@ IconSet conditional format for 4 icons, i.e. 3 values }
function TsConditionalFormatList.AddIconSetRule(ASheet: TsBasicWorksheet;
ARange: TsCellRange; AIconSet: TsCFIconSet;
AValueKind1: TsCFValueKind; AValue1: Double;
@ -687,7 +709,7 @@ begin
Result := AddRule(ASheet, ARange, rule);
end;
{ Iconset conditional format for 5 icons, i.e. 4 values }
{@@ Iconset conditional format for 5 icons, i.e. 4 values }
function TsConditionalFormatList.AddIconSetRule(ASheet: TsBasicWorksheet;
ARange: TsCellRange; AIconSet: TsCFIconSet;
AValueKind1: TsCFValueKind; AValue1: Double; AValueKind2: TsCFValueKind; AValue2: Double;

64
components/fpspreadsheet/source/common/fpspreadsheet.pas
View File

@ -3015,7 +3015,6 @@ begin
Result := Workbook.GetDefaultFont;
end;
{@@ ----------------------------------------------------------------------------
Returns @true if the worksheet does not contain any cell, column or row records
-------------------------------------------------------------------------------}
@ -3278,9 +3277,6 @@ begin
begin
AFormula^.Col := ACell^.Col;
AFormula^.Row := ACell^.Row;
// ACell^.ContentType := cctFormula;
ACell^.Flags := ACell^.Flags + [cfHasFormula];
if (AFormula^.Parser <> nil) and AFormula^.Parser.Has3DLinks then
ACell^.Flags := ACell^.Flags + [cf3dFormula];
@ -3288,9 +3284,14 @@ begin
DeleteFormula(ACell);
end;
{@@ ----------------------------------------------------------------------------
Assigns a hyperlink to an image. The image is specified by its index in the
internal image list
{@@ Assigns a hyperlink to an image. The image is specified by its index in the
internal image list}
@param AImageIndex Specifies the index of the image in the internal image list.
@param ATarget Link target
@param AToolTip Optional text to be displayed as mouse-over popup
-------------------------------------------------------------------------------}
procedure TsWorksheet.AddHyperlinkToImage(AImageIndex: Integer; ATarget: String;
AToolTip: String = '');
var
@ -3303,7 +3304,6 @@ begin
end;
end;
{@@ ----------------------------------------------------------------------------
Removes a cell from its tree container. DOES NOT RELEASE ITS MEMORY!
@ -3761,7 +3761,6 @@ begin
ClearSelection;
end;
{@@ ----------------------------------------------------------------------------
Returns the list of selected cell ranges
-------------------------------------------------------------------------------}
@ -3883,11 +3882,10 @@ begin
if Assigned(FOnZoom) then FOnZoom(Self);
end;
{@@ ----------------------------------------------------------------------------
Writes UTF-8 encoded text to a cell.
On formats that don't support unicode, the text will be converted
On file formats that don't support unicode, the text will be converted
to ISO Latin 1.
@param ARow The row of the cell
@ -3977,17 +3975,17 @@ begin
end;
{@@ ----------------------------------------------------------------------------
Writes text containing HTML codes to a cell. Here are the allowed HTML codes:
<b>, <strong> ... bold text
<i>, <em> ........ italic text
<u>, <ins> ....... underlined text
<s>, <del> ....... strike-out text
<sub> ............ subscript
<sup> ............ superscript
<font tags> ...... full font selection. "tags" can be:
Writes text containing HTML codes to a cell. Here are the allowed HTML codes:@br
@preformatted( <b>, <strong> ... bold text)
@preformatted( <i>, <em> ........ italic text)
@preformatted( <u>, <ins> ....... underlined text)
@preformatted( <s>, <del> ....... strike-out text)
@preformatted( <sub> ............ subscript)
@preformatted( <sup> ............ superscript)
@preformatted( <font tags> ...... full font selection. "tags" can be:
face="..." ... font name
size="..." ... font size, in pt, em, px, % (add units!)
color="..." .. font color (e.g. red, or #FF0000).
size="..." ... font size, in pt, em, px, %. Add units!
color="..." .. font color, e.g. red, or #FF0000.)
@param ARow The row of the cell
@param ACol The column of the cell
@ -4019,16 +4017,16 @@ end;
{@@ ----------------------------------------------------------------------------
Writes text containing HTML codes to a cell. Here are the allowed HTML codes:
<b>, <strong> ... bold text
<i>, <em> ........ italic text
<u>, <ins> ....... underlined text
<s>, <del> ....... strike-out text
<sub> ............ subscript
<sup> ............ superscript
<font tags> ...... full font selection. "tags" can be:
@preformatted( <b>, <strong> ... bold text)
@preformatted( <i>, <em> ........ italic text)
@preformatted( <u>, <ins> ....... underlined text)
@preformatted( <s>, <del> ....... strike-out text)
@preformatted( <sub> ............ subscript)
@preformatted( <sup> ............ superscript)
@preformatted( <font tags> ...... full font selection. "tags" can be:
face="..." ... font name
size="..." ... font size, in pt, em, px, % (add units!)
color="..." .. font color (e.g. red, or #FF0000).
size="..." ... font size, in pt, em, px, %. Add units!
color="..." .. font color, e.g. red, or #FF0000.)
@param ACell Pointer to the cell
@param AText The text containing the html codes
@ -5386,6 +5384,10 @@ begin
Result := lRow^.RowHeightType;
end;
{@@ ----------------------------------------------------------------------------
Returns @TRUE if the workbook contains at least one column with an individual
column format.
-------------------------------------------------------------------------------}
function TsWorksheet.HasColFormats: Boolean;
var
c: Integer;
@ -5399,6 +5401,10 @@ begin
Result := false;
end;
{@@ ----------------------------------------------------------------------------
Returns @TRUE if the workbook contains at least one row with an individual
row format.
-------------------------------------------------------------------------------}
function TsWorksheet.HasRowFormats: Boolean;
var
r: Integer;

162
components/fpspreadsheet/source/common/fpspreadsheet_cf.inc
View File

@ -76,7 +76,15 @@ end;
{@@ ----------------------------------------------------------------------------
Writes the conditional format "color range"
Writes the conditional format "color range": The cell background in the
specified cell range is painted in colors according to the cell values.
The colors are varied between the given start color (at the miniumum cell value)
and end color (at the maximum cell value).
@param ARange Range of the cells to be formatted
@param AStartColor Start color of the gradient of cell background colors corresponding to the minimum cell value in the given cell range.
@param AEndColor End color of the gradient of cell background colors corresponding to the maximum cell value in the given cell range.
-------------------------------------------------------------------------------}
function TsWorksheet.WriteColorRange(ARange: TsCellRange;
AStartColor, AEndColor: TsColor): Integer;
@ -87,6 +95,18 @@ begin
end;
{@@ ----------------------------------------------------------------------------
Writes the conditional format "color range": The cell background in the
specified cell range is painted in colors according to the cell values.
The 3-color gradient varies between the given start color (at the minimum cell value),
the center color (at the median value) and the end color (at the maximum cell value).
@param ARange Range of the cells to be formatted
@param AStartColor Start color of the background color gradient corresponding to the minimum cell value in the given cell range.
@param ACenterColor Intermediate color, corresponding to the median of the cell values.
@param AEndColor End color, corresponding to the maximum cell value.
-------------------------------------------------------------------------------}
function TsWorksheet.WriteColorRange(ARange: TsCellRange;
AStartColor, ACenterColor, AEndColor: TsColor): Integer;
begin
@ -96,6 +116,25 @@ begin
end;
{@@ ----------------------------------------------------------------------------
Writes the conditional format "color range": The cell background in the
specified cell range is painted in colors according to the cell values.
The 2-color background color gradient begins at the cell value AStartValue with
the AStartColor and is valid for the cells fulfilling the condition AStartKind.
The gradient ends at the cell value AEndValue with AEndColor for the cells
fulfilling the condition AEndKind.
@param ARange Range of the cells to be formatted
@param AStartColor First color of the background color gradient
@param AStartKind Condition for the cell(s) to be painted in AStartColor
@param AStartValue Value to be used in the AStartKind condition
@param AEndColor Last color of the background color gradient
@param AEndKind Conditions for the cell(s) to be painted in AEndColor
@param AEndValue Value to be used in the AEndKind condition
@seeAlso TsCFValueKind
-------------------------------------------------------------------------------}
function TsWorksheet.WriteColorRange(ARange: TsCellRange;
AStartColor: TsColor; AStartKind: TsCFValueKind; AStartValue: Double;
AEndColor: TsColor; AEndKind: TsCFValueKind; AEndValue: Double): Integer;
@ -107,6 +146,32 @@ begin
end;
{@@ ----------------------------------------------------------------------------
Writes the conditional format "color range"
Writes the conditional format "color range": The cell background in the
specified cell range is painted in colors according to the cell values.
The 3-color background color gradient begins at the cell value AStartValue with
the AStartColor and is valid for the cells fulfilling the condition AStartKind.
The ACenterColor is an intermediate color for the cell(s) fulfilling the
condition ACenterKind when their value is equal to ACenterValue.
The gradient ends at the cell value AEndValue with AEndColor for the cells
fulfilling the condition AEndKind.
@param ARange Range of the cells to be formatted
@param AStartColor First color of the background color gradient
@param AStartKind Condition for the cell(s) to be painted in AStartColor
@param AStartValue Value to be used in the AStartKind condition
@param ACenterColor Intermediate color of the background color gradient
@param ACenterKind Condition for the cell(s) to be painted in ACenterColor
@param ACenterValue Value to be used in the ACenterKind condition
@param AEndColor Last color of the background color gradient
@param AEndKind Conditions for the cell(s) to be painted in AEndColor
@param AEndValue Value to be used in the AEndKind condition
@seeAlso TsCFValueKind
-------------------------------------------------------------------------------}
function TsWorksheet.WriteColorRange(ARange: TsCellRange;
AStartColor: TsColor; AStartKind: TsCFValueKind; AStartValue: Double;
ACenterColor: TsColor; ACenterKind: TsCFValueKind; ACenterValue: Double;
@ -121,16 +186,31 @@ end;
{@@ ----------------------------------------------------------------------------
Writes the conditional format "data bars"
Writes the conditional format "data bars" in which the cell values are
illustrated graphically as horizontal bars.
@param ARange Range of the cells to be formatted
@param ABarColor Color of the bars
-------------------------------------------------------------------------------}
function TsWorksheet.WriteDataBars(ARange: TscellRange; ABarColor: TsColor): Integer;
function TsWorksheet.WriteDataBars(ARange: TsCellRange; ABarColor: TsColor): Integer;
begin
Result := FWorkbook.FConditionalFormatList.AddDataBarRule(Self, ARange, ABarColor);
StoreCFIndexInCells(self, Result, ARange);
end;
function TsWorksheet.WriteDataBars(ARange: TscellRange; ABarColor: TsColor;
{@@ ----------------------------------------------------------------------------
Writes the conditional format "data bars" in which the cell values are
illustrated graphically as horizontal bars.
@param ARange Range of the cells to be formatted
@param ABarColor Color of the bars
@param AStartKind Condition to be met for the cell(s) at which the bar starts
@param AStartValue Value to be used for comparison in AStartKind
@param AEndKind Condition to be met for the cell(s) at which the bar ends
@param AEndValue Value to be used for comparison in AEndKind
-------------------------------------------------------------------------------}
function TsWorksheet.WriteDataBars(ARange: TsCellRange; ABarColor: TsColor;
AStartKind: TsCFValueKind; AStartValue: Double;
AEndKind: TsCFValueKind; AEndValue: Double): Integer;
begin
@ -144,9 +224,16 @@ end;
{@@ ----------------------------------------------------------------------------
Writes the conditional format "icon set"
-------------------------------------------------------------------------------}
Writes the conditional format "icon set" in which cell values are illustrated
by means of icons.
@param ARange Range of the cells to be formatted
@param AIconSet Selection of the icon set to be used.
@param AHideText Hides the normal cell text
@param AReverse Icons are assigned in reverse order.
@seeAlso TsCFIconSet
-------------------------------------------------------------------------------}
function TsWorksheet.WriteIconSet(ARange: TsCellRange; AIconSet: TsCFIconSet;
AHideText: Boolean = false; AReverse: Boolean = false): Integer;
begin
@ -156,6 +243,22 @@ begin
StoreCFIndexInCells(self, Result, ARange);
end;
{@@ ----------------------------------------------------------------------------
Writes the conditional format "icon set" in which cell values are illustrated
by means of three icons.
@param ARange Range of the cells to be formatted
@param AIconSet Selection of the icon set to be used.
@param AValueKind1 Condition for the cell values to be displayed with the first icon in the icon set
@param AValue1 Value to be compared with in the AValueKind1 condition
@param AValueKind2 Condition for the cell values to be displayed with the second icon in the icon set
@param AValue2 Value to be compared with in the AValueKind2 condition
@param AHideText Hides the normal cell text
@param AReverse Icons are assigned in reverse order.
@seeAlso TsCFIconSet
@seeAlso TsCFValueKind
-------------------------------------------------------------------------------}
function TsWorksheet.WriteIconSet(ARange: TsCellRange; AIconSet: TsCFIconSet;
AValueKind1: TsCFValueKind; AValue1: Double;
AValueKind2: TsCFValueKind; AValue2: Double;
@ -171,6 +274,24 @@ begin
StoreCFIndexInCells(self, Result, ARange);
end;
{@@ ----------------------------------------------------------------------------
Writes the conditional format "icon set" in which cell values are illustrated
by means of four icons.
@param ARange Range of the cells to be formatted
@param AIconSet Selection of the icon set to be used.
@param AValueKind1 Condition for the cell values to be displayed with the first icon in the icon set
@param AValue1 Value to be compared with in the AValueKind1 condition
@param AValueKind2 Condition for the cell values to be displayed with the second icon in the icon set
@param AValue2 Value to be compared with in the AValueKind2 condition
@param AValueKind3 Condition for the cell values to be displayed with the third icon in the icon set
@param AValue3 Value to be compared with in the AValueKind3 condition
@param AHideText Hides the normal cell text
@param AReverse Icons are assigned in reverse order.
@seeAlso TsCFIconSet
@seeAlso TsCFValueKind
-------------------------------------------------------------------------------}
function TsWorksheet.WriteIconSet(ARange: TsCellRange; AIconSet: TsCFIconSet;
AValueKind1: TsCFValueKind; AValue1: Double;
AValueKind2: TsCFValueKind; AValue2: Double;
@ -188,6 +309,27 @@ begin
StoreCFIndexInCells(self, Result, ARange);
end;
{@@ ----------------------------------------------------------------------------
Writes the conditional format "icon set" in which cell values are illustrated
by means of five icons.
@param ARange Range of the cells to be formatted
@param AIconSet Selection of the icon set to be used.
@param AValueKind1 Condition for the cell values to be displayed with the first icon in the icon set
@param AValue1 Value to be compared with in the AValueKind1 condition
@param AValueKind2 Condition for the cell values to be displayed with the second icon in the icon set
@param AValue2 Value to be compared with in the AValueKind2 condition
@param AValueKind3 Condition for the cell values to be displayed with the third icon in the icon set
@param AValue3 Value to be compared with in the AValueKind3 condition
@param AValueKind4 Condition for the cell values to be displayed with the fourth icon in the icon set
@param AValue4 Value to be compared with in the AValueKind4 condition
@param AHideText Hides the normal cell text
@param AReverse Icons are assigned in reverse order.
@seeAlso TsCFIconSet
@seeAlso TsCFValueKind
-------------------------------------------------------------------------------}
function TsWorksheet.WriteIconSet(ARange: TsCellRange; AIconSet: TsCFIconSet;
AValueKind1: TsCFValueKind; AValue1: Double;
AValueKind2: TsCFValueKind; AValue2: Double;
@ -213,12 +355,18 @@ end;
{ TsWorkbook code for conditional formats }
{==============================================================================}
{@@ ----------------------------------------------------------------------------
Returns the conditional format record at the specified index in the workbook's
conditional format list.
-------------------------------------------------------------------------------}
function TsWorkbook.GetConditionalFormat(AIndex: Integer): TsConditionalFormat;
begin
Result := FConditionalFormatList[AIndex] as TsConditionalFormat;
end;
{@@ ----------------------------------------------------------------------------
Returns the count of conditional formats available in the the workbook.
-------------------------------------------------------------------------------}
function TsWorkbook.GetNumConditionalFormats: Integer;
begin
Result := FConditionalFormatList.Count;

4
components/fpspreadsheet/source/common/fpspreadsheet_embobj.inc
View File

@ -198,7 +198,11 @@ begin
Result := FImages.Count;
end;
{@@ ----------------------------------------------------------------------------
Returns a pointer to the image record at the specified index.
@param AIndex Index of the image to be considered.
-------------------------------------------------------------------------------}
function TsWorksheet.GetPointerToImage(AIndex: Integer): PsImage;
begin
Result := PsImage(FImages[AIndex]);

11
components/fpspreadsheet/source/common/fpspreadsheet_fmt.inc
View File

@ -136,7 +136,7 @@ begin
end;
{@@ ----------------------------------------------------------------------------
Determines which the style of a particular cell border
Determines the style of a particular cell border
-------------------------------------------------------------------------------}
function TsWorksheet.ReadCellBorderStyle(ACell: PCell;
ABorder: TsCelLBorder): TsCellBorderStyle;
@ -152,7 +152,7 @@ begin
end;
{@@ ----------------------------------------------------------------------------
Determines which all border styles of a given cell
Determines all border styles of a given cell
-------------------------------------------------------------------------------}
function TsWorksheet.ReadCellBorderStyles(ACell: PCell): TsCellBorderStyles;
var
@ -166,7 +166,6 @@ begin
end;
end;
{@@ ----------------------------------------------------------------------------
Returns the format record that is assigned to a specified cell
-------------------------------------------------------------------------------}
@ -175,7 +174,6 @@ begin
Result := Workbook.GetCellFormat(ACell^.FormatIndex);
end;
{@@ ----------------------------------------------------------------------------
Returns the protection flags of the cell.
@ -716,7 +714,12 @@ begin
WriteCellProtection(Result, AValue);
end;
{@@ ----------------------------------------------------------------------------
Defines how the specified cell is protected: lock cell modification and/or hide formulas.
Note that this is activated only after enabling worksheet protection (worksheet.Protect(true)).
@NOTE FPSpreadsheet does not enforce these actions. They are only written to the file for the Office application.
-------------------------------------------------------------------------------}
procedure TsWorksheet.WriteCellProtection(ACell: PCell;
AValue: TsCellProtections);
var