diff --git a/components/fpspreadsheet/docs/api/builddoc.bat b/components/fpspreadsheet/docs/api/builddoc.bat index cb0608a26..97b3f34fd 100644 --- a/components/fpspreadsheet/docs/api/builddoc.bat +++ b/components/fpspreadsheet/docs/api/builddoc.bat @@ -1,47 +1,5 @@ -@echo off +set pasdoc_cmd=pasdoc.exe +set hhc_cmd="C:\Program Files (x86)\HTML Help Workshop\hhc.exe" -set DOX_CMD="C:\Program Files (x86)\Doc-O-Matic 7 Express\domexpress.exe" -if not exist %DOX_CMD% goto :dox_error - -rem *** Prepare files *** -if not exist output mkdir output -pushd . -cd ..\..\source - -if not exist fps.inc goto :next1 -ren fps.inc ---fps.inc - -:next1 -if not exist fpspreadsheetctrls.lrs goto :next2 -ren fpspreadsheetctrls.lrs ---fpspreadsheetctrls.lrs - -:next2 -popd - -rem Extract help topics and create chm files... -echo Running %DOX_CMD% -config "HTML Help" fpspreadsheet.dox-express -%DOX_CMD% -config "HTML Help" fpspreadsheet.dox-express > doc-o-matic.txt - -rem *** Clean up *** -pushd . - -cd ..\..\source -chdir -if not exist ---fps.inc goto :next3 -ren ---fps.inc fps.inc - -:next3 -if not exist ---fpspreadsheetctrls.lrs goto :next4 -ren ---fpspreadsheetctrls.lrs fpspreadsheetctrls.lrs - -:next4 -popd - -if exist output\fpspreadsheet.chm copy output\fpspreadsheet.chm ..\fpspreadsheet-api.chm /y - -goto :end - -:dox_error -echo Doc-O-Matic program not found. Check the script. - -:end +%pasdoc_cmd% @options.txt --format=htmlhelp --output=output --name=fpspreadsheet --source=source-files.txt +::%hhc_cmd% output\fpspreadsheet.hhc \ No newline at end of file diff --git a/components/fpspreadsheet/docs/api/fpspreadsheet.css b/components/fpspreadsheet/docs/api/fpspreadsheet.css new file mode 100644 index 000000000..e98fe2a12 --- /dev/null +++ b/components/fpspreadsheet/docs/api/fpspreadsheet.css @@ -0,0 +1,263 @@ +/* + Copyright 1998-2018 PasDoc developers. + + This file is part of "PasDoc". + + "PasDoc" is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 2 of the License, or + (at your option) any later version. + + "PasDoc" is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with "PasDoc"; if not, write to the Free Software + Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA + + ---------------------------------------------------------------------------- +*/ + +body, html { + margin: 0; + padding: 0; +} + +body { + font-family: Verdana,Arial; + font-size: 10pt; + color: black; + background-color: white; +} + +.container { + width: 100%; + height: 100%; + border-spacing: 0; +} + +.navigation { + float: left; + width: 20em; /* must match .content margin-left */ + height: 100%; + color: white; + background-color: #787878; + position: fixed; + margin: 0; + box-sizing: border-box; /* without this, you could not have padding here, it would overlap with .content, causing errors on narrow screens */ + padding: 1em; +} +.navigation ul { + margin: 0em; + padding: 0em; +} +.navigation li { + list-style-type: none; + margin: 0.2em 0em 0em 0em; + padding: 0.25em; +} +.navigation h2 { + text-align: center; + margin: 0em; + padding: 0.5em; +} + +.content { + margin-left: 20em; /* must match .navigation width */ + box-sizing: border-box; /* without this, you could not have padding here, it would overlap with .navigation, causing errors on narrow screens */ + padding: 1em; +} +.content h1 { + margin-top: 0; +} + +.appinfo { + float: right; + text-align: right; + margin-bottom: 1em; +} + +img { border:0px; } + +hr { + border-bottom: medium none; + border-top: thin solid #888; +} + +a:link {color:#C91E0C; text-decoration: none; } +a:visited {color:#7E5C31; text-decoration: none; } +a:hover {text-decoration: underline; } +a:active {text-decoration: underline; } + +.navigation a:link { color: white; text-decoration: none; } +.navigation a:visited { color: white; text-decoration: none; } +.navigation a:hover { color: white; font-weight: bold; text-decoration: none; } +.navigation a:active { color: white; text-decoration: none; } + +a.bold:link {color:#C91E0C; text-decoration: none; font-weight:bold; } +a.bold:visited {color:#7E5C31; text-decoration: none; font-weight:bold; } +a.bold:hover {text-decoration: underline; font-weight:bold; } +a.bold:active {text-decoration: underline; font-weight:bold; } + +a.section {color: green; text-decoration: none; font-weight: bold; } +a.section:hover {color: green; text-decoration: underline; font-weight: bold; } + +ul.useslist a:link {color:#C91E0C; text-decoration: none; font-weight:bold; } +ul.useslist a:visited {color:#7E5C31; text-decoration: none; font-weight:bold; } +ul.useslist a:hover {text-decoration: underline; font-weight:bold; } +ul.useslist a:active {text-decoration: underline; font-weight:bold; } + +ul.hierarchy { list-style-type:none; } +ul.hierarchylevel { list-style-type:none; } + +p.unitlink a:link {color:#C91E0C; text-decoration: none; font-weight:bold; } +p.unitlink a:visited {color:#7E5C31; text-decoration: none; font-weight:bold; } +p.unitlink a:hover {text-decoration: underline; font-weight:bold; } +p.unitlink a:active {text-decoration: underline; font-weight:bold; } + +/* +tr.list { background: #FFBF44; } +tr.list2 { background: #FFC982; } +tr.listheader { background: #C91E0C; color: white; } +*/ +tr.list { background: #EEEEEE; } +tr.list2 { background: #F4F4F4; } +tr.listheader { background: #333333; color: white; } + +table.wide_list { border-spacing:2px; width:100%; } +table.wide_list td { vertical-align:top; padding:4px; } + +table.markerlegend { width:auto; } +table.markerlegend td.legendmarker { text-align:center; } + +.sections { background:white; } +.sections .one_section { + background:lightgray; + display: inline-block; + margin: 0.2em; + padding: 0.5em 1em; +} + +table.summary td.itemcode { width:100%; } +table.detail td.itemcode { width:100%; } + +td.itemname {white-space:nowrap; } +td.itemunit {white-space:nowrap; } +td.itemdesc { width:100%; } + +div.nodescription { color:red; } +dl.parameters dt { + color:blue; +} + +code { + font-family: monospace; + font-size:1.2em; +} + +/* style for warning and note tag */ +dl.tag.warning { + margin-left:-2px; + padding-left: 3px; + border-left:4px solid; + border-color: #FF0000; +} +dl.tag.note { + margin-left:-2px; + padding-left: 3px; + border-left:4px solid; + border-color: #D0C000; +} + +/* Various browsers have various default styles for
, + sometimes ugly for our purposes, so it's best to set things + like font-size and font-weight in out pasdoc.css explicitly. */ +h6.description_section { + /* font-size 100% means that it has the same font size as the + parent element, i.e. normal description text */ + font-size: 100%; + font-weight: bold; + /* By default browsers usually have some large margin-bottom and + margin-top for tags. In our case, margin-bottom is + unnecessary, we want to visually show that description_section + is closely related to content below. In this situation + (where the font size is just as a normal text), smaller bottom + margin seems to look good. */ + margin-top: 1.4em; + margin-bottom: 0em; +} + +/* Style applied to Pascal code in documentation + (e.g. produced by @longcode tag) } */ +.longcode { + font-family: monospace; + font-size: 1.2em; + background-color: #eee; + padding: 0.5em; + border: thin solid #ccc; +} +span.pascal_string { color: #000080; } +span.pascal_keyword { font-weight: bolder; } +span.pascal_comment { color: #000080; font-style: italic; } +span.pascal_compiler_comment { color: #008000; } +span.pascal_numeric { } +span.pascal_hex { } + +p.hint_directive { color: red; } + +input#search_text { } +input#search_submit_button { } + +acronym.mispelling { background-color: #f00; } + +/* Actually this reduces vertical space between *every* paragraph + inside list with @itemSpacing(compact). + While we would like to reduce this space only for the + top of 1st and bottom of last paragraph within each list item. + But, well, user probably will not do any paragraph breaks + within a list with @itemSpacing(compact) anyway, so it's + acceptable solution. */ +ul.compact_spacing p { margin-top: 0em; margin-bottom: 0em; } +ol.compact_spacing p { margin-top: 0em; margin-bottom: 0em; } +dl.compact_spacing p { margin-top: 0em; margin-bottom: 0em; } + +/* Style for table created by @table tags: + just some thin border. + + This way we have some borders around the cells + (so cells are visibly separated), but the border + "blends with the background" so it doesn't look too ugly. + Hopefully it looks satisfactory in most cases and for most + people. + + We add padding for cells, otherwise they look too close. + This is normal thing to do when border-collapse is set to + collapse (because this eliminates spacing between cells). +*/ +table.table_tag { border-collapse: collapse; } +table.table_tag td { border: 1pt solid gray; padding: 0.3em; } +table.table_tag th { border: 1pt solid gray; padding: 0.3em; } + +table.detail { + border: 1pt solid gray; + margin-top: 0.3em; + margin-bottom: 0.3em; +} + +.search-form { white-space: nowrap; } +.search-input input { max-width: 80%; } /* this provides some safe space to always fit even on very narrow screens */ +.search-input input, .search-button { display: inline-block; vertical-align: middle; } +.search-input { display: inline-block; } + +/* Do not make extra vertical space at the beginning/end of table cells. + We need ">" selector, to not change paragraphs inside lists inside + table cells. */ +table.table_tag td > p:first-child, +table.table_tag th > p:first-child, + td.itemdesc > p:first-child { margin-top: 0em; } + +table.table_tag td > p:last-child, +table.table_tag th > p:last-child, + td.itemdesc > p:last-child { margin-bottom: 0em; } diff --git a/components/fpspreadsheet/docs/api/fpspreadsheet.dox-express b/components/fpspreadsheet/docs/api/fpspreadsheet.dox-express deleted file mode 100644 index 5ec6b2e79..000000000 --- a/components/fpspreadsheet/docs/api/fpspreadsheet.dox-express +++ /dev/null @@ -1,895 +0,0 @@ -; This is a Doc-O-Matic version 7.0.1.1645 project file. -; This file is maintained by Doc-O-Matic, do not edit manually. - -[AutoTexts] -Empty=1 -Saved=1 -Text0=This is unknown %SYMBOLNAME%. -Text1=This is class %SYMBOLNAME%. -Text10=This is file %SYMBOLNAME%. -Text11=This is record %SYMBOLNAME%. -Text12=This is %SYMBOLNAME%. -Text13=This is nested type %SYMBOLNAME%. -Text14=This is namespace %SYMBOLNAME%. -Text2=This is %MEMBERNAME%, a member of class %CLASSNAME%. -Text3=This is %MEMBERNAME%, a member of class %CLASSNAME%. -Text4=This is %MEMBERNAME%, a member of class %CLASSNAME%. -Text5=This is function %SYMBOLNAME%. -Text6=This is type %SYMBOLNAME%. -Text7=This is variable %SYMBOLNAME%. -Text8=This is constant %SYMBOLNAME%. -Text9=This is macro %SYMBOLNAME%. - -[Configurations] -Count=3 -Current=0 -Name0=HTML -Name1=HTML Help -Name2=Help 2 - -[Configurations\Help 2\{D3A588E0-9472-11D3-BDD1-0080C8BA053D}\AdditionalFiles] -Count=4 -File0=..\..\..\..\..\..\..\Programme\Doc-O-Matic 7 Express\graphics\footer-bkg-whitegradient.gif -File1=..\..\..\..\..\..\..\Programme\Doc-O-Matic 7 Express\graphics\header-bkg-whitegradient.gif -File2=..\..\..\..\..\..\..\Programme\Doc-O-Matic 7 Express\graphics\html_fullframegradient.gif -File3=..\..\..\..\..\..\..\Programme\Doc-O-Matic 7 Express\graphics\html_titlebkg.jpg - -[Configurations\Help 2\{D3A588E0-9472-11D3-BDD1-0080C8BA053D}\General] -ClearDirectoryBeforeExport=0 -HelpKind=2 -OutputDir=output -OutputXHTML=0 -TargetBOM=1 -TargetCodepage=utf-8 - -[Configurations\Help 2\{D3A588E0-9472-11D3-BDD1-0080C8BA053D}\General Build Options] -ShowDocumentation=1 - -[Configurations\Help 2\{D3A588E0-9472-11D3-BDD1-0080C8BA053D}\HTMLHelp] -CompileFullTextSearchInformation=1 -CreateBinaryIndex=1 -CreateBinaryTOC=0 -CreateCHIFile=0 -CreateHelp2FullTextIndex=1 -DontIncludeFolders=0 -Help2AdditionalXMLData= -Help2Collection= -Help2Compiler= -Help2CompileResult=0 -Help2Dexplore= -Help2GenericInfoType=kbRef -Help2ID= -Help2Locale=kbEnglish -Help2Namespace= -Help2PluginNamespace=0 -Help2PluginNamespaceName=MS.VSIPCC+ -Help2RegisterType=0 -Help2UnregisterNamespace=1 -Help3BookName= -Help3Catalog=vs -Help3Locale=en-us -Help3PackageFilename= -Help3Product=MyProduct -Help3ProductVersion=100 -Help3RegisterBook=1 -Help3Vendor=MyCompany -HelpCompiler= -HTMLHelp2Filename= -HTMLHelpDisplayFontScaleButton=0 -HTMLHelpFilename= -SaveUserPosition=1 -SupportEnhancedDecompilation=0 -WindowPosition_Bottom=0 -WindowPosition_Left=0 -WindowPosition_Right=0 -WindowPosition_Top=0 - -[Configurations\Help 2\Image Paths] -Count=2 -Path0=..\..\..\..\..\..\..\Programme\Doc-O-Matic 7 Express\graphics -Path1=..\..\..\..\..\..\..\Programme\Doc-O-Matic 7 Express\graphics\en - -[Configurations\Help 2\Output Options] -ClassHierarchyLayoutOutputDir=output - -[Configurations\Help 2\OutputFormat] -ID={D3A588E0-9472-11D3-BDD1-0080C8BA053D} - -[Configurations\HTML Help\{D3A588E0-9472-11D3-BDD1-0080C8BA053D}\AdditionalFiles] -Count=4 -File0=..\..\..\..\..\..\..\Programme\Doc-O-Matic 7 Express\graphics\footer-bkg-whitegradient.gif -File1=..\..\..\..\..\..\..\Programme\Doc-O-Matic 7 Express\graphics\header-bkg-whitegradient.gif -File2=..\..\..\..\..\..\..\Programme\Doc-O-Matic 7 Express\graphics\html_fullframegradient.gif -File3=..\..\..\..\..\..\..\Programme\Doc-O-Matic 7 Express\graphics\html_titlebkg.jpg - -[Configurations\HTML Help\{D3A588E0-9472-11D3-BDD1-0080C8BA053D}\General] -ClearDirectoryBeforeExport=0 -HelpKind=1 -OutputDir=output -OutputXHTML=0 -TargetBOM=0 -TargetCodepage=utf-8 - -[Configurations\HTML Help\{D3A588E0-9472-11D3-BDD1-0080C8BA053D}\General Build Options] -ShowDocumentation=1 - -[Configurations\HTML Help\{D3A588E0-9472-11D3-BDD1-0080C8BA053D}\HTMLHelp] -CompileFullTextSearchInformation=1 -CreateBinaryIndex=1 -CreateBinaryTOC=1 -CreateCHIFile=0 -CreateHelp2FullTextIndex=1 -DontIncludeFolders=0 -Help2AdditionalXMLData= -Help2Collection= -Help2Compiler= -Help2CompileResult=0 -Help2Dexplore= -Help2GenericInfoType=kbRef -Help2ID= -Help2Locale=kbEnglish -Help2Namespace= -Help2PluginNamespace=0 -Help2PluginNamespaceName=MS.VSIPCC+ -Help2RegisterType=0 -Help2UnregisterNamespace=1 -Help3BookName= -Help3Catalog=vs -Help3Locale=en-us -Help3PackageFilename= -Help3Product=MyProduct -Help3ProductVersion=100 -Help3RegisterBook=1 -Help3Vendor=MyCompany -HelpCompiler=C:\Program Files (X86)\HTML Help Workshop\hhc.exe -HTMLHelp2Filename= -HTMLHelpDisplayFontScaleButton=0 -HTMLHelpFilename= -SaveUserPosition=1 -SupportEnhancedDecompilation=0 -WindowPosition_Bottom=0 -WindowPosition_Left=0 -WindowPosition_Right=0 -WindowPosition_Top=0 - -[Configurations\HTML Help\Image Paths] -Count=2 -Path0=..\..\..\..\..\..\..\Programme\Doc-O-Matic 7 Express\graphics -Path1=..\..\..\..\..\..\..\Programme\Doc-O-Matic 7 Express\graphics\en - -[Configurations\HTML Help\Output Options] -ClassHierarchyLayoutOutputDir=output - -[Configurations\HTML Help\OutputFormat] -ID={D3A588E0-9472-11D3-BDD1-0080C8BA053D} - -[Configurations\HTML\{D3A588E0-9472-11D3-BDD1-0080C8BA053D}\AdditionalFiles] -Count=4 -File0=..\..\..\..\..\..\..\Programme\Doc-O-Matic 7 Express\graphics\footer-bkg-whitegradient.gif -File1=..\..\..\..\..\..\..\Programme\Doc-O-Matic 7 Express\graphics\header-bkg-whitegradient.gif -File2=..\..\..\..\..\..\..\Programme\Doc-O-Matic 7 Express\graphics\html_fullframegradient.gif -File3=..\..\..\..\..\..\..\Programme\Doc-O-Matic 7 Express\graphics\html_titlebkg.jpg - -[Configurations\HTML\{D3A588E0-9472-11D3-BDD1-0080C8BA053D}\General] -ClearDirectoryBeforeExport=0 -HelpKind=0 -OutputDir=output -OutputXHTML=0 -TargetBOM=0 -TargetCodepage=utf-8 - -[Configurations\HTML\{D3A588E0-9472-11D3-BDD1-0080C8BA053D}\General Build Options] -ShowDocumentation=1 - -[Configurations\HTML\{D3A588E0-9472-11D3-BDD1-0080C8BA053D}\HTMLHelp] -CompileFullTextSearchInformation=1 -CreateBinaryIndex=1 -CreateBinaryTOC=0 -CreateCHIFile=0 -CreateHelp2FullTextIndex=1 -DontIncludeFolders=0 -Help2AdditionalXMLData= -Help2Collection= -Help2Compiler= -Help2CompileResult=0 -Help2Dexplore= -Help2GenericInfoType=kbRef -Help2ID= -Help2Locale=kbEnglish -Help2Namespace= -Help2PluginNamespace=0 -Help2PluginNamespaceName=MS.VSIPCC+ -Help2RegisterType=0 -Help2UnregisterNamespace=1 -Help3BookName= -Help3Catalog=vs -Help3Locale=en-us -Help3PackageFilename= -Help3Product=MyProduct -Help3ProductVersion=100 -Help3RegisterBook=1 -Help3Vendor=MyCompany -HelpCompiler= -HTMLHelp2Filename= -HTMLHelpDisplayFontScaleButton=0 -HTMLHelpFilename= -SaveUserPosition=1 -SupportEnhancedDecompilation=0 -WindowPosition_Bottom=0 -WindowPosition_Left=0 -WindowPosition_Right=0 -WindowPosition_Top=0 - -[Configurations\HTML\Image Paths] -Count=2 -Path0=..\..\..\..\..\..\..\Programme\Doc-O-Matic 7 Express\graphics -Path1=..\..\..\..\..\..\..\Programme\Doc-O-Matic 7 Express\graphics\en - -[Configurations\HTML\Output Options] -ClassHierarchyLayoutOutputDir=output - -[Configurations\HTML\OutputFormat] -ID={D3A588E0-9472-11D3-BDD1-0080C8BA053D} - -[General] -Author=Felipe Monteiro de Carvalho and Werner Pamler -AuthorEmail= -Copyright=Copyright (c) 2008-2020 -Summary=Free Pascal Spreadsheet Library -Title=FPSpreadsheet -VersionBuild=0 -VersionMajor=1 -VersionMinor=12 -VersionRelease=0 - -[Macro Header Files] -Count=0 - -[Parsing] -AssignedCommentsToFollowingSymbols=1 -CommentDistance=0 -DocUseTripleSlashOnly=0 -HeaderUnderlineCharactersCenter== -HeaderUnderlineCharactersJustify=# -HeaderUnderlineCharactersLeft=- -HeaderUnderlineCharactersRight=~ -HeadlineDelimiterChars=*#- -IgnoredTrimLineCount=1 -IgnoredTrimLine_0=__________________________________________________ -InitOptional=0 -InitSequence=@@ -ListBulletChars=*+-# -NamespaceOption=2 -ParameterDelimiterChars=:- -ParameterDescriptionMode=0 -ParametersAllowSpaceAsDelimiter=0 -SectionAllowSpaceAsDelimiter=0 -SectionDelimiterChars=:*- -SupportJavaDoc=1 -SupportJavaDocBackslashTags=0 -SupportXMLDoc=0 -TabExpandCount=4 -TrailerChars=-+~/# -WallCharacters="#$%&'*+-/=@[\]^_`{|}~ - -[Project File Info] -Version=700 - -[Section\0] -Count=3 -Description=Contains a short summary of the purpose of an object. This text usually contains one or two sentences. -DisplayName=Summary -EditorName= -JavaDocTags= -OutputFind= -OutputReplace= -SectionFlags=15 -Type=4 -Value0=Summary -Value1=Brief -Value2=Short -XMLDocTags=summary - -[Section\1] -Count=2 -Description=Contains the general description of an object. This text describes the purpose of the item. -DisplayName=Description -EditorName= -JavaDocTags= -OutputFind= -OutputReplace= -SectionFlags=15 -Type=0 -Value0=Description -Value1=Long -XMLDocTags=value - -[Section\10] -Count=3 -Description=Contains text that describes bugs or problems related to the object. -DisplayName=Bugs -EditorName= -JavaDocTags=bug -OutputFind= -OutputReplace= -SectionFlags=15 -Type=0 -Value0=Bugs -Value1=Known Bugs -Value2=Current Bugs -XMLDocTags= - -[Section\11] -Count=2 -Description=Contains documentation parts which should only be available to internal team members and not to the general public. -DisplayName=Internal -EditorName= -JavaDocTags=internal -OutputFind= -OutputReplace= -SectionFlags=15 -Type=0 -Value0=Internal -Value1=Special Info -XMLDocTags= - -[Section\12] -Count=1 -Description=Contains text that describes which parts of the object are incomplete and need additional work. -DisplayName=Todo -EditorName= -JavaDocTags=todo -OutputFind= -OutputReplace= -SectionFlags=15 -Type=0 -Value0=TODO -XMLDocTags= - -[Section\13] -Count=3 -Description=Contains text that describes which exceptions can be raised by a function or method. -DisplayName=Exceptions -EditorName= -JavaDocTags=exception,exceptions,throws,raises -OutputFind= -OutputReplace= -SectionFlags=15 -Type=12 -Value0=Exceptions -Value1=Throws -Value2=Raises -XMLDocTags=exception - -[Section\14] -Count=2 -Description=Contains text that describes conditions (for example pre- and postconditions) for a function call. -DisplayName=Conditions -EditorName= -JavaDocTags= -OutputFind= -OutputReplace= -SectionFlags=15 -Type=0 -Value0=Conditions -Value1=Preconditions -XMLDocTags=permission - -[Section\15] -Count=2 -Description=Contains information who the author(s) of a topic are -DisplayName=Author -EditorName= -JavaDocTags=author -OutputFind= -OutputReplace= -SectionFlags=15 -Type=0 -Value0=Author -Value1=Authors -XMLDocTags= - -[Section\16] -Count=1 -Description=Contains text which describes the history of the object -DisplayName=History -EditorName= -JavaDocTags=since,history -OutputFind= -OutputReplace= -SectionFlags=15 -Type=0 -Value0=History -XMLDocTags= - -[Section\17] -Count=2 -Description=Contains version information of the object. -DisplayName=Version -EditorName= -JavaDocTags=version -OutputFind= -OutputReplace= -SectionFlags=15 -Type=0 -Value0=Version -Value1=Current Version -XMLDocTags= - -[Section\18] -Count=1 -Description=Contains the text for the glossary entry of the topic. -DisplayName=Glossary -EditorName= -JavaDocTags= -OutputFind= -OutputReplace= -SectionFlags=15 -Type=7 -Value0=Glossary -XMLDocTags= - -[Section\19] -Count=3 -Description=Contains the text for the description of the implementation source of functions. -DisplayName=Source Description -EditorName= -JavaDocTags= -OutputFind= -OutputReplace= -SectionFlags=15 -Type=9 -Value0=Source Description -Value1=Implementation Notes -Value2=Implementation Description -XMLDocTags= - -[Section\2] -Count=1 -Description=Used for one or more short notes on an object. -DisplayName=Notes -EditorName= -JavaDocTags= -OutputFind= -OutputReplace= -SectionFlags=15 -Type=0 -Value0=Note -XMLDocTags= - -[Section\20] -Count=4 -Description=Like a standard section with the additional possibility to give it an individual name in each topic it is used. -DisplayName=Link List -EditorName= -JavaDocTags= -OutputFind= -OutputReplace= -SectionFlags=15 -Type=10 -Value0=Link List -Value1=Membergroups -Value2=Member Groups -Value3=Class Group -XMLDocTags= - -[Section\21] -Count=1 -Description=Contains the Pascal declaration syntax. It will be generated automatically if it does not exist in a topic. -DisplayName=Pascal -EditorName= -JavaDocTags= -OutputFind= -OutputReplace= -SectionFlags=9 -Type=21 -Value0=Pascal Syntax -XMLDocTags= - -[Section\22] -Count=1 -Description=Contains the C++ declaration syntax. It will be generated automatically if it does not exist in a topic. -DisplayName=C++ -EditorName= -JavaDocTags= -OutputFind= -OutputReplace= -SectionFlags=9 -Type=22 -Value0=C++ Syntax -XMLDocTags= - -[Section\23] -Count=1 -Description=Contains the C# declaration syntax. It will be generated automatically if it does not exist in a topic. -DisplayName=C# -EditorName= -JavaDocTags= -OutputFind= -OutputReplace= -SectionFlags=9 -Type=23 -Value0=C# Syntax -XMLDocTags= - -[Section\24] -Count=1 -Description=Contains the Visual Basic declaration syntax. It will be generated automatically if it does not exist in a topic. -DisplayName=Visual Basic -EditorName= -JavaDocTags= -OutputFind= -OutputReplace= -SectionFlags=9 -Type=24 -Value0=Visual Basic Syntax -XMLDocTags= - -[Section\25] -Count=1 -Description=Contains the Java declaration syntax. It will be generated automatically if it does not exist in a topic. -DisplayName=Java -EditorName= -JavaDocTags= -OutputFind= -OutputReplace= -SectionFlags=9 -Type=25 -Value0=Java Syntax -XMLDocTags= - -[Section\26] -Count=1 -Description=Contains the IDL declaration syntax. It will be generated automatically if it does not exist in a topic. -DisplayName=IDL -EditorName= -JavaDocTags= -OutputFind= -OutputReplace= -SectionFlags=9 -Type=26 -Value0=IDL Syntax -XMLDocTags= - -[Section\27] -Count=1 -Description=Contains the JavaScript declaration syntax. It will be generated automatically if it does not exist in a topic. -DisplayName=JavaScript -EditorName= -JavaDocTags= -OutputFind= -OutputReplace= -SectionFlags=9 -Type=27 -Value0=JavaScript Syntax -XMLDocTags= - -[Section\28] -Count=1 -Description=Contains the MATLAB declaration syntax. It will be generated automatically if it does not exist in a topic. -DisplayName=MATLAB -EditorName= -JavaDocTags= -OutputFind= -OutputReplace= -SectionFlags=9 -Type=29 -Value0=MATLAB Syntax -XMLDocTags= - -[Section\29] -Count=1 -Description=Contains the PHP declaration syntax. It will be generated automatically if it does not exist in a topic. -DisplayName=PHP -EditorName= -JavaDocTags= -OutputFind= -OutputReplace= -SectionFlags=9 -Type=30 -Value0=PHP Syntax -XMLDocTags= - -[Section\3] -Count=1 -Description=Used for special remarks on a topic. Contrary to Notes, this text can be fairly long. -DisplayName=Remarks -EditorName= -JavaDocTags= -OutputFind= -OutputReplace= -SectionFlags=15 -Type=0 -Value0=Remarks -XMLDocTags=remarks - -[Section\30] -Count=0 -Description=Automatically filled section that contains a table of members of structs, records, enumerations and unions along with their descriptions. -DisplayName=Members -EditorName= -JavaDocTags= -OutputFind= -OutputReplace= -SectionFlags=15 -Type=13 -XMLDocTags= - -[Section\31] -Count=0 -Description=Automatically filled section that contains navigation listings for class and namespace members and sub-topics. -DisplayName=Navigation -EditorName= -JavaDocTags= -OutputFind= -OutputReplace= -SectionFlags=15 -Type=14 -XMLDocTags= - -[Section\32] -Count=0 -Description=Automatically filled section that contains the body source code for functions and files. -DisplayName=Body Source -EditorName= -JavaDocTags= -OutputFind= -OutputReplace= -SectionFlags=15 -Type=16 -XMLDocTags= - -[Section\33] -Count=0 -Description=Automatically filled section that contains the local class hierarchy for a single class. -DisplayName=Class Hierarchy -EditorName= -JavaDocTags= -OutputFind= -OutputReplace= -SectionFlags=15 -Type=17 -XMLDocTags= - -[Section\34] -Count=0 -Description=Automatically filled section that contains a link to the file in which a symbol is declared. -DisplayName=File -EditorName= -JavaDocTags= -OutputFind= -OutputReplace= -SectionFlags=15 -Type=18 -XMLDocTags= - -[Section\35] -Count=0 -Description=Automatically filled section that contains a list of links to pages with more information about the topic that are maintained by Doc-O-Matic -DisplayName=Links -EditorName= -JavaDocTags= -OutputFind= -OutputReplace= -SectionFlags=15 -Type=19 -XMLDocTags= - -[Section\36] -Count=0 -Description=Automatically filled section that contains the reports assigned to a topic. -DisplayName=Reports -EditorName= -JavaDocTags= -OutputFind= -OutputReplace= -SectionFlags=15 -Type=20 -XMLDocTags= - -[Section\37] -Count=0 -Description=Automatically filled section that contains an overview for overloaded member functions. -DisplayName=Overload List -EditorName= -JavaDocTags= -OutputFind= -OutputReplace= -SectionFlags=15 -Type=28 -XMLDocTags= - -[Section\38] -Count=1 -Description=Contains multiple glossary entries of the topic. -DisplayName=Multi Item Glossary -EditorName= -JavaDocTags= -OutputFind= -OutputReplace= -SectionFlags=15 -Type=12 -Value0=Multi Item Glossary -XMLDocTags= - -[Section\39] -Count=1 -Description=Contains a parameter descriptions for generic types. -DisplayName=Type Parameters -EditorName= -JavaDocTags= -OutputFind= -OutputReplace= -SectionFlags=15 -Type=1 -Value0=Type Parameters -XMLDocTags=typeparam - -[Section\4] -Count=4 -Description=Used for detailed descriptions of each parameter of a global or member function. -DisplayName=Parameters -EditorName= -JavaDocTags= -OutputFind= -OutputReplace= -SectionFlags=15 -Type=1 -Value0=Parameters -Value1=Arguments -Value2=Inputs -Value3=Input -XMLDocTags= - -[Section\40] -Count=2 -Description=Contains information on the license -DisplayName=License -EditorName= -JavaDocTags=license -OutputFind= -OutputReplace= -SectionFlags=15 -Type=0 -Value0=License -Value1=Licenses -XMLDocTags= - -[Section\5] -Count=4 -Description=Used to generally describe the return value of a global or member function. -DisplayName=Returns -EditorName= -JavaDocTags=return,returns -OutputFind= -OutputReplace= -SectionFlags=15 -Type=2 -Value0=Returns -Value1=Return Value -Value2=Result -Value3=Output -XMLDocTags=returns - -[Section\6] -Count=2 -Description=Used to describe all possible return values in detail in form of a value-description list. -DisplayName=Return Values -EditorName= -JavaDocTags= -OutputFind= -OutputReplace= -SectionFlags=15 -Type=11 -Value0=Return Value List -Value1=Return Value Details -XMLDocTags= - -[Section\7] -Count=3 -Description=Used for one or more usage examples of the object being described. -DisplayName=Example -EditorName= -JavaDocTags= -OutputFind= -OutputReplace= -SectionFlags=15 -Type=3 -Value0=Example -Value1=Examples -Value2=Sample -XMLDocTags=example - -[Section\8] -Count=8 -Description=All text that appears in this section is ignored. -DisplayName=Ignore -EditorName= -JavaDocTags=beaninfo,component,deprecated,event,exclude,index,obsolete,seealso,serial,serialdata,serialfield,tutorial -OutputFind= -OutputReplace= -SectionFlags=8 -Type=6 -Value0=Ignore Text -Value1=$Log -Value2=$Filename -Value3=$Revision -Value4=$Date -Value5=$Author -Value6=$History -Value7=$Id -XMLDocTags= - -[Section\9] -Count=2 -Description=Contains a comma separated list of topic IDs which build the see also list of the topic. -DisplayName=See Also -EditorName= -JavaDocTags= -OutputFind= -OutputReplace= -SectionFlags=15 -Type=5 -Value0=See Also -Value1=Seealso -XMLDocTags= - -[Sections] -Count=41 -DefID=1 -ID0=0 -ID1=1 -ID10=10 -ID11=11 -ID12=12 -ID13=13 -ID14=14 -ID15=15 -ID16=16 -ID17=17 -ID18=18 -ID19=19 -ID2=2 -ID20=20 -ID21=21 -ID22=22 -ID23=23 -ID24=24 -ID25=25 -ID26=26 -ID27=27 -ID28=28 -ID29=29 -ID3=3 -ID30=30 -ID31=31 -ID32=32 -ID33=33 -ID34=34 -ID35=35 -ID36=36 -ID37=37 -ID38=38 -ID39=39 -ID4=4 -ID40=40 -ID5=5 -ID6=6 -ID7=7 -ID8=8 -ID9=9 -SavedValues=1 - -[Source Files] -Count=7 -File0=..\..\source\common\fpsimages.pas -File1=..\..\source\common\fpsnumformat.pas -File2=..\..\source\common\fpspreadsheet.pas -File3=..\..\source\common\fpstypes.pas -File4=..\..\source\common\fpsutils.pas -File5=..\..\source\visual\fpspreadsheetctrls.pas -File6=..\..\source\visual\fpspreadsheetgrid.pas - -[Source Include Directories] -Count=0 - diff --git a/components/fpspreadsheet/docs/api/options.txt b/components/fpspreadsheet/docs/api/options.txt new file mode 100644 index 000000000..66d3d605f --- /dev/null +++ b/components/fpspreadsheet/docs/api/options.txt @@ -0,0 +1,9 @@ +css=fpspreadsheet.css +marker=@@ +implementation-comments=join +ignore-leading=- +sort=methods,properties,constants,functions,variables,types +markdown +visible-members=protected,public,published +include=../../source +include=../../source/common diff --git a/components/fpspreadsheet/docs/api/source-files.txt b/components/fpspreadsheet/docs/api/source-files.txt new file mode 100644 index 000000000..4f1008b67 --- /dev/null +++ b/components/fpspreadsheet/docs/api/source-files.txt @@ -0,0 +1,7 @@ +../../source/common/fpspreadsheet.pas +../../source/common/fpstypes.pas +../../source/common/fpsutils.pas +../../source/common/fpsimages.pas +../../source/common/fpsnumformat.pas +../../source/common/fpsallformats.pas +../../source/common/fpsrpn.pas diff --git a/components/fpspreadsheet/docs/fpspreadsheet-api.chm b/components/fpspreadsheet/docs/fpspreadsheet-api.chm index bf8833346..fa984cbf3 100644 Binary files a/components/fpspreadsheet/docs/fpspreadsheet-api.chm and b/components/fpspreadsheet/docs/fpspreadsheet-api.chm differ diff --git a/components/fpspreadsheet/source/common/fpsallformats.pas b/components/fpspreadsheet/source/common/fpsallformats.pas index f1f5bceb8..c486fddb0 100644 --- a/components/fpspreadsheet/source/common/fpsallformats.pas +++ b/components/fpspreadsheet/source/common/fpsallformats.pas @@ -1,10 +1,10 @@ -{ -fpsallformats.pas - -Unit to quickly add all supported fpspreadsheet formats to the project +{@@ ---------------------------------------------------------------------------- + Unit **fpsallformats** quickly adds all supported fpspreadsheet format + readers/writers to the project. AUTHORS: Felipe Monteiro de Carvalho -} +-------------------------------------------------------------------------------} + unit fpsallformats; interface diff --git a/components/fpspreadsheet/source/common/fpsimages.pas b/components/fpspreadsheet/source/common/fpsimages.pas index 730a37646..af06e729e 100644 --- a/components/fpspreadsheet/source/common/fpsimages.pas +++ b/components/fpspreadsheet/source/common/fpsimages.pas @@ -1,3 +1,12 @@ +{@@ ---------------------------------------------------------------------------- + Unit **fpsImages** implements basic routines for **embedding images** in + worksheets. + + AUTHORS: Werner Pamler + + LICENSE: See the file COPYING.modifiedLGPL.txt, included in the Lazarus + distribution, for details about the license. +-------------------------------------------------------------------------------} unit fpsImages; {$mode objfpc}{$H+} @@ -703,16 +712,13 @@ end; {@@ ---------------------------------------------------------------------------- Returns the width and height of the image loaded into the specified stream. - @param AStream Stream containing the image to be analyzed. It is - assumed that the image begins at stream start. + @param AStream Stream containing the image to be analyzed. It is assumed that the image begins at stream start. @param AWidthInches Image width, in inches @param AHeightInches Image height, in inches - @param AImageType Type of the image to be assumed. If this parameter is - missing or itUnknown then the image type is determined - from the file header. + @param AImageType Type of the image to be assumed. If this parameter is missing or itUnknown then the image type is determined from the file header. - @return Image type code found from the file header. - @see RegisterImageType + @returns Image type code found from the file header. + @seeAlso RegisterImageType -------------------------------------------------------------------------------} function GetImageInfo(AStream: TStream; out AWidthInches, AHeightInches: Double; AImagetype: TsImageType = itUnknown): TsImageType; @@ -730,18 +736,15 @@ end; {@@ ---------------------------------------------------------------------------- Returns the width and height of the image loaded into the specified stream. - @param AStream Stream containing the image to be analyzed. It is - assumed that the image begins at stream start. + @param AStream Stream containing the image to be analyzed. It is assumed that the image begins at stream start. @param AWidth Image width, in pixels @param AHeight Image height, in pixels @param dpiX Pixel density in x direction, per inch @param dpiY Pixel density in y direction, per inch - @param AImageType Type of the image to be assumed. If this parameter is - missing or itUnknown then the image type is determined - from the file header. + @param AImageType Type of the image to be assumed. If this parameter is missing or itUnknown then the image type is determined from the file header. - @return Image type code found from the file header. - @see RegisterImageType + @returns Image type code found from the file header. + @seeAlso RegisterImageType -------------------------------------------------------------------------------} function GetImageInfo(AStream: TStream; out AWidth, AHeight: DWord; out dpiX, dpiY: Double; AImageType: TsImageType = itUnknown): TsImageType; @@ -769,9 +772,8 @@ end; {@@ ---------------------------------------------------------------------------- Returns the MimeType of the specified image type - @param AImageType Format code of the image type as returned from the - image registration procedure - @return MimeType of the file format + @param AImageType Format code of the image type as returned from the image registration procedure + @returns MimeType of the file format as string -------------------------------------------------------------------------------} function GetImageMimeType(AImageType: TsImageType): String; begin @@ -785,6 +787,9 @@ end; Returns the file extension belonging the specified image type. If there are several extensions the first one is selected. The extension is returned without a leading period. + + @param AImageType Format code of the image type as returned from the image registration procedure + @returns String with the file extension used by this image type (without leading dot). -------------------------------------------------------------------------------} function GetImageTypeExt(AImageType: TsImageType): String; var @@ -805,9 +810,9 @@ end; Extracts the image file type identifier from the extension of the specified file name. - @param AFileName Name of the file to be analyzed - @return Format code value as returned from the image registration procedure - @see RegisterImageType, itXXXX values. + @param AFileName Name of the file to be analyzed + @returns Format code value as returned from the image registration procedure + @seeAlso RegisterImageType -------------------------------------------------------------------------------} function GetImageTypeFromFileName(const AFilename: String): TsImageType; var @@ -835,12 +840,10 @@ end; {@@ ---------------------------------------------------------------------------- Registers an image type for usage in fpspreadsheet - @param AExt Extension(s) of the file format. Separate by "|" if a - file format can use several extensions. - @param AMimeType MimeType of the file format, for usage by ods - @param AGetImageSize Function which can extract the image size and - pixel density. It should only read the file header. - @return Identifier of the image type (consecutive number) + @param AExt Extension(s) of the file format. Separate by "|" if a file format can use several extensions. + @param AMimeType MimeType of the file format, for usage by ods + @param AGetImageSize Function which can extract the image size and pixel density. It should only read the file header. + @returns Identifier of the image type (consecutive number) -------------------------------------------------------------------------------} function RegisterImageType(AMimeType, AExt: String; AGetImageSize: TGetImageSizeFunc): TsImageType; diff --git a/components/fpspreadsheet/source/common/fpsnumformat.pas b/components/fpspreadsheet/source/common/fpsnumformat.pas index 71e6a7874..8e1f93920 100644 --- a/components/fpspreadsheet/source/common/fpsnumformat.pas +++ b/components/fpspreadsheet/source/common/fpsnumformat.pas @@ -1,6 +1,6 @@ {@@ ---------------------------------------------------------------------------- - Unit fpsNumFormat contains classes and procedures to analyze and process - number formats. + Unit @bold(fpsNumFormat) contains classes and procedures to analyze and process + @bold(number formats). AUTHORS: Werner Pamler @@ -97,15 +97,16 @@ type ); {@@ Element of the parsed number format sequence. Each element is identified - by a token and has optional parameters stored as integer, float, and/or text. } + by a token and has optional parameters stored as integer, float, and/or text. + + @member Token Identifies the number format element + @member IntValue Integer value associated with the number format element + @member FloatValue Floating point value associated with the number format element + @member TextValue String value associated with the number format element } TsNumFormatElement = record - {@@ Token identifying the number format element } Token: TsNumFormatToken; - {@@ Integer value associated with the number format element } IntValue: Integer; - {@@ Floating point value associated with the number format element } FloatValue: Double; - {@@ String value associated with the number format element } TextValue: String; end; @@ -157,7 +158,7 @@ type { TsNumFormatParams } {@@ Describes a parsed number format and provides all the information to - convert a number to a number or date/time string. These data are created + convert a number value to a number or date/time string. These data are created by the number format parser from a format string. } TsNumFormatParams = class(TObject) private @@ -190,7 +191,7 @@ type {@@ List containing parsed number format parameters } TsNumFormatList = class(TFPList) - private + { private } FOwnsData: Boolean; function GetItem(AIndex: Integer): TsNumFormatParams; procedure SetItem(AIndex: Integer; const AValue: TsNumFormatParams); @@ -297,7 +298,6 @@ type end; - { Utility functions } function AddAMPM(const ATimeFormatString: String; @@ -381,7 +381,7 @@ uses fpsUtils, fpsCurrency; const - {@@ Array of format strings identifying the order of number and + { Array of format strings identifying the order of number and currency symbol of a positive currency value. The number is expected at index 0, the currency symbol at index 1 of the parameter array used by the fpc Format() function. } @@ -391,7 +391,7 @@ const ('%1:s %0:s'), // 2: $ 1 ('%0:s %1:s') // 3: 1 $ ); - {@@ Array of format strings identifying the order of number and + { Array of format strings identifying the order of number and currency symbol of a negative currency value. The sign is shown as a dash character ("-") or by means of brackets. The number is expected at index 0, the currency symbol at index 1 of the @@ -420,26 +420,26 @@ const {==============================================================================} type - {@@ Set of parsed number format tokens } + { Set of parsed number format tokens } TsNumFormatTokenSet = set of TsNumFormatToken; const - {@@ Set of tokens which terminate number information in a format string } + { Set of tokens which terminate number information in a format string } TERMINATING_TOKENS: TsNumFormatTokenSet = [nftSpace, nftText, nftEscaped, nftPercent, nftCurrSymbol, nftSign, nftSignBracket]; - {@@ Set of tokens which describe the integer part of a number format } + { Set of tokens which describe the integer part of a number format } INT_TOKENS: TsNumFormatTokenSet = [nftIntOptDigit, nftIntZeroDigit, nftIntSpaceDigit]; - {@@ Set of tokens which describe the decimals of a number format } + { Set of tokens which describe the decimals of a number format } DECS_TOKENS: TsNumFormatTokenSet = [nftZeroDecs, nftOptDecs, nftSpaceDecs]; - {@@ Set of tokens which describe the numerator of a fraction format } + { Set of tokens which describe the numerator of a fraction format } FRACNUM_TOKENS: TsNumFormatTokenSet = [nftFracNumOptDigit, nftFracNumZeroDigit, nftFracNumSpaceDigit]; - {@@ Set of tokens which describe the denominator of a fraction format } + { Set of tokens which describe the denominator of a fraction format } FRACDENOM_TOKENS: TsNumFormatTokenSet = [nftFracDenomOptDigit, nftFracDenomZeroDigit, nftFracDenomSpaceDigit, nftFracDenom]; - {@@ Set of tokens which describe the exponent in exponential formatting of a number } + { Set of tokens which describe the exponent in exponential formatting of a number } EXP_TOKENS: TsNumFormatTokenSet = [nftExpDigits]; // todo: expand by optional digits (0.00E+#) @@ -897,14 +897,10 @@ end; Converts a floating point number to a string as determined by the specified number format parameters - @param AValue Value to be converted to a string - @param AParams Number format parameters which will be applied in the - conversion. The number format params are obtained - by the number format parser from the number format - string. - @param AFormatSettings Format settings needed by the number format parser for - the conversion - @return Converted string + @param AValue Value to be converted to a string + @param AParams Number format parameters which will be applied in the conversion. The number format params are obtained by the number format parser from the number format string. + @param AFormatSettings Format settings needed by the number format parser for the conversion + @returns Converted string -------------------------------------------------------------------------------} function ConvertFloatToStr(AValue: Double; AParams: TsNumFormatParams; AFormatSettings: TFormatSettings): String; @@ -1126,11 +1122,11 @@ end; {@@ ---------------------------------------------------------------------------- Adds an AM/PM format code to a pre-built time formatting string. - @param ATimeFormatString String of time formatting codes (such as 'hh:nn') - @param AFormatSettings FormatSettings for locale-dependent information - @result Formatting string with AM/PM option activated. - Example: ATimeFormatString = 'hh:nn' ==> 'hh:nn AM/PM' + + @param ATimeFormatString String of time formatting codes (such as 'hh:nn') + @param AFormatSettings FormatSettings for locale-dependent information + @returns Formatting string with AM/PM option activated. -------------------------------------------------------------------------------} function AddAMPM(const ATimeFormatString: String; const AFormatSettings: TFormatSettings): String; @@ -1143,10 +1139,8 @@ end; first time symbol must be enclosed by square brackets. Checks if this is true, and adds the brackes if not. - @param AFormatString String with time formatting codes - @return Unchanged format string if its first time code is in square brackets - (as in '[h]:nn:ss'). If not, the first time code is enclosed in - square brackets. + @param AFormatString String with time formatting codes + @returns Unchanged format string if its first time code is in square brackets (as in '[h]:nn:ss'). If not, the first time code is enclosed in square brackets. -------------------------------------------------------------------------------} function AddIntervalBrackets(AFormatString: String): String; var @@ -1170,10 +1164,8 @@ end; Builds a string list with samples of the predefined currency formats @param AList String list in which the format samples are stored - @param APositive If true, samples are built for positive currency - values, otherwise for negative values - @param AValue Currency value to be used when calculating the sample - strings + @param APositive If @true, samples are built for positive currency values, otherwise for negative values + @param AValue Currency value to be used when calculating the sample strings @param ACurrencySymbol Currency symbol string to be used in the samples -------------------------------------------------------------------------------} procedure BuildCurrencyFormatList(AList: TStrings; @@ -1212,27 +1204,17 @@ end; or minus signs) is taken from the provided format settings. The format string consists of three sections, separated by semicolons. - @param ANumberFormat Identifier of the built-in number format for which the - format string is to be generated. - @param AFormatSettings FormatSettings to be applied (used to extract default - values for the parameters following) - @param ADecimals number of decimal places. If < 0, the CurrencyDecimals - of the FormatSettings is used. - @param APosCurrFmt Identifier for the order of currency symbol, value and - spaces of positive values - - see pcfXXXX constants in fpsTypes.pas. - If < 0, the CurrencyFormat of the FormatSettings is used. - @param ANegCurrFmt Identifier for the order of currency symbol, value and - spaces of negative values. Specifies also usage of (). - - see ncfXXXX constants in fpsTypes.pas. - If < 0, the NegCurrFormat of the FormatSettings is used. - @param ACurrencySymbol String to identify the currency, like $ or USD. - If ? the CurrencyString of the FormatSettings is used. + Example: '"$"#,##0.00;("$"#,##0.00);"$"0.00' + + @param ANumberFormat Identifier of the built-in number format for which the format string is to be generated. + @param AFormatSettings FormatSettings to be applied (used to extract default values for the parameters following) + @param ADecimals number of decimal places. If < 0, the CurrencyDecimals of the FormatSettings is used. + @param APosCurrFmt Identifier for the order of currency symbol, value and spaces of positive values - see pcfXXXX constants in fpsTypes.pas. If < 0, the CurrencyFormat of the FormatSettings is used. + @param ANegCurrFmt Identifier for the order of currency symbol, value and spaces of negative values. Specifies also usage of (). - see ncfXXXX constants in fpsTypes.pas. If < 0, the NegCurrFormat of the FormatSettings is used. + @param ACurrencySymbol String to identify the currency, like $ or USD. If ? the CurrencyString of the FormatSettings is used. @param Accounting If true, adds spaces for alignment of decimals - @return String of formatting codes - - @example '"$"#,##0.00;("$"#,##0.00);"$"0.00' + @returns String of formatting codes -------------------------------------------------------------------------------} function BuildCurrencyFormatString(ANumberFormat: TsNumberFormat; const AFormatSettings: TFormatSettings; @@ -1293,14 +1275,10 @@ end; {@@ ---------------------------------------------------------------------------- Builds a date/time format string from the number format code. - @param ANumberFormat built-in number format identifier - @param AFormatSettings Format settings from which locale-dependent - information like day-month-year order is taken. - @param AFormatString Optional pre-built formatting string. It is used - only for the format nfInterval where square brackets - are added to the first time code field. - @return String of date/time formatting code constructed from the built-in - format information. + @param ANumberFormat Built-in number format identifier + @param AFormatSettings Format settings from which locale-dependent information like day-month-year order is taken. + @param AFormatString Optional pre-built formatting string. It is used only for the format nfInterval where square brackets are added to the first time code field. + @returns String of date/time formatting code constructed from the built-in format information. -------------------------------------------------------------------------------} function BuildDateTimeFormatString(ANumberFormat: TsNumberFormat; const AFormatSettings: TFormatSettings; AFormatString: String = '') : string; @@ -1369,13 +1347,11 @@ end; Builds a number format string for fraction formatting from the number format code and the count of numerator and denominator digits. - @param AMixedFraction If TRUE, fraction is presented as mixed fraction - @param ANumeratorDigits Count of numerator digits - @param ADenominatorDigits Count of denominator digits. If the value is negative - then its absolute value is inserted literally as - as denominator. + @param AMixedFraction If @TRUE, fraction is presented as mixed fraction + @param ANumeratorDigits Count of numerator digits + @param ADenominatorDigits Count of denominator digits. If the value is negative then its absolute value is inserted literally as as denominator. - @return String of formatting code, here something like: '##/##' or '# ##/##' + @returns String of formatting code, here something like: '##/##' or '# ##/##' -------------------------------------------------------------------------------} function BuildFractionFormatString(AMixedFraction: Boolean; ANumeratorDigits, ADenominatorDigits: Integer): String; @@ -1396,19 +1372,15 @@ end; Builds a number format string from the number format code and the count of decimal places. - @param ANumberFormat Identifier of the built-in numberformat for which a - format string is to be generated + Example: ANumberFormat = nfFixedTh, ADecimals = 2 --> '#,##0.00' + + @param ANumberFormat Identifier of the built-in numberformat for which a format string is to be generated @param AFormatSettings FormatSettings for default parameters - @param ADecimals Number of decimal places. If < 0 the CurrencyDecimals - value of the FormatSettings is used. In case of a - fraction format "ADecimals" refers to the maximum count - digits of the denominator. - @param AMinIntDigits minimum count of integer digits, i.e. count of '0' in - the format string before the decimal separator + @param ADecimals Number of decimal places. If < 0 the CurrencyDecimals value of the FormatSettings is used. In case of a fraction format "ADecimals" refers to the maximum count digits of the denominator. + @param AMinIntDigits Minimum count of integer digits, i.e. count of '0' in the format string before the decimal separator - @return String of formatting codes + @returns String of formatting codes - @example ANumberFormat = nfFixedTh, ADecimals = 2 --> '#,##0.00' -------------------------------------------------------------------------------} function BuildNumberFormatString(ANumberFormat: TsNumberFormat; const AFormatSettings: TFormatSettings; ADecimals: Integer = -1; @@ -1467,14 +1439,10 @@ end; The format string is created according to Excel convention (which is understood by ODS as well). - @param ASection Parsed section of number format elements as created by the - number format parser - @param AllowLocalizedAMPM Replaces "AMPM" in a time format string by "AM/PM". - "AMPM" is allowed by FPS, but not by Excel. When converting a time to - string it is replaced by the localized strings - FormatSettings.TimeAMString/.TimePMString. + @param ASection Parsed section of number format elements as created by the number format parser + @param AllowLocalizedAMPM Replaces "AMPM" in a time format string by "AM/PM". "AMPM" is allowed by FPS, but not by Excel. When converting a time to string it is replaced by the localized strings FormatSettings.TimeAMString/.TimePMString. - @return Excel-compatible format string + @returns Excel-compatible format string -------------------------------------------------------------------------------} function BuildFormatStringFromSection(const ASection: TsNumFormatSection; AllowLocalizedAMPM: Boolean = true): String; @@ -1583,11 +1551,9 @@ end; {@@ ---------------------------------------------------------------------------- Counts how many decimal places are coded into a given number format string. - @param AFormatString String with number format codes, such as '0.000' - @param ADecChars Characters which are considered as symbols for decimals. - For the fixed decimals, this is the '0'. Optional - decimals are encoced as '#'. - @return Count of decimal places found (3 in above example). + @param AFormatString String with number format codes, such as '0.000' + @param ADecChars Characters which are considered as symbols for decimals. For the fixed decimals, this is the '0'. Optional decimals are encoced as '#'. + @returns Count of decimal places found -------------------------------------------------------------------------------} function CountDecs(AFormatString: String; ADecChars: TsDecsChars = ['0']): Byte; var @@ -1633,7 +1599,7 @@ end; {@@ ---------------------------------------------------------------------------- Checks whether the specified text corresponds to a boolean value. For this, - it must match the specified TRUE and FALSE text phrases. + it must match the specified @TRUE and @FALSE text phrases. -------------------------------------------------------------------------------} function IsBoolValue(const AText, ATrueText, AFalseText: String; out AValue: Boolean): Boolean; @@ -1655,8 +1621,8 @@ end; Checks whether the given number format code is for currency, i.e. requires a currency symbol. - @param AFormat Built-in number format identifier to be checked - @return True if AFormat is nfCurrency or nfCurrencyRed, false otherwise. + @param AFormat Built-in number format identifier to be checked + @returns @True if AFormat is nfCurrency or nfCurrencyRed, @false otherwise. -------------------------------------------------------------------------------} function IsCurrencyFormat(AFormat: TsNumberFormat): Boolean; begin @@ -1666,9 +1632,8 @@ end; {@@ ---------------------------------------------------------------------------- Checks whether the specified number format parameters apply to currency values. - @param ANumFormat Number format parameters - @return True if Kind of the 1st format parameter section contains the - nfkCurrency elements; false otherwise + @param ANumFormat Number format parameters + @returns @True if Kind of the 1st format parameter section contains the nfkCurrency elements; @false otherwise -------------------------------------------------------------------------------} function IsCurrencyFormat(ANumFormat: TsNumFormatParams): Boolean; begin @@ -1679,9 +1644,8 @@ end; {@@ ---------------------------------------------------------------------------- Checks whether the given number format code is for date/time values. - @param AFormat Built-in number format identifier to be checked - @return True if AFormat is a date/time format (such as nfShortTime), - false otherwise + @param AFormat Built-in number format identifier to be checked + @returns @True if AFormat is a date/time format (such as nfShortTime), @false otherwise -------------------------------------------------------------------------------} function IsDateTimeFormat(AFormat: TsNumberFormat): Boolean; begin @@ -1693,9 +1657,8 @@ end; {@@ ---------------------------------------------------------------------------- Checks whether the given string with formatting codes is for date/time values. - @param AFormatStr String with formatting codes to be checked. - @return True if AFormatStr is a date/time format string (such as 'hh:nn'), - false otherwise + @param AFormatStr String with formatting codes to be checked. + @returns @True if AFormatStr is a date/time format string (such as 'hh:nn'), @false otherwise -------------------------------------------------------------------------------} function IsDateTimeFormat(AFormatStr: string): Boolean; var @@ -1712,9 +1675,8 @@ end; {@@ ---------------------------------------------------------------------------- Checks whether the specified number format parameters apply to date/time values. - @param ANumFormat Number format parameters - @return True if Kind of the 1st format parameter section contains the - nfkDate or nfkTime elements; false otherwise + @param ANumFormat Number format parameters + @returns @True if Kind of the 1st format parameter section contains the nfkDate or nfkTime elements; @false otherwise -------------------------------------------------------------------------------} function IsDateTimeFormat(ANumFormat: TsNumFormatParams): Boolean; begin @@ -1724,7 +1686,7 @@ end; {@@ ---------------------------------------------------------------------------- Checks whether the specified text corresponds to a date/time value and returns - true, its numerical value and its built-in numberformat if it is. + @true, its numerical value and its built-in numberformat if it is. -------------------------------------------------------------------------------} function IsDateTimeValue(AText: String; const AFormatSettings: TFormatSettings; out ADateTime: TDateTime; out ANumFormat: TsNumberFormat): Boolean; @@ -1774,9 +1736,8 @@ end; {@@ ---------------------------------------------------------------------------- Checks whether the specified number format parameters apply to a date value. - @param ANumFormat Number format parameters - @return True if Kind of the 1st format parameter section contains the - nfkDate, but no nfkTime tags; false otherwise + @param ANumFormat Number format parameters + @returns @True if Kind of the 1st format parameter section contains the nfkDate, but no nfkTime tags; @false otherwise -------------------------------------------------------------------------------} function IsDateFormat(ANumFormat: TsNumFormatParams): Boolean; begin @@ -1787,8 +1748,8 @@ end; {@@ ---------------------------------------------------------------------------- Checks whether the given built-in number format code is for time values. - @param AFormat Built-in number format identifier to be checked - @return True if AFormat represents to a time-format, false otherwise + @param AFormat Built-in number format identifier to be checked + @returns @True if AFormat represents to a time-format, @false otherwise -------------------------------------------------------------------------------} function IsTimeFormat(AFormat: TsNumberFormat): boolean; begin @@ -1817,9 +1778,8 @@ end; {@@ ---------------------------------------------------------------------------- Checks whether the specified number format parameters apply to time values. - @param ANumFormat Number format parameters - @return True if Kind of the 1st format parameter section contains the - nfkTime, but no nfkDate elements; false otherwise + @param ANumFormat Number format parameters + @returns @True if Kind of the 1st format parameter section contains the nfkTime, but no nfkDate elements; @false otherwise -------------------------------------------------------------------------------} function IsTimeFormat(ANumFormat: TsNumFormatParams): Boolean; begin @@ -1828,8 +1788,8 @@ begin end; {@@ ---------------------------------------------------------------------------- - Returns TRUE if the specified format string represents a long time format, i.e. - it contains two TimeSeparators. + Returns @TRUE if the specified format string represents a long time format, + i.e. it contains two TimeSeparators. -------------------------------------------------------------------------------} function IsLongTimeFormat(AFormatStr: String; ATimeSeparator: Char): Boolean; var @@ -1843,7 +1803,7 @@ end; {@@ ---------------------------------------------------------------------------- Checks whether the specified text corresponds to a numerical value. If it is - then the function result is TRUE, and the number value and its formatting + then the function result is @TRUE, and the number value and its formatting parameters are returned. -------------------------------------------------------------------------------} function IsNumberValue(AText: String; AutoDetectNumberFormat: Boolean; @@ -1941,9 +1901,8 @@ end; Checks whether the specified number format parameters is a time interval format. - @param ANumFormat Number format parameters - @return True if Kind of the 1st format parameter section contains the - nfkTimeInterval elements; false otherwise + @param ANumFormat Number format parameters + @returns @True if Kind of the 1st format parameter section contains the nfkTimeInterval elements; @false otherwise -------------------------------------------------------------------------------} function IsTimeIntervalFormat(ANumFormat: TsNumFormatParams): Boolean; begin @@ -1962,9 +1921,8 @@ end; Retains the order of year-month-day and the separators, but uses 4 digits for year and 3 digits of month. - @param ADateFormat String with date formatting code representing a - "short" date, such as 'dd/mm/yy' - @return Format string modified to represent a "long" date, such as 'dd/mmm/yyyy' + @param ADateFormat String with date formatting code representing a "short" date, such as 'dd/mm/yy' + @returns Format string modified to represent a "long" date, such as 'dd/mmm/yyyy' -------------------------------------------------------------------------------} function MakeLongDateFormat(ADateFormat: String): String; var @@ -1997,9 +1955,8 @@ end; Modifies the short date format such that it has a two-digit year and a two-digit month. Retains the order of year-month-day and the separators. - @param ADateFormat String with date formatting codes representing a - "long" date, such as 'dd/mmm/yyyy' - @return Format string modified to represent a "short" date, such as 'dd/mm/yy' + @param ADateFormat String with date formatting codes representing a "long" date, such as 'dd/mmm/yyyy' + @returns Format string modified to represent a "short" date, such as 'dd/mm/yy' -------------------------------------------------------------------------------} function MakeShortDateFormat(ADateFormat: String): String; var @@ -2033,8 +1990,7 @@ end; in square brackets. @param Src Source format string, must be a time format string, like 'hh:nn' - @param Dest Destination format string, will have the first time code element - of the src format string in square brackets, like '[hh]:nn'. + @param Dest Destination format string, will have the first time code element of the src format string in square brackets, like '[hh]:nn'. -------------------------------------------------------------------------------} procedure MakeTimeIntervalMask(Src: String; var Dest: String); var @@ -2058,8 +2014,8 @@ end; of "AM/PM" are considered as well. The string is left unchanged if it does not contain AM/PM codes. - @param ATimeFormatString String of time formatting codes (such as 'hh:nn AM/PM') - @return Formatting string with AM/PM being removed (--> 'hh:nn') + @param ATimeFormatString String of time formatting codes (such as 'hh:nn AM/PM') + @returns Formatting string with AM/PM being removed (--> 'hh:nn') -------------------------------------------------------------------------------} function StripAMPM(const ATimeFormatString: String): String; var @@ -2208,9 +2164,8 @@ end; {@@ ---------------------------------------------------------------------------- Deletes a parsed number format element from the specified format section. - @param ASectionIndex Index of the format section containing the element to - be deleted - @param AElementIndex Index of the format element to be deleted + @param ASectionIndex Index of the format section containing the element to be deleted + @param AElementIndex Index of the format element to be deleted -------------------------------------------------------------------------------} procedure TsNumFormatParams.DeleteElement(ASectionIndex, AElementIndex: Integer); var @@ -2229,10 +2184,8 @@ end; Creates the built-in number format identifier from the parsed number format sections and elements - @return Built-in number format identifer if the format is built into - fpspreadsheet, or nfCustom otherwise - - @see TsNumFormat + @returns Built-in number format identifer if the format is built into fpspreadsheet, or nfCustom otherwise + @seeAlso TsNumberFormat -------------------------------------------------------------------------------} function TsNumFormatParams.GetNumFormat: TsNumberFormat; begin @@ -2256,7 +2209,7 @@ end; Constructs the number format string from the parsed sections and elements. The format symbols are selected according to Excel syntax. - @return Excel-compatible number format string. + @returns Excel-compatible number format string. -------------------------------------------------------------------------------} function TsNumFormatParams.GetNumFormatStr: String; var @@ -2274,13 +2227,11 @@ end; Inserts a parsed format token into the specified format section before the specified element. - @param ASectionIndex Index of the parsed format section into which the - token is to be inserted - @param AElementIndex Index of the format element before which the token - is to be inserted - @param AToken Parsed format token to be inserted + @param ASectionIndex Index of the parsed format section into which the token is to be inserted + @param AElementIndex Index of the format element before which the token is to be inserted + @param AToken Parsed format token to be inserted - @see TsNumFormatToken + @seeAlso TsNumFormatToken -------------------------------------------------------------------------------} procedure TsNumFormatParams.InsertElement(ASectionIndex, AElementIndex: Integer; AToken: TsNumFormatToken); @@ -2301,8 +2252,7 @@ end; Checks whether the parsed format sections passed as a parameter are identical to the interal section array. - @param ASections Array of parsed format sections to be compared with the - internal format sections + @param ASections Array of parsed format sections to be compared with the internal format sections -------------------------------------------------------------------------------} function TsNumFormatParams.SectionsEqualTo(ASections: TsNumFormatSections): Boolean; var @@ -2371,8 +2321,7 @@ end; {@@ ---------------------------------------------------------------------------- Defines the currency symbol used in the format params sequence - @param AValue String containing the currency symbol to be used in the - converted numbers + @param AValue String containing the currency symbol to be used in the converted numbers -------------------------------------------------------------------------------} procedure TsNumFormatParams.SetCurrSymbol(AValue: String); var @@ -2425,8 +2374,7 @@ end; If AEnable is false the format tokens are modified such that negative values are displayed in default color. - @param AEnable The format tokens are modified such as to display negative - values in red if AEnable is true. + @param AEnable The format tokens are modified such as to display negative values in red if AEnable is true. -------------------------------------------------------------------------------} procedure TsNumFormatParams.SetNegativeRed(AEnable: Boolean); var @@ -2468,8 +2416,7 @@ end; Inserts a thousand separator token into the format elements at the appropriate position, or removes it - @param AEnable A thousand separator is inserted if AEnable is true, or else - deleted. + @param AEnable A thousand separator is inserted if AEnable is @true, or else deleted. -------------------------------------------------------------------------------} procedure TsNumFormatParams.SetThousandSep(AEnable: Boolean); var @@ -2515,10 +2462,8 @@ end; {@@ ---------------------------------------------------------------------------- Constructor of the number format list class. - @param AFormatSettings Format settings needed internally by the number - format parser (currency symbol, etc.) - @param AOwnsData If true then the list is responsible to destroy - the list items + @param AFormatSettings Format settings needed internally by the number format parser (currency symbol, etc.) + @param AOwnsData If @true then the list is responsible to destroy the list items -------------------------------------------------------------------------------} constructor TsNumFormatList.Create(AFormatSettings: TFormatSettings; AOwnsData: Boolean); @@ -2544,9 +2489,8 @@ end; Adds the specified sections of a parsed number format to the list. Duplicates are not checked before adding the format item. - @param ASections Array of number format sections as obtained by the - number format parser for a given format string - @return Index of the format item in the list. + @param ASections Array of number format sections as obtained by the number format parser for a given format string + @returns Index of the format item in the list. -------------------------------------------------------------------------------} function TsNumFormatList.AddFormat(ASections: TsNumFormatSections): Integer; var @@ -2567,8 +2511,8 @@ end; Duplicates are not checked before adding the format item. - @param AFormatStr Excel-like format string describing the format to be added - @return Index of the format item in the list + @param AFormatStr Excel-like format string describing the format to be added + @returns Index of the format item in the list -------------------------------------------------------------------------------} function TsNumFormatList.AddFormat(AFormatStr: String): Integer; var @@ -2600,7 +2544,7 @@ end; Clears the list. If the list "owns" the format items they are destroyed. - @see TsNumFormatList.Create + @seeAlso TsNumFormatList.Create -------------------------------------------------------------------------------} procedure TsNumFormatList.Clear; var @@ -2615,7 +2559,7 @@ end; If the list "owns" the format items, the item is destroyed. @param AIndex Index of the format item to be deleted - @see TsNumformatList.Create + @seeAlso TsNumformatList.Create -------------------------------------------------------------------------------} procedure TsNumFormatList.Delete(AIndex: Integer); var @@ -2633,9 +2577,8 @@ end; Checks whether a parsed format item having the specified format sections is contained in the list and returns its index if found, or -1 if not found. - @param ASections Array of number format sections as obtained by the - number format parser for a given format string - @return Index of the found format item, or -1 if not found + @param ASections Array of number format sections as obtained by the number format parser for a given format string + @returns Index of the found format item, or -1 if not found -------------------------------------------------------------------------------} function TsNumFormatList.Find(ASections: TsNumFormatSections): Integer; var @@ -2655,9 +2598,9 @@ end; Should be called before adding a format to the list to avoid duplicates. - @param AFormatStr Number format string of the format item which is seeked - @return Index of the found format item, or -1 if not found - @see TsNumFormatList.Add + @param AFormatStr Number format string of the format item which is seeked + @returns Index of the found format item, or -1 if not found + @seeAlso TsNumFormatList.AddFormat -------------------------------------------------------------------------------} function TsNumFormatList.Find(AFormatStr: String): Integer; var @@ -2672,11 +2615,10 @@ end; {@@ ---------------------------------------------------------------------------- Getter function returning the correct type of the list items - (i.e., TsNumFormatParams which are parsed format descriptions). + (i.e., @link(TsNumFormatParams) which are parsed format descriptions). - @param AIndex Index of the format item - @return Pointer to the list item at the specified index, cast to the type - TsNumFormatParams + @param AIndex Index of the format item + @returns Pointer to the list item at the specified index, cast to the type @link(TsNumFormatParams) -------------------------------------------------------------------------------} function TsNumFormatList.GetItem(AIndex: Integer): TsNumFormatParams; begin @@ -2687,8 +2629,7 @@ end; Setter function for the list items @param AIndex Index of the format item - @param AValue Pointer to the parsed format description to be stored in the - list at the specified index. + @param AValue Pointer to the parsed format description to be stored in the list at the specified index. -------------------------------------------------------------------------------} procedure TsNumFormatList.SetItem(AIndex: Integer; const AValue: TsNumFormatParams); @@ -2810,9 +2751,9 @@ begin Result := CurrencyRegistered(AValue); end; -{ Creates a formatstring for all sections. - Note: this implementation is only valid for the fpc and Excel dialects of - format string. } +{@@ Creates a formatstring for all sections. + + @Note This implementation is only valid for the fpc and Excel dialects of format string. } function TsNumFormatParser.BuildFormatString: String; var i: Integer; @@ -3040,7 +2981,7 @@ begin SetLength(FSections[ASection].Elements, n-1); end; -{ Identify the ambiguous "m" token ("month" or "minute") } +{@@ Identify the ambiguous "m" token ("month" or "minute") } procedure TsNumFormatParser.FixMonthMinuteToken(var ASection: TsNumFormatSection); var i, j: Integer; @@ -3166,7 +3107,7 @@ begin Result := BuildFormatString; end; -{ Extracts the currency symbol form the formatting sections. It is assumed that +{@@ Extracts the currency symbol form the formatting sections. It is assumed that all two or three sections of the currency/accounting format use the same currency symbol, otherwise it would be custom format anyway which ignores the currencysymbol value. } @@ -3178,7 +3119,7 @@ begin Result := ''; end; -{ Creates a string which summarizes the date/time formats in the given section. +{@@ Creates a string which summarizes the date/time formats in the given section. The string contains a 'y' for a nftYear, a 'm' for a nftMonth, a 'd' for a nftDay, a 'h' for a nftHour, a 'n' for a nftMinute, a 's' for a nftSeconds, and a 'z' for a nftMilliseconds token. The order is retained. @@ -3206,7 +3147,7 @@ begin end; end; -{ Extracts the number of decimals from the sections. Since they are needed only +{@@ Extracts the number of decimals from the sections. Since they are needed only for default formats having only a single section, only the first section is considered. In case of currency/accounting having two or three sections, it is assumed that all sections have the same decimals count, otherwise it would not @@ -3243,7 +3184,7 @@ begin Result := 0; end; -{ Tries to extract a common builtin number format from the sections. If there +{@@ Tries to extract a common built-in number format from the sections. If there are multiple sections, it is always a custom format, except for Currency and Accounting. } function TsNumFormatParser.GetNumFormat: TsNumberFormat; @@ -3390,7 +3331,8 @@ begin (FSections[ASection].Elements[AIndex].TextValue = AText); end; } -{ Returns true if the format elements contain only time, no date tokens. } + +{@@ Returns @true if the format elements contain only time, no date tokens. } function TsNumFormatParser.IsTimeFormat: Boolean; var section: TsNumFormatSection; @@ -3403,6 +3345,7 @@ begin end; Result := false; end; + { function TsNumFormatParser.IsTokenAt(AToken: TsNumFormatToken; ASection, AIndex: Integer): Boolean; @@ -3412,7 +3355,8 @@ begin (FSections[ASection].Elements[AIndex].Token = AToken); end; } -{ Limits the decimals to 0 or 2, as required by Excel2. } + +{@@ Limits the decimals to 0 or 2, as required by Excel2. } procedure TsNumFormatParser.LimitDecimals; var i, j: Integer; @@ -3470,7 +3414,7 @@ begin end; end; -{ Scans an AM/PM sequence (or AMPM or A/P). +{@@ Scans an AM/PM sequence (or AMPM or A/P). At exit, cursor is a next character } procedure TsNumFormatParser.ScanAMPM; var @@ -3499,7 +3443,7 @@ begin end; end; -{ Counts the number of characters equal to ATestChar. Stops at the next +{@@ Counts the number of characters equal to ATestChar. Stops at the next different character. This is also where the cursor is at exit. } procedure TsNumFormatParser.ScanAndCount(ATestChar: Char; out ACount: Integer); begin @@ -3512,7 +3456,7 @@ begin until (FToken <> ATestChar) or (FCurrent >= FEnd); end; -{ Extracts the text between square brackets. This can be +{@@ Extracts the text between square brackets. This can be - a time duration like [hh] - a condition, like [>= 2.0] - a currency symbol like [$€-409] @@ -3580,7 +3524,7 @@ begin end; end; -{ Scans a condition like [>=2.0]. Starts after the "[" and ends before at "]". +{@@ Scans a condition like [>=2.0]. Starts after the "[" and ends before at "]". Returns first character after the number (spaces allowed). } procedure TsNumFormatParser.ScanCondition(AFirstChar: Char); var @@ -3636,7 +3580,7 @@ begin end; end; -{ Scans to end of a symbol like [$EUR-409], starting after the $ and ending at +{@@ Scans to end of a symbol like [$EUR-409], starting after the $ and ending at the "]". After the "$" follows the currency symbol, after the "-" country information } procedure TsNumFormatParser.ScanCurrSymbol; @@ -3662,7 +3606,7 @@ begin end; end; -{ Scans a date/time format. Procedure is left with the cursor at the last char +{@@ Scans a date/time format. Procedure is left with the cursor at the last char of the date/time format. } procedure TsNumFormatParser.ScanDateTime; var @@ -3829,7 +3773,7 @@ begin end; end; -{ Scans for the word "General", it may be used like other tokens } +{@@ Scans for the word "General", it may be used like other tokens } procedure TsNumFormatParser.ScanGeneral; begin FStatus := psErrGeneralExpected; @@ -3849,7 +3793,7 @@ begin FStatus := psOK; end; -{ Scans a floating point format. Procedure is left with the cursor at the last +{@@ Scans a floating point format. Procedure is left with the cursor at the last character of the format. } procedure TsNumFormatParser.ScanNumber; var @@ -4012,7 +3956,7 @@ begin end; end; -{ Scans a text in quotation marks. Tries to interpret the text as a currency +{@@ Scans a text in quotation marks. Tries to interpret the text as a currency symbol (--> AnalyzeText). The procedure is entered and left with the cursor at a quotation mark. } procedure TsNumFormatParser.ScanQuotedText; diff --git a/components/fpspreadsheet/source/common/fpspreadsheet.pas b/components/fpspreadsheet/source/common/fpspreadsheet.pas index d34ab841d..9fced0771 100644 --- a/components/fpspreadsheet/source/common/fpspreadsheet.pas +++ b/components/fpspreadsheet/source/common/fpspreadsheet.pas @@ -1,5 +1,5 @@ {@@ ---------------------------------------------------------------------------- - Unit fpspreadsheet implements spreadsheet documents and their + Unit **fpspreadsheet** implements spreadsheet documents and their properties and methods. AUTHORS: Felipe Monteiro de Carvalho, Reinier Olislagers, Werner Pamler @@ -107,8 +107,7 @@ type FOnSelectCell: TsCellEvent; FOnWriteCellData: TsWorksheetWriteCellDataEvent; - { Setter/Getter } - + // Setter/Getter function GetFormatSettings: TFormatSettings; function GetIndex: Integer; procedure SetBiDiMode(AValue: TsBiDiMode); @@ -381,6 +380,7 @@ type AValue: TsCellProtections); overload; { Conditional formatting } + // cell-related comparisons function WriteConditionalCellFormat(ARange: TsCellRange; ACondition: TsCFCondition; ACellFormatIndex: Integer): Integer; overload; @@ -670,6 +670,7 @@ type property VirtualRowCount: cardinal read FVirtualRowCount write SetVirtualRowCount; // These are properties to interface to TsWorksheetGrid + property BiDiMode: TsBiDiMode read FBiDiMode write SetBiDiMode; {@@ Column index of the selected cell of this worksheet } property ActiveCellCol: Cardinal read FActiveCellCol; @@ -726,7 +727,7 @@ type TsFormulaCorrection = (fcWorksheetRenamed, fcWorksheetDeleted); - { TsWorkbook } + { TsWorkbook } {@@ The workbook contains the worksheets and provides methods for reading from and writing to file. } @@ -921,7 +922,7 @@ type property CryptoInfo: TsCryptoInfo read FCryptoInfo write FCryptoInfo; {property RevisionsCrypto: TsCryptoInfo read FRevisionsCrypto write FRevisionsCrypto;} - {@@ Meta data} + {@@ Workbook metadata} property MetaData: TsMetaData read FMetaData write FMetaData; {@@ This event fires whenever a new worksheet is added } @@ -997,17 +998,10 @@ const spreadsheet format. @param AWorkbook Workbook to be written - @param AFormatID Identifier of the file format which is assumed when reading - a document into the workbook. An exception is raised when - the document has a different format. + @param AFormatID Identifier of the file format which is assumed when reading a document into the workbook. An exception is raised when the document has a different format. + @param AParams Optional parameters to control stream access. If contains the element spClipboard the reader knows that access is to the clipboard, and it can read a special clipboard version of the data. - @param AParams Optional parameters to control stream access. If contains - the element spClipboard the reader knows that access is to - the clipboard, and it can read a special clipboard version - of the data. - - @return An instance of a TsBasicSpreadReader descendent which is able to - read the given file format. + @returns An instance of a TsBasicSpreadReader descendent which is able to read the given file format. -------------------------------------------------------------------------------} function CreateSpreadReader(AWorkbook: TsWorkbook; AFormatID: TsSpreadFormatID; AParams: TsStreamParams = []): TsBasicSpreadReader; @@ -1029,16 +1023,11 @@ end; Convenience method which creates the correct writer object for a given spreadsheet format. - @param AWorkbook Workbook to be written - @param AFormatID Identifier of the file format which is used for writing the - workbook - @param AParams Optional parameters to control stream access. If contains - the element spClipboard then the writer can write a - dedicated clipboard version of the stream if required. - @return An instance of a TsBasicSpreadWriter descendant which is able to - write the given file format. + @param AWorkbook Workbook to be written + @param AFormatID Identifier of the file format which is used for writing the workbook + @param AParams Optional parameters to control stream access. If contains the element spClipboard then the writer can write a dedicated clipboard version of the stream if required. + @returns An instance of a TsBasicSpreadWriter descendant which is able to write the given file format. -------------------------------------------------------------------------------} - function CreateSpreadWriter(AWorkbook: TsWorkbook; AFormatID: TsSpreadFormatID; AParams: TsStreamParams = []): TsBasicSpreadWriter; var @@ -1058,8 +1047,8 @@ end; {@@ ---------------------------------------------------------------------------- Copies the format of a cell to another one. - @param AFromCell Cell from which the format is to be copied - @param AToCell Cell to which the format is to be copied + @param AFromCell Pointer to the cell from which the format is to be copied + @param AToCell Pointer to the cell to which the format is to be copied -------------------------------------------------------------------------------} procedure CopyCellFormat(AFromCell, AToCell: PCell); var @@ -1202,6 +1191,8 @@ end; {@@ ---------------------------------------------------------------------------- Constructor of the TsWorksheet class. + + Creates internal lists and initialies some internal variables. -------------------------------------------------------------------------------} constructor TsWorksheet.Create; begin @@ -1238,10 +1229,10 @@ end; {@@ ---------------------------------------------------------------------------- Destructor of the TsWorksheet class. - Releases all memory, but does not delete from the workbook's worksheetList !!! + Releases all memory, but does not delete itself from the workbook's + worksheetList !!! - NOTE: Don't call directly. Always use Workbook.RemoveWorksheet to remove a - worksheet from a workbook. + @NOTE Don't call directly. Always use Workbook.RemoveWorksheet to remove a worksheet from a workbook. -------------------------------------------------------------------------------} destructor TsWorksheet.Destroy; begin @@ -1266,7 +1257,9 @@ end; Helper function which constructs an rpn formula from the cell's string formula. This is needed, for example, when writing a formula to xls biff file format. + The formula is stored in ACell. + If ADestCell is not nil then the relative references are adjusted as seen from ADestCell. This means that this function returns the formula that would be created if ACell is copied to the location of ADestCell. @@ -1300,8 +1293,7 @@ end; which may have not yet been calculated. It is better to call CalcFormulas instead. - @param AFormula Formula to be calculated. The formula belongs to the - cell specified by the formula's Row and Col parameters. + @param AFormula Formula to be calculated. The formula belongs to the cell specified by the formula's Row and Col parameters. -------------------------------------------------------------------------------} procedure TsWorksheet.CalcFormula(AFormula: PsFormula); var @@ -1420,15 +1412,16 @@ end; Since formulas may reference not-yet-calculated cells, this occurs in two steps: + 1. All formulas are marked as "not calculated". + 2. Formulas are calculated. If formulas in referenced are found as being "not calculated" they are calculated and then tagged as "calculated". + This results in an iterative calculation procedure. In the end, all formulas are calculated. - NOTE: IF THE WORKSHEET CONTAINS CELLS WHICH LINK TO OTHER WORKSHEETS THEN - THIS CALCULATION MAY NOT BE CORRECT. USE THE METHOD CalcFormulas OF THE - WORKBOOK INSTEAD !!! + @NOTE IF THE WORKSHEET CONTAINS CELLS WHICH LINK TO OTHER WORKSHEETS THEN THIS CALCULATION MAY NOT BE CORRECT. USE THE METHOD CalcFormulas OF THE WORKBOOK INSTEAD !!! -------------------------------------------------------------------------------} procedure TsWorksheet.CalcSheet; var @@ -1457,6 +1450,11 @@ end; {@@ ---------------------------------------------------------------------------- Checks whether a cell given by its row and column indexes belongs to a specified rectangular cell range. + + @param ARow Zero-based row index of the cell + @param ACol Zero-based column index of the cell + @param ARange @link(TsCellRange) record with the top/left and bottom/right cells of the rectangle to be checked. + @returns @true if the cell is inside, @false if it is outside the cell range -------------------------------------------------------------------------------} class function TsWorksheet.CellInRange(ARow, ACol: Cardinal; ARange: TsCellRange): Boolean; @@ -1476,11 +1474,11 @@ begin end; {@@ ---------------------------------------------------------------------------- - Checks entire worksheet, whether this cell is used in any formula. + Checks entire worksheet, whether this cell is used by any formula. - @param ARow Row index of the cell considered - @param ACol Column index of the cell considered - @return TRUE if the cell is used in a formula, FALSE if not + @param ARow (Zero-based) row index of the cell considered + @param ACol (Zero-based) column index of the cell considered + @returns @TRUE if the cell is used by a formula, @FALSE if not -------------------------------------------------------------------------------} function TsWorksheet.CellUsedInFormula(ARow, ACol: Cardinal): Boolean; var @@ -1528,8 +1526,8 @@ end; Is called whenever a cell value or formatting has changed. Fires an event "OnChangeCell". This is handled by TsWorksheetGrid to update the grid cell. - @param ARow Row index of the cell which has been changed - @param ACol Column index of the cell which has been changed + @param ARow (Zero-based) row index of the cell which has been changed + @param ACol (Zero-based) column index of the cell which has been changed -------------------------------------------------------------------------------} procedure TsWorksheet.ChangedCell(ARow, ACol: Cardinal); begin @@ -1550,7 +1548,7 @@ end; Is called whenever a column width or column format has changed. Fires an event "OnChangedCol" which is handled by TsWorkbookSource - @param ACol Index of the column which as changed + @param ACol (Zero-based) index of the column which as changed -------------------------------------------------------------------------------} procedure TsWorksheet.ChangedCol(ACol: Cardinal); begin @@ -1564,7 +1562,7 @@ end; Is called whenever a row height or row format has changed. Fires an event "OnChangedRow" which is handled by TsWorkbookSource - @param ARow Index of the row which as changed + @param Row (Zero-based) index of the row which as changed -------------------------------------------------------------------------------} procedure TsWorksheet.ChangedRow(ARow: Cardinal); begin @@ -1578,8 +1576,8 @@ end; Is called whenever a font height changes. Fires an even "OnChangeFont" which is handled by TsWorksheetGrid to update the row heights. - @param ARow Row index of the cell for which the font height has changed - @param ACol Column index of the cell for which the font height has changed. + @param ARow (Zero-based) row index of the cell for which the font height has changed + @param ACol (Zero-based) column index of the cell for which the font height has changed. -------------------------------------------------------------------------------} procedure TsWorksheet.ChangedFont(ARow, ACol: Cardinal); begin @@ -1596,8 +1594,8 @@ end; Both cells can be in different worksheets. - @param FromCell Pointer to the source cell which will be copied - @param ToCell Pointer to the destination cell + @param AFromCell Pointer to the source cell which will be copied + @param AToCell Pointer to the destination cell -------------------------------------------------------------------------------} procedure TsWorksheet.CopyCell(AFromCell, AToCell: PCell); var @@ -1685,13 +1683,13 @@ end; Copies a cell. The source cell can be located in a different worksheet, while the destination cell must be in the same worksheet which calls the methode. - @param AFromRow Row index of the source cell - @param AFromCol Column index of the source cell - @param AToRow Row index of the destination cell - @param AToCol Column index of the destination cell - @param AFromWorksheet Worksheet containing the source cell. Self, if omitted. + @param AFromRow (Zero-based) row index of the source cell + @param AFromCol (Zero-based) column index of the source cell + @param AToRow (Zero-based) row index of the destination cell + @param AToCol (Zero-based) column index of the destination cell + @param AFromWorksheet Worksheet containing the source cell. Self, if omitted. - @return Created new destination cell + @returns Pointer to newly created destination cell -------------------------------------------------------------------------------} function TsWorksheet.CopyCell(AFromRow, AFromCol, AToRow, AToCol: Cardinal; AFromWorksheet: TsWorksheet = nil): PCell; @@ -1715,8 +1713,8 @@ end; {@@ ---------------------------------------------------------------------------- Copies all format parameters from the format cell to another cell. - @param AFromCell Pointer to source cell - @param AToCell Pointer to destination cell + @param AFromCell Pointer to source cell + @param AToCell Pointer to destination cell -------------------------------------------------------------------------------} procedure TsWorksheet.CopyFormat(AFromCell, AToCell: PCell); begin @@ -1734,8 +1732,8 @@ end; by its row/column indexes. @param AFormatCell Pointer to the source cell from which the format is copied. - @param AToRow Row index of the destination cell - @param AToCol Column index of the destination cell + @param AToRow (Zero-basec) row index of the destination cell + @param AToCol (Zero-based) column index of the destination cell -------------------------------------------------------------------------------} procedure TsWorksheet.CopyFormat(AFormatCell: PCell; AToRow, AToCol: Cardinal); begin @@ -1746,8 +1744,7 @@ end; Copies the formula of a specified cell to another cell. Adapts relative cell references to the new cell. - @param AFromCell Pointer to the source cell from which the formula is to be - copied + @param AFromCell Pointer to the source cell from which the formula is to be copied @param AToCell Pointer to the destination cell -------------------------------------------------------------------------------} procedure TsWorksheet.CopyFormula(AFromCell, AToCell: PCell); @@ -1812,10 +1809,9 @@ end; Copies the formula of a specified cell to another cell given by its row and column index. Relative cell references are adapted to the new cell. - @param AFormatCell Pointer to the source cell containing the formula to be - copied - @param AToRow Row index of the destination cell - @param AToCol Column index of the destination cell + @param AFormatCell Pointer to the source cell containing the formula to be copied + @param AToRow (Zero-based) row index of the destination cell + @param AToCol (Zero-based) column index of the destination cell -------------------------------------------------------------------------------} procedure TsWorksheet.CopyFormula(AFormulaCell: PCell; AToRow, AToCol: Cardinal); begin @@ -1826,8 +1822,8 @@ end; Copies the value of a specified cell to another cell (without copying formulas or formats) - @param AFromCell Pointer to the source cell providing the value to be copied - @param AToCell Pointer to the destination cell + @param AFromCell Pointer to the source cell providing the value to be copied + @param AToCell Pointer to the destination cell -------------------------------------------------------------------------------} procedure TsWorksheet.CopyValue(AFromCell, AToCell: PCell); begin @@ -1855,9 +1851,9 @@ end; Copies the value of a specified cell to another cell given by its row and column index - @param AValueCell Pointer to the cell containing the value to be copied - @param AToRow Row index of the destination cell - @param AToCol Column index of the destination cell + @param AValueCell Pointer to the cell containing the value to be copied + @param AToRow (Zero-based) row index of the destination cell + @param AToCol (Zero-based) column index of the destination cell -------------------------------------------------------------------------------} procedure TsWorksheet.CopyValue(AValueCell: PCell; AToRow, AToCol: Cardinal); begin @@ -1868,8 +1864,10 @@ end; Copies a column record to another location. The new column has the same colwidth and the same formatting. - @param AFromCol Index of the column to be copied - @param AToCol Index of the destination column + @param AFromCol (Zero-based) index of the column to be copied + @param AToCol (Zero-based) index of the destination column + @param AFromWorksheet Worksheet from which the column record is copied. If not specified the current worksheet is used. + -------------------------------------------------------------------------------} procedure TsWorksheet.CopyCol(AFromCol, AToCol: Cardinal; AFromWorksheet: TsWorksheet = nil); @@ -1905,10 +1903,11 @@ end; {@@ ---------------------------------------------------------------------------- Copies a row record to another location. The new row has the same - row heightand the same formatting. + row height and the same formatting. - @param AFromRow Index of the row to be copied - @param AToTow Index of the destination row + @param AFromRow (Zero-based) index of the row to be copied + @param AToTow (Zero-based) index of the destination row + @param AFromWorksheet Worksheet from which the row record is to be copied -------------------------------------------------------------------------------} procedure TsWorksheet.CopyRow(AFromRow, AToRow: Cardinal; AFromWorksheet: TsWorksheet); @@ -1957,6 +1956,8 @@ end; Deletes a specified cell. If the cell belongs to a merged block its content and formatting is erased. Otherwise the cell is destroyed and its memory is released. + + @param ACell Pointer to the cell to be deleted -------------------------------------------------------------------------------} procedure TsWorksheet.DeleteCell(ACell: PCell); {$warning TODO: Shift cells to the right/below !!! ??? } @@ -2000,7 +2001,8 @@ end; {@@ ---------------------------------------------------------------------------- Erases content and formatting of a cell. The cell still occupies memory. - @param ACell Pointer to cell to be erased. + @param ACell Pointer to cell to be erased. + @param AKeepFormat Optional parameter to avoid deletion of any existing cell format. -------------------------------------------------------------------------------} procedure TsWorksheet.EraseCell(ACell: PCell; AKeepFormat: Boolean = false); var @@ -2036,13 +2038,11 @@ end; {@@ ---------------------------------------------------------------------------- Exchanges two cells - @param ARow1 Row index of the first cell - @param ACol1 Column index of the first cell - @param ARow2 Row index of the second cell - @param ACol2 Column index of the second cell - - @note This method does not take care of merged cells and does not - check for this situation. Therefore, the method is not public! + @param ARow1 (Zero-based) row index of the first cell + @param ACol1 (Zero-based) column index of the first cell + @param ARow2 (Zero-based) row index of the second cell + @param ACol2 (Zero-based) column index of the second cell + @note This method does not take care of merged cells and does not check for this situation. Therefore, the method is not public! -------------------------------------------------------------------------------} procedure TsWorksheet.ExchangeCells(ARow1, ACol1, ARow2, ACol2: Cardinal); begin @@ -2054,9 +2054,12 @@ end; {@@ ---------------------------------------------------------------------------- Adds a new cell at a specified row and column index to the Cells list. - NOTE: It is not checked if there exists already another cell at this location. - This case must be avoided. USE CAREFULLY WITHOUT FindCell - (e.g., during reading into empty worksheets). + @param ARow The row index of the cell (zero-based) + @param ACol The column index of the cell (zero-based) + @returns Pointer to the newly created cell + + @note It is not checked if another cell already exists at the same location. This case must be avoided. USE CAREFULLY WITHOUT FindCell (e.g., during reading into empty worksheets). + @seeAlso TCell -------------------------------------------------------------------------------} function TsWorksheet.AddCell(ARow, ACol: Cardinal): PCell; var @@ -2089,10 +2092,10 @@ end; {@@ ---------------------------------------------------------------------------- Tries to locate a Cell in the list of already written Cells - @param ARow The row of the cell - @param ACol The column of the cell - @return Pointer to the cell if found, or nil if not found - @see TCell + @param ARow The row index of the cell (zero-based) + @param ACol The column index of the cell (zero-based) + @returns Pointer to the cell if found, or nil if not found + @seeAlso TCell -------------------------------------------------------------------------------} function TsWorksheet.FindCell(ARow, ACol: Cardinal): PCell; begin @@ -2102,9 +2105,9 @@ end; {@@ ---------------------------------------------------------------------------- Tries to locate a cell in the list of already written cells - @param AddressStr Address of the cell in Excel A1 notation - @return Pointer to the cell if found, or nil if not found - @see TCell + @param AddressStr Address of the cell in Excel A1 notation + @returns Pointer to the cell if found, or nil if not found + @seeAlso TCell -------------------------------------------------------------------------------} function TsWorksheet.FindCell(AddressStr: String): PCell; var @@ -2116,6 +2119,15 @@ begin Result := nil; end; +{@@ ---------------------------------------------------------------------------- + Returns the next cell in the same column as the cell in row ARow and + column ACol. + + @param ARow Row index of the cell at which the search is started + @param ACol Column index of the cell at which the search is started + @returns Pointer to the cell found, or nil if not found + @seeAlso TCell +-------------------------------------------------------------------------------} function TsWorksheet.FindNextCellInCol(ARow, ACol: Cardinal): PCell; var last: Cardinal; @@ -2130,6 +2142,15 @@ begin until (Result <> nil) or (ARow = last); end; +{@@ ---------------------------------------------------------------------------- + Returns the next cell in the same row as the cell in row ARow and + column ACol. + + @param ARow Row index of the cell at which the search is started + @param ACol Column index of the cell at which the search is started + @returns Pointer to the cell found, or nil if not found + @seeAlso TCell +-------------------------------------------------------------------------------} function TsWorksheet.FindNextCellInRow(ARow, ACol: Cardinal): PCell; var last: Cardinal; @@ -2144,6 +2165,15 @@ begin until (Result <> nil) or (ACol = last); end; +{@@ ---------------------------------------------------------------------------- + Returns the previous cell in the same column as the cell in row ARow and + column ACol. + + @param ARow Row index of the cell at which the search is started + @param ACol Column index of the cell at which the search is started + @returns Pointer to the cell found, or nil if not found + @seeAlso TCell +-------------------------------------------------------------------------------} function TsWorksheet.FindPrevCellInCol(ARow, ACol: Cardinal): PCell; begin if ARow = 0 then @@ -2155,6 +2185,15 @@ begin until (Result <> nil) or (ARow = 0); end; +{@@ ---------------------------------------------------------------------------- + Returns the next cell in the same row as the cell in row ARow and + column ACol. + + @param ARow Row index of the cell at which the search is started + @param ACol Column index of the cell at which the search is started + @returns Pointer to the cell found, or nil if not found) + @seeAlso TCell +-------------------------------------------------------------------------------} function TsWorksheet.FindPrevCellInRow(ARow, ACol: Cardinal): PCell; begin if ACol = 0 then @@ -2167,19 +2206,17 @@ begin end; {@@ ---------------------------------------------------------------------------- - Obtains an allocated cell at the desired location. + Find the cell at the specified row and column indexes. If the cell already exists, a pointer to it will be returned. If not, then new memory for the cell will be allocated, a pointer to it will be returned and it will be added to the list of cells. - @param ARow Row index of the cell - @param ACol Column index of the cell - - @return A pointer to the cell at the desired location. - - @see TCell + @param ARow (Zero-based) row index of the cell + @param ACol (Zero-based) column index of the cell + @returns A pointer to the cell at the desired location. + @seeAlso TCell -------------------------------------------------------------------------------} function TsWorksheet.GetCell(ARow, ACol: Cardinal): PCell; begin @@ -2196,11 +2233,10 @@ end; If not, then new memory for the cell will be allocated, a pointer to it will be returned and it will be added to the list of cells. - @param AddressStr Address of the cell in Excel A1 notation (an exception is - raised in case on an invalid cell address). - @return A pointer to the cell at the desired location. + @param AddressStr Address of the cell in Excel A1 notation (an exception is raised in case on an invalid cell address). + @returns A pointer to the cell at the desired location. - @see TCell + @seeAlso TCell -------------------------------------------------------------------------------} function TsWorksheet.GetCell(AddressStr: String): PCell; var @@ -2215,7 +2251,7 @@ end; {@@ ---------------------------------------------------------------------------- Returns the number of cells in the worksheet with contents. - @return The number of cells with contents in the worksheet + @returns The number of cells with contents in the worksheet -------------------------------------------------------------------------------} function TsWorksheet.GetCellCount: Cardinal; begin @@ -2225,8 +2261,8 @@ end; {@@ ---------------------------------------------------------------------------- Determines the number of decimals displayed for the number in the cell - @param ACell Pointer to the cell under investigation - @return Number of decimals places used in the string display of the cell. + @param ACell Pointer to the cell under investigation + @returns Number of decimals places used for the numeric string display of the cell. -------------------------------------------------------------------------------} function TsWorksheet.GetDisplayedDecimals(ACell: PCell): Byte; var @@ -2249,18 +2285,16 @@ end; {@@ ---------------------------------------------------------------------------- - Returns the 0-based index of the first column with a cell with contents. + Returns the zero-based index of the first column with a cell with contents. If no cells have contents, zero will be returned, which is also a valid value. - Use GetCellCount to verify if there is at least one cell with contents in the + Use @link(GetCellCount) to verify if there is at least one cell with contents in the worksheet. - @param AForceCalculation The index of the first column is continuously updated - whenever a new cell is created. If AForceCalculation - is true all cells are scanned to determine the index - of the first column. - @see GetCellCount + @param AForceCalculation The index of the first column is continuously updated whenever a new cell is created. If AForceCalculation is true all cells are scanned to determine the index of the first column. + @returns Column index + @seeAlso GetCellCount -------------------------------------------------------------------------------} function TsWorksheet.GetFirstColIndex(AForceCalculation: Boolean = false): Cardinal; var @@ -2289,21 +2323,19 @@ begin end; {@@ ---------------------------------------------------------------------------- - Returns the 0-based index of the last column containing a cell with a + Returns the zero-based index of the last column containing a cell with a column record (due to content or formatting), or containing a Col record. If no cells have contents or there are no column records, zero will be returned, which is also a valid value. - Use GetCellCount to verify if there is at least one cell with contents in the + Use @link(GetCellCount) to verify if there is at least one cell with contents in the worksheet. - @param AForceCalculation The index of the last column is continuously updated - whenever a new cell is created. If AForceCalculation - is true all cells are scanned to determine the index - of the last column. - @see GetCellCount - @see GetLastOccupiedColIndex + @param AForceCalculation The index of the last column is continuously updated whenever a new cell is created. If AForceCalculation is @true all cells are scanned to determine the index of the last column. + @returns Zero-based column index + @seeAlso GetCellCount + @seeAlso GetLastOccupiedColIndex -------------------------------------------------------------------------------} function TsWorksheet.GetLastColIndex(AForceCalculation: Boolean = false): Cardinal; var @@ -2329,7 +2361,7 @@ end; {@@ ---------------------------------------------------------------------------- Deprecated, use GetLastColIndex instead - @see GetLastColIndex + @seeAlso GetLastColIndex -------------------------------------------------------------------------------} function TsWorksheet.GetLastColNumber: Cardinal; begin @@ -2340,11 +2372,11 @@ end; Returns the 0-based index of the last column with a cell with contents. If no cells have contents, zero will be returned, which is also a valid value. - Use GetCellCount to verify if there is at least one cell with contents in the - worksheet. + Use @link(GetCellCount) to verify if there is at least one cell with contents + in the worksheet. - @see GetCellCount - @see GetLastColIndex + @seeAlso GetCellCount + @seeAlso GetLastColIndex -------------------------------------------------------------------------------} function TsWorksheet.GetLastOccupiedColIndex: Cardinal; var @@ -2358,14 +2390,13 @@ begin end; {@@ ---------------------------------------------------------------------------- - Returns the 0-based index of the first row with a cell with data or formatting. + Returns the zero-based index of the first row with a cell containing + data or formatting. + If no cells have contents, -1 will be returned. - @param AForceCalculation The index of the first row is continuously updated - whenever a new cell is created. If AForceCalculation - is true all cells are scanned to determine the index - of the first row. - @see GetCellCount + @param AForceCalculation The index of the first row is continuously updated whenever a new cell is created. If AForceCalculation is true all cells are scanned to determine the index of the first row. + @seeAlso GetCellCount -------------------------------------------------------------------------------} function TsWorksheet.GetFirstRowIndex(AForceCalculation: Boolean = false): Cardinal; var @@ -2393,20 +2424,18 @@ begin end; {@@ ---------------------------------------------------------------------------- - Returns the 0-based index of the last row with a cell with contents or with + Returns the zero-based index of the last row with a cell with contents or with a ROW record. If no cells have contents, zero will be returned, which is also a valid value. - Use GetCellCount to verify if there is at least one cell with contents in the - worksheet. + Use @link(GetCellCount) to verify if there is at least one cell with + contents in the worksheet. - @param AForceCalculation The index of the last row is continuously updated - whenever a new cell is created. If AForceCalculation - is true all cells are scanned to determine the index - of the last row. - @see GetCellCount - @see GetLastOccupiedRowIndex + @param AForceCalculation The index of the last row is continuously updated whenever a new cell is created. If AForceCalculation is true all cells are scanned to determine the index of the last row. + @returns Row index + @seeAlso GetCellCount + @seeAlso GetLastOccupiedRowIndex -------------------------------------------------------------------------------} function TsWorksheet.GetLastRowIndex(AForceCalculation: Boolean = false): Cardinal; var @@ -2428,14 +2457,15 @@ begin end; {@@ ---------------------------------------------------------------------------- - Returns the 0-based index of the last row with a cell with contents. + Returns the zero-based index of the last row with a cell with contents. If no cells have contents, zero will be returned, which is also a valid value. - Use GetCellCount to verify if there is at least one cell with contents in the - worksheet. + Use @link(GetCellCount) to verify if there is at least one cell with contents + in the worksheet. - @see GetCellCount - @see GetLastRowIndex + @returns Row index + @seeAlso GetCellCount + @seeAlso GetLastRowIndex -------------------------------------------------------------------------------} function TsWorksheet.GetLastOccupiedRowIndex: Cardinal; var @@ -2450,7 +2480,7 @@ end; {@@ ---------------------------------------------------------------------------- Deprecated, use GetLastColIndex instead - @see GetLastColIndex + @seeAlso GetLastColIndex -------------------------------------------------------------------------------} function TsWorksheet.GetLastRowNumber: Cardinal; begin @@ -2463,16 +2493,19 @@ end; The resulting string is UTF-8 encoded. - @param ARow The row of the cell - @param ACol The column of the cell - @return The text representation of the cell + @param ARow (Zero-based) row index of the cell + @param ACol (Zero-based) column index of the cell + @returns The text representation of the cell as string -------------------------------------------------------------------------------} function TsWorksheet.ReadAsText(ARow, ACol: Cardinal): string; var cell: PCell; begin cell := FindCell(ARow, ACol); - if cell <> nil then Result := ReadAsText(cell) else Result := ''; + if cell <> nil then + Result := ReadAsText(cell) + else + Result := ''; { avoid creating a blenk cell if the cell does not exist Result := ReadAsText(GetCell(ARow, ACol)); } end; @@ -2488,8 +2521,8 @@ end; The resulting string is UTF-8 encoded. - @param ACell Pointer to the cell - @return The text representation of the cell + @param ACell Pointer to the cell + @returns The text representation of the cell as string -------------------------------------------------------------------------------} function TsWorksheet.ReadAsText(ACell: PCell): string; begin @@ -2502,15 +2535,14 @@ begin end; {@@ ---------------------------------------------------------------------------- - Reads the contents of a cell and returns an user readable text + Reads the contents of a cell and returns an user-readable text representing the contents of the cell. The resulting string is UTF-8 encoded. - @param ACell Pointer to the cell - @param AFormatSettings Format settings to be used for string conversion - of numbers and date/times. - @return The text representation of the cell + @param ACell Pointer to the cell + @param AFormatSettings Format settings to be used for string conversion of numbers and date/times. + @returns The text representation of the cell -------------------------------------------------------------------------------} function TsWorksheet.ReadAsText(ACell: PCell; AFormatSettings: TFormatSettings): string; @@ -2588,10 +2620,9 @@ end; If the cell is empty or its contents cannot be represented as a number the value 0.0 is returned. - @param ARow The row of the cell - @param ACol The column of the cell - @return Floating-point value representing the cell contents, or 0.0 if cell - does not exist or its contents cannot be converted to a number. + @param ARow (Zero-based) row index of the cell + @param ACol (Zero-based) column index of the cell + @returns Floating-point value representing the cell contents, or 0.0 if cell does not exist or its contents cannot be converted to a number. -------------------------------------------------------------------------------} function TsWorksheet.ReadAsNumber(ARow, ACol: Cardinal): Double; begin @@ -2609,9 +2640,8 @@ end; If the cell is empty or its contents cannot be represented as a number the value NaN is returned. - @param ACell Pointer to the cell - @return Floating-point value representing the cell contents, or NaN if cell - does not exist or its contents cannot be converted to a number. + @param ACell Pointer to the cell + @returns Floating-point value representing the cell contents, or NaN if cell does not exist or its contents cannot be converted to a number. -------------------------------------------------------------------------------} function TsWorksheet.ReadAsNumber(ACell: PCell): Double; begin @@ -2635,10 +2665,10 @@ end; {@@ ---------------------------------------------------------------------------- Reads the contents of a cell and returns the date/time value of the cell. - @param ARow The row of the cell - @param ACol The column of the cell - @param AResult Date/time value of the cell (or 0.0, if no date/time cell) - @return True if the cell is a datetime value, false otherwise + @param ARow (Zero-based) row index of the cell + @param ACol (Zero-based) column index of the cell + @param AResult Date/time value of the cell (or 0.0, if no date/time cell) + @returns @True if the cell is a datetime value, @false otherwise -------------------------------------------------------------------------------} function TsWorksheet.ReadAsDateTime(ARow, ACol: Cardinal; out AResult: TDateTime): Boolean; @@ -2649,9 +2679,9 @@ end; {@@ ---------------------------------------------------------------------------- Reads the contents of a cell and returns the date/time value of the cell. - @param ACell Pointer to the cell - @param AResult Date/time value of the cell (or 0.0, if no date/time cell) - @return True if the cell is a datetime value, false otherwise + @param ACell Pointer to the cell + @param AResult Date/time value of the cell (or 0.0, if no date/time cell) + @returns @true if the cell is a datetime value, @false otherwise -------------------------------------------------------------------------------} function TsWorksheet.ReadAsDateTime(ACell: PCell; out AResult: TDateTime): Boolean; @@ -2672,10 +2702,8 @@ end; is returned as a string in Excel syntax. @param ACell Pointer to the cell considered - @param ALocalized If true, the formula is returned with decimal and list - separators accoding to the workbook's FormatSettings. - Otherwise it uses dot and comma, respectively. - @return Formula string in Excel syntax (does not contain a leading "=") + @param ALocalized If @true, the formula is returned with decimal and list separators according to the workbook's FormatSettings. Otherwise it uses dot and comma, respectively. + @returns Formula string in Excel syntax (does not contain a leading "=") -------------------------------------------------------------------------------} function TsWorksheet.ReadFormulaAsString(ACell: PCell; ALocalized: Boolean = false): String; @@ -2700,9 +2728,9 @@ end; of a boolean cell, or the string converted to a number of a string cell. All other cases return NaN. - @param ACell Cell to be considered - @param AValue (output) extracted numeric value - @return True if conversion to number is successful, otherwise false + @param ACell Pointer to cell to be considered + @param AValue (output) extracted numeric value + @returns @true if conversion to number is successful, otherwise @false -------------------------------------------------------------------------------} function TsWorksheet.ReadNumericValue(ACell: PCell; out AValue: Double): Boolean; begin @@ -2747,8 +2775,8 @@ end; Converts an RPN formula (as read from an xls biff file, for example) to a string formula. - @param AFormula Array of rpn formula tokens - @return Formula string in Excel syntax (without leading "=") + @param AFormula Array of rpn formula tokens + @returns Formula string in Excel A1 syntax (without leading "=") -------------------------------------------------------------------------------} function TsWorksheet.ConvertRPNFormulaToStringFormula(const AFormula: TsRPNFormula): String; var @@ -2768,6 +2796,9 @@ end; {@@ ---------------------------------------------------------------------------- Returns a pointer to the formula record assigned to a cell, or nil if the cell has no formula + + @param ACell Pointer to the cell + @Returns Pointer to the formula record assigned to the cell -------------------------------------------------------------------------------} function TsWorksheet.GetFormula(ACell: PCell): PsFormula; begin @@ -2781,6 +2812,11 @@ end; "Effective" cell format means: At first, look for the cell format. If it is default, look for the row format. If it is default, look for the column format. (see "excelfileformat", p. 89) + + @param ARow (Zero-based) row index of the cell + @param ACol (Zero-based) column index of the cell + @returns Index of the cell format record used by the cell into the workbook cell format list. + @seeAlso TsCellFormat -------------------------------------------------------------------------------} function TsWorksheet.GetEffectiveCellFormatIndex(ARow, ACol: Cardinal): Integer; var @@ -2820,6 +2856,11 @@ end; "Effective" cell format means: At first, look for the cell format. If it is default, look for the row format. If it is default, look for the column format. (see "excelfileformat", p. 89) + + @param ARow (Zero-based) row index of the cell + @param ACol (Zero-based) column index of the cell + @returns Pointer to the cell format record used by the cell. + @seeAlso TsCellFormat -------------------------------------------------------------------------------} function TsWorksheet.GetPointerToEffectiveCellFormat(ARow, ACol: Cardinal): PsCellFormat; var @@ -2858,6 +2899,7 @@ end; *) {@@ ---------------------------------------------------------------------------- Determines the font used in a specified column record. + Returns the workbook's default font if the column record does not exist. -------------------------------------------------------------------------------} function TsWorksheet.ReadColFont(ACol: PCol): TsFont; @@ -2875,6 +2917,7 @@ end; {@@ ---------------------------------------------------------------------------- Determines the font used in a specified row record. + Returns the workbook's default font if the row record does not exist. -------------------------------------------------------------------------------} function TsWorksheet.ReadRowFont(ARow: PRow): TsFont; @@ -2893,7 +2936,7 @@ end; {@@ ---------------------------------------------------------------------------- - Returns true if the worksheet does not contain any cell, column or row records + Returns @true if the worksheet does not contain any cell, column or row records -------------------------------------------------------------------------------} function TsWorksheet.IsEmpty: Boolean; var @@ -2917,10 +2960,8 @@ end; Finds the upper left cell of a merged block to which a specified cell belongs. This is the "merge base". Returns nil if the cell is not merged. - @param ACell Cell under investigation - @return A pointer to the cell in the upper left corner of the merged block - to which ACell belongs. - If ACell is isolated then the function returns nil. + @param ACell Cell under investigation + @returns A pointer to the cell in the upper left corner of the merged block to which ACell belongs. If ACell is isolated then the function returns nil. -------------------------------------------------------------------------------} function TsWorksheet.FindMergeBase(ACell: PCell): PCell; var @@ -2983,8 +3024,7 @@ end; {@@ ---------------------------------------------------------------------------- Merges adjacent individual cells to a larger single cell - @param ARange Cell range string given in Excel notation (e.g: A1:D5). - A non-range string (e.g. A1) is not allowed. + @param ARange Cell range string given in Excel notation (e.g: A1:D5). A non-range string (e.g. A1) is not allowed. -------------------------------------------------------------------------------} procedure TsWorksheet.MergeCells(ARange: String); var @@ -3024,10 +3064,7 @@ end; {@@ ---------------------------------------------------------------------------- Disconnects merged cells to make them individual cells again. - @param ARange Cell (range) string given in Excel notation (e.g: A1, or A1:D5) - In case of a range string, only the upper left corner cell is - considered. It must belong to the merged range of cells to be - unmerged. + @param ARange Cell (range) string given in Excel notation (e.g: A1, or A1:D5). In case of a range string, only the upper left corner cell is considered. It must belong to the merged range of cells to be unmerged. -------------------------------------------------------------------------------} procedure TsWorksheet.UnmergeCells(ARange: String); var @@ -3041,14 +3078,13 @@ end; {@@ ---------------------------------------------------------------------------- Determines the merged cell block to which a particular cell belongs - @param ACell Pointer to the cell being investigated - @param ARow1 (output) Top row index of the merged block - @param ACol1 (outout) Left column index of the merged block - @param ARow2 (output) Bottom row index of the merged block - @param ACol2 (output) Right column index of the merged block + @param ACell Pointer to the cell being investigated + @param ARow1 (output) Top row index of the merged block + @param ACol1 (outout) Left column index of the merged block + @param ARow2 (output) Bottom row index of the merged block + @param ACol2 (output) Right column index of the merged block - @return True if the cell belongs to a merged block, False if not, or if the - cell does not exist at all. + @returns @True if the cell belongs to a merged block, False if not, or if the cell does not exist at all. -------------------------------------------------------------------------------} function TsWorksheet.FindMergedRange(ACell: PCell; out ARow1, ACol1, ARow2, ACol2: Cardinal): Boolean; @@ -3074,10 +3110,9 @@ end; {@@ ---------------------------------------------------------------------------- Checks whether the two specified cells belong to the same merged cell block. - @param ACell1 Pointer to the first cell - @param ACell2 Pointer to the second cell - @reult TRUE if both cells belong to the same merged cell block - FALSE if the cells are not merged or are in different blocks + @param ACell1 Pointer to the first cell + @param ACell2 Pointer to the second cell + @returns @TRUE if both cells belong to the same merged cell block, @FALSE if the cells are not merged or are in different blocks -------------------------------------------------------------------------------} function TsWorksheet.InSameMergedRange(ACell1, ACell2: PCell): Boolean; begin @@ -3086,12 +3121,11 @@ begin end; {@@ ---------------------------------------------------------------------------- - Returns true if the specified cell is the base of a merged cell range, i.e. + Returns @true if the specified cell is the base of a merged cell range, i.e. the upper left corner of that range. - @param ACell Pointer to the cell being considered - @return True if the cell is the upper left corner of a merged range - False if not + @param ACell Pointer to the cell being considered + @returns @True if the cell is the upper left corner of a merged range, @False if not -------------------------------------------------------------------------------} function TsWorksheet.IsMergeBase(ACell: PCell): Boolean; begin @@ -3099,10 +3133,10 @@ begin end; {@@ ---------------------------------------------------------------------------- - Returns TRUE if the specified cell belongs to a merged block + Returns @TRUE if the specified cell belongs to a merged block - @param ACell Pointer to the cell of interest - @return TRUE if the cell belongs to a merged block, FALSE if not. + @param ACell Pointer to the cell of interest + @returns @TRUE if the cell belongs to a merged block, @FALSE if not. -------------------------------------------------------------------------------} function TsWorksheet.IsMerged(ACell: PCell): Boolean; begin @@ -3192,9 +3226,9 @@ end; {@@ ---------------------------------------------------------------------------- Removes a cell from its tree container. DOES NOT RELEASE ITS MEMORY! - @param ARow Row index of the cell to be removed - @param ACol Column index of the cell to be removed - @return Pointer to the cell removed + @param ARow Row index of the cell to be removed + @param ACol Column index of the cell to be removed + @returns Pointer to the cell removed -------------------------------------------------------------------------------} function TsWorksheet.RemoveCell(ARow, ACol: Cardinal): PCell; begin @@ -3295,7 +3329,7 @@ begin end; {@@ ---------------------------------------------------------------------------- - Returns TRUE if the worksheet is hidden + Returns @TRUE if the worksheet is hidden -------------------------------------------------------------------------------} function TsWorksheet.IsHidden: Boolean; begin @@ -3327,15 +3361,17 @@ end; found to be "equal" the next parameter is set is used until a difference is found, or all parameters are used. - @param ARow1 Row index of the first cell to be compared - @param ACol1 Column index of the first cell to be compared - @param ARow2 Row index of the second cell to be compared - @parem ACol2 Column index of the second cell to be compared - @param ASortOptions Sorting options: case-insensitive and/or descending - @return -1 if the first cell is "smaller", i.e. is sorted in front of the - second one - +1 if the first cell is "larger", i.e. is behind the second one - 0 if both cells are equal + The funtion result is + * -1 if the first cell is "smaller" --> the first cell is sorted before the second cell + * +1 if the first cell is "larger" --> the first cell is sorted behind the second cell + * 0 if both cells are "equal" + + @param ARow1 (Zero-based) row index of the first cell to be compared + @param ACol1 (Zero-based) column index of the first cell to be compared + @param ARow2 (Zero-based) row index of the second cell to be compared + @param ACol2 (Zero-based) column index of the second cell to be compared + @param ASortOptions Sorting options: case-insensitive and/or descending + @returns -1, 0, +1 depending on whether the first cell is "smaller", "equal" or "larger" that the second cell. ------------------------------------------------------------------------------- } function TsWorksheet.DoCompareCells(AColRow1, AColRow2: Cardinal): Integer; var @@ -3368,22 +3404,25 @@ end; {@@ ---------------------------------------------------------------------------- Compare function for sorting of rows and columns. Called by DoCompareCells. + Date/time and boolean cells are sorted like number cells according + to their number value + + Label cells are sorted as UTF8 strings. + + In case of mixed cell content types the order is determined by + the parameter Priority of the SortParams. + + Empty cells are always at the end (in both ascending and descending order) + + The funtion result is + * -1 if the first cell is "smaller" + * +1 if the first cell is "larger" + * 0 if both cells are "equal" + @param ACell1 Pointer to the first cell of the comparison @param ACell2 Pointer to the second cell of the comparison - @param ASortKey Sorting criteria: sorted column/row, descending, - case-insensitive, numbers first, etc. - @return -1 if the first cell is "smaller" - +1 if the first cell is "larger", - 0 if both cells are "equal" - - Date/time and boolean cells are sorted like number cells according - to their number value - Label cells are sorted as UTF8 strings. - - In case of mixed cell content types the order is determined by - the parameter Priority of the SortParams. - Empty cells are always at the end (in both ascending and descending - order) + @param ASortKey Sorting criteria: sorted column/row, descending, case-insensitive, numbers first, etc. + @returns -1, 0, +1 depending on whether the first cell is "smaller", "equal" or "larger" that the second cell. -------------------------------------------------------------------------------} function TsWorksheet.DefaultCompareCells(ACell1, ACell2: PCell; ASortKey: TsSortKey): Integer; @@ -3447,17 +3486,11 @@ end; {@@ ---------------------------------------------------------------------------- Exchanges columns or rows, depending on value of "AIsColumn" - @param AIsColumn if true the exchange is done for columns, otherwise for rows - @param AIndex Index of the column (if AIsColumn is true) or the row - (if AIsColumn is false) which is to be exchanged with the - one having index "WidthIndex" - @param WithIndex Index of the column (if AIsColumn is true) or the row - (if AIsColumn is false) with which "AIndex" is to be - replaced. - @param AFromIndex First row (if AIsColumn is true) or column (if AIsColumn - is false) which is affected by the exchange - @param AToIndex Last row (if AIsColumn is true) or column (if AsColumn is - false) which is affected by the exchange + @param AIsColumn If @true the exchange is done for columns, otherwise for rows + @param AIndex Index of the column (if AIsColumn is @true) or the row (if AIsColumn is @false) which is to be exchanged with the one having index "WidthIndex" + @param WithIndex Index of the column (if AIsColumn is @true) or the row (if AIsColumn is @false) with which "AIndex" is to be replaced. + @param AFromIndex First row (if AIsColumn is @true) or column (if AIsColumn is @false) which is affected by the exchange + @param AToIndex Last row (if AIsColumn is @true) or column (if AsColumn is @false) which is affected by the exchange -------------------------------------------------------------------------------} procedure TsWorksheet.DoExchangeColRow(AIsColumn: Boolean; AIndex, WithIndex: Cardinal; AFromIndex, AToIndex: Cardinal); @@ -3476,9 +3509,7 @@ end; Sorts a range of cells defined by the cell rectangle from ARowFrom/AColFrom to ARowTo/AColTo according to the parameters specified in ASortParams - @param ASortParams Set of parameters to define sorting along rows or colums, - the sorting key column or row indexes, and the sorting - directions + @param ASortParams Set of parameters to define sorting along rows or colums, the sorting key column or row indexes, and the sorting directions @param ARange Cell range to be sorted, in Excel notation, such as 'A1:C8' -------------------------------------------------------------------------------} procedure TsWorksheet.Sort(ASortParams: TsSortParams; ARange: String); @@ -3495,9 +3526,7 @@ end; Sorts a range of cells defined by the cell rectangle from ARowFrom/AColFrom to ARowTo/AColTo according to the parameters specified in ASortParams - @param ASortParams Set of parameters to define sorting along rows or colums, - the sorting key column or row indexes, and the sorting - directions + @param ASortParams Set of parameters to define sorting along rows or colums, the sorting key column or row indexes, and the sorting directions @param ARowFrom Top row of the range to be sorted @param AColFrom Left column of the range to be sorted @param ARowTo Last row of the range to be sorted @@ -3783,13 +3812,12 @@ end; @param ARow The row of the cell @param ACol The column of the cell @param AText The text to be written encoded in utf-8 - @param ARichTextParams Array of formatting instructions for characters or - groups of characters (see TsRichTextParam). + @param ARichTextParams Array of formatting instructions for characters or groups of characters (see TsRichTextParam). @return Pointer to cell created or used - @see TsRichTextParams - @see TsRichTextParam + @seeAlso TsRichTextParams + @seeAlso TsRichTextParam -------------------------------------------------------------------------------} function TsWorksheet.WriteText(ARow, ACol: Cardinal; AText: String; ARichTextParams: TsRichTextParams = nil): PCell; @@ -3810,13 +3838,12 @@ end; @param ACell Pointer to the cell @param AText The text to be written encoded in utf-8 - @param ARichTextParams Array of formatting instructions for characters or - groups of characters (see TsRichTextParam). + @param ARichTextParams Array of formatting instructions for characters or groups of characters (see TsRichTextParam). @note The cell content will be set to cctEmpty if the string is empty. - @see TsRichTextParams - @see TsRichTextParam + @seeAlso TsRichTextParams + @seeAlso TsRichTextParam -------------------------------------------------------------------------------} procedure TsWorksheet.WriteText(ACell: PCell; AText: String; ARichTextParams: TsRichTextParams = nil); @@ -3885,10 +3912,10 @@ end; @param ACol The column of the cell @param AText The text containing the html codes - @return Pointer to cell created or used + @returns Pointer to cell created or used - @see TsRichTextParams - @see TsRichTextParam + @seeAlso TsRichTextParams + @seeAlso TsRichTextParam -------------------------------------------------------------------------------} function TsWorksheet.WriteTextAsHTML(ARow, ACol: Cardinal; AText: String): PCell; begin @@ -3925,8 +3952,8 @@ end; @param ACell Pointer to the cell @param AText The text containing the html codes - @see TsRichTextParams - @see TsRichTextParam + @seeAlso TsRichTextParams + @seeAlso TsRichTextParam -------------------------------------------------------------------------------} procedure TsWorksheet.WriteTextAsHTML(ACell: PCell; AText: String); var @@ -3976,15 +4003,14 @@ end; {@@ ---------------------------------------------------------------------------- Writes a floating-point number to a cell - @param ARow Cell row index - @param ACol Cell column index - @param ANumber Number to be written - @param ANumFormat Identifier for a built-in number format, - e.g. nfFixed (optional) - @param ADecimals Number of decimal places used for formatting (optional) - @param AMinIntDigits Minimum count of digits before the decimal separator - @return Pointer to cell created or used - @see TsNumberFormat + @param ARow Cell row index + @param ACol Cell column index + @param ANumber Number to be written + @param ANumFormat Identifier for a built-in number format, e.g. nfFixed (optional) + @param ADecimals Number of decimal places used for formatting (optional) + @param AMinIntDigits Minimum count of digits before the decimal separator + @returns Pointer to cell created or used + @seeAlso TsNumberFormat -------------------------------------------------------------------------------} function TsWorksheet.WriteNumber(ARow, ACol: Cardinal; ANumber: Double; ANumFormat: TsNumberFormat; ADecimals: Byte = 2; @@ -3997,14 +4023,12 @@ end; {@@ ---------------------------------------------------------------------------- Writes a floating-point number to a cell - @param ACell Pointer to the cell - @param ANumber Number to be written - @param ANumFormat Identifier for a built-in number format, e.g. nfFixed - @param ADecimals Optional number of decimal places used for formatting - If ANumFormat is nfFraction the ADecimals defines the - digits of Numerator and denominator. - @param AMinIntDigits Minimum count of digits before the decimal separator - @see TsNumberFormat + @param ACell Pointer to the cell + @param ANumber Number to be written + @param ANumFormat Identifier for a built-in number format, e.g. nfFixed + @param ADecimals Optional number of decimal places used for formatting. If ANumFormat is nfFraction the ADecimals defines the digits of Numerator and denominator. + @param AMinIntDigits Minimum count of digits before the decimal separator + @seeAlso TsNumberFormat -------------------------------------------------------------------------------} procedure TsWorksheet.WriteNumber(ACell: PCell; ANumber: Double; ANumFormat: TsNumberFormat; ADecimals: Byte = 2; @@ -4051,12 +4075,12 @@ end; Note that fpspreadsheet may not be able to detect the formatting when reading the file. - @param ARow Cell row index - @param ACol Cell column index - @param ANumber Number to be written - @param ANumFormat Format identifier (nfCustom) - @param ANumFormatString String of formatting codes (such as 'dd/mmm' - @return Pointer to cell created or used + @param ARow Cell row index + @param ACol Cell column index + @param ANumber Number to be written + @param ANumFormat Format identifier (nfCustom) + @param ANumFormatString String of formatting codes (such as 'dd/mmm' + @returns Pointer to cell created or used -------------------------------------------------------------------------------} function TsWorksheet.WriteNumber(ARow, ACol: Cardinal; ANumber: Double; ANumFormat: TsNumberFormat; ANumFormatString: String): PCell; @@ -4121,14 +4145,11 @@ end; {@@ ---------------------------------------------------------------------------- Writes an empty cell - @param ARow The row of the cell - @param ACol The column of the cell - @param KeepFormula Does not erase the formula. Off by default because it - would be very confusing if the formula had a - non-blank result. - @return Pointer to the cell - Note: Empty cells are useful when, for example, a border line extends - along a range of cells including empty cells. + @param ARow The row of the cell + @param ACol The column of the cell + @param KeepFormula Does not erase the formula. Off by default because it would be very confusing if the formula had a non-blank result. + @returns Pointer to the cell + @Note Empty cells are useful when, for example, a border line extends along a range of cells including empty cells. -------------------------------------------------------------------------------} function TsWorksheet.WriteBlank(ARow, ACol: Cardinal; KeepFormula: Boolean = false): PCell; @@ -4141,11 +4162,8 @@ end; Writes an empty cell @param ACel Pointer to the cell - @param KeepFormula Does not erase the formula. Off by default because it - would be very confusing if the formula had a - non-blank result. - Note: Empty cells are useful when, for example, a border line extends - along a range of cells including empty cells. + @param KeepFormula Does not erase the formula. Off by default because it would be very confusing if the formula had a non-blank result. + @Note Empty cells are useful when, for example, a border line extends along a range of cells including empty cells. -------------------------------------------------------------------------------} procedure TsWorksheet.WriteBlank(ACell: PCell; KeepFormula: Boolean = false); begin @@ -4167,10 +4185,10 @@ end; {@@ ---------------------------------------------------------------------------- Writes a boolean cell - @param ARow The row of the cell - @param ACol The column of the cell - @param AValue The boolean value - @return Pointer to the cell + @param ARow The row of the cell + @param ACol The column of the cell + @param AValue The boolean value + @returns Pointer to the cell -------------------------------------------------------------------------------} function TsWorksheet.WriteBoolValue(ARow, ACol: Cardinal; AValue: Boolean): PCell; begin @@ -4201,12 +4219,10 @@ end; string, the worksheet tries to guess whether it is a number, a date/time or a text and calls the corresponding writing method. - @param ARow Row index of the cell - @param ACol Column index of the cell - @param AValue Value to be written into the cell given as a string. Depending - on the structure of the string, however, the value is written - as a number, a date/time or a text. - @return Pointer to the cell + @param ARow Row index of the cell + @param ACol Column index of the cell + @param AValue Value to be written into the cell given as a string. Depending on the structure of the string, however, the value is written as a number, a date/time or a text. + @returns Pointer to the cell -------------------------------------------------------------------------------} function TsWorksheet.WriteCellValueAsString(ARow, ACol: Cardinal; AValue: String): PCell; @@ -4220,14 +4236,11 @@ end; string, the worksheet tries to guess whether it is a number, a date/time or a text and calls the corresponding writing method. - @param ARow Row index of the cell - @param ACol Column index of the cell - @param AValue Value to be written into the cell given as a string. Depending - on the structure of the string, however, the value is written - as a number, a date/time or a text. - @param AFormatSettings FormatSettings record used for conversion of strings - with date/time, numbers etc. - @return Pointer to the cell + @param ARow Row index of the cell + @param ACol Column index of the cell + @param AValue Value to be written into the cell given as a string. Depending on the structure of the string, however, the value is written as a number, a date/time or a text. + @param AFormatSettings FormatSettings record used for conversion of strings with date/time, numbers etc. + @returns Pointer to the cell -------------------------------------------------------------------------------} function TsWorksheet.WriteCellValueAsString(ARow, ACol: Cardinal; AValue: String; const AFormatSettings: TFormatSettings): PCell; @@ -4244,9 +4257,7 @@ end; defined in the workbook. @param ACell Pointer to the cell - @param AValue Value to be written into the cell given as a string. Depending - on the structure of the string, however, the value is written - as a number, a date/time or a text. + @param AValue Value to be written into the cell given as a string. Depending on the structure of the string, however, the value is written as a number, a date/time or a text. -------------------------------------------------------------------------------} procedure TsWorksheet.WriteCellValueAsString(ACell: PCell; AValue: String); begin @@ -4260,11 +4271,8 @@ end; Uses the provided FormatSettings for date/time etc. @param ACell Pointer to the cell - @param AValue Value to be written into the cell given as a string. Depending - on the structure of the string, however, the value is written - as a number, a date/time or a text. - @param AFormatSettings FormatSettings record used for conversion of strings - with date/time, numbers etc. + @param AValue Value to be written into the cell given as a string. Depending on the structure of the string, however, the value is written as a number, a date/time or a text. + @param AFormatSettings FormatSettings record used for conversion of strings with date/time, numbers etc. -------------------------------------------------------------------------------} procedure TsWorksheet.WriteCellValueAsString(ACell: PCell; AValue: String; const AFormatSettings: TFormatSettings); @@ -4435,20 +4443,15 @@ end; Writes a currency value to a given cell. Its number format can be provided optionally by specifying various parameters. - @param ARow Cell row index - @param ACol Cell column index - @param AValue Number value to be written - @param ANumFormat Format identifier, must be nfCurrency, or nfCurrencyRed. - @param ADecimals Number of decimal places - @param APosCurrFormat Code specifying the order of value, currency symbol - and spaces (see pcfXXXX constants) - @param ANegCurrFormat Code specifying the order of value, currency symbol, - spaces, and how negative values are shown - (see ncfXXXX constants) - @param ACurrencySymbol String to be shown as currency, such as '$', or 'EUR'. - In case of '?' the currency symbol defined in the - workbook's FormatSettings is used. - @return Pointer to the cell + @param ARow Cell row index + @param ACol Cell column index + @param AValue Number value to be written + @param ANumFormat Format identifier, must be nfCurrency, or nfCurrencyRed. + @param ADecimals Number of decimal places + @param APosCurrFormat Code specifying the order of value, currency symbol and spaces (see pcfXXXX constants) + @param ANegCurrFormat Code specifying the order of value, currency symbol, spaces, and how negative values are shown (see ncfXXXX constants) + @param ACurrencySymbol String to be shown as currency, such as '$', or 'EUR'. In case of '?' the currency symbol defined in the workbook's FormatSettings is used. + @returns Pointer to the cell -------------------------------------------------------------------------------} function TsWorksheet.WriteCurrency(ARow, ACol: Cardinal; AValue: Double; ANumFormat: TsNumberFormat = nfCurrency; ADecimals: Integer = 2; @@ -4464,18 +4467,13 @@ end; Writes a currency value to a given cell. Its number format can be provided optionally by specifying various parameters. - @param ACell Pointer to the cell considered - @param AValue Number value to be written - @param ANumFormat Format identifier, must be nfCurrency or nfCurrencyRed. - @param ADecimals Number of decimal places - @param APosCurrFormat Code specifying the order of value, currency symbol - and spaces (see pcfXXXX constants) - @param ANegCurrFormat Code specifying the order of value, currency symbol, - spaces, and how negative values are shown - (see ncfXXXX constants) - @param ACurrencySymbol String to be shown as currency, such as '$', or 'EUR'. - In case of '?' the currency symbol defined in the - workbook's FormatSettings is used. + @param ACell Pointer to the cell considered + @param AValue Number value to be written + @param ANumFormat Format identifier, must be nfCurrency or nfCurrencyRed. + @param ADecimals Number of decimal places + @param APosCurrFormat Code specifying the order of value, currency symbol and spaces (see pcfXXXX constants) + @param ANegCurrFormat Code specifying the order of value, currency symbol, spaces, and how negative values are shown (see ncfXXXX constants) + @param ACurrencySymbol String to be shown as currency, such as '$', or 'EUR'. In case of '?' the currency symbol defined in the workbook's FormatSettings is used. -------------------------------------------------------------------------------} procedure TsWorksheet.WriteCurrency(ACell: PCell; AValue: Double; ANumFormat: TsNumberFormat = nfCurrency; ADecimals: Integer = -1; @@ -4512,11 +4510,8 @@ end; @param ACol Cell column index @param AValue Number value to be written @param ANumFormat Format identifier, must be nfCurrency or nfCurrencyRed. - @param ANumFormatString String of formatting codes, including currency symbol. - Can contain sections for different formatting of positive - and negative number. - Example: '"EUR" #,##0.00;("EUR" #,##0.00)' - @return Pointer to the cell + @param ANumFormatString String of formatting codes, including currency symbol. Can contain sections for different formatting of positive and negative number. Example: '"EUR" #,##0.00;("EUR" #,##0.00)' + @returns Pointer to the cell -------------------------------------------------------------------------------} function TsWorksheet.WriteCurrency(ARow, ACol: Cardinal; AValue: Double; ANumFormat: TsNumberFormat; ANumFormatString: String): PCell; @@ -4532,10 +4527,7 @@ end; @param ACell Pointer to the cell considered @param AValue Number value to be written @param ANumFormat Format identifier, must be nfCurrency or nfCurrencyRed. - @param ANumFormatString String of formatting codes, including currency symbol. - Can contain sections for different formatting of positive - and negative number. - Example: '"EUR" #,##0.00;("EUR" #,##0.00)' + @param ANumFormatString String of formatting codes, including currency symbol. Can contain sections for different formatting of positive and negative number. Example: '"EUR" #,##0.00;("EUR" #,##0.00)' -------------------------------------------------------------------------------} procedure TsWorksheet.WriteCurrency(ACell: PCell; AValue: Double; ANumFormat: TsNumberFormat; ANumFormatString: String); @@ -4565,10 +4557,10 @@ end; {@@ ---------------------------------------------------------------------------- Writes a date/time value to a cell, does not change number format - @param ARow The row of the cell - @param ACol The column of the cell - @param AValue The date/time/datetime to be written - @return Pointer to the cell + @param ARow The row of the cell + @param ACol The column of the cell + @param AValue The date/time/datetime to be written + @returns Pointer to the cell -------------------------------------------------------------------------------} function TsWorksheet.WriteDateTime(ARow, ACol: Cardinal; AValue: TDateTime): PCell; begin @@ -4600,14 +4592,11 @@ end; @param ARow The row of the cell @param ACol The column of the cell @param AValue The date/time/datetime to be written - @param ANumFormat The format specifier, e.g. nfShortDate (optional) - If not specified format is not changed. + @param ANumFormat The format specifier, e.g. nfShortDate (optional). If not specified format is not changed. @param ANumFormatStr Format string, used only for nfCustom or nfTimeInterval. - @return Pointer to the cell + @returns Pointer to the cell - Note: at least Excel xls does not recognize a separate datetime cell type: - a datetime is stored as a (floating point) number, and the cell is formatted - as a date (either built-in or a custom format). + @Note At least Excel xls does not recognize a separate datetime cell type: a datetime is stored as a (floating point) number, and the cell is formatted as a date (either built-in or a custom format). -------------------------------------------------------------------------------} function TsWorksheet.WriteDateTime(ARow, ACol: Cardinal; AValue: TDateTime; ANumFormat: TsNumberFormat; ANumFormatStr: String = ''): PCell; @@ -4621,13 +4610,10 @@ end; @param ACell Pointer to the cell considered @param AValue The date/time/datetime to be written - @param ANumFormat The format specifier, e.g. nfShortDate (optional) - If not specified format is not changed. + @param ANumFormat The format specifier, e.g. nfShortDate (optional). If not specified format is not changed. @param ANumFormatStr Format string, used only for nfCustom or nfTimeInterval. - Note: at least Excel xls does not recognize a separate datetime cell type: - a datetime is stored as a (floating point) number, and the cell is formatted - as a date (either built-in or a custom format). + @Note At least Excel xls does not recognize a separate datetime cell type: a datetime is stored as a (floating point) number, and the cell is formatted as a date (either built-in or a custom format). -------------------------------------------------------------------------------} procedure TsWorksheet.WriteDateTime(ACell: PCell; AValue: TDateTime; ANumFormat: TsNumberFormat; ANumFormatStr: String = ''); @@ -4692,16 +4678,13 @@ end; {@@ ---------------------------------------------------------------------------- Writes a date/time value to a cell - @param ARow The row index of the cell - @param ACol The column index of the cell - @param AValue The date/time/datetime to be written - @param ANumFormatStr Format string (the format identifier nfCustom is used to - classify the format). - @return Pointer to the cell + @param ARow The row index of the cell + @param ACol The column index of the cell + @param AValue The date/time/datetime to be written + @param ANumFormatStr Format string (the format identifier nfCustom is used to classify the format). + @returns Pointer to the cell - Note: at least Excel xls does not recognize a separate datetime cell type: - a datetime is stored as a (floating point) number, and the cell is formatted - as a date (either built-in or a custom format). + @Note At least Excel xls does not recognize a separate datetime cell type: a datetime is stored as a (floating point) number, and the cell is formatted as a date (either built-in or a custom format). -------------------------------------------------------------------------------} function TsWorksheet.WriteDateTime(ARow, ACol: Cardinal; AValue: TDateTime; ANumFormatStr: String): PCell; @@ -4715,12 +4698,9 @@ end; @param ACell Pointer to the cell considered @param AValue The date/time/datetime to be written - @param ANumFormatStr Format string (the format identifier nfCustom is used to - classify the format). + @param ANumFormatStr Format string (the format identifier nfCustom is used to classify the format). - Note: at least Excel xls does not recognize a separate datetime cell type: - a datetime is stored as a (floating point) number, and the cell is formatted - as a date (either built-in or a custom format). + @Note At least Excel xls does not recognize a separate datetime cell type: a datetime is stored as a (floating point) number, and the cell is formatted as a date (either built-in or a custom format). -------------------------------------------------------------------------------} procedure TsWorksheet.WriteDateTime(ACell: PCell; AValue: TDateTime; ANumFormatStr: String); @@ -4731,12 +4711,12 @@ end; {@@ ---------------------------------------------------------------------------- Writes an error value to a cell. - @param ARow The row of the cell - @param ACol The column of the cell - @param AValue The error code value - @return Pointer to the cell + @param ARow The row of the cell + @param ACol The column of the cell + @param AValue The error code value + @returns Pointer to the cell - @see TsErrorValue + @seeAlso TsErrorValue -------------------------------------------------------------------------------} function TsWorksheet.WriteErrorValue(ARow, ACol: Cardinal; AValue: TsErrorValue): PCell; begin @@ -4747,10 +4727,10 @@ end; {@@ ---------------------------------------------------------------------------- Writes an error value to a cell. - @param ACol Pointer to the cell to be written - @param AValue The error code value + @param ACol Pointer to the cell to be written + @param AValue The error code value - @see TsErrorValue + @seeAlso TsErrorValue -------------------------------------------------------------------------------} procedure TsWorksheet.WriteErrorValue(ACell: PCell; AValue: TsErrorValue); begin @@ -4767,16 +4747,12 @@ end; {@@ ---------------------------------------------------------------------------- Writes a formula to a given cell - @param ARow The row of the cell - @param ACol The column of the cell - @param AFormula The formula string to be written. A leading "=" will be removed. - @param ALocalized If true, the formula is expected to have decimal and list - separators of the workbook's FormatSettings. Otherwise - uses dot and comma, respectively. - @param R1C1Mode If true, the formula is expected to contain cell references - in Excel's "R1C1" notation; otherwise "A1" references are - expected. - @return Pointer to the cell + @param ARow The row of the cell + @param ACol The column of the cell + @param AFormula The formula string to be written. A leading "=" will be removed. + @param ALocalized If @true, the formula is expected to have decimal and list separators of the workbook's FormatSettings. Otherwise uses dot and comma, respectively. + @param R1C1Mode If @true, the formula is expected to contain cell references in Excel's "R1C1" notation; otherwise "A1" references are expected. + @returns Pointer to the cell -------------------------------------------------------------------------------} function TsWorksheet.WriteFormula(ARow, ACol: Cardinal; AFormula: String; ALocalized: Boolean = false; R1C1Mode: Boolean = false): PCell; @@ -4789,12 +4765,8 @@ end; Writes a formula to a given cell @param ACell Pointer to the cell - @param AFormula Formula string to be written. A leading '=' will be removed. - If AFormula is '' then an formula already assigned to this - cell is deleted. - @param ALocalized If true, the formula is expected to have decimal and list - separators of the workbook's FormatSettings. Otherwise - uses dot and comma, respectively. + @param AFormula Formula string to be written. A leading '=' will be removed. If AFormula is '' then an formula already assigned to this cell is deleted. + @param ALocalized If @true, the formula is expected to have decimal and list separators of the workbook's FormatSettings. Otherwise uses dot and comma, respectively. -------------------------------------------------------------------------------} procedure TsWorksheet.WriteFormula(ACell: PCell; AFormula: String; ALocalized: Boolean = false; R1C1Mode: Boolean = false); @@ -4869,15 +4841,14 @@ end; Writes an RPN formula to a cell. An RPN formula is an array of tokens describing the calculation to be performed. - @param ARow Row indows of the cell considered - @param ACol Column index of the cell - @param AFormula Array of TsFormulaElements. The array can be created by - using "CreateRPNFormla". - @return Pointer to the cell + @param ARow Row indows of the cell considered + @param ACol Column index of the cell + @param AFormula Array of @link(TsFormulaElement) records. The array can be created by using "CreateRPNFormla". + @returns Pointer to the cell - @see TsNumberFormat - @see TsFormulaElements - @see CreateRPNFormula + @seeAlso TsNumberFormat + @seeAlso TsFormulaElement + @seeAlso CreateRPNFormula -------------------------------------------------------------------------------} function TsWorksheet.WriteRPNFormula(ARow, ACol: Cardinal; AFormula: TsRPNFormula): PCell; @@ -4892,12 +4863,11 @@ end; converted to a string formula. @param ACell Pointer to the cell - @param AFormula Array of TsFormulaElements. The array can be created by - using "CreateRPNFormla". + @param AFormula Array of TsFormulaElements. The array can be created by using "CreateRPNFormla". - @see TsNumberFormat - @see TsFormulaElements - @see CreateRPNFormula + @seeAlso TsNumberFormat + @seeAlso TsFormulaElement + @seeAlso CreateRPNFormula -------------------------------------------------------------------------------} procedure TsWorksheet.WriteRPNFormula(ACell: PCell; ARPNFormula: TsRPNFormula); var @@ -4932,10 +4902,7 @@ end; {@@ ---------------------------------------------------------------------------- Moves the worksheet to the specified index in the workbook. - @param AValue New index of the sheet in the workbook. If less than 0 the - worksheet will become the first, if greater than the - worksheet count it will become the last worksheet of the - workbook. + @param AValue New index of the sheet in the workbook. If less than 0 the worksheet will become the first, if greater than the worksheet count it will become the last worksheet of the workbook. -------------------------------------------------------------------------------} procedure TsWorksheet.SetIndex(AValue: Integer); var @@ -4962,7 +4929,7 @@ end; of the individual cells in the row. Is converted to workbook units. @param ARow Index of the row to be considered - @return Row height in workbook units + @returns Row height in workbook units -------------------------------------------------------------------------------} function TsWorksheet.CalcAutoRowHeight(ARow: Cardinal): Single; var @@ -5020,7 +4987,7 @@ end; to the row record, or nil if not found @param ARow Index of the row looked for - @return Pointer to the row record with this row index, or nil if not found + @returns Pointer to the row record with this row index, or nil if not found -------------------------------------------------------------------------------} function TsWorksheet.FindRow(ARow: Cardinal): PRow; var @@ -5038,9 +5005,8 @@ end; Checks if a column record exists for the given column index and returns a pointer to the TCol record, or nil if not found - @param ACol Index of the column looked for - @return Pointer to the column record with this column index, or nil - if not found + @param ACol Index of the column looked for + @returns Pointer to the column record with this column index, or nil if not found. -------------------------------------------------------------------------------} function TsWorksheet.FindCol(ACol: Cardinal): PCol; var @@ -5058,9 +5024,8 @@ end; Checks if a row record exists for the given row index and creates it if not found. - @param ARow Index of the row looked for - @return Pointer to the row record with this row index. It can safely be - assumed that this row record exists. + @param ARow Index of the row looked for + @returns Pointer to the row record with this row index. It can safely be assumed that this row record exists. -------------------------------------------------------------------------------} function TsWorksheet.GetRow(ARow: Cardinal): PRow; begin @@ -5073,8 +5038,8 @@ end; Creates a new row record for the specific row index. It is not checked whether a row record already exists for this index. Dupliate records must be avoided! - @param ARow Index of the row to be added - @return Pointer to the row record with this row index. + @param ARow Index of the row to be added + @returns Pointer to the row record with this row index. -------------------------------------------------------------------------------} function TsWorksheet.AddRow(ARow: Cardinal): PRow; begin @@ -5094,9 +5059,8 @@ end; Checks if a column record exists for the given column index and creates it if not found. - @param ACol Index of the column looked for - @return Pointer to the TCol record with this column index. It can - safely be assumed that this column record exists. + @param ACol Index of the column looked for + @returns Pointer to the TCol record with this column index. It can safely be assumed that this column record exists. -------------------------------------------------------------------------------} function TsWorksheet.GetCol(ACol: Cardinal): PCol; begin @@ -5110,8 +5074,8 @@ end; It is not checked whether a column record already exists for this index. Dupliate records must be avoided! - @param ACol Index of the column to be added - @return Pointer to the column record with this column index. + @param ACol Index of the column to be added + @returns Pointer to the column record with this column index. -------------------------------------------------------------------------------} function TsWorksheet.AddCol(ACol: Cardinal): PCol; begin @@ -5131,8 +5095,8 @@ end; Counts how many cells exist in the given column. Blank cells do contribute to the sum, as well as formatted cells. - @param ACol Index of the column considered - @return Count of cells with value or format in this column + @param ACol Index of the column considered + @returns Count of cells with value or format in this column -------------------------------------------------------------------------------} function TsWorksheet.GetCellCountInCol(ACol: Cardinal): Cardinal; var @@ -5156,8 +5120,8 @@ end; Counts how many cells exist in the given row. Blank cells do contribute to the sum, as well as formatted cell.s - @param ARow Index of the row considered - @return Count of cells with value or format in this row + @param ARow Index of the row considered + @returns Count of cells with value or format in this row -------------------------------------------------------------------------------} function TsWorksheet.GetCellCountInRow(ARow: Cardinal): Cardinal; var @@ -5181,10 +5145,8 @@ end; Returns the index to the cell format to be used for a given column. If there is no column record then the default format (index 0) is used. - @param ACol Index of the column considered - @return Index of the format into the workbook's FCellFormatList. This format - will be used for formatting a cell if itself does not have a - non-zero format index, and if there is no row format either. + @param ACol Index of the column considered + @returns Index of the format into the workbook's FCellFormatList. This format will be used for formatting a cell if itself does not have a non-zero format index, and if there is no row format either. -------------------------------------------------------------------------------} function TsWorksheet.GetColFormatIndex(ACol: Cardinal): Integer; var @@ -5203,9 +5165,9 @@ end; Returns the width of the given column. If there is no column record then the default column width is returned. - @param ACol Index of the column considered - @param AUnits Units for the column width. - @return Width of the column + @param ACol Index of the column considered + @param AUnits Units for the column width. + @returns Width of the column -------------------------------------------------------------------------------} function TsWorksheet.GetColWidth(ACol: Cardinal; AUnits: TsSizeUnits): Single; var @@ -5243,10 +5205,9 @@ end; Returns the type of column width of a specific column. If there is no column record then cwtDefault is returned. - @param ACol Index of the column considered - @param AUnits Units for the column width. - @return Width of the column. This is the "raw" value, without application of - the zoom factor. + @param ACol Index of the column considered + @param AUnits Units for the column width. + @returns Width of the column. This is the "raw" value, without application of the zoom factor. -------------------------------------------------------------------------------} function TsWorksheet.GetColWidthType(ACol: Cardinal): TsColWidthType; var @@ -5264,10 +5225,8 @@ end; Returns the index to the cell format to be used for a given row. If there is no row record then the default format (index 0) is returned. - @param ARow Index of the row considered - @return Index of the format into the workbook's FCellFormatList. This format - will be used for formatting a cell if itself does not have a - non-zero format index. + @param ARow Index of the row considered + @returns Index of the format into the workbook's FCellFormatList. This format will be used for formatting a cell if itself does not have a non-zero format index. -------------------------------------------------------------------------------} function TsWorksheet.GetRowFormatIndex(ARow: Cardinal): Integer; var @@ -5286,10 +5245,9 @@ end; Returns the height of the given row. If there is no row record then the default row height is returned - @param ARow Index of the row considered - @param AUnits Units for the row height. - @return Height of the row. This is the "raw" value, without application of - the zoom factor. + @param ARow Index of the row considered + @param AUnits Units for the row height. + @returns Height of the row. This is the "raw" value, without application of the zoom factor. -------------------------------------------------------------------------------} function TsWorksheet.GetRowHeight(ARow: Cardinal; AUnits: TsSizeUnits): Single; var @@ -5327,13 +5285,12 @@ begin end; {@@ ---------------------------------------------------------------------------- - Returns the type of rowheight of a specific row. + Returns the type of row height of a specific row. If there is no row record then rhtDefault is returned. - @param ARow Index of the row considered - @param AUnits Units for the row height. - @return Height of the row. This is the "raw" value, without application of - the zoom factor. + @param ARow Index of the row considered + @param AUnits Units for the row height. + @returns Height of the row. This is the "raw" value, without application of the zoom factor. -------------------------------------------------------------------------------} function TsWorksheet.GetRowHeightType(ARow: Cardinal): TsRowHeightType; var @@ -5515,7 +5472,7 @@ end; Merged cell blocks and cell references in formulas are considered as well. @param AIndex Index of the row to be deleted - @param IsRow If TRUE then AIndex is a row index, otherwise a column index + @param IsRow If @TRUE then AIndex is a row index, otherwise a column index -------------------------------------------------------------------------------} procedure TsWorksheet.DeleteRowOrCol(AIndex: Integer; IsRow: Boolean); var @@ -5616,10 +5573,8 @@ end; Cells with greater row/column indexes are moved one row down/right. Merged cell blocks and cell references in formulas are considered as well. - @param AIndex Index of the row or column before which a new row or - column is inserted. - @param IsRow Determines whether AIndex refers to a row index (TRUE) or - column index (FALSE). + @param AIndex Index of the row or column before which a new row or column is inserted. + @param IsRow Determines whether AIndex refers to a row index (@TRUE) or column index (@FALSE). -------------------------------------------------------------------------------} procedure TsWorksheet.InsertRowOrCol(AIndex: Integer; IsRow: Boolean); var @@ -5800,7 +5755,8 @@ end; {@@ ---------------------------------------------------------------------------- Removes all row records from the worksheet and frees the occupied memory. - Note: Cells are retained. + + @Note Cells are retained. -------------------------------------------------------------------------------} procedure TsWorksheet.RemoveAllRows; var @@ -5816,7 +5772,8 @@ end; {@@ ---------------------------------------------------------------------------- Removes all column records from the worksheet and frees the occupied memory. - Note: Cells are retained. + + @Note Cells are retained. -------------------------------------------------------------------------------} procedure TsWorksheet.RemoveAllCols; var @@ -5834,7 +5791,7 @@ end; Removes a specified column record from the worksheet and frees the occupied memory. This resets its column width and format to default. - Note: Cells in that column are retained. + @Note Cells in that column are retained. -------------------------------------------------------------------------------} procedure TsWorksheet.RemoveCol(ACol: Cardinal); var @@ -5853,7 +5810,7 @@ end; {@@ ---------------------------------------------------------------------------- Removes a specified row record from the worksheet and frees the occupied memory. This resets the its row height to default. - Note: Cells in that row are retained. + @Note Cells in that row are retained. -------------------------------------------------------------------------------} procedure TsWorksheet.RemoveRow(ARow: Cardinal); var @@ -5876,8 +5833,7 @@ end; Creates a new row record if it does not yet exist. @param ARow Index of the row record which will be created or modified - @param AData Data to be written. Row height expected to be already in the - units defined for the workbook. + @param AData Data to be written. Row height expected to be already in the units defined for the workbook. -------------------------------------------------------------------------------} procedure TsWorksheet.WriteRowInfo(ARow: Cardinal; AData: TRow); var @@ -5896,8 +5852,7 @@ end; Creates a new row record if it does not yet exist. @param ARow Index of the row to be considered - @param AFormatIndex Index into the workbook's FCellFormatList. This format - will be used if a cell has default format index (0). + @param AFormatIndex Index into the workbook's FCellFormatList. This format will be used if a cell has default format index (0). -------------------------------------------------------------------------------} procedure TsWorksheet.WriteRowFormatIndex(ARow: Cardinal; AFormatIndex:Integer); var @@ -5914,11 +5869,10 @@ end; Sets the row height for a given row. Creates a new row record if it does not yet exist. - @param ARow Index of the row to be considered - @param AHeight Row height to be assigned to the row. - @param AUnits Units measuring the row height. - @param ARowHeightType Specifies whether the row height is a default, - automatic or custom row height. + @param ARow Index of the row to be considered + @param AHeight Row height to be assigned to the row. + @param AUnits Units measuring the row height. + @param ARowHeightType Specifies whether the row height is a default, automatic or custom row height. -------------------------------------------------------------------------------} procedure TsWorksheet.WriteRowHeight(ARow: Cardinal; AHeight: Single; AUnits: TsSizeUnits; ARowHeightType: TsRowHeightType = rhtCustom); @@ -5956,8 +5910,7 @@ end; Creates a new column record if it does not yet exist. @param ACol Index of the column record which will be created or modified - @param AData Data to be written. The column width must already be in - the units defined for the workbook. + @param AData Data to be written. The column width must already be in the units defined for the workbook. -------------------------------------------------------------------------------} procedure TsWorksheet.WriteColInfo(ACol: Cardinal; AData: TCol); var @@ -5976,9 +5929,7 @@ end; Creates a new column record if it does not yet exist. @param ACol Index of the column to be considered - @param AFormatIndex Index into the workbook's FCellFormatList. This format - will be used if a cell has default format index (0) and - if there is no specific default row format. + @param AFormatIndex Index into the workbook's FCellFormatList. This format will be used if a cell has default format index (0) and if there is no specific default row format. -------------------------------------------------------------------------------} procedure TsWorksheet.WriteColFormatIndex(ACol: Cardinal; AFormatIndex:Integer); var @@ -5995,11 +5946,10 @@ end; Sets the column width for a given column. Creates a new column record if it does not yet exist. - @param ACol Index of the column to be considered - @param AWidth Width to be assigned to the column. - @param AColWidthType Type of the column width (default -> AWidth is ignored) - or custom) - @param AUnits Units used for parameter AWidth. + @param ACol Index of the column to be considered + @param AWidth Width to be assigned to the column. + @param AColWidthType Type of the column width (default -> AWidth is ignored) or custom + @param AUnits Units used for parameter AWidth. -------------------------------------------------------------------------------} procedure TsWorksheet.WriteColWidth(ACol: Cardinal; AWidth: Single; AUnits: TsSizeUnits; AColWidthType: TsColWidthType = cwtCustom); @@ -6071,6 +6021,7 @@ end; {@@ ---------------------------------------------------------------------------- Sets the PageBreak flag for the row record with the specified row index. This means that, when printed, a page break will occur before this row. + Note that FPS currently does not support printing by itself. -------------------------------------------------------------------------------} procedure TsWorksheet.AddPageBreakToRow(ARow: Cardinal); @@ -6111,6 +6062,7 @@ end; index. This means that, during printing, page break handling of this column will be automatic. + Note that FPS currently does not support printing by itself. -------------------------------------------------------------------------------} procedure TsWorksheet.RemovePageBreakFromCol(ACol: Cardinal); @@ -6131,6 +6083,7 @@ end; Removes the PageBreak flag for the row record with the specified row index. This means that, during printing, page break handling of this row will be automatic. + Note that FPS currently does not support printing by itself. -------------------------------------------------------------------------------} procedure TsWorksheet.RemovePageBreakFromRow(ARow: Cardinal); @@ -6454,6 +6407,7 @@ end; {@@ ---------------------------------------------------------------------------- Determines the maximum index of used columns and rows in all sheets of this workbook. Respects VirtualMode. + Is needed to disable saving when limitations of the format is exceeded. -------------------------------------------------------------------------------} procedure TsWorkbook.GetLastRowColIndex(out ALastRow, ALastCol: Cardinal); @@ -6686,9 +6640,7 @@ end; @param AFileName Name of the file to be written @param AFormat The file will be written in this file format. - @param AOverwriteExisting If the file is already existing it will be - overwritten in case of AOverwriteExisting = true. - If false an exception will be raised. + @param AOverwriteExisting If the file is already existing it will be overwritten in case of AOverwriteExisting = @true. If @false an exception will be raised. @param AParams Optional parameters to control stream access. -------------------------------------------------------------------------------} procedure TsWorkbook.WriteToFile(const AFileName: string; @@ -6707,9 +6659,7 @@ end; @param AFileName Name of the file to be written @param AFormatID The file will be written in the file format identified by this number. - @param AOverwriteExisting If the file is already existing it will be - overwritten in case of AOverwriteExisting = true. - If the parameter is FALSE then an exception will be raised. + @param AOverwriteExisting If the file is already existing it will be overwritten in case of AOverwriteExisting = @true. If the parameter is @FALSE then an exception will be raised. @param AParams Optional parameters to control stream access. -------------------------------------------------------------------------------} procedure TsWorkbook.WriteToFile(const AFileName: string; @@ -6737,9 +6687,7 @@ end; If this was an earlier sfExcel type file, it will be upgraded to sfExcel8. @param AFileName Name of the destination file - @param AOverwriteExisting If the file already exists it will be overwritten - of AOverwriteExisting is true. In case of false, an - exception will be raised. + @param AOverwriteExisting If the file already exists it will be overwritten if AOverwriteExisting is @true. In case of @false, an exception will be raised. @param AParams Optional parameters to control stream access -------------------------------------------------------------------------------} procedure TsWorkbook.WriteToFile(const AFileName: String; @@ -6769,9 +6717,7 @@ end; @param AStream Instance of the stream being written to @param AFormat File format to be written. @param AClipboardMode Stream will be used by calling method for clipboard access - @param AParams Optional parameters to control stream access - The HTML writer, for example, can be forced to write - a valid html document in Windows. + @param AParams Optional parameters to control stream access. The HTML writer, for example, can be forced to write a valid html document in Windows. -------------------------------------------------------------------------------} procedure TsWorkbook.WriteToStream(AStream: TStream; AFormat: TsSpreadsheetFormat; AParams: TsStreamParams = []); @@ -6789,9 +6735,7 @@ end; @param AStream Instance of the stream being written to @param AFormatID Identifier of the file format to be written. @param AClipboardMode Stream will be used by calling method for clipboard access - @param AParams Optional parameters to control stream access - The HTML writer, for example, can be forced to write - a valid html document in Windows. + @param AParams Optional parameters to control stream access. The HTML writer, for example, can be forced to write a valid html document in Windows. -------------------------------------------------------------------------------} procedure TsWorkbook.WriteToStream(AStream: TStream; AFormatID: TsSpreadFormatID; AParams: TsStreamParams = []); @@ -6815,12 +6759,11 @@ end; Adds a new worksheet to the workbook. It is put to the end of the worksheet list. - @param AName The name of the new worksheet - @param ReplaceDupliateName If true and the sheet name already exists then - a number is added to the sheet name to make it - unique. - @return The instance of the newly created worksheet - @see TsWorksheet + @param AName The name of the new worksheet + @param ReplaceDupliateName If @true and the sheet name already exists then a number is added to the sheet name to make it unique. + @returns The instance of the newly created worksheet + @seeAlso TsWorksheet + @seeAlso TsWorkbook -------------------------------------------------------------------------------} function TsWorkbook.AddWorksheet(AName: string; ReplaceDuplicateName: Boolean = false): TsWorksheet; @@ -6869,14 +6812,11 @@ end; Copies a worksheet (even from an external workbook) and adds it to the current workbook - @param AWorksheet Worksheet to be copied. Can be in a different - workbook. - @param ReplaceDuplicateName The copied worksheet gets the name of the original. - If ReplaceDuplicateName is true and this sheet - name already exists then a number is added to - the sheet name to make it unique. - @return The instance of the newly created worksheet - @see TsWorksheet + @param AWorksheet Worksheet to be copied. Can be in a different workbook. + @param ReplaceDuplicateName The copied worksheet gets the name of the original. If ReplaceDuplicateName is true and this sheet name already exists then a number is added to the sheet name to make it unique. + @returns The instance of the newly created worksheet + @seeAlso TsWorksheet + @seeAlso TsWorkbook -------------------------------------------------------------------------------} function TsWorkbook.CopyWorksheetFrom(AWorksheet: TsWorksheet; ReplaceDuplicateName: boolean): TsWorksheet; @@ -6944,12 +6884,11 @@ end; {@@ ---------------------------------------------------------------------------- Quick helper routine which returns the first worksheet - @return A TsWorksheet instance if at least one is present. - nil otherwise. + @returns A @link(TsWorksheet) instance if at least one is present, nil otherwise. - @see TsWorkbook.GetWorksheetByIndex - @see TsWorkbook.GetWorksheetByName - @see TsWorksheet + @seeAlso TsWorkbook.GetWorksheetByIndex + @seeAlso TsWorkbook.GetWorksheetByName + @seeAlso TsWorksheet -------------------------------------------------------------------------------} function TsWorkbook.GetFirstWorksheet: TsWorksheet; begin @@ -6959,12 +6898,11 @@ end; {@@ ---------------------------------------------------------------------------- Quick helper routine which returns the last worksheet - @return A TsWorksheet instance if at least one is present. - nil otherwise. + @returns A TsWorksheet instance if at least one is present, nil otherwise.) - @see TsWorkbook.GetWorksheetByIndex - @see TsWorkbook.GetWorksheetByName - @see TsWorksheet + @seeAlso TsWorkbook.GetWorksheetByIndex + @seeAlso TsWorkbook.GetWorksheetByName + @seeAlso TsWorksheet -------------------------------------------------------------------------------} function TsWorkbook.GetLastWorksheet: TsWorksheet; begin @@ -6975,16 +6913,16 @@ end; {@@ ---------------------------------------------------------------------------- Returns the worksheet following the specified one. - @return A TsWorksheet instance if the specified worksheet is not the last one - nil otherwise. + @param AWorksheet The worksheet for which the next worksheet has to be determined. + @returns A TsWorksheet instance if the specified worksheet is not the last one nil otherwise. - @see TsWorkbook.GetFirstWorksheet - @see TsWorkbook.GetPreviousWorksheet - @see TsWorkbook.GetLastWorksheet - @see TsWorkbook.GetFirstWorksheet - @see TsWorkbook.GetWorksheetByIndex - @see TsWorkbook.GetWorksheetByName - @see TsWorksheet + @seeAlso TsWorkbook.GetFirstWorksheet + @seeAlso TsWorkbook.GetPreviousWorksheet + @seeAlso TsWorkbook.GetLastWorksheet + @seeAlso TsWorkbook.GetFirstWorksheet + @seeAlso TsWorkbook.GetWorksheetByIndex + @seeAlso TsWorkbook.GetWorksheetByName + @seeAlso TsWorksheet -------------------------------------------------------------------------------} function TsWorkbook.GetNextWorksheet(AWorksheet: TsWorksheet): TsWorksheet; var @@ -7000,16 +6938,16 @@ end; {@@ ---------------------------------------------------------------------------- Returns the worksheet preceding the specified one. - @return A TsWorksheet instance if the specified worksheet is not - the first one, nil otherwise. + @param AWorksheet Worksheet for which the previous worksheet has to be determined. + @returns A TsWorksheet instance if the specified worksheet is not the first one, nil otherwise. - @see TsWorkbook.GetFirstWorksheet - @see TsWorkbook.GetNextWorksheet - @see TsWorkbook.GetLastWorksheet - @see TsWorkbook.GetFirstWorksheet - @see TsWorkbook.GetWorksheetByIndex - @see TsWorkbook.GetWorksheetByName - @see TsWorksheet + @seeAlso TsWorkbook.GetFirstWorksheet + @seeAlso TsWorkbook.GetNextWorksheet + @seeAlso TsWorkbook.GetLastWorksheet + @seeAlso TsWorkbook.GetFirstWorksheet + @seeAlso TsWorkbook.GetWorksheetByIndex + @seeAlso TsWorkbook.GetWorksheetByName + @seeAlso TsWorksheet -------------------------------------------------------------------------------} function TsWorkbook.GetPreviousWorksheet(AWorksheet: TsWorksheet): TsWorksheet; var @@ -7023,19 +6961,16 @@ begin end; {@@ ---------------------------------------------------------------------------- - Gets the worksheet with a given index + Finds the worksheet with a given index - The index is zero-based, so the first worksheet - added has index 0, the second 1, etc. + The index is zero-based, so the first worksheet added has index 0, the second 1, etc. - @param AIndex The index of the worksheet (0-based) + @param AIndex The index of the worksheet (zero-based) + @returns A TsWorksheet instance if one is present at that index, nil otherwise. - @return A TsWorksheet instance if one is present at that index. - nil otherwise. - - @see TsWorkbook.GetFirstWorksheet - @see TsWorkbook.GetWorksheetByName - @see TsWorksheet + @seeAlso TsWorkbook.GetFirstWorksheet + @seeAlso TsWorkbook.GetWorksheetByName + @seeAlso TsWorksheet -------------------------------------------------------------------------------} function TsWorkbook.GetWorksheetByIndex(AIndex: Integer): TsWorksheet; begin @@ -7046,15 +6981,14 @@ begin end; {@@ ---------------------------------------------------------------------------- - Gets the worksheet with a given worksheet name + Finds the worksheet with a given worksheet name - @param AName The name of the worksheet - @return A TsWorksheet instance if one is found with that name, - nil otherwise. Case is ignored. + @param AName The name of the worksheet + @returns A @link(TsWorksheet) instance if one is found with that name, nil otherwise. Case is ignored. - @see TsWorkbook.GetFirstWorksheet - @see TsWorkbook.GetWorksheetByIndex - @see TsWorksheet + @seeAlso TsWorkbook.GetFirstWorksheet + @seeAlso TsWorkbook.GetWorksheetByIndex + @seeAlso TsWorksheet -------------------------------------------------------------------------------} function TsWorkbook.GetWorksheetByName(AName: String): TsWorksheet; var @@ -7074,9 +7008,12 @@ begin end; {@@ ---------------------------------------------------------------------------- - The number of worksheets on the workbook + Returns to count of worksheets in the workbook - @see TsWorksheet + @returns Total number of worksheets in the workbook + @seeAlso TsWorkbook.GetVisibleWorksheetCount + @seeAlso TsWorksheet + @seeAlso TsWorkbook -------------------------------------------------------------------------------} function TsWorkbook.GetWorksheetCount: Integer; begin @@ -7084,7 +7021,12 @@ begin end; {@@ ---------------------------------------------------------------------------- - Counts the number of visible (= not hidden) worksheets + Counts the number of visible (= not hidden) worksheets in the workbook. + + @returns Number of visible worksheets in the workbook + @seeAlso TsWorkbook.GetWorksheetCount + @seeAlso TsWorksheet + @seeAlso TsWorkbook -------------------------------------------------------------------------------} function TsWorkbook.GetVisibleWorksheetCount: Integer; var @@ -7097,7 +7039,12 @@ begin end; {@@ ---------------------------------------------------------------------------- - Returns the index of a worksheet in the worksheet list + Returns the index of the specified worksheet in the worksheet list + + @param AWorksheet Worksheet for which the index is to be found. + @returns Index of the worksheet + @seeAlso TsWorksheet + @seeAlso TsWorkbook -------------------------------------------------------------------------------} function TsWorkbook.GetWorksheetIndex(AWorksheet: TsBasicWorksheet): Integer; begin @@ -7107,6 +7054,11 @@ end; {@@ ---------------------------------------------------------------------------- Returns the index of the worksheet having the specified name, or -1 if the worksheet does not exist. + + @param AWorksheetName Name of the worksheet to be found + @returns Index of the worksheet + @seeAlso TsWorksheet + @seeAlso TsWorkbook -------------------------------------------------------------------------------} function TsWorkbook.GetWorksheetIndex(const AWorksheetName: String): Integer; var @@ -7124,8 +7076,9 @@ end; {@@ ---------------------------------------------------------------------------- Clears the list of Worksheets and releases their memory. - NOTE: This procedure conflicts with the WorkbookLink mechanism which requires - at least 1 worksheet per workbook! + @note This procedure conflicts with the WorkbookLink mechanism which requires at least one worksheet per workbook! + + @seeAlso RemoveAllEmptyWorksheets -------------------------------------------------------------------------------} procedure TsWorkbook.RemoveAllWorksheets; begin @@ -7138,6 +7091,8 @@ end; {@@ ---------------------------------------------------------------------------- Removes all empty worksheets + + @seeAlso(RemoveAllWorksheets); -------------------------------------------------------------------------------} procedure TsWorkbook.RemoveAllEmptyWorksheets; var @@ -7157,6 +7112,8 @@ end; list, generates an event OnRemoveWorksheet, and releases all memory. The event handler specifies the index of the deleted worksheet; the worksheet itself does no longer exist. + + @param AWorksheet Worksheet to be removed -------------------------------------------------------------------------------} procedure TsWorkbook.RemoveWorksheet(AWorksheet: TsWorksheet); var @@ -7186,6 +7143,8 @@ end; Makes the specified worksheet "active". Only needed for visual controls. The active worksheet is displayed in a TsWorksheetGrid and in the selected tab of a TsWorkbookTabControl. + + @param AWorksheet Worksheet to be selected -------------------------------------------------------------------------------} procedure TsWorkbook.SelectWorksheet(AWorksheet: TsWorksheet); begin @@ -7203,11 +7162,9 @@ end; (ODS seems to be a bit less restrictive, but if we follow Excel's convention we always have valid sheet names independent of the format. - @param AName Name to be checked. - @param ReplaceDuplicateName If there exists already a sheet name equal to - AName then a number is added to AName such that - the name is unique. - @return TRUE if it is a valid worksheet name, FALSE otherwise + @param AName Name to be checked. + @param ReplaceDuplicateName If there exists already a sheet name equal to AName then a number is added to AName such that the name is unique. + @returns @true if it is a valid worksheet name, @false otherwise -------------------------------------------------------------------------------} function TsWorkbook.ValidWorksheetName(var AName: String; ReplaceDuplicateName: Boolean = false): Boolean; @@ -7263,21 +7220,11 @@ end; worksheet name. Extracts the worksheet (if missing the "active" worksheet of the workbook is returned) and the cell's row and column indexes. - @param AText General cell range string in Excel notation, - i.e. worksheet name + ! + cell in A1 notation. - Example: Sheet1!A1:A10; A1:A10 or A1 are valid as well. - @param AWorksheet Pointer to the worksheet referred to by AText. If AText - does not contain the worksheet name, the active worksheet - of the workbook is returned - @param ARow, ACol Zero-based row and column index of the cell identified - by ATest. If AText contains one ore more cell ranges - then the upper left corner of the first range is returned. - @param AListSeparator Character to separate the cell blocks in the text - If #0 then the ListSeparator of the workbook's FormatSettings - is used. - @returns TRUE if AText is a valid list of cell ranges, FALSE if not. If the - result is FALSE then AWorksheet, ARow and ACol may have unpredictable - values. + @param AText General cell range string in Excel notation, i.e. worksheet name + ! + cell in A1 notation. Example: Sheet1!A1:A10; A1:A10 or A1 are valid as well. + @param AWorksheet Pointer to the worksheet referred to by AText. If AText does not contain the worksheet name, the active worksheet of the workbook is returned + @param ARow, ACol Zero-based row and column index of the cell identified by AText. If AText contains one ore more cell ranges then the upper left corner of the first range is returned. + @param AListSeparator Character to separate the cell blocks in the text. If #0 then the ListSeparator of the workbook's FormatSettings is used. + @returns @TRUE if AText is a valid list of cell ranges, @FALSE if not. If the result is @FALSE then AWorksheet, ARow and ACol may have unpredictable values. -------------------------------------------------------------------------------} function TsWorkbook.TryStrToCell(AText: String; out AWorksheet: TsWorksheet; out ARow,ACol: Cardinal; AListSeparator: Char = #0): Boolean; @@ -7298,20 +7245,11 @@ end; the workbook is returned) and the cell range (or the first cell range, if there are several ranges). - @param AText General cell range string in Excel notation, - i.e. worksheet name + ! + cell in A1 notation. - Example: Sheet1!A1:A10; A1:A10 or A1 are valid as well. - @param AWorksheet Pointer to the worksheet referred to by AText. If AText - does not contain the worksheet name, the active worksheet - of the workbook is returned - @param ARange TsCellRange records identifying the cell block. If AText - contains several cell ranges the first one is returned. - @param AListSeparator Character to separate the cell blocks in the text - If #0 then the ListSeparator of the workbook's FormatSettings - is used. - @returns TRUE if AText is a valid cell range, FALSE if not. If the - result is FALSE then AWorksheet and ARange may have unpredictable - values. + @param AText General cell range string in Excel notation, i.e. worksheet name + ! + cell in A1 notation. Example: Sheet1!A1:A10; A1:A10 or A1 are valid as well. + @param AWorksheet Pointer to the worksheet referred to by AText. If AText does not contain the worksheet name, the active worksheet of the workbook is returned + @param ARange @link(TsCellRange) records identifying the cell block. If AText contains several cell ranges the first one is returned. + @param AListSeparator Character to separate the cell blocks in the text. If #0 then the ListSeparator of the workbook's FormatSettings is used. + @returns @TRUE if AText is a valid cell range, @FALSE if not. If the result is @FALSE then AWorksheet and ARange may have unpredictable values. -------------------------------------------------------------------------------} function TsWorkbook.TryStrToCellRange(AText: String; out AWorksheet: TsWorksheet; out ARange: TsCellRange; AListSeparator: Char = #0): Boolean; @@ -7327,19 +7265,11 @@ end; worksheet name. Extracts the worksheet (if missing the "active" worksheet of the workbook is returned) and the range array. - @param AText General cell range string in Excel notation, - i.e. worksheet name + ! + cell in A1 notation. - Example: Sheet1!A1:A10; A1:A10 or A1 are valid as well. - @param AWorksheet Pointer to the worksheet referred to by AText. If AText - does not contain the worksheet name, the active worksheet - of the workbook is returned - @param ARanges Array of TsCellRange records identifying the cell blocks - @param AListSeparator Character to separate the cell blocks in the text - If #0 then the ListSeparator of the workbook's FormatSettings - is used. - @returns TRUE if AText is a valid list of cell ranges, FALSE if not. If the - result is FALSE then AWorksheet and ARanges may have unpredictable - values. + @param AText General cell range string in Excel notation, i.e. worksheet name + ! + cell in A1 notation. Example: Sheet1!A1:A10; A1:A10 or A1 are valid as well. + @param AWorksheet Pointer to the worksheet referred to by AText. If AText does not contain the worksheet name, the active worksheet of the workbook is returned + @param ARanges Array of @link(TsCellRange) records identifying the cell blocks + @param AListSeparator Character to separate the cell blocks in the text. If #0 then the ListSeparator of the workbook's FormatSettings is used. + @returns @TRUE if AText is a valid list of cell ranges, @FALSE if not. If the result is @FALSE then AWorksheet and ARanges may have unpredictable values. -------------------------------------------------------------------------------} function TsWorkbook.TryStrToCellRanges(AText: String; out AWorksheet: TsWorksheet; out ARanges: TsCellRangeArray; AListSeparator: Char = #0): Boolean; @@ -7413,6 +7343,7 @@ end; 1. All formulas are marked as "not calculated". 2. Formulas are calculated. If referenced formulas are found as being "not calculated" they are calculated and then tagged as "calculated". + This results in an iterative calculation procedure. In the end, all formulas are calculated. This strategy is often very ineffective because it unnecessarily recalculates formulas. You can provide a different algorithm in @@ -7458,21 +7389,12 @@ end; {@@ ---------------------------------------------------------------------------- Something was changed anywhere in the workbook which has an effect on existing - formulas. This procedure runs through all formulas and performs the - correction. + formulas. This procedure runs through all formulas and performs the correction. - @param ACorrection Describes what has to be corrected. - Example: fcWorksheetRenamed means that a worksheet has - been renamed and the new name must be used in - corresponding formulas - @param AData A pointer with further information on the correction to - be made. Depends on ACorrection. - Example: - In the fcWorksheetRenamed example above this points to - the worksheet that was renamed. - @param AParam Provides additional information. Depends on ACorrection - @return The function returns true if the string formulas of the - workbook have to be recreated. + @param ACorrection Describes what has to be corrected. Example: fcWorksheetRenamed means that a worksheet has been renamed and the new name must be used in corresponding formulas + @param AData A pointer with further information on the correction to be made. Depends on ACorrection. Example: In the fcWorksheetRenamed example above this points to the worksheet that was renamed. + @param AParam Provides additional information. Depends on ACorrection. + @returns The function returns true if the string formulas of the workbook have to be recreated. -------------------------------------------------------------------------------} function TsWorkbook.FixFormulas(ACorrection: TsFormulaCorrection; AData: Pointer; AParam: PtrInt): Boolean; diff --git a/components/fpspreadsheet/source/common/fpspreadsheet_comments.inc b/components/fpspreadsheet/source/common/fpspreadsheet_comments.inc index 62068dccf..bcbca3af4 100644 --- a/components/fpspreadsheet/source/common/fpspreadsheet_comments.inc +++ b/components/fpspreadsheet/source/common/fpspreadsheet_comments.inc @@ -7,9 +7,8 @@ Checks whether a cell contains a comment and returns a pointer to the comment data. - @param ACell Pointer to the cell - @return Pointer to the TsComment record (nil, if the cell does not have a - comment) + @param ACell Pointer to the cell + @returns Pointer to the @link(TsComment) record (nil, if the cell does not have a comment) -------------------------------------------------------------------------------} function TsWorksheet.FindComment(ACell: PCell): PsComment; begin @@ -32,9 +31,9 @@ end; {@@ ---------------------------------------------------------------------------- Returns the comment text attached to a specific cell - @param ARow (0-based) index to the row - @param ACol (0-based) index to the column - @return Text assigned to the cell as a comment + @param ARow (0-based) index to the row + @param ACol (0-based) index to the column + @returns Text assigned to the cell as a comment -------------------------------------------------------------------------------} function TsWorksheet.ReadComment(ARow, ACol: Cardinal): String; var @@ -50,8 +49,8 @@ end; {@@ ---------------------------------------------------------------------------- Returns the comment text attached to a specific cell - @param ACell Pointer to the cell - @return Text assigned to the cell as a comment + @param ACell Pointer to the cell + @returns Text assigned to the cell as a comment -------------------------------------------------------------------------------} function TsWorksheet.ReadComment(ACell: PCell): String; var @@ -80,10 +79,10 @@ end; {@@ ---------------------------------------------------------------------------- Adds a comment to a specific cell - @param ARow (0-based) row index of the cell - @param ACol (0-based) column index of the cell - @param AText Comment text - @return Pointer to the cell containing the comment + @param ARow (0-based) row index of the cell + @param ACol (0-based) column index of the cell + @param AText Comment text + @returns Pointer to the cell containing the comment -------------------------------------------------------------------------------} function TsWorksheet.WriteComment(ARow, ACol: Cardinal; AText: String): PCell; begin diff --git a/components/fpspreadsheet/source/common/fpspreadsheet_embobj.inc b/components/fpspreadsheet/source/common/fpspreadsheet_embobj.inc index 4b553f6e0..ee35d761d 100644 --- a/components/fpspreadsheet/source/common/fpspreadsheet_embobj.inc +++ b/components/fpspreadsheet/source/common/fpspreadsheet_embobj.inc @@ -10,14 +10,14 @@ Calculates the position of the image with given index relative to the cell containing the top/left corner of the image. - @@param x worksheet-relative coordinate of the left image edge, in workbook units - @@param y worksheet-relative coordinate of the top image edge, in workbook units - @@param ARow Index of the row containing the top/left corner of the image - @@param ACol Index of the column containing the top/left corner of the image - @@param ARowOffset Distance, in workbook units, between top cell and image borders - @@param AColOffset Distance, in workbook units, between left cell and image borders - @@param AScaleX Scaling factor for the image width - @@param AScaleY Scaling factor for the image height + @param x worksheet-relative coordinate of the left image edge, in workbook units + @param y worksheet-relative coordinate of the top image edge, in workbook units + @param ARow Index of the row containing the top/left corner of the image + @param ACol Index of the column containing the top/left corner of the image + @param ARowOffset Distance, in workbook units, between top cell and image borders + @param AColOffset Distance, in workbook units, between left cell and image borders + @param AScaleX Scaling factor for the image width + @param AScaleY Scaling factor for the image height -------------------------------------------------------------------------------} procedure TsWorksheet.CalcImageCell(AIndex: Integer; x, y, AWidth, AHeight: Double; out ARow, ACol: Cardinal; out ARowOffs, AColOffs, AScaleX, AScaleY: Double); @@ -56,8 +56,7 @@ end; Calculates image extent @param AIndex Index of the image into the worksheet's image list - @param UsePixels if TRUE then pixels are used for calculation - this improves - the display of the images in Excel + @param UsePixels If @TRUE then pixels are used for calculation - this improves the display of the images in Excel @param ARow1 Index of the row containing the top edge of the image @param ACol1 Index of the column containing the left edege of the image @param ARow2 Index of the row containing the right edge of the image @@ -179,8 +178,8 @@ end; Returns the parameters of the image stored in the internal image list at the specified index. - @param AIndex Index of the image to be retrieved - @return TsImage record with all image parameters. + @param AIndex Index of the image to be retrieved + @returns @link(TsImage) record with all image parameters. -------------------------------------------------------------------------------} function TsWorksheet.GetImage(AIndex: Integer): TsImage; var @@ -246,15 +245,11 @@ end; @param ARow Index of the row at which the image begins (top edge) @param ACol Index of the column at which the image begins (left edge) @param AFileName Name of the image file - @param AOffsetX The image is offset horizontally from the left edge of - the anchor cell. May reach into another cell. - Value is in workbook units. - @param AOffsetY The image is offset vertically from the top edge of the - anchor cell. May reach into another cell. - Value is in workbook units. + @param AOffsetX The image is offset horizontally from the left edge of the anchor cell. May reach into another cell. Value is in workbook units. + @param AOffsetY The image is offset vertically from the top edge of the anchor cell. May reach into another cell. Value is in workbook units. @param AScaleX Horizontal scaling factor of the image @param AScaleY Vertical scaling factor of the image - @return Index into the internal image list. + @returns Index into the internal image list. -------------------------------------------------------------------------------} function TsWorksheet.WriteImage(ARow, ACol: Cardinal; AFileName: String; AOffsetX: Double = 0.0; AOffsetY: Double = 0.0; @@ -279,19 +274,15 @@ end; {@@ ---------------------------------------------------------------------------- Adds an embedded image to the worksheet. The image passed in a stream. - @param ARow Index of the row at which the image begins (top edge) - @param ACol Index of the column at which the image begins (left edge) - @param AStream Stream which contains the image data - @param AOffsetX The image is offset horizontally from the left edge of - the anchor cell. May reach into another cell. - Value is in workbook units. - @param AOffsetY The image is offset vertically from the top edge of the - anchor cell. May reach into another cell. - Value is in workbook units. - @param AScaleX Horizontal scaling factor of the image - @param AScaleY Vertical scaling factor of the image - @param ASize Number ob bytes to be read from the input stream. - @return Index into the internal image list. + @param ARow Index of the row at which the image begins (top edge) + @param ACol Index of the column at which the image begins (left edge) + @param AStream Stream which contains the image data + @param AOffsetX The image is offset horizontally from the left edge of the anchor cell. May reach into another cell. Value is in workbook units. + @param AOffsetY The image is offset vertically from the top edge of the anchor cell. May reach into another cell. Value is in workbook units. + @param AScaleX Horizontal scaling factor of the image + @param AScaleY Vertical scaling factor of the image + @param ASize Number ob bytes to be read from the input stream. + @returns Index into the internal image list. -------------------------------------------------------------------------------} function TsWorksheet.WriteImage(ARow, ACol: Cardinal; AStream: TStream; AOffsetX: Double = 0.0; AOffsetY: Double = 0.0; @@ -423,7 +414,7 @@ end; {@@ ---------------------------------------------------------------------------- - Returns true if there is at least one worksheet with an embedded images. + Returns @true if there is at least one worksheet with an embedded images. -------------------------------------------------------------------------------} function TsWorkbook.HasEmbeddedSheetImages: Boolean; var diff --git a/components/fpspreadsheet/source/common/fpspreadsheet_fmt.inc b/components/fpspreadsheet/source/common/fpspreadsheet_fmt.inc index 781dedc6b..1863f8c84 100644 --- a/components/fpspreadsheet/source/common/fpspreadsheet_fmt.inc +++ b/components/fpspreadsheet/source/common/fpspreadsheet_fmt.inc @@ -9,16 +9,14 @@ Modifies the background parameters of the format record stored at the specified index. - @param AFormatIndex Index of the format record to be changed - @param AStyle Fill style ("pattern") to be used - see TsFillStyle - @param APatternColor RGB value of the pattern color - @param ABackgroundColor RGB value of the background color + @param AFormatIndex Index of the format record to be changed + @param AStyle Fill style ("pattern") to be used - see @link(TsFillStyle) + @param APatternColor RGB value of the pattern color + @param ABackgroundColor RGB value of the background color - @return Index of the new format record. + @returns Index of the new format record. - @NOTE When AStyle is fsSolidFill the color is defined by APatternColor, - ABackgroundColor is ignored unless the APatternColor is not - used (scTransparent). + @NOTE When AStyle is fsSolidFill the color is defined by APatternColor, ABackgroundColor is ignored unless the APatternColor is not used (scTransparent). -------------------------------------------------------------------------------} function TsWorksheet.ChangeBackground(AFormatIndex: Integer; AStyle: TsFillStyle; APatternColor: TsColor = scTransparent; @@ -48,9 +46,8 @@ end; {@@ ---------------------------------------------------------------------------- Returns the background fill pattern and colors of a cell. - @param ACell Pointer to the cell - @return TsFillPattern record (or EMPTY_FILL, if the cell does not have a - filled background + @param ACell Pointer to the cell + @returns @link(TsFillPattern) record (or @link(EMPTY_FILL), if the cell does not have a filled background -------------------------------------------------------------------------------} function TsWorksheet.ReadBackground(ACell: PCell): TsFillPattern; var @@ -69,8 +66,8 @@ end; {@@ ---------------------------------------------------------------------------- Returns the background color of a cell as rbg value - @param ACell Pointer to the cell - @return Value containing the rgb bytes in little-endian order + @param ACell Pointer to the cell + @returns Value containing the rgb bytes in little-endian order -------------------------------------------------------------------------------} function TsWorksheet.ReadBackgroundColor(ACell: PCell): TsColor; begin @@ -84,8 +81,8 @@ end; Returns the background color stored at the specified index in the format list of the workkbok. - @param AFormatIndex Index of the format record - @return Value containing the rgb bytes in little-endian order + @param AFormatIndex Index of the format record + @returns Value containing the rgb bytes in little-endian order -------------------------------------------------------------------------------} function TsWorksheet.ReadBackgroundColor(AFormatIndex: Integer): TsColor; var @@ -182,8 +179,7 @@ end; {@@ ---------------------------------------------------------------------------- Returns the protection flags of the cell. - NOTE: These flags are active only if sheet protection is active, i.e. - soProtected in Worksheet.Options. + @NOTE These flags are active only if sheet protection is active, i.e. soProtected in Worksheet.Options. -------------------------------------------------------------------------------} function TsWorksheet.ReadCellProtection(ACell: PCell): TsCellProtections; var @@ -239,8 +235,8 @@ end; Each cell contains a set of "used formatting fields". Formatting is applied only if the corresponding element is contained in the set. - @param ACell Pointer to the cell - @return Set of elements used in formatting the cell + @param ACell Pointer to the cell + @returns Set of elements used in formatting the cell -------------------------------------------------------------------------------} function TsWorksheet.ReadUsedFormatting(ACell: PCell): TsUsedFormattingFields; var @@ -292,17 +288,14 @@ end; {@@ ---------------------------------------------------------------------------- Defines a background pattern for a cell - @param ARow Row index of the cell - @param ACol Column index of the cell - @param AFillStyle Fill style to be used - see TsFillStyle - @param APatternColor RGB value of the pattern color - @param ABackgroundColor RGB value of the background color - @return Pointer to cell - - @NOTE When AStyle is fsSolidFill the color is defined by APatternColor, - ABackgroundColor is ignored unless the APatternColor is not - used (scTransparent). + @param ARow Row index of the cell + @param ACol Column index of the cell + @param AFillStyle Fill style to be used - see @link(TsFillStyle) + @param APatternColor RGB value of the pattern color + @param ABackgroundColor RGB value of the background color + @returns Pointer to cell + @NOTE When AStyle is fsSolidFill the color is defined by APatternColor, ABackgroundColor is ignored unless the APatternColor is not used (scTransparent). @NOTE Is replaced by uniform fill if WriteBackgroundColor is called later. -------------------------------------------------------------------------------} function TsWorksheet.WriteBackground(ARow, ACol: Cardinal; AStyle: TsFillStyle; @@ -317,14 +310,11 @@ end; Defines a background pattern for a cell @param ACell Pointer to the cell - @param AStyle Fill style ("pattern") to be used - see TsFillStyle + @param AStyle Fill style ("pattern") to be used - see @link(TsFillStyle) @param APatternColor RGB value of the pattern color @param ABackgroundColor RGB value of the background color - @NOTE When AStyle is fsSolidFill the color is defined by APatternColor, - ABackgroundColor is ignored unless the APatternColor is not - used (scTransparent). - + @NOTE When AStyle is fsSolidFill the color is defined by APatternColor, ABackgroundColor is ignored unless the APatternColor is not used (scTransparent). @NOTE Is replaced by uniform fill if WriteBackgroundColor is called later. -------------------------------------------------------------------------------} procedure TsWorksheet.WriteBackground(ACell: PCell; AStyle: TsFillStyle; @@ -343,12 +333,10 @@ end; {@@ ---------------------------------------------------------------------------- Sets a uniform background color of a cell. - @param ARow Row index of the cell - @param ACol Column index of the cell - @param AColor RGB value of the new background color. - Use the value "scTransparent" to clear an existing - background color. - @return Pointer to cell + @param ARow Row index of the cell + @param ACol Column index of the cell + @param AColor RGB value of the new background color. Use the value "scTransparent" to clear an existing background color. + @returns Pointer to cell -------------------------------------------------------------------------------} function TsWorksheet.WriteBackgroundColor(ARow, ACol: Cardinal; AColor: TsColor): PCell; @@ -362,9 +350,7 @@ end; Sets a uniform background color of a cell. @param ACell Pointer to cell - @param AColor RGB value of the new background color. - Use the value "scTransparent" to clear an existing - background color. + @param AColor RGB value of the new background color. Use the value "scTransparent" to clear an existing background color. -------------------------------------------------------------------------------} procedure TsWorksheet.WriteBackgroundColor(ACell: PCell; AColor: TsColor); begin @@ -405,12 +391,11 @@ end; Sets the color of a cell border line. Note: the border must be included in Borders set in order to be shown! - @param ARow Row index of the cell - @param ACol Column index of the cell - @param ABorder Indicates to which border (left/top etc) this color is - to be applied - @param AColor RGB value of the new border color - @return Pointer to cell + @param ARow Row index of the cell + @param ACol Column index of the cell + @param ABorder Indicates to which border (left/top etc) this color is to be applied + @param AColor RGB value of the new border color + @returns Pointer to cell -------------------------------------------------------------------------------} function TsWorksheet.WriteBorderColor(ARow, ACol: Cardinal; ABorder: TsCellBorder; AColor: TsColor): PCell; @@ -425,8 +410,7 @@ end; Note: the border must be included in Borders set in order to be shown! @param ACell Pointer to cell - @param ABorder Indicates to which border (left/top etc) this color is - to be applied + @param ABorder Indicates to which border (left/top etc) this color is to be applied @param AColor RGB value of the new border color -------------------------------------------------------------------------------} procedure TsWorksheet.WriteBorderColor(ACell: PCell; ABorder: TsCellBorder; @@ -447,14 +431,13 @@ end; Sets the linestyle of a cell border. Note: the border must be included in the "Borders" set in order to be shown! - @param ARow Row index of the cell - @param ACol Column index of the cell - @param ABorder Indicates to which border (left/top etc) this color is - to be applied - @param ALineStyle Identifier of the new line style to be applied. - @return Pointer to cell + @param ARow Row index of the cell + @param ACol Column index of the cell + @param ABorder Indicates to which border (left/top etc) this color is to be applied + @param ALineStyle Identifier of the new line style to be applied. + @returns Pointer to cell - @see TsLineStyle + @seeAlso TsLineStyle -------------------------------------------------------------------------------} function TsWorksheet.WriteBorderLineStyle(ARow, ACol: Cardinal; ABorder: TsCellBorder; ALineStyle: TsLineStyle): PCell; @@ -468,12 +451,11 @@ end; Sets the linestyle of a cell border. Note: the border must be included in the "Borders" set in order to be shown! - @param ACell Pointer to cell - @param ABorder Indicates to which border (left/top etc) this color is - to be applied - @param ALineStyle Identifier of the new line style to be applied. + @param ACell Pointer to cell + @param ABorder Indicates to which border (left/top etc) this color is to be applied + @param ALineStyle Identifier of the new line style to be applied. - @see TsLineStyle + @seeAlso TsLineStyle -------------------------------------------------------------------------------} procedure TsWorksheet.WriteBorderLineStyle(ACell: PCell; ABorder: TsCellBorder; ALineStyle: TsLineStyle); @@ -495,11 +477,11 @@ end; The borders are drawn using the "BorderStyles" assigned to the cell. - @param ARow Row index of the cell - @param ACol Column index of the cell - @param ABorders Set with elements to identify the border(s) to will be shown - @return Pointer to cell - @see TsCellBorder + @param ARow Row index of the cell + @param ACol Column index of the cell + @param ABorders Set with elements to identify the border(s) to will be shown + @returns Pointer to cell + @seeAlso TsCellBorder -------------------------------------------------------------------------------} function TsWorksheet.WriteBorders(ARow, ACol: Cardinal; ABorders: TsCellBorders): PCell; begin @@ -514,9 +496,9 @@ end; The borders are drawn using the "BorderStyles" assigned to the cell. - @param ACell Pointer to cell - @param ABorders Set with elements to identify the border(s) to will be shown - @see TsCellBorder + @param ACell Pointer to cell + @param ABorders Set with elements to identify the border(s) to will be shown + @seeAlso TsCellBorder -------------------------------------------------------------------------------} procedure TsWorksheet.WriteBorders(ACell: PCell; ABorders: TsCellBorders); var @@ -538,12 +520,11 @@ end; Sets the style of a cell border, i.e. line style and line color. Note: the border must be included in the "Borders" set in order to be shown! - @param ARow Row index of the cell considered - @param ACol Column index of the cell considered - @param ABorder Identifies the border to be modified (left/top/right/bottom) - @param AStyle record of parameters controlling how the border line is drawn - (line style, line color) - @result Pointer to cell + @param ARow Row index of the cell considered + @param ACol Column index of the cell considered + @param ABorder Identifies the border to be modified (left/top/right/bottom) + @param AStyle @link(TsCellBorderStyle) record with parameters controlling how the border line is drawn (line style, line color) + @returns Pointer to cell -------------------------------------------------------------------------------} function TsWorksheet.WriteBorderStyle(ARow, ACol: Cardinal; ABorder: TsCellBorder; AStyle: TsCellBorderStyle): PCell; @@ -559,8 +540,7 @@ end; @param ACell Pointer to cell @param ABorder Identifies the border to be modified (left/top/right/bottom) - @param AStyle record of parameters controlling how the border line is drawn - (line style, line color) + @param AStyle @link(TsCellBorderStyle) record with parameters controlling how the border line is drawn (line style, line color) -------------------------------------------------------------------------------} procedure TsWorksheet.WriteBorderStyle(ACell: PCell; ABorder: TsCellBorder; AStyle: TsCellBorderStyle); @@ -580,14 +560,14 @@ end; Sets line style and line color of a cell border. Note: the border must be included in the "Borders" set in order to be shown! - @param ARow Row index of the considered cell - @param ACol Column index of the considered cell - @param ABorder Identifier of the border to be modified - @param ALineStyle Identifier for the new line style of the border - @param AColor RGB value of the border line color - @return Pointer to cell + @param ARow Row index of the considered cell + @param ACol Column index of the considered cell + @param ABorder Identifier of the border to be modified + @param ALineStyle Identifier for the new line style of the border + @param AColor RGB value of the border line color + @returns Pointer to cell - @see WriteBorderStyles + @seeAlso WriteBorderStyles -------------------------------------------------------------------------------} function TsWorksheet.WriteBorderStyle(ARow, ACol: Cardinal; ABorder: TsCellBorder; ALineStyle: TsLineStyle; AColor: TsColor): PCell; @@ -606,7 +586,7 @@ end; @param ALineStyle Identifier for the new line style of the border @param AColor RGB value of the color of the border line - @see WriteBorderStyles + @seeAlso WriteBorderStyles -------------------------------------------------------------------------------} procedure TsWorksheet.WriteBorderStyle(ACell: PCell; ABorder: TsCellBorder; ALineStyle: TsLineStyle; AColor: TsColor); @@ -627,12 +607,12 @@ end; Sets the style of all cell border of a cell, i.e. line style and line color. Note: Only those borders included in the "Borders" set are shown! - @param ARow Row index of the considered cell - @param ACol Column index of the considered cell - @param AStyles Array of CellBorderStyles for each cell border. - @return Pointer to cell + @param ARow Row index of the considered cell + @param ACol Column index of the considered cell + @param AStyles Array of @link(CellBorderStyle) records for each cell border. + @returns Pointer to cell - @see WriteBorderStyle + @seeAlso WriteBorderStyle -------------------------------------------------------------------------------} function TsWorksheet.WriteBorderStyles(ARow, ACol: Cardinal; const AStyles: TsCellBorderStyles): PCell; @@ -646,11 +626,11 @@ end; Sets the style of all cell border of a cell, i.e. line style and line color. Note: Only those borders included in the "Borders" set are shown! - @param ACell Pointer to cell - @param ACol Column index of the considered cell - @param AStyles Array of CellBorderStyles for each cell border. + @param ACell Pointer to cell + @param ACol Column index of the considered cell + @param AStyles Array of @link(CellBorderStyle) records for each cell border. - @see WriteBorderStyle + @seeAlso WriteBorderStyle -------------------------------------------------------------------------------} procedure TsWorksheet.WriteBorderStyles(ACell: PCell; const AStyles: TsCellBorderStyles); @@ -673,7 +653,7 @@ end; @param ACell Pointer to the cell to be modified @param ACellFormat Cell format record to be used by the cell - @see TsCellFormat + @seeAlso TsCellFormat -------------------------------------------------------------------------------} procedure TsWorksheet.WriteCellFormat(ACell: PCell; const ACellFormat: TsCellFormat); @@ -692,7 +672,7 @@ end; @param ACell Pointer to the cell to be formatted @param AIndex Index of the cell format record to be used by the cell - @see TsCellFormat + @seeAlso TsCellFormat -------------------------------------------------------------------------------} procedure TsWorksheet.WriteCellFormatIndex(ACell: PCell; AIndex: Integer); begin @@ -713,9 +693,7 @@ end; 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. + @NOTE FPSpreadsheet does not enforce these actions. They are only written to the file for the Office application. -------------------------------------------------------------------------------} function TsWorksheet.WriteCellProtection(ARow, ACol: Cardinal; AValue: TsCellProtections): PCell; @@ -748,11 +726,8 @@ end; @param ARow Row index of the cell considered @param ACol Column index of the cell considered - @param AValue Parameter for horizontal text alignment - (haDefault, vaLeft, haCenter, haRight) - By default, texts are left-aligned, numbers and dates are - right-aligned. - @return Pointer to cell + @param AValue Parameter for horizontal text alignment (haDefault, vaLeft, haCenter, haRight). By default, texts are left-aligned, numbers and dates are right-aligned. + @returns Pointer to cell -------------------------------------------------------------------------------} function TsWorksheet.WriteHorAlignment(ARow, ACol: Cardinal; AValue: TsHorAlignment): PCell; begin @@ -764,10 +739,7 @@ end; Defines the horizontal alignment of text in a cell. @param ACell Pointer to the cell considered - @param AValue Parameter for horizontal text alignment - (haDefault, vaLeft, haCenter, haRight) - By default, texts are left-aligned, numbers and dates are - right-aligned. + @param AValue Parameter for horizontal text alignment (haDefault, vaLeft, haCenter, haRight). By default, texts are left-aligned, numbers and dates are right-aligned. -------------------------------------------------------------------------------} procedure TsWorksheet.WriteHorAlignment(ACell: PCell; AValue: TsHorAlignment); var @@ -788,12 +760,12 @@ end; {@@ ---------------------------------------------------------------------------- Adds text rotation to the formatting of a cell - @param ARow The row of the cell - @param ACol The column of the cell - @param ARotation How to rotate the text - @return Pointer to cell + @param ARow The row of the cell + @param ACol The column of the cell + @param ARotation How to rotate the text + @returns Pointer to cell - @see TsTextRotation + @seeAlso TsTextRotation -------------------------------------------------------------------------------} function TsWorksheet.WriteTextRotation(ARow, ACol: Cardinal; ARotation: TsTextRotation): PCell; @@ -805,10 +777,10 @@ end; {@@ ---------------------------------------------------------------------------- Adds text rotation to the formatting of a cell - @param ACell Pointer to the cell - @param ARotation How to rotate the text + @param ACell Pointer to the cell + @param ARotation How to rotate the text - @see TsTextRotation + @seeAlso TsTextRotation -------------------------------------------------------------------------------} procedure TsWorksheet.WriteTextRotation(ACell: PCell; ARotation: TsTextRotation); var @@ -829,13 +801,13 @@ end; Directly modifies the used formatting fields of a cell. Only formatting corresponding to items included in this set is executed. - @param ARow The row of the cell - @param ACol The column of the cell - @param AUsedFormatting set of the used formatting fields - @return Pointer to the (existing or created) cell + @param ARow The row of the cell + @param ACol The column of the cell + @param AUsedFormatting set of the used formatting fields + @returns Pointer to the (existing or created) cell - @see TsUsedFormattingFields - @see TCell + @seeAlso TsUsedFormattingFields + @seeAlso TCell -------------------------------------------------------------------------------} function TsWorksheet.WriteUsedFormatting(ARow, ACol: Cardinal; AUsedFormatting: TsUsedFormattingFields): PCell; @@ -848,11 +820,11 @@ end; Directly modifies the used formatting fields of an existing cell. Only formatting corresponding to items included in this set is executed. - @param ACell Pointer to the cell to be modified - @param AUsedFormatting set of the used formatting fields + @param ACell Pointer to the cell to be modified + @param AUsedFormatting Set of the used formatting fields - @see TsUsedFormattingFields - @see TCell + @seeAlso TsUsedFormattingFields + @seeAlso TCell -------------------------------------------------------------------------------} procedure TsWorksheet.WriteUsedFormatting(ACell: PCell; AUsedFormatting: TsUsedFormattingFields); @@ -870,12 +842,10 @@ end; {@@ ---------------------------------------------------------------------------- Defines the vertical alignment of text in a cell. - @param ARow Row index of the cell considered - @param ACol Column index of the cell considered - @param AValue Parameter for vertical text alignment - (vaDefault, vaTop, vaCenter, vaBottom) - By default, texts are bottom-aligned. - @return Pointer to cell + @param ARow Row index of the cell considered + @param ACol Column index of the cell considered + @param AValue Parameter for vertical text alignment (vaDefault, vaTop, vaCenter, vaBottom). By default, texts are bottom-aligned. + @returns Pointer to cell -------------------------------------------------------------------------------} function TsWorksheet.WriteVertAlignment(ARow, ACol: Cardinal; AValue: TsVertAlignment): PCell; @@ -888,9 +858,7 @@ end; Defines the vertical alignment of text in a cell. @param ACell Poiner to the cell considered - @param AValue Parameter for vertical text alignment - (vaDefault, vaTop, vaCenter, vaBottom) - By default, texts are bottom-aligned. + @param AValue Parameter for vertical text alignment (vaDefault, vaTop, vaCenter, vaBottom). By default, texts are bottom-aligned. -------------------------------------------------------------------------------} procedure TsWorksheet.WriteVertAlignment(ACell: PCell; AValue: TsVertAlignment); var @@ -911,10 +879,10 @@ end; {@@ ---------------------------------------------------------------------------- Enables or disables the word-wrapping feature for a cell. - @param ARow Row index of the cell considered - @param ACol Column index of the cell considered - @param AValue true = word-wrapping enabled, false = disabled. - @return Pointer to cell + @param ARow Row index of the cell considered + @param ACol Column index of the cell considered + @param AValue @true = word-wrapping enabled, @false = disabled. + @returns Pointer to cell -------------------------------------------------------------------------------} function TsWorksheet.WriteWordwrap(ARow, ACol: Cardinal; AValue: boolean): PCell; begin @@ -926,7 +894,7 @@ end; Enables or disables the word-wrapping feature for a cell. @param ACel Pointer to the cell considered - @param AValue true = word-wrapping enabled, false = disabled. + @param AValue @true = word-wrapping enabled, @false = disabled. -------------------------------------------------------------------------------} procedure TsWorksheet.WriteWordwrap(ACell: PCell; AValue: boolean); var @@ -1048,7 +1016,7 @@ end; {@@ ---------------------------------------------------------------------------- Removes all cell formats from the workbook. - If AKeepDefaultFormat is true then index 0 containing the default cell format + If AKeepDefaultFormat is @true then index 0 containing the default cell format is retained. Use carefully! diff --git a/components/fpspreadsheet/source/common/fpspreadsheet_fonts.inc b/components/fpspreadsheet/source/common/fpspreadsheet_fonts.inc index 60b166c81..017a7f740 100644 --- a/components/fpspreadsheet/source/common/fpspreadsheet_fonts.inc +++ b/components/fpspreadsheet/source/common/fpspreadsheet_fonts.inc @@ -46,15 +46,14 @@ end; FontList and creates an new entry if the font is not used so far. Returns the index of the font in the font list. - @param ARow The row of the cell - @param ACol The column of the cell - @param AFontName Name of the font - @param AFontSize Size of the font, in points - @param AFontStyle Set with font style attributes - (don't use those of unit "graphics" !) - @param AFontColor RGB value of the font's color - @param APosition Specifies sub- or superscript text - @return Index of the font in the workbook's font list. + @param ARow The row of the cell + @param ACol The column of the cell + @param AFontName Name of the font + @param AFontSize Size of the font, in points + @param AFontStyle Set with font style attributes (don't use those of unit "graphics" !) + @param AFontColor RGB value of the font's color + @param APosition Specifies sub- or superscript text + @returns Index of the font in the workbook's font list. -------------------------------------------------------------------------------} function TsWorksheet.WriteFont(ARow, ACol: Cardinal; const AFontName: String; AFontSize: Single; AFontStyle: TsFontStyles; AFontColor: TsColor; @@ -70,14 +69,13 @@ end; FontList and creates an new entry if the font is not used so far. Returns the index of the font in the font list. - @param ACell Pointer to the cell considered - @param AFontName Name of the font - @param AFontSize Size of the font, in points - @param AFontStyle Set with font style attributes - (don't use those of unit "graphics" !) - @param AFontColor RGB value of the font's color - @param APosition Specified subscript or superscript text. - @return Index of the font in the workbook's font list. + @param ACell Pointer to the cell considered + @param AFontName Name of the font + @param AFontSize Size of the font, in points + @param AFontStyle Set with font style attributes (don't use those of unit "graphics" !) + @param AFontColor RGB value of the font's color + @param APosition Specified subscript or superscript text. + @returns Index of the font in the workbook's font list. -------------------------------------------------------------------------------} function TsWorksheet.WriteFont(ACell: PCell; const AFontName: String; AFontSize: Single; AFontStyle: TsFontStyles; AFontColor: TsColor; @@ -108,10 +106,10 @@ end; Applies a font to the formatting of a cell. The font is determined by its index in the workbook's font list: - @param ARow The row of the cell - @param ACol The column of the cell - @param AFontIndex Index of the font in the workbook's font list - @return Pointer to the cell + @param ARow The row of the cell + @param ACol The column of the cell + @param AFontIndex Index of the font in the workbook's font list + @returns Pointer to the cell -------------------------------------------------------------------------------} function TsWorksheet.WriteFont(ARow, ACol: Cardinal; AFontIndex: Integer): PCell; begin @@ -151,10 +149,10 @@ end; font list if this modified font has already been used. If not a new font entry is created. Returns the index of this font in the font list. - @param ARow The row of the cell - @param ACol The column of the cell - @param AFontColor RGB value of the new text color - @return Index of the font in the workbook's font list. + @param ARow The row of the cell + @param ACol The column of the cell + @param AFontColor RGB value of the new text color + @returns Index of the font in the workbook's font list. -------------------------------------------------------------------------------} function TsWorksheet.WriteFontColor(ARow, ACol: Cardinal; AFontColor: TsColor): Integer; begin @@ -167,9 +165,9 @@ end; font list if this modified font has already been used. If not a new font entry is created. Returns the index of this font in the font list. - @param ACell Pointer to the cell - @param AFontColor RGB value of the new text color - @return Index of the font in the workbook's font list. + @param ACell Pointer to the cell + @param AFontColor RGB value of the new text color + @returns Index of the font in the workbook's font list. -------------------------------------------------------------------------------} function TsWorksheet.WriteFontColor(ACell: PCell; AFontColor: TsColor): Integer; var @@ -190,10 +188,10 @@ end; font list if this modified font has already been used. If not a new font entry is created. Returns the index of this font in the font list. - @param ARow The row of the cell - @param ACol The column of the cell - @param AFontName Name of the new font to be used - @return Index of the font in the workbook's font list. + @param ARow The row of the cell + @param ACol The column of the cell + @param AFontName Name of the new font to be used + @returns Index of the font in the workbook's font list. -------------------------------------------------------------------------------} function TsWorksheet.WriteFontName(ARow, ACol: Cardinal; AFontName: String): Integer; begin @@ -207,9 +205,9 @@ end; font list if this modified font has already been used. If not a new font entry is created. Returns the index of this font in the font list. - @param ACell Pointer to the cell - @param AFontName Name of the new font to be used - @return Index of the font in the workbook's font list. + @param ACell Pointer to the cell + @param AFontName Name of the new font to be used + @returns Index of the font in the workbook's font list. -------------------------------------------------------------------------------} function TsWorksheet.WriteFontName(ACell: PCell; AFontName: String): Integer; var @@ -229,10 +227,10 @@ end; font list if this modified font has already been used. If not a new font entry is created. Returns the index of this font in the font list. - @param ARow The row of the cell - @param ACol The column of the cell - @param ASize Size of the font to be used (in points). - @return Index of the font in the workbook's font list. + @param ARow The row of the cell + @param ACol The column of the cell + @param ASize Size of the font to be used (in points). + @returns Index of the font in the workbook's font list. -------------------------------------------------------------------------------} function TsWorksheet.WriteFontSize(ARow, ACol: Cardinal; ASize: Single): Integer; begin @@ -245,9 +243,9 @@ end; font list if this modified font has already been used. If not a new font entry is created. Returns the index of this font in the font list. - @param ACell Pointer to the cell - @param ASize Size of the font to be used (in points). - @return Index of the font in the workbook's font list. + @param ACell Pointer to the cell + @param ASize Size of the font to be used (in points). + @returns Index of the font in the workbook's font list. -------------------------------------------------------------------------------} function TsWorksheet.WriteFontSize(ACell: PCell; ASize: Single): Integer; var @@ -268,12 +266,12 @@ end; If not a new font entry is created. Returns the index of this font in the font list. - @param ARow The row of the cell - @param ACol The column of the cell - @param AStyle New font style to be used - @return Index of the font in the workbook's font list. + @param ARow The row of the cell + @param ACol The column of the cell + @param AStyle New font style to be used + @returns Index of the font in the workbook's font list. - @see TsFontStyle + @seeAlso TsFontStyle -------------------------------------------------------------------------------} function TsWorksheet.WriteFontStyle(ARow, ACol: Cardinal; AStyle: TsFontStyles): Integer; @@ -288,11 +286,11 @@ end; If not a new font entry is created. Returns the index of this font in the font list. - @param ACell Pointer to the cell considered - @param AStyle New font style to be used - @return Index of the font in the workbook's font list. + @param ACell Pointer to the cell considered + @param AStyle New font style to be used + @returns Index of the font in the workbook's font list. - @see TsFontStyle + @seeAlso TsFontStyle -------------------------------------------------------------------------------} function TsWorksheet.WriteFontStyle(ACell: PCell; AStyle: TsFontStyles): Integer; var @@ -320,7 +318,7 @@ end; @param AStyle Style of the font, a combination of TsFontStyle elements @param AColor RGB valoe of the font color @param APosition Specifies subscript or superscript text. - @return Index of the font in the workbook's font list + @returns Index of the font in the workbook's font list -------------------------------------------------------------------------------} function TsWorkbook.AddFont(const AFontName: String; ASize: Single; AStyle: TsFontStyles; AColor: TsColor; @@ -342,7 +340,7 @@ end; Adds a font to the font list. Returns the index in the font list. @param AFont TsFont record containing all font parameters - @return Index of the font in the workbook's font list + @returns Index of the font in the workbook's font list -------------------------------------------------------------------------------} function TsWorkbook.AddFont(const AFont: TsFont): Integer; begin @@ -398,7 +396,7 @@ end; @param AStyle Style of the font, a combination of TsFontStyle elements @param AColor RGB value of the font color @param APosition Specified subscript or superscript text. - @return Index of the font in the font list, or -1 if not found. + @returns Index of the font in the font list, or -1 if not found. -------------------------------------------------------------------------------} function TsWorkbook.FindFont(const AFontName: String; ASize: Single; AStyle: TsFontStyles; AColor: TsColor; APosition: TsFontPosition = fpNormal): Integer; @@ -438,8 +436,8 @@ end; {@@ ---------------------------------------------------------------------------- Returns the font with the given index. - @param AIndex Index of the font to be considered - @return Record containing all parameters of the font (or nil if not found). + @param AIndex Index of the font to be considered + @returns @link(TsFont) instance containing all parameters of the font (or nil if not found). -------------------------------------------------------------------------------} function TsWorkbook.GetFont(AIndex: Integer): TsFont; begin @@ -453,8 +451,8 @@ end; {@@ ---------------------------------------------------------------------------- Returns a string which identifies the font with a given index. - @param AIndex Index of the font - @return String with font name, font size etc. + @param AIndex Index of the font + @returns String with font name, font size etc. -------------------------------------------------------------------------------} function TsWorkbook.GetFontAsString(AIndex: Integer): String; begin diff --git a/components/fpspreadsheet/source/common/fpspreadsheet_hyperlinks.inc b/components/fpspreadsheet/source/common/fpspreadsheet_hyperlinks.inc index a2751a67e..9112ff2b9 100644 --- a/components/fpspreadsheet/source/common/fpspreadsheet_hyperlinks.inc +++ b/components/fpspreadsheet/source/common/fpspreadsheet_hyperlinks.inc @@ -6,9 +6,8 @@ Checks whether the specified cell contains a hyperlink and returns a pointer to the hyperlink data. - @param ACell Pointer to the cell - @return Pointer to the TsHyperlink record, or NIL if the cell does not contain - a hyperlink. + @param ACell Pointer to the cell + @returns Pointer to the @link(TsHyperlink) record, or NIL if the cell does not contain a hyperlink. -------------------------------------------------------------------------------} function TsWorksheet.FindHyperlink(ACell: PCell): PsHyperlink; begin @@ -23,8 +22,7 @@ end; Reads the hyperlink information of a specified cell. @param ACell Pointer to the cell considered - @returns Record with the hyperlink data assigned to the cell. - If the cell is not a hyperlink the result field Kind is hkNone. + @returns @link(TsHyperlink) record with the hyperlink data assigned to the cell. If the cell is not a hyperlink the result field Kind is hkNone. -------------------------------------------------------------------------------} function TsWorksheet.ReadHyperlink(ACell: PCell): TsHyperlink; var @@ -61,11 +59,14 @@ end; {@@ ---------------------------------------------------------------------------- Checks whether the passed string represents a valid hyperlink target - @param AValue String to be checked. Must be either a fully qualified URI, - a local relative (!) file name, or a # followed by a cell - address in the current workbook + The string must either be + * a fully qualified URI, + * a local relative (!) file name, or + * a # followed by a cell address in the current workbook + + @param AValue String to be checked. @param AErrMsg Error message in case that the string is not correct. - @returns TRUE if the string is correct, FALSE otherwise + @returns @TRUE if the string is correct, @FALSE otherwise -------------------------------------------------------------------------------} function TsWorksheet.ValidHyperlink(AValue: String; out AErrMsg: String): Boolean; var @@ -122,9 +123,7 @@ end; @param ARow Row index of the cell considered @param ACol Column index of the cell considered - @param ATarget Hyperlink address given as a fully qualitifed URI for - external links, or as a # followed by a cell address - for internal links. + @param ATarget Hyperlink address given as a fully qualitifed URI for external links, or as a # followed by a cell address for internal links. @param ATooltip Text for popup tooltip hint used by Excel @returns Pointer to the cell with the hyperlink -------------------------------------------------------------------------------} @@ -140,11 +139,7 @@ end; Assigns a hyperlink to the specified cell. @param ACell Pointer to the cell considered - @param ATarget Hyperlink address given as a fully qualitifed URI for - external links, or as a # followed by a cell address - for internal links. Local files can be specified also - by their name relative to the workbook. - An existing hyperlink is removed if ATarget is empty. + @param ATarget Hyperlink address given as a fully qualitifed URI for external links, or as a # followed by a cell address for internal links. Local files can be specified also by their name relative to the workbook. An existing hyperlink is removed if ATarget is empty. @param ATooltip Text for popup tooltip hint used by Excel -------------------------------------------------------------------------------} procedure TsWorksheet.WriteHyperlink(ACell: PCell; ATarget: String; @@ -218,7 +213,7 @@ end; {==============================================================================} {@@ ---------------------------------------------------------------------------- - Returns the hypertext font. This is font with index 6 in the font list + Returns the hyperlink font. This is the font with index 6 in the font list -------------------------------------------------------------------------------} function TsWorkbook.GetHyperlinkFont: TsFont; begin diff --git a/components/fpspreadsheet/source/common/fpspreadsheet_numfmt.inc b/components/fpspreadsheet/source/common/fpspreadsheet_numfmt.inc index cc9f8289f..0379ca1b4 100644 --- a/components/fpspreadsheet/source/common/fpspreadsheet_numfmt.inc +++ b/components/fpspreadsheet/source/common/fpspreadsheet_numfmt.inc @@ -10,14 +10,11 @@ Determines some number format attributes (decimal places, currency symbol) of a cell - @param ACell Pointer to the cell under investigation - @param ADecimals Number of decimal places that can be extracted from - the formatting string, e.g. in case of '0.000' this - would be 3. - @param ACurrencySymbol String representing the currency symbol extracted from - the formatting string. + @param ACell Pointer to the cell under investigation + @param ADecimals Number of decimal places that can be extracted from the formatting string, e.g. in case of '0.000' this would be 3. + @param ACurrencySymbol String representing the currency symbol extracted from the formatting string. - @return true if the the format string could be analyzed successfully, false if not + @returns @true if the the format string could be analyzed successfully, @false if not -------------------------------------------------------------------------------} function TsWorksheet.GetNumberFormatAttributes(ACell: PCell; out ADecimals: byte; out ACurrencySymbol: String): Boolean; @@ -61,6 +58,10 @@ end; {@@ ---------------------------------------------------------------------------- Returns the number format type and format string used in a specific cell + + @param ACell Pointer to the cell of interest + @param ANumFormat Number format record to be used in this cell. + @param ANumFormatStr Number format string to be used in this cell. -------------------------------------------------------------------------------} procedure TsWorksheet.ReadNumFormat(ACell: PCell; out ANumFormat: TsNumberFormat; out ANumFormatStr: String); @@ -93,14 +94,13 @@ end; {@@ ---------------------------------------------------------------------------- Adds a date/time format to the formatting of a cell - @param ARow The row of the cell - @param ACol The column of the cell - @param ANumFormat Identifier of the format to be applied (nfXXXX constant) - @param ANumFormatString Optional string of formatting codes. Is only considered - if ANumberFormat is nfCustom. - @return Pointer to the cell + @param ARow The row index of the cell (zero-based) + @param ACol The column index of the cell (zero-based) + @param ANumFormat Identifier of the format to be applied (nfXXXX constant) + @param ANumFormatString Optional string of formatting codes. Is only considered if ANumberFormat is nfCustom. + @returns Pointer to the cell - @see TsNumberFormat + @seeAlso TsNumberFormat -------------------------------------------------------------------------------} function TsWorksheet.WriteDateTimeFormat(ARow, ACol: Cardinal; ANumFormat: TsNumberFormat; const ANumFormatString: String = ''): PCell; @@ -113,12 +113,11 @@ end; {@@ ---------------------------------------------------------------------------- Adds a date/time format to the formatting of a cell - @param ACell Pointer to the cell considered - @param ANumFormat Identifier of the format to be applied (nxXXXX constant) - @param ANumFormatString optional string of formatting codes. Is only considered - if ANumberFormat is nfCustom. + @param ACell Pointer to the cell considered + @param ANumFormat Identifier of the format to be applied (nxXXXX constant) + @param ANumFormatString Optional string of formatting codes. Is only considered if ANumberFormat is nfCustom. - @see TsNumberFormat + @seeAlso TsNumberFormat -------------------------------------------------------------------------------} procedure TsWorksheet.WriteDateTimeFormat(ACell: PCell; ANumFormat: TsNumberFormat; const ANumFormatString: String = ''); @@ -175,11 +174,11 @@ end; Formats the number in a cell to show a given count of decimal places. Is ignored for non-decimal formats (such as most date/time formats). - @param ARow Row indows of the cell considered - @param ACol Column indows of the cell considered - @param ADecimals Number of decimal places to be displayed - @return Pointer to the cell - @see TsNumberFormat + @param ARow Row index of the cell considered (zero-based) + @param ACol Column index of the cell considered (zero-based) + @param ADecimals Number of decimal places to be displayed + @returns Pointer to the cell + @seeAlso TsNumberFormat -------------------------------------------------------------------------------} function TsWorksheet.WriteDecimals(ARow, ACol: Cardinal; ADecimals: Byte): PCell; begin @@ -189,12 +188,12 @@ end; {@@ ---------------------------------------------------------------------------- - Formats the number in a cell to show a given count of decimal places. + Formats the numeric value in a cell to show a given count of decimal places. Is ignored for non-decimal formats (such as most date/time formats). - @param ACell Pointer to the cell considered - @param ADecimals Number of decimal places to be displayed - @see TsNumberFormat + @param ACell Pointer to the cell considered + @param ADecimals Number of decimal places to be displayed + @seeAlso TsNumberFormat -------------------------------------------------------------------------------} procedure TsWorksheet.WriteDecimals(ACell: PCell; ADecimals: Byte); var @@ -229,15 +228,14 @@ end; {@@ ---------------------------------------------------------------------------- Formats a number as a fraction - @param ARow Row index of the cell - @param ACol Column index of the cell - @param ANumFormat Identifier of the format to be applied. Must be - either nfFraction or nfMixedFraction - @param ANumeratorDigts Count of numerator digits - @param ADenominatorDigits Count of denominator digits - @return Pointer to the cell + @param ARow Row index of the cell + @param ACol Column index of the cell + @param ANumFormat Identifier of the format to be applied. Must be either nfFraction or nfMixedFraction + @param ANumeratorDigts Count of numerator digits + @param ADenominatorDigits Count of denominator digits + @returns Pointer to the cell - @see TsNumberFormat + @seeAlso TsNumberFormat -------------------------------------------------------------------------------} function TsWorksheet.WriteFractionFormat(ARow, ACol: Cardinal; AMixedFraction: Boolean; ANumeratorDigits, ADenominatorDigits: Integer): PCell; @@ -249,13 +247,12 @@ end; {@@ ---------------------------------------------------------------------------- Formats a number as a fraction - @param ACell Pointer to the cell to be formatted - @param ANumFormat Identifier of the format to be applied. Must be - either nfFraction or nfMixedFraction - @param ANumeratorDigts Count of numerator digits - @param ADenominatorDigits Count of denominator digits + @param ACell Pointer to the cell to be formatted + @param ANumFormat Identifier of the format to be applied. Must be either nfFraction or nfMixedFraction + @param ANumeratorDigts Count of numerator digits + @param ADenominatorDigits Count of denominator digits - @see TsNumberFormat + @seeAlso TsNumberFormat -------------------------------------------------------------------------------} procedure TsWorksheet.WriteFractionFormat(ACell: PCell; AMixedFraction: Boolean; ANumeratorDigits, ADenominatorDigits: Integer); @@ -279,16 +276,16 @@ end; {@@ ---------------------------------------------------------------------------- Adds a number format to the formatting of a cell - @param ARow The row of the cell - @param ACol The column of the cell - @param ANumFormat Identifier of the format to be applied - @param ADecimals Number of decimal places - @param ACurrencySymbol optional currency symbol in case of nfCurrency - @param APosCurrFormat optional identifier for positive currencies - @param ANegCurrFormat optional identifier for negative currencies - @return Pointer to the cell + @param ARow The row of the cell + @param ACol The column of the cell + @param ANumFormat Identifier of the format to be applied + @param ADecimals Number of decimal places + @param ACurrencySymbol optional currency symbol in case of nfCurrency + @param APosCurrFormat optional identifier for positive currencies + @param ANegCurrFormat optional identifier for negative currencies + @returns Pointer to the cell - @see TsNumberFormat + @seeAlso TsNumberFormat -------------------------------------------------------------------------------} function TsWorksheet.WriteNumberFormat(ARow, ACol: Cardinal; ANumFormat: TsNumberFormat; ADecimals: Integer; ACurrencySymbol: String = ''; @@ -302,15 +299,15 @@ end; {@@ ---------------------------------------------------------------------------- Adds a number format to the formatting of a cell - @param ARow The row of the cell - @param ACol The column of the cell - @param ANumFormat Identifier of the format to be applied - @param ADecimals Number of decimal places - @param ACurrencySymbol optional currency symbol in case of nfCurrency - @param APosCurrFormat optional identifier for positive currencies - @param ANegCurrFormat optional identifier for negative currencies + @param ARow The row of the cell + @param ACol The column of the cell + @param ANumFormat Identifier of the format to be applied + @param ADecimals Number of decimal places + @param ACurrencySymbol optional currency symbol in case of nfCurrency + @param APosCurrFormat optional identifier for positive currencies + @param ANegCurrFormat optional identifier for negative currencies - @see TsNumberFormat + @seeAlso TsNumberFormat -------------------------------------------------------------------------------} procedure TsWorksheet.WriteNumberFormat(ACell: PCell; ANumFormat: TsNumberFormat; ADecimals: Integer; ACurrencySymbol: String = ''; @@ -359,14 +356,13 @@ end; {@@ ---------------------------------------------------------------------------- Adds a number format to the formatting of a cell - @param ARow The row of the cell - @param ACol The column of the cell - @param ANumFormat Identifier of the format to be applied - @param ANumFormatString Optional string of formatting codes. Is only considered - if ANumberFormat is nfCustom. - @return Pointer to the cell + @param ARow The row of the cell + @param ACol The column of the cell + @param ANumFormat Identifier of the format to be applied + @param ANumFormatString Optional string of formatting codes. Is only considered if ANumberFormat is nfCustom. + @returns Pointer to the cell - @see TsNumberFormat + @seeAlso TsNumberFormat -------------------------------------------------------------------------------} function TsWorksheet.WriteNumberFormat(ARow, ACol: Cardinal; ANumFormat: TsNumberFormat; const ANumFormatString: String = ''): PCell; @@ -381,10 +377,9 @@ end; @param ACell Pointer to the cell considered @param ANumFormat Identifier of the format to be applied - @param ANumFormatString Optional string of formatting codes. Is only considered - if ANumberFormat is nfCustom. + @param ANumFormatString Optional string of formatting codes. Is only considered if ANumberFormat is nfCustom. - @see TsNumberFormat + @seeAlso TsNumberFormat -------------------------------------------------------------------------------} procedure TsWorksheet.WriteNumberFormat(ACell: PCell; ANumFormat: TsNumberFormat; const ANumFormatString: String = ''); diff --git a/components/fpspreadsheet/source/common/fpsrpn.pas b/components/fpspreadsheet/source/common/fpsrpn.pas index e9d020737..24354e663 100644 --- a/components/fpspreadsheet/source/common/fpsrpn.pas +++ b/components/fpspreadsheet/source/common/fpsrpn.pas @@ -1,6 +1,6 @@ {@@ ---------------------------------------------------------------------------- - The unit fpsRPN contains methods for simple creation of an RPNFormula - array to be used in fpspreadsheet. + The unit **fpsRPN** contains methods for simple creation of an **RPNFormula** + array to be used in fpSpreadsheet. AUTHORS: Werner Pamler @@ -20,13 +20,13 @@ uses type {@@ Pointer to a TPRNItem record - @see TRPNItem } + @seeAlso TRPNItem } PRPNItem = ^TRPNItem; {@@ Helper record for simplification of RPN formula creation @param FE Formula element record stored in the RPN item @param Next Pointer to the next RPN item of the formula - @see TsFormulaElement } + @seeAlso TsFormulaElement } TRPNItem = record FE: TsFormulaElement; Next: PRPNItem; @@ -81,7 +81,7 @@ uses Creates a pointer to a new RPN item. This represents an element in the array of token of an RPN formula. - @return Pointer to the RPN item + @returns Pointer to the RPN item -------------------------------------------------------------------------------} function NewRPNItem: PRPNItem; begin @@ -303,7 +303,7 @@ end; @param AErrCode Error code to be inserted (see TsErrorValue @param ANext Pointer to the next RPN item in the list - @see TsErrorValue + @seeAlso TsErrorValue -------------------------------------------------------------------------------} function RPNErr(AErrCode: TsErrorValue; ANext: PRPNItem): PRPNItem; begin @@ -386,11 +386,10 @@ end; (--> TFEKind). Note that array elements for all needed parameters must have been created before. - @param AToken Formula element indicating the function to be executed, - see the TFEKind enumeration for possible values. + @param AToken Formula element indicating the function to be executed, see the @link(TFEKind) enumeration for possible values. @param ANext Pointer to the next RPN item in the list - @see TFEKind + @seeAlso TFEKind -------------------------------------------------------------------------------} function RPNFunc(AToken: TFEKind; ANext: PRPNItem): PRPNItem; begin @@ -437,16 +436,9 @@ end; For each formula element, use one of the RPNxxxx functions implemented here. They are designed to be nested into each other. Terminate the chain by using nil. - @param AItem Pointer to the first RPN item representing the formula. - Each item contains a pointer to the next item in the list. - The list is terminated by nil. - @param AReverse If true the first rpn item in the chained list becomes the - last item in the token array. This feature is needed for - reading an xls file. - - @example - The RPN formula for the string expression "$A1+2" can be created as follows: - 
+  **Example**:
+  The RPN formula for the string expression "$A1+2" can be created as follows:
+   @preformatted(
       var
         f: TsRPNFormula;
       begin
@@ -455,7 +447,11 @@ end;
           RPNNumber(2,
           RPNFunc(fekAdd,
           nil))));
-
+ ) + + @param AItem Pointer to the first RPN item representing the formula. Each item contains a pointer to the next item in the list. The list is terminated by nil. + @param AReverse If @true the first rpn item in the chained list becomes the last item in the token array. This feature is needed for reading an xls file. + -------------------------------------------------------------------------------} function CreateRPNFormula(AItem: PRPNItem; AReverse: Boolean = false): TsRPNFormula; var @@ -491,9 +487,7 @@ end; {@@ ---------------------------------------------------------------------------- Destroys the RPN formula starting with the given RPN item. - @param AItem Pointer to the first RPN items representing the formula. - Each item contains a pointer to the next item in the list. - The list is terminated by nil. + @param AItem Pointer to the first RPN items representing the formula. Each item contains a pointer to the next item in the list. The list is terminated by nil. -------------------------------------------------------------------------------} procedure DestroyRPNFormula(AItem: PRPNItem); var diff --git a/components/fpspreadsheet/source/common/fpstypes.pas b/components/fpspreadsheet/source/common/fpstypes.pas index 5daacc98d..67d181464 100644 --- a/components/fpspreadsheet/source/common/fpstypes.pas +++ b/components/fpspreadsheet/source/common/fpstypes.pas @@ -1,6 +1,7 @@ {@@ ---------------------------------------------------------------------------- - Unit fpsTypes collects the most fundamental declarations used - throughout the fpspreadsheet library. + Unit **fpsTypes** collects the most **fundamental declarations** used + throughout the fpspreadsheet library. It is very likey that this unit must + be added to the uses clause of the application. AUTHORS: Werner Pamler @@ -20,6 +21,9 @@ uses Classes, SysUtils, fpimage; {$IF FPC_FullVersion < 30000} +{@@ This string type is not re-encoded by FPC. It is a standard type of FPC 3.0+, + its declaration must be repeated here in order to keep fpSpreadsheet usable by + older FPC versions. } type RawByteString = ansistring; {$ENDIF} @@ -29,7 +33,18 @@ type TsBasicWorksheet = class; TsBasicWorkbook = class; - {@@ Built-in file formats of fpspreadsheet } + {@@ Built-in file formats of fpspreadsheet + @value sfExcel2 File format of Excel 2.1 + @value sfExcel5 File format of Excel 5 + @value sfExcel8 File format of Excel 97 + @value sfExcelXML XML file format of Excel 2003 + @value sfOOXML Default file format of Excel 2007 and later + @value sfOpenDocument File format of LibreOffice/OpenOffice Calc + @value sfCSV Comma-separated text file + @value sfHTML HTML file format + @value sfWikiTable_Pipes Wiki table file format + @value sfWikiTable_WikiMedia Wiki media file format + @value sfUser User-defined file format. The user must provide the reader and writer classes. } TsSpreadsheetFormat = (sfExcel2, sfExcel5, sfExcel8, sfExcelXML, sfOOXML, sfOpenDocument, sfCSV, sfHTML, sfWikiTable_Pipes, sfWikiTable_WikiMedia, sfUser); // Use this for user-defined readers/writers @@ -41,17 +56,26 @@ type TsSpreadFormatIDArray = array of TsSpreadFormatID; const - {@@ Format identifier of an undefined, unknown, etc. file format. } - sfidUnknown = -1; - { Each unit implementing a reader/writer will define an sfidXXXX value as a + {@@ Format identifier of an undefined, unknown, etc. file format. + + Each unit implementing a reader/writer will define an sfidXXXX value as a numerical identifer of the file format. In case of the built-in formats, the identifier is equal to the ord of the TsSpreadsheetFormat value. } + sfidUnknown = -1; type - {@@ Flag set during reading or writing of a workbook } + {@@ Flag set during reading or writing of a workbook + @value rwfNormal The workbook is in normal read/write state, i.e. it is currently neither being read nor being written. + @value rwfRead The workbook is currently being read. + @value rwfWrite The workbook is currently being written. } TsReadWriteFlag = (rwfNormal, rwfRead, rwfWrite); - {@@ Record collection limitations of a particular file format } + {@@ This record collect limitations of a particular file format. + @member MaxRowCount Gives the maximum number of rows supported by this file format. + @member MaxColCount Gives the maximum number of columns supported by this file format. + @member MaxPaletteSize Gives the maximum count of color palette entries supported by this file format + @member MaxSheetNameLength Defines the maximum length of the worksheet name supported by this file format. + @member MaxCharsInTextCell Defines the maximum length of the text in a cell supported by this file format. } TsSpreadsheetFormatLimitations = record MaxRowCount: Cardinal; MaxColCount: Cardinal; @@ -82,13 +106,13 @@ const {@@ Explanatory name of sfWikiTableWikiMedia file format } STR_FILEFORMAT_WIKITABLE_WIKIMEDIA = 'WikiTable (WikiMedia)'; - {@@ Default binary Excel file extension (<= Excel 97) } + {@@ Default binary **Excel** file extension (<= Excel 97) } STR_EXCEL_EXTENSION = '.xls'; - {@@ Default xml Excel file extension (Excel XP, 2003) } + {@@ Default xml **Excel** file extension (Excel XP, 2003) } STR_XML_EXCEL_EXTENSION = '.xml'; - {@@ Default xml Excel file extension (>= Excel 2007) } + {@@ Default xml **Excel** file extension (>= Excel 2007) } STR_OOXML_EXCEL_EXTENSION = '.xlsx'; - {@@ Default OpenDocument spreadsheet file extension } + {@@ Default **OpenDocument** spreadsheet file extension } STR_OPENDOCUMENT_CALC_EXTENSION = '.ods'; {@@ Default extension of comma-separated-values file } STR_COMMA_SEPARATED_EXTENSION = '.csv'; @@ -141,11 +165,20 @@ const type - {@@ Units for size dimensions } + {@@ Units for size dimensions + @value suChars Horizontal size is given as the count of '0' characters in the default font (not very exact) + @value suLines Vertical size is given as the count of lines measured by the height of the default font (not very exact) + @value suMillimeters Size is given in millimeters + @value suCentimeters Size is given in centimeters + @value suPoints Size is given in points + @value suInches Size is given in inches + + Adjustment of the @link(fpsutils.ScreenPixelsPerInch) is required for accurate + values in case of high-resolution monitors. } TsSizeUnits = (suChars, suLines, suMillimeters, suCentimeters, suPoints, suInches); const - {@@ Unit names } + {@@ Names of the size units } SizeUnitNames: array[TsSizeUnits] of string = ( 'chars', 'lines', 'mm', 'cm', 'pt', 'in'); @@ -162,12 +195,12 @@ const type - {@@ Tokens to identify the elements in an expanded formula. + {@@ Tokens to identify the @bold(elements in an expanded RPN formula). - NOTE: When adding or rearranging items + @note(When adding or rearranging items * make sure that the subtypes TOperandTokens and TBasicOperationTokens are complete - * make sure to keep the table "TokenIDs" in unit xlscommon in sync + * make sure to keep the table "TokenIDs" in unit xlscommon in sync) } TFEKind = ( { Basic operands } @@ -191,27 +224,50 @@ type TBasicOperationTokens = fekAdd..fekParen; type - {@@ Flags to mark the address or a cell or a range of cells to be absolute - or relative. They are used in the set TsRelFlags. } + {@@ Flags to mark the address or a cell or a range of cells to be @bold(absolute) or @bold(relative). They are used in the set @link(TsRelFlags). + @value rfRelRow Signals that the row reference is relative + @value rfRelCol Signals that the column reference is relative + @value rfRelRow2 Signals that the reference to the last row of a cell block is relative + @value rfRelCol2 Signals that the reference to the last column of a cell block is relative} TsRelFlag = (rfRelRow, rfRelCol, rfRelRow2, rfRelCol2); - {@@ Flags to mark the address of a cell or a range of cells to be absolute - or relative. It is a set consisting of TsRelFlag elements. } + {@@ Flags to mark the address of a cell or a range of cells to be @bold(absolute) + or @bold(relative). It is a set consisting of @link(TsRelFlag) elements. } TsRelFlags = set of TsRelFlag; const - {@@ Abbreviation of all-relative cell reference flags } + {@@ Abbreviation of all-relative cell reference flags (@seeAlso(TsRelFlag))} rfAllRel = [rfRelRow, rfRelCol, rfRelRow2, rfRelCol2]; {@@ Separator between worksheet name and cell (range) reference in an address } SHEETSEPARATOR = '!'; type + {@@ Flag indicating the calculation state of a formula. + @value ffCalculating The formula is currently being calculated. + @value ffCalculated The calculation of the formula is completed. } TsFormulaFlag = (ffCalculating, ffCalculated); + + {@@ Set of formula calculation state flags, @link(TsFormulaFlag) } TsFormulaFlags = set of TsFormulaFlag; - {@@ Elements of an expanded formula. - Note: If ElementKind is fekCellOffset, "Row" and "Col" have to be cast to signed integers! } + {@@ Elements of an expanded RPN formula. + @member ElementKind Identifies the type of the formula element, @seeAlso(TFEKind) + @member Row Row index of the cell to which this formula refers (zero-based) + @member Row2 Row index of the last cell in the cell range to which this formula refers (zero-based) + @member Col Column index of the cell to which this formula refers (zero-based) + @member Col2 Column index of the last cell in the cell range to which this formula refers (zero-based) + @member Sheet Index of the worksheet to which this formula refers (zero-based) + @member Sheet2 Index of the last worksheet in the 3d cell range to which this formula refers (zero-based) + @member SheetNames Tab-separated list of the worksheet names refered by this formula (intermediate use only). + @member DoubleValue Floating point value assigned to this formula element + @member IntValue Integer value assigned to this formula element + @member Stringvalue String value assigned to this formula element + @member RelFlags Information about relative/absolute cell addresses, @seeAlso(TsRelFlags) + @member FuncName Name of the function called by this formula element + @member ParamsNum Count of parameters needed by this formula element + + @note(If ElementKind is fekCellOffset, "Row" and "Col" have to be cast to signed integers!) } TsFormulaElement = record ElementKind: TFEKind; Row, Row2: Cardinal; // zero-based @@ -230,10 +286,24 @@ type Simplifies the task of format writers which need RPN } TsRPNFormula = array of TsFormulaElement; - {@@ Formula dialect } + {@@ Formula dialect + @value fdExcelA1 Default A1 syntax of Excel cell references: Cells are identified by column letters ('A', 'B', ...) and 1-based row numbers ('1', '2') + @value fdExcelR1C1 R1C1 syntax of excel + @value fdOpenDocument Syntax of OpenOffice/LibreOffice Calc. + @value fdLocalized The formula uses localized format settings in A1 syntax. } TsFormulaDialect = (fdExcelA1, fdExcelR1C1, fdOpenDocument, fdLocalized); - {@@ Describes the type of content in a cell of a TsWorksheet } + {@@ Describes the **type of content** in a cell of a @link(TsWorksheet) + @value cctEmpty The cell is empty, however, can carry a format. + @value cctFormula The cell contains a formula which has not yet been calculated + @value cctNumber The cell contains a number (integer or float) + @value cctUTF8String The cell contains a string which is considered to be UTF8-encoded. + @value cctDateTime The cell contains a date/time value. + @value cctBool The cell contains a boolean value + @value cctError The cell contains an error value + + @seeAlso TsErrorValue + } TCellContentType = (cctEmpty, cctFormula, cctNumber, cctUTF8String, cctDateTime, cctBool, cctError); @@ -252,22 +322,30 @@ type {@@ The record TsHyperlink contains info on a hyperlink in a cell @param Row Row index of the cell containing the hyperlink @param Col Column index of the cell containing the hyperlink - @param Target Target of hyperlink: URI of file, web link, mail; or: - internal link (# followed by cell address) - @param Note Text displayed as a popup hint by Excel } + @param Target Target of hyperlink: URI of file, web link, mail; or: internal link (# followed by cell address) + @param Tooltip Text displayed as a popup hint by Excel } TsHyperlink = record Row, Col: Cardinal; Target: String; Tooltip: String; end; - {@@ Pointer to a TsHyperlink record } + {@@ Pointer to a @link(TsHyperlink) record } PsHyperlink = ^TsHyperlink; {@@ Callback function, e.g. for iterating the internal AVL trees of the workbook/sheet} TsCallback = procedure (data, arg: Pointer) of object; - {@@ Error code values } + {@@ Error code values + @value errOK ok, no error + @value errEmptyIntersection A space was used in formulas that reference multiple ranges; a comma separates range references (#NULL!) + @value errDivideByZero Trying to divide by zero (#DIV/0!) + @value errWrongType The wrong type of operand or function argument is used (#VALUE!) + @value errIllegalRef A reference is invalid (#REF!) + @value errWrongName Text in the formula is not recognized (#NAME?) + @value errOverflow A formula has invalid numeric data for the type of operation (#NUM!) + @value errArgError A formula or a function inside a formula cannot find the referenced data (#N/A) + @value errFormulaNotSupported This formula is not suppored by fpSpreadsheet (error code not used by Excel and Calc) } TsErrorValue = ( errOK, // no error errEmptyIntersection, // #NULL! @@ -277,18 +355,27 @@ type errWrongName, // #NAME? errOverflow, // #NUM! errArgError, // #N/A ( = #NV in German ) - // --- no Excel errors -- - errFormulaNotSupported + errFormulaNotSupported // No excel error ); - {@@ List of possible formatting fields } + {@@ List of possible formatting fields + @value uffTextRotation The cell format supports text rotation. + @value uffFont The cell format supports using font different from default. + @value uffBorder The cell format supports decorating the cell with a border. + @value uffBackground The cell format supports a dedicated background color and fill style. + @value uffNumberFormat The cell format supports individual number formats of numeric cell values. + @value uffWordwrap The cell format supports wrapping of long cell text into new lines. + @value uffHorAlign The cell format supports horizontal text alignment. + @value uffVertAlign The cell format supports vertical text alignment + @value uffBiDi The cell format supports right-to-left text display. + @value uffProtection The cell format supports locking of cells. } TsUsedFormattingField = (uffTextRotation, uffFont, uffBorder, uffBackground, uffNumberFormat, uffWordWrap, uffHorAlign, uffVertAlign, uffBiDi, uffProtection ); { NOTE: "uffBackgroundColor" of older versions replaced by "uffBackground" } - {@@ Describes which formatting fields are active } + {@@ Describes which formatting fields are active (see @link(TsUsedFormattingField)). } TsUsedFormattingFields = set of TsUsedFormattingField; {$IFDEF NO_RAWBYTESTRING} @@ -334,82 +421,97 @@ const type {@@ Text rotation formatting. The text is rotated relative to the standard orientation, which is from left to right horizontal: - 
+      @preformatted(
        --->
-       ABC
+ ABC) So 90 degrees clockwise means that the text will be: - 
+      @preformatted(
        |  A
        |  B
-       v  C
+ v C) And 90 degree counter clockwise will be: - 
+      @preformatted(
        ^  C
        |  B
-       |  A
+ | A) Due to limitations of the text mode the characters are not rotated here. There is, however, also a "stacked" variant which looks exactly like the 90-degrees-clockwise case. + + @value trHorizontal Text is written horizontally as usual. + @value rt90DegreeClockwiseRotation Text is written vertically from top to bottom + @value rt90DegreeCounterClockwiseRotation Text is written vertically from bottom to top + @value rtStacked Text is written vertically from top to bottom, but with horizontal chararacters. } TsTextRotation = (trHorizontal, rt90DegreeClockwiseRotation, rt90DegreeCounterClockwiseRotation, rtStacked); - {@@ Indicates horizontal text alignment in cells } + {@@ Indicates horizontal text alignment in cells + @value haDefault Default text alignment (left for alphanumeric, right for numbers and dates) + @value haLeft Left-aligned cell text + @value haCenter Centered cell text + @value haRight Right-aligned cell text } TsHorAlignment = (haDefault, haLeft, haCenter, haRight); - {@@ Indicates vertical text alignment in cells } + {@@ Indicates vertical text alignment in cells + @value vaDefault Default vertical alignment (bottom) + @value vaTop Top-aligned cell text + @value vaCenter Vertically centered cell text + @value vaBottom Bottom-aligned cell text } TsVertAlignment = (vaDefault, vaTop, vaCenter, vaBottom); {@@ Colors in fpspreadsheet are given as rgb values in little-endian notation (i.e. "r" is the low-value byte). The highest-value byte, if not zero, - indicates special colors. } + indicates special colors. + + @note(This byte order in TsColor is opposite to that in HTML colors.) } TsColor = DWord; const {@@ These are some basic rgb color volues. FPSpreadsheet will support - built-in color constants only for the EGA palette. + only those built-in color constants originating in the EGA palette. } - {@@ rgb value of black color, BIFF2 palette index 0, BIFF8 index 8} + {@@ rgb value of @bold(black) color, BIFF2 palette index 0, BIFF8 index 8} scBlack = $00000000; - {@@ rgb value of white color, BIFF2 palette index 1, BIFF8 index 9 } + {@@ rgb value of @bold(white) color, BIFF2 palette index 1, BIFF8 index 9 } scWhite = $00FFFFFF; - {@@ rgb value of red color, BIFF2 palette index 2, BIFF8 index 10 } + {@@ rgb value of @bold(red) color, BIFF2 palette index 2, BIFF8 index 10 } scRed = $000000FF; - {@@ rgb value of green color, BIFF2 palette index 3, BIFF8 index 11 } + {@@ rgb value of @bold(green) color, BIFF2 palette index 3, BIFF8 index 11 } scGreen = $0000FF00; - {@@ rgb value of blue color, BIFF2 palette index 4, BIFF8 indexes 12 and 39} + {@@ rgb value of @bold(blue) color, BIFF2 palette index 4, BIFF8 indexes 12 and 39} scBlue = $00FF0000; - {@@ rgb value of yellow color, BIFF2 palette index 5, BIFF8 indexes 13 and 34} + {@@ rgb value of @bold(yellow) color, BIFF2 palette index 5, BIFF8 indexes 13 and 34} scYellow = $0000FFFF; - {@@ rgb value of magenta color, BIFF2 palette index 6, BIFF8 index 14 and 33} + {@@ rgb value of @bold(magenta) color, BIFF2 palette index 6, BIFF8 index 14 and 33} scMagenta = $00FF00FF; - {@@ rgb value of cyan color, BIFF2 palette index 7, BIFF8 indexes 15} + {@@ rgb value of @bold(cyan) color, BIFF2 palette index 7, BIFF8 indexes 15} scCyan = $00FFFF00; - {@@ rgb value of dark red color, BIFF8 indexes 16 and 35} + {@@ rgb value of @bold(dark red) color, BIFF8 indexes 16 and 35} scDarkRed = $00000080; - {@@ rgb value of dark green color, BIFF8 index 17 } + {@@ rgb value of @bold(dark green) color, BIFF8 index 17 } scDarkGreen = $00008000; - {@@ rgb value of dark blue color } + {@@ rgb value of @bold(dark blue) color } scDarkBlue = $00800000; - {@@ rgb value of olive color } + {@@ rgb value of @bold(olive) color } scOlive = $00008080; - {@@ rgb value of purple color, BIFF8 palette indexes 20 and 36 } + {@@ rgb value of @bold(purple) color, BIFF8 palette indexes 20 and 36 } scPurple = $00800080; - {@@ rgb value of teal color, BIFF8 palette index 21 and 38 } + {@@ rgb value of @bold(teal) color, BIFF8 palette index 21 and 38 } scTeal = $00808000; - {@@ rgb value of silver color } + {@@ rgb value of @bold(silver) color } scSilver = $00C0C0C0; - {@@ rgb value of grey color } + {@@ rgb value of @bold(grey) color } scGray = $00808080; - {@@ rgb value of gray color } + {@@ rgb value of @bold(gray) color } scGrey = scGray; // redefine to allow different spelling {@@ Identifier for not-defined color } scNotDefined = $40000000; - {@@ Identifier for transparent color } + {@@ Identifier for @bold(transparent) color } scTransparent = $20000000; {@@ Identifier for palette index encoded into the TsColor } scPaletteIndexMask = $80000000; @@ -467,13 +569,20 @@ const scWheat = $00B3DEF5 deprecated; type - {@@ Font style (redefined to avoid usage of "Graphics" } + {@@ Font style (redefined to avoid usage of graphics unit) + @value fssBold Bold text + @value fssItalic Italic text + @value fssStrikeOut Strike-through text (there is only a single strike-out line) + @value fssUnderLine Underlined text (there is only a single underline) } TsFontStyle = (fssBold, fssItalic, fssStrikeOut, fssUnderline); {@@ Set of font styles } TsFontStyles = set of TsFontStyle; - {@@ Font position (subscript or superscript) } + {@@ Font position (subscript or superscript) + @value fpNormal Normals character position + @value fpSuperscript Superscripted characters, like in @code('10²') + @value fpSubscript Subscripted characters} TsFontPosition = (fpNormal, fpSuperscript, fpSubscript); // Keep order for compatibility with xls! {@@ Font record used in fpspreadsheet. Contains the font name, the font size @@ -481,9 +590,9 @@ type TsFont = class {@@ Name of the font face, such as 'Arial' or 'Times New Roman' } FontName: String; - {@@ Size of the font in points } + {@@ Size of the font, in points } Size: Single; // in "points" - {@@ Font style, such as bold, italics etc. - see TsFontStyle} + {@@ Font style, such as bold, italics etc. - see @link(TsFontStyle)} Style: TsFontStyles; {@@ Text color given as rgb value } Color: TsColor; @@ -497,9 +606,18 @@ type {@@ Array of font records } TsFontArray = array of TsFont; - {@@ Parameter describing formatting of an text range in cell text } + {@@ Parameter describing formatting of an text range in cell text + + @member FirstIndex One-based index of the utf8 code-point ("character") + at which the FontIndex should be used. + @member FontIndex Index of the font in the workbook's font list to + be used for painting the characters following the + FirstIndex. + @member HyperlinkIndex Index of the hyperlink assigned to the text following + the character at FirstIndex. + } TsRichTextParam = record - FirstIndex: Integer; // 1-based utf8 code-point ("character") index + FirstIndex: Integer; FontIndex: Integer; HyperlinkIndex: Integer; end; @@ -507,20 +625,47 @@ type {@@ Parameters describing formatting of text ranges in cell text } TsRichTextParams = array of TsRichTextParam; - {@@ Indicates the border for a cell. If included in the CellBorders set the - corresponding border is drawn in the style defined by the CellBorderStyle. } + {@@ Indicates the border for a cell. If included in the CellBorders set + the corresponding border is drawn in the style defined by + the CellBorderStyle. + + @value cbNorth Horizontal border line at the top of the cell + @value cbWest Vertical border line at the left of the cell + @value cbEast Vertical border line at the right of the cell + @value cbSouth Horizontal border line at the bottom of the cell + @value cbDiagUp Diagonal border line running from the bottom-left to the top-right corner of the cell (/) + @value cbDiagDown Diagonal border line running from the top-left to the bottom-right corner of the cell (\) + + @seeAlso(TsCellBorderStyle)} TsCellBorder = (cbNorth, cbWest, cbEast, cbSouth, cbDiagUp, cbDiagDown); {@@ Indicates the border for a cell } TsCellBorders = set of TsCellBorder; - {@@ Line style (for cell borders) } + {@@ Line style (for cell borders) + @value lsThin Thin solid line + @value lsMedium Medium thick solid line + @value lsDashed Dashed line, thin + @value lsDotted Dotted line, thin + @value lsThick Very thick solid line + @value lsDouble Double line (solid) + @value lsHair Very thin line + @value lsMediumDash Dashed line, medium thickness + @value lsDashDot Dash-dot line, thin + @value lsMediumDashDot Dash-dot line, medium thickness + @value lsDashDotDot Dash-dot-dot line, thin + @value lsMediumDashDotDot Dash-dot-dot line, medium thickness + @value lsSlantDashDot Dash-dot line, slanted segment ends } TsLineStyle = (lsThin, lsMedium, lsDashed, lsDotted, lsThick, lsDouble, lsHair, lsMediumDash, lsDashDot, lsMediumDashDot, lsDashDotDot, lsMediumDashDotDot, lsSlantDashDot); {@@ The Cell border style reocrd contains the linestyle and color of a cell - border. There is a CellBorderStyle for each border. } + border. There is a CellBorderStyle for each border. + + @member LineStyle LineStyle to be used for this cell border. See @link(TsLineStyle). + @member Color Color to be used for this cell border. See @link(TsColor). + } TsCellBorderStyle = record LineStyle: TsLineStyle; Color: TsColor; @@ -541,9 +686,9 @@ const ); {@@ Border style to be used for "no border"} - NO_CELL_BORDER: TsCellBorderStyle = (LineStyle: lsThin; Color: scNotDefined); + {@@ Default border style in which all borders are used. } ALL_BORDERS: TsCellBorders = [cbNorth, cbEast, cbSouth, cbWest]; type @@ -593,30 +738,54 @@ type // other (format string goes directly into the file) nfCustom); - {@@ Cell calculation state } + {@@ Cell calculation state + + @value csNotCalculated The cell formula has not yet been calculated. + @value csCalculating The flag indicates that the cell is currently + being calculated. + @value csCalculated The cell formula has been calculated, and the + result is stored in the cell's data fields. } TsCalcState = (csNotCalculated, csCalculating, csCalculated); - {@@ Cell flag } + {@@ Cell flag providing particular information about the state of a cell + @value cfHasComment The cell has a comment record + @value cfHyperlink The cell has a hyperlink record + @value cfMerged The cell belongs to a block of merged cells + @value cfHasFormula The cell has a formula. + @value cf3dFormula The cell formula links to other worksheets. } TsCellFlag = (cfHasComment, cfHyperlink, cfMerged, cfHasFormula, cf3dFormula); {@@ Set of cell flags } TsCellFlags = set of TsCellFlag; - {@@ Record combining a cell's row and column indexes } + {@@ Record combining a cell's row and column indexes + @member Row Row index of the cell (0-based) + @member Col Column index of the cell (0-based) } TsCellCoord = record Row, Col: Cardinal; end; - {@@ Record combining row and column corner indexes of a range of cells } + {@@ Record combining row and column corner indexes of a range of cells + @member Row1 The index of the top row of the cell block (0-based) + @member Col1 The index of the left column of the cell block (0-based) + @member Row2 The index of the bottom row of the cell block (0-based) + @member Col2 The index of the right column of the cell block (0-based) } TsCellRange = record Row1, Col1, Row2, Col2: Cardinal; end; + {@@ Pointer to a @link(TsCellRange) record } PsCellRange = ^TsCellRange; {@@ Array with cell ranges } TsCellRangeArray = array of TsCellRange; - {@@ Record combining sheet index and row/column corner indexes of a cell range } + {@@ Record combining sheet index and row/column corner indexes of a 3d cell range + @member Row1 The index of the top row of the 3d cell block (0-based) + @member Col1 The index of the left column of the 3d cell block (0-based) + @member Row2 The index of the bottom row of the 3d cell block (0-based) + @member Col2 The index of the right column of the 3d cell block (0-based) + @member Sheet1 The index of the first sheet of the 3d cell block (0-based) + @member Sheet2 The index of the last sheet of the 3d cell block (0-based)} TsCellRange3d = record Row1, Col1, Row2, Col2: Cardinal; Sheet1, Sheet2: Integer; @@ -625,20 +794,34 @@ type {@@ Array of 3d cell ranges } TsCellRange3dArray = array of TsCellRange3d; - {@@ Record containing limiting indexes of column or row range } + {@@ Record containing limiting indexes of column or row range + @member FirstIndex Index of the first column/row of a range of columns/rows + @member LastIndex Index of the last column/row of a range of columns/rows } TsRowColRange = record FirstIndex, LastIndex: Cardinal; end; - {@@ Options for sorting } + {@@ Options for sorting + @value ssoDescending Sort values in descending order + @value ssoCaseInsensitive Ignore character case for sorting + @value ssoAlphaBeforeNum Sort alphanumeric characters to be before + numeric characters} TsSortOption = (ssoDescending, ssoCaseInsensitive, ssoAlphaBeforeNum); {@@ Set of options for sorting } TsSortOptions = set of TsSortOption; - {@@ Sort priority } + {@@ Sort priority + @value spNumAlpha Numbers are considered to be "smaller" than Alpha-Text, + i.e. will be put before text + @value spAlphaNum Numbers are considered to be "larger" than Alpha-Text, + i.e. will be sorted after text. } TsSortPriority = (spNumAlpha, spAlphaNum); // spNumAlpha: Number < Text - {@@ Sort key: sorted column or row index and sort direction } + {@@ Sort key: parameters for sorting + @member ColRowIndex Index of the sorted column or row + @member Options Options used for sorting) + + @seeAlso TsSortOption } TsSortKey = record ColRowIndex: Integer; Options: TsSortOptions; @@ -648,9 +831,9 @@ type TsSortKeys = array of TsSortKey; {@@ Complete set of sorting parameters - @param SortByCols If true sorting is top-down, otherwise left-right - @param Priority Determines whether numbers are before or after text. - @param SortKeys Array of sorting col/row indexes and sorting directions } + @member SortByCols If true sorting is top-down, otherwise left-right + @member Priority Determines whether numbers are before or after text. + @member Keys Array of sorting col/row indexes and sorting directions } TsSortParams = record SortByCols: Boolean; Priority: TsSortPriority; @@ -734,8 +917,7 @@ type procedure SetTextRotation(ARotation: TsTextRotation); procedure SetVertAlignment(AVertAlign: TsVertAlignment); end; - - {@@ Pointer to a format record } + {@@ Pointer to a @link(TsCellFormat) record } PsCellFormat = ^TsCellFormat; {@@ Cell structure for TsWorksheet @@ -745,21 +927,30 @@ type Never suppose that all *Value fields are valid, only one of the ContentTypes is valid. For other fields - use TWorksheet.ReadAsUTF8Text and similar methods + use @link(TsWorksheet.ReadAsText) and similar methods - @see ReadAsUTF8Text } + @member Row Row index of the cell (zero-based) + @member Col Column index of the cell (zero-based) + @member Worksheet Worksheet to which this cell belongs. In order to avoid circular unit references the worksheet is declared as @link(TsBasicWorksheet) here; usually it must be cast to TsWorksheet when used. + @member Flags Status flags for this cell (see @link(TsCellFlags)) + @member FormatIndex Index to the @link(TsCellFormat) record to be applied to this cell. The format records are collected in the workbook's CellFormatList. + @member ConditionalFormatIndex Array of indexes to the worksheet's ConditionalalFormats list needed for conditional formatting + @member UTF8StringValue String to be displayed in the cell if ContentType is cctUTF8String + @member RichTextParams Descriptions to be used for individual text formatting of parts of the cell text + @member ContentType Type of the data stored in the cell. See @link(TsCellContentType). + @member NumberValue Floating point value assigned to the cell. It is valid only when ContentType is cctNumber. + @member DateTimeValue Date/time value assigned to the cell. It is valid only when ContentType is cctDateTime. + @member BoolValue Boolean value assigned to the cell. It is valid only when ContentType is cctBoole. + @member ErrorValue Error value assigned to the cell. The value is valid only when ContentType is cctError. .} TCell = record - { Location of the cell } Row: Cardinal; // zero-based Col: Cardinal; // zero-based Worksheet: TsBasicWorksheet; // Must be cast to TsWorksheet when used (avoids circular unit reference) - { Status flags } Flags: TsCellFlags; - { Index of format record in the workbook's CellFormatList } FormatIndex: Integer; - { Indexes to worksheet's ConditionalFormats list needed for conditional formatting } ConditionalFormatIndex: array of Integer; - { Cell content } + + // Cell content UTF8StringValue: String; // Strings cannot be part of a variant record RichTextParams: TsRichTextParams; // Formatting of individual text ranges // FormulaValue: String; // Formula for calculation of cell content @@ -772,39 +963,33 @@ type cctBool : (BoolValue: boolean); cctError : (ErrorValue: TsErrorValue); end; - - {@@ Pointer to a TCell record } + {@@ Pointer to a @link(TCell) record } PCell = ^TCell; {@@ Types of row heights - rhtDefault - default row height - rhtAuto - automatically determined row height, depends on font size, - text rotation, rich-text parameters, word-wrap - rhtCustom - user-determined row height (dragging the row header borders in - the grid, or changed by code) } + @value rhtDefault Default row height + @value rhtAuto Automatically determined row height, depends on font size, text rotation, rich-text parameters, word-wrap + @value rhtCustom User-determined row height (dragging the row header borders in the grid, or changed by code) } TsRowHeightType = (rhtDefault, rhtCustom, rhtAuto); {@@ Types of column widths - cwtDefault - default column width - cwtCustom - userdefined column width (dragging the column header border - in the grid, or by changed by code) } + @value cwtDefault Default column width + @value cwtCustom Userdefined column width (dragging the column header border in the grid, or by changed by code) } TsColWidthtype = (cwtDefault, cwtCustom); {@@ Column or row options - croHidden - Column or row is hidden - croPageBreak - Enforces a pagebreak before this column/row during printing } + @value croHidden Column or row is hidden + @value croPageBreak Enforces a pagebreak before this column/row during printing } TsColRowOption = (croHidden, croPageBreak); TsColRowOptions = set of TsColRowOption; {@@ The record TRow contains information about a spreadsheet row: - @param Row The index of the row (beginning with 0) - @param Height The height of the row (expressed in the units defined - by the workbook) - @param RowHeightType Specifies whether the row has default, custom, or - automatic height - @param FormatIndex Row default format, index into the workbook's - FCellFormatList - @param Options @See TsColRowOption + @member Row The index of the row (beginning with 0) + @member Height The height of the row (expressed in the units defined by the workbook) + @member RowHeightType Specifies whether the row has default, custom, or automatic height + @member FormatIndex Row default format, index into the workbook's FCellFormatList + @member Options See @link(TsColRowOption) + Only rows with non-default height or non-default format or non-default Options have a row record. } TRow = record @@ -814,18 +999,16 @@ type FormatIndex: Integer; Options: TsColRowOptions; end; - - {@@ Pointer to a TRow record } + {@@ Pointer to a @link(TRow) record } PRow = ^TRow; {@@ The record TCol contains information about a spreadsheet column: - @param Col The index of the column (beginning with 0) - @param Width The width of the column (expressed in the units defined - in the workbook) - @param ColWidthType Specifies whether the column has default or custom width - @param FormatIndex Column default format, index into the workbook's - FCellFormatlist - @param Options @see TsColRowOptions + @member Col The index of the column (beginning with 0) + @member Width The width of the column (expressed in the units defined in the workbook) + @member ColWidthType Specifies whether the column has default or custom width + @member FormatIndex Column default format, index into the workbook's FCellFormatlist + @member Options See @link(TsColRowOptions) + Only columns with non-default width or non-default format or non-default Options have a column record. } TCol = record @@ -835,28 +1018,41 @@ type FormatIndex: Integer; Options: TsColRowOptions; end; - - {@@ Pointer to a TCol record } + {@@ Pointer to a @link(TCol) record } PCol = ^TCol; - {@@ Embedded image } + {@@ Embedded image + @member Row Row index of the cell at which the top sie of the image is anchored + @member Index Index of the image in the workbook's embedded streams list. + @member Col Column index of cell at which the left side of the image is anchored + @member OffsetX Horizontal displacement of the image relative to the top/left corner of the anchor cell (in millimeters) + @member OffsetY Vertical displacement of the image relative to the top/left corner of the anchor cell (in millimeters) + @member ScaleX Horizontal scaling factor of the image + @member ScaleY Vertical scaling factor of the image + @member Picture Used internally by TPicture to display the image in the worksheet grid + @member HyperlinkTarget Hyperlink assigned to the image + @member HyperlinkToolTip Tooltip for the hyperlink of the image } TsImage = record - Row, Col: Cardinal; // cell for top/left edge of the image (anchor) - Index: Integer; // index into the workbook's embedded streams list - OffsetX, OffsetY: Double; // mm, relative to anchor - ScaleX, ScaleY: Double; // scaling factor of image - Picture: TObject; // used for TPicture to display in grid - HyperlinkTarget: String; // Hyperlink assigned to the image - HyperlinkToolTip: String; // Tooltip for hyperlink of the image + Row, Col: Cardinal; + Index: Integer; + OffsetX, OffsetY: Double; + ScaleX, ScaleY: Double; + Picture: TObject; + HyperlinkTarget: String; + HyperlinkToolTip: String; end; + {@@ Pointer to a @link(TsImage) record} PsImage = ^TsImage; - {@@ Image embedded in header or footer} + {@@ Image embedded in header or footer + @member Index Index of the image in the workbook's embedded streams list } TsHeaderFooterImage = record - Index: Integer; // index into the workbook's embedded streams list + Index: Integer; end; - {@@ Page orientation for printing } + {@@ Page orientation for printing + @value spoPortrait Printed page is in portrait orientation + @value spoLandscape Printed page is in landscape orientation } TsPageOrientation = (spoPortrait, spoLandscape); {@@ Options for the print layout records } @@ -912,60 +1108,38 @@ type TsStreamParams = set of TsStreamParam; {@@ Worksheet user interface options: - @param soShowGridLines Show or hide the grid lines in the spreadsheet - @param soShowHeaders Show or hide the column or row headers of the - spreadsheet - @param soHasFrozenPanes If set a number of rows and columns of the - spreadsheet is fixed and does not scroll. The number - is defined by LeftPaneWidth and TopPaneHeight. - @param soHidden Worksheet is hidden. - @param soProtected Worksheet is protected - @param soPanesProtection Panes are locked due to workbook protection - @param soAutoDetectCellType Auomatically detect type of cell content} + @value soShowGridLines Show or hide the grid lines in the spreadsheet + @value soShowHeaders Show or hide the column or row headers of the spreadsheet + @value soHasFrozenPanes If set a number of rows and columns of the spreadsheet is fixed and does not scroll. The number is defined by LeftPaneWidth and TopPaneHeight. + @value soHidden Worksheet is hidden. + @value soProtected Worksheet is protected + @value soPanesProtection Panes are locked due to workbook protection + @value soAutoDetectCellType Auomatically detect type of cell content} TsSheetOption = (soShowGridLines, soShowHeaders, soHasFrozenPanes, soHidden, soProtected, soPanesProtection, soAutoDetectCellType); - {@@ Set of user interface options - @ see TsSheetOption } + {@@ Set of user interface options ( + @seeAlso(TsSheetOption) } TsSheetOptions = set of TsSheetOption; {@@ Option flags for the workbook - @param boVirtualMode If in virtual mode date are not taken from cells - when a spreadsheet is written to file, but are - provided by means of the event OnWriteCellData. - Similarly, when data are read they are not added - as cells but passed the the event OnReadCellData; - @param boBufStream When this option is set a buffered stream is used - for writing (a memory stream swapping to disk) or - reading (a file stream pre-reading chunks of data - to memory) - @param boFileStream Uses file streams and temporary files during - reading and writing. Lowest memory consumptions, - but slow. - @param boAutoCalc Automatically recalculate formulas whenever a - cell value changes, in particular when file is - loaded. - @param boCalcBeforeSaving Calculates formulas before saving the file. - Otherwise there are no results when the file is - loaded back by fpspreadsheet. - @param boReadFormulas Allows to turn off reading of rpn formulas; this - is a precaution since formulas not correctly - implemented by fpspreadsheet could crash the - reading operation. - @param boWriteZoomfactor Instructs the writer to write the current zoom - factors of the worksheets to file. - @param boAbortReadOnFormulaError Aborts reading if a formula error is - encountered - @param boIgnoreFormulas Formulas are not checked and not calculated. - Cannot be used for biff formats. } + @value boVirtualMode If in virtual mode date are not taken from cells when a spreadsheet is written to file, but are provided by means of the event OnWriteCellData. Similarly, when data are read they are not added as cells but passed the the event OnReadCellData; + @value boBufStream When this option is set a buffered stream is used for writing (a memory stream swapping to disk) or reading (a file stream pre-reading chunks of data to memory) + @value boFileStream Uses file streams and temporary files during reading and writing. Lowest memory consumptions, but slow. + @value boAutoCalc Automatically recalculate formulas whenever a cell value changes, in particular when file is loaded. + @value boCalcBeforeSaving Calculates formulas before saving the file. Otherwise there are no results when the file is loaded back by fpspreadsheet. + @value boReadFormulas Allows to turn off reading of rpn formulas; this is a precaution since formulas not correctly implemented by fpspreadsheet could crash the reading operation. + @value boWriteZoomfactor Instructs the writer to write the current zoom factors of the worksheets to file. + @value boAbortReadOnFormulaError Aborts reading if a formula error is encountered + @value boIgnoreFormulas Formulas are not checked and not calculated. Cannot be used for biff formats. } TsWorkbookOption = (boVirtualMode, boBufStream, boFileStream, boAutoCalc, boCalcBeforeSaving, boReadFormulas, boWriteZoomFactor, boAbortReadOnFormulaError, boIgnoreFormulas); - {@@ Set of option flags for the workbook } + {@@ Set of option flags for the workbook (see @link(TsWorkbookOption)} TsWorkbookOptions = set of TsWorkbookOption; - {@@ Meta data for the workbook} + {@@ Workbook metadata } TsMetaData = class private FDateCreated: TDateTime; @@ -1013,7 +1187,7 @@ type displayed in the tab of the sheet. } property Name: string read FName write SetName; {@@ Parameters controlling visibility of grid lines and row/column headers, - usage of frozen panes etc. } + usage of frozen panes etc. See @link(TsSheetOption). } property Options: TsSheetOptions read FOptions write FOptions; {@@ Worksheet protection options } property Protection: TsWorksheetProtections read FProtection write FProtection; @@ -1034,7 +1208,7 @@ type FUnits: TsSizeUnits; // Units for row heights and col widths public {@@ A copy of SysUtil's DefaultFormatSettings (converted to UTF8) to provide - some kind of localization to some formatting strings. + some kind of localization of some formatting strings. Can be modified before loading/writing files } FormatSettings: TFormatSettings; @@ -1063,9 +1237,11 @@ type property Units: TsSizeUnits read FUnits; end; - {@@ Exception types for fpspreadsheet } + {@@ Ancestor of the fpSpreadsheet exceptions } EFpSpreadsheet = class(Exception); + {@@ Class of exceptions fired by the workbook reader } EFpSpreadsheetReader = class(EFpSpreadsheet); + {@@ Class of exceptions fired for the workbook writer } EFpSpreadsheetWriter = class(EFpSpreadsheet); const @@ -1075,10 +1251,15 @@ const ColWidthTypeNames: array[TsColWidthType] of string = ( 'Default', 'Custom'); - {@@ Indexes to be used for the various headers and footers } + { Indexes to be used for the various headers and footers } + + {@@ Index of the first header/footer to be used } HEADER_FOOTER_INDEX_FIRST = 0; + {@@ Index of the header/footer to be used for odd page numbers } HEADER_FOOTER_INDEX_ODD = 1; + {@@ Index of the header/footer to be used for even page numbers } HEADER_FOOTER_INDEX_EVEN = 2; + {@@ Index of the header/footer to be used for all pages } HEADER_FOOTER_INDEX_ALL = 1; procedure InitUTF8FormatSettings(out AFormatSettings: TFormatSettings); @@ -1255,8 +1436,10 @@ begin (FCustom.Count = 0) and (FDateCreated = 0) and (FDateLastModified = 0); end; -{ Provide initial author. In case of multiple authors, separate the names by - semicolons. } +{@@ ---------------------------------------------------------------------------- + Provide initial author. In case of multiple authors, separate the names by + semicolons. +-------------------------------------------------------------------------------} procedure TsMetaData.SetCreatedBy(AValue: String); begin FAuthors.DelimitedText := AValue; diff --git a/components/fpspreadsheet/source/common/fpsutils.pas b/components/fpspreadsheet/source/common/fpsutils.pas index e41265f84..5d4a10251 100644 --- a/components/fpspreadsheet/source/common/fpsutils.pas +++ b/components/fpspreadsheet/source/common/fpsutils.pas @@ -1,5 +1,5 @@ {@@ ---------------------------------------------------------------------------- - Unit fpsUtils provides a variety of utility functions used + Unit **fpsUtils** provides a variety of **utility functions** used throughout the fpspreadsheet library. LICENSE: See the file COPYING.modifiedLGPL.txt, included in the Lazarus @@ -284,8 +284,8 @@ const {@@ ---------------------------------------------------------------------------- WordLEToLE converts a word value from big-endian to little-endian byte order. - @param AValue Big-endian word value - @return Little-endian word value + @param AValue Big-endian word value + @returns Little-endian word value -------------------------------------------------------------------------------} function WordToLE(AValue: Word): Word; begin @@ -299,8 +299,8 @@ end; {@@ ---------------------------------------------------------------------------- DWordLEToLE converts a DWord value from big-endian to little-endian byte-order. - @param AValue Big-endian DWord value - @return Little-endian DWord value + @param AValue Big-endian DWord value + @returns Little-endian DWord value -------------------------------------------------------------------------------} function DWordToLE(AValue: Cardinal): Cardinal; begin @@ -314,8 +314,8 @@ end; {@@ ---------------------------------------------------------------------------- Converts an integer value from big-endian to little-endian byte-order. - @param AValue Big-endian integer value - @return Little-endian integer value + @param AValue Big-endian integer value + @returns Little-endian integer value -------------------------------------------------------------------------------} function IntegerToLE(AValue: Integer): Integer; begin @@ -329,8 +329,8 @@ end; {@@ ---------------------------------------------------------------------------- Converts a word value from little-endian to big-endian byte-order. - @param AValue Little-endian word value - @return Big-endian word value + @param AValue Little-endian word value + @returns Big-endian word value -------------------------------------------------------------------------------} function WordLEtoN(AValue: Word): Word; begin @@ -344,8 +344,8 @@ end; {@@ ---------------------------------------------------------------------------- Converts a DWord value from little-endian to big-endian byte-order. - @param AValue Little-endian DWord value - @return Big-endian DWord value + @param AValue Little-endian DWord value + @returns Big-endian DWord value -------------------------------------------------------------------------------} function DWordLEtoN(AValue: Cardinal): Cardinal; begin @@ -359,8 +359,8 @@ end; {@@ ---------------------------------------------------------------------------- Converts a widestring from big-endian to little-endian byte-order. - @param AValue Big-endian widestring - @return Little-endian widestring + @param AValue Big-endian widestring + @returns Little-endian widestring -------------------------------------------------------------------------------} function WideStringToLE(const AValue: WideString): WideString; {$IFNDEF FPC} @@ -385,8 +385,8 @@ end; {@@ ---------------------------------------------------------------------------- Converts a widestring from little-endian to big-endian byte-order. - @param AValue Little-endian widestring - @return Big-endian widestring + @param AValue Little-endian widestring + @returns Big-endian widestring -------------------------------------------------------------------------------} function WideStringLEToN(const AValue: WideString): WideString; {$IFNDEF FPC} @@ -415,10 +415,9 @@ end; @param AFirstCellRow Row index of the first cell of the range (output) @param AFirstCellCol Column index of the first cell of the range (output) @param ACount Number of cells included in the range (output) - @param ADirection fpsVerticalSelection if the range is along a column, - fpsHorizontalSelection if the range is along a row + @param ADirection fpsVerticalSelection if the range is along a column, fpsHorizontalSelection if the range is along a row - @return false if the string is not a valid cell range + @returns @False if the string is not a valid cell range -------------------------------------------------------------------------------} function ParseIntervalString(const AStr: string; out AFirstCellRow, AFirstCellCol, ACount: Cardinal; @@ -480,11 +479,9 @@ end; @param AFirstCellCol Column index of the top/left cell of the range (output) @param ALastCellRow Row index of the bottom/right cell of the range (output) @param ALastCellCol Column index of the bottom/right cell of the range (output) - @param AFlags a set containing an element for AFirstCellRow, AFirstCellCol, - ALastCellRow, ALastCellCol if they represent relative - cell addresses. + @param AFlags A set containing an element for AFirstCellRow, AFirstCellCol, ALastCellRow, ALastCellCol if they represent relative cell addresses. - @return false if the string is not a valid cell range + @returns @False if the string is not a valid cell range -------------------------------------------------------------------------------} function ParseCellRangeString(const AStr: string; out AFirstCellRow, AFirstCellCol, ALastCellRow, ALastCellCol: Cardinal; @@ -532,7 +529,7 @@ end; @param AFirstCellCol Column index of the top/left cell of the range (output) @param ALastCellRow Row index of the bottom/right cell of the range (output) @param ALastCellCol Column index of the bottom/right cell of the range (output) - @return false if the string is not a valid cell range + @returns @False if the string is not a valid cell range --------------------------------------------------------------------------------} function ParseCellRangeString(const AStr: string; out AFirstCellRow, AFirstCellCol, ALastCellRow, ALastCellCol: Cardinal): Boolean; @@ -550,14 +547,10 @@ end; Parses strings like A5:C10 into a range selection information. Returns in AFlags also information on relative/absolute cells. - @param AStr Cell range string, such as A5:C10 - @param ARange TsCellRange record of the zero-based row and column - indexes of the top/left and right/bottom corrners - @param AFlags a set containing an element for ARange.Row1 (top row), - ARange.Col1 (left column), ARange.Row2 (bottom row), - ARange.Col2 (right column) if they represent relative - cell addresses. - @return false if the string is not a valid cell range + @param AStr Cell range string, such as A5:C10 + @param ARange @link(TsCellRange) record of the zero-based row and column indexes of the top/left and right/bottom corrners + @param AFlags A set containing an element for ARange.Row1 (top row), ARange.Col1 (left column), ARange.Row2 (bottom row), ARange.Col2 (right column) if they represent relative cell addresses. + @returns @False if the string is not a valid cell range --------------------------------------------------------------------------------} function ParseCellRangeString(const AStr: String; out ARange: TsCellRange; out AFlags: TsRelFlags): Boolean; @@ -570,10 +563,9 @@ end; Parses strings like A5:C10 into a range selection information. Information on relative/absolute cells is ignored. - @param AStr Cell range string, such as A5:C10 - @param ARange TsCellRange record of the zero-based row and column - indexes of the top/left and right/bottom corrners - @return false if the string is not a valid cell range + @param AStr Cell range string, such as A5:C10 + @param ARange @link(TsCellRange) record of the zero-based row and column indexes of the top/left and right/bottom corrners + @returns @False if the string is not a valid cell range --------------------------------------------------------------------------------} function ParseCellRangeString(const AStr: String; out ARange: TsCellRange): Boolean; @@ -588,15 +580,14 @@ end; Note that there can be several letters to address for more than 26 columns. 'AFlags' indicates relative addresses. + Example: "AMP$200" --> (rel) column 1029 (= 26*26*1 + 26*16 + 26 - 1) + (abs) row = 199 (abs) + @param AStr Cell range string, such as A1 @param ACellRow Row index of the top/left cell of the range (output) @param ACellCol Column index of the top/left cell of the range (output) - @param AFlags A set containing an element for ACellRow and/or ACellCol, - if they represent a relative cell address. - @return False if the string is not a valid cell range - - @example "AMP$200" --> (rel) column 1029 (= 26*26*1 + 26*16 + 26 - 1) - (abs) row = 199 (abs) + @param AFlags A set containing an element for ACellRow and/or ACellCol, if they represent a relative cell address. + @returns @False if the string is not a valid cell range -------------------------------------------------------------------------------} function ParseCellString(const AStr: String; out ACellRow, ACellCol: Cardinal; out AFlags: TsRelFlags): Boolean; @@ -683,19 +674,16 @@ end; Extracts information on cell range from a cellrange string in "R1C1" notation. Returns in AFlags also information on relative/absolute cells. - @param AStr Cell range string, in R1C1 syntax, - such as R[2]C[3]:R[4]C[8] + @param AStr Cell range string, in R1C1 syntax, such as R[2]C[3]:R[4]C[8] @param ABaseRow Row index from which the cell reference is seen. @param ABaseCol Column index from which the cell reference is seen. @param AFirstCellRow Row index of the top/left cell of the range (output) @param AFirstCellCol Column index of the top/left cell of the range (output) @param ALastCellRow Row index of the bottom/right cell of the range (output) @param ALastCellCol Column index of the bottom/right cell of the rng (output) - @param AFlags A set containing an element for AFirstCellRow, - AFirstCellCol, ALastCellRow, ALastCellCol if they - represent a relative cell address. + @param AFlags A set containing an element for AFirstCellRow, AFirstCellCol, ALastCellRow, ALastCellCol if they represent a relative cell address. - @return FALSE if the string is not a valid cell range + @returns @FALSE if the string is not a valid cell range -------------------------------------------------------------------------------} function ParseCellRangeString_R1C1(const AStr: string; ABaseRow, ABaseCol: Cardinal; out AFirstCellRow, AFirstCellCol, ALastCellRow, ALastCellCol: Cardinal; @@ -752,9 +740,8 @@ end; @param ABaseCol Column index from which the cell reference is seen. @param ACellRow Row index of the top/left cell of the range (output) @param ACellCol Column index of the top/left cell of the range (output) - @param AFlags A set containing an element for ACellRow and/or ACellCol, - if they represent a relative cell address. - @return FALSE if the string is not a valid cell range + @param AFlags A set containing an element for ACellRow and/or ACellCol, if they represent a relative cell address. + @returns @FALSE if the string is not a valid cell range -------------------------------------------------------------------------------} function ParseCellString_R1C1(const AStr: String; ABaseRow, ABaseCol: Cardinal; out ACellRow, ACellCol: Cardinal; out AFlags: TsRelFlags): Boolean; @@ -861,7 +848,7 @@ end; {@@ ---------------------------------------------------------------------------- Parses a 3D cell and sheet range string in Excel R1C1 dialect. Returns the names of the limiting sheets and the indexes of the limiting borders. - The function result is false if the provided string is not valid. + The function result is @false if the provided string is not valid. -------------------------------------------------------------------------------} function ParseCellRangeString_R1C1(const AStr: String; ABaseRow, ABaseCol: Cardinal; out ASheet1, ASheet2: String; out ARow1, ACol1, ARow2, ACol2: Cardinal; @@ -907,7 +894,7 @@ end; @param AStr Cell range string, such as A1 @param ACellRow Row index of the top/left cell of the range (output) @param ACellCol Column index of the top/left cell of the range (output) - @return False if the string is not a valid cell range + @returns @False if the string is not a valid cell range -------------------------------------------------------------------------------} function ParseCellString(const AStr: string; out ACellRow, ACellCol: Cardinal): Boolean; @@ -938,7 +925,7 @@ end; @param AStr Cell row string, such as '1', 1-based! @param ARow Index of the row (zero-based!) (putput) - @return False if the string is not a valid cell row string + @returns @False if the string is not a valid cell row string -------------------------------------------------------------------------------} function ParseCellRowString(const AStr: string; out ARow: Cardinal): Boolean; begin @@ -956,7 +943,7 @@ end; @param AStr Cell range string, such as A1 @param ACol Zero-based index of the column (output) - @return False if the string is not a valid cell column string + @returns @False if the string is not a valid cell column string -------------------------------------------------------------------------------} function ParseCellColString(const AStr: string; out ACol: Cardinal): Boolean; var @@ -1012,7 +999,7 @@ end; {@@ ---------------------------------------------------------------------------- Parses a 3D cell and sheet range string in Excel A1 dialect. Returns the names of the limiting sheets and the indexes of the limiting borders. - The function result is false if the provided string is not valid. + The function result is @false if the provided string is not valid. -------------------------------------------------------------------------------} function ParseCellRangeString(const AStr: String; out ASheet1, ASheet2: String; out ARow1, ACol1, ARow2, ACol2: Cardinal; out AFlags: TsRelFlags): Boolean; @@ -1049,7 +1036,7 @@ end; {@@ ---------------------------------------------------------------------------- Parses a 3D cell and sheet range string in ODS dialect. Returns the names of the limiting sheets and the indexes of the limiting borders. - The function result is false if the provided string is not valid. + The function result is @false if the provided string is not valid. -------------------------------------------------------------------------------} function ParseCellRangeString_ODS(const AStr: String; out ASheet1, ASheet2: String; out ARow1, ACol1, ARow2, ACol2: Cardinal; out AFlags: TsRelFlags): Boolean; @@ -1100,9 +1087,8 @@ end; {@@ ---------------------------------------------------------------------------- Calculates an Excel column name ('A', 'B' etc) from the zero-based column index - @param AColIndex Zero-based column index - @return Letter-based column name string. Can contain several letter in case of - more than 26 columns + @param AColIndex Zero-based column index + @returns Letter-based column name string. Can contain several letter in case of more than 26 columns -------------------------------------------------------------------------------} function GetColString(AColIndex: Integer): String; { Code adapted from: @@ -1123,8 +1109,8 @@ end; {@@ ---------------------------------------------------------------------------- Calculates an Excel row name ('1', '2' etc) from the zero-based row index - @param ARowIndex Zero-based row index - @return Numerical, one-based row name string. + @param ARowIndex Zero-based row index + @returns Numerical, one-based row name string. -------------------------------------------------------------------------------} function GetRowString(ARowIndex: Integer): String; begin @@ -1138,14 +1124,12 @@ const Calculates a cell address string from zero-based column and row indexes and the relative address state flags. + Example: ARowIndex = 0, AColIndex = 0, AFlags = [rfRelRow] --> $A1 + @param ARowIndex Zero-based row index @param AColIndex Zero-based column index - @param AFlags An optional set containing an entry for column and row - if these addresses are relative. By default, relative - addresses are assumed. - @return Excel type of cell address containing $ characters for absolute - address parts. - @example ARowIndex = 0, AColIndex = 0, AFlags = [rfRelRow] --> $A1 + @param AFlags An optional set containing an entry for column and row if these addresses are relative. By default, relative addresses are assumed. + @returns Excel type of cell address containing $ characters for absolute address parts. -------------------------------------------------------------------------------} function GetCellString(ARow, ACol: Cardinal; AFlags: TsRelFlags = [rfRelRow, rfRelCol]): String; @@ -1162,14 +1146,10 @@ end; @param ARow Zero-based row index @param ACol Zero-based column index - @param AFlags An optional set containing an entry for column and row - if these addresses are relative. By default, relative - addresses are assumed. - @param @ARefRow Zero-based row index of the reference cell in case of - relative address. - @param @ARefCol Zero-based column index of the reference cell in case of - relative address. - @return Excel type of cell address in R1C1 notation. + @param AFlags An optional set containing an entry for column and row if these addresses are relative. By default, relative addresses are assumed. + @param @ARefRow Zero-based row index of the reference cell in case of relative address. + @param @ARefCol Zero-based column index of the reference cell in case of relative address. + @returns Excel type of cell address in R1C1 notation. -------------------------------------------------------------------------------} function GetCellString_R1C1(ARow, ACol: Cardinal; AFlags: TsRelFlags = [rfRelRow, rfRelCol]; ARefRow: Cardinal = Cardinal(-1); ARefCol: Cardinal = Cardinal(-1)): String; @@ -1230,20 +1210,15 @@ end; Calculates a cell range address string from zero-based column and row indexes and the relative address state flags. - @param ARow1 Zero-based index of the first row in the range - @param ACol1 Zero-based index of the first column in the range - @param ARow2 Zero-based index of the last row in the range - @param ACol2 Zero-based index of the last column in the range - @param AFlags A set containing an entry for first and last column and - row if their addresses are relative. - @param Compact If the range consists only of a single cell and compact - is true then the simple cell string is returned (e.g. A1). - If compact is false then the cell is repeated (e.g. A1:A1) - @return Excel type of cell address range containing '$' characters for absolute - address parts and a ':' to separate the first and last cells of the - range - @example ARow1 = 0, ACol1 = 0, ARow = 2, ACol = 1, AFlags = [rfRelRow, rfRelRow2] - --> $A1:$B3 + Example: ARow1 = 0, ACol1 = 0, ARow = 2, ACol = 1, AFlags = [rfRelRow, rfRelRow2] --> $A1:$B3 + + @param ARow1 Zero-based index of the first row in the range + @param ACol1 Zero-based index of the first column in the range + @param ARow2 Zero-based index of the last row in the range + @param ACol2 Zero-based index of the last column in the range + @param AFlags A set containing an entry for first and last column and row if their addresses are relative. + @param Compact If the range consists only of a single cell and compact is true then the simple cell string is returned (e.g. A1). If compact is false then the cell is repeated (e.g. A1:A1) + @returns Excel type of cell address range containing '$' characters for absolute address parts and a ':' to separate the first and last cells of the range -------------------------------------------------------------------------------} function GetCellRangeString(ARow1, ACol1, ARow2, ACol2: Cardinal; AFlags: TsRelFlags = rfAllRel; Compact: Boolean = false): String; @@ -1292,16 +1267,10 @@ end; Calculates a cell range address string from a TsCellRange record and the relative address state flags. - @param ARange TsCellRange record containing the zero-based indexes of - the first and last row and columns of the range - @param AFlags A set containing an entry for first and last column and - row if their addresses are relative. - @param Compact If the range consists only of a single cell and compact - is true then the simple cell string is returned (e.g. A1). - If compact is false then the cell is repeated (e.g. A1:A1) - @return Excel type of cell address range containing '$' characters for absolute - address parts and a ':' to separate the first and last cells of the - range + @param ARange TsCellRange record containing the zero-based indexes of the first and last row and columns of the range + @param AFlags A set containing an entry for first and last column and row if their addresses are relative. + @param Compact If the range consists only of a single cell and compact is @true then the simple cell string is returned (e.g. A1). If compact is @false then the cell is repeated (e.g. A1:A1) + @returns Excel type of cell address range containing '$' characters for absolute address parts and a ':' to separate the first and last cells of the range -------------------------------------------------------------------------------} function GetCellRangeString(ARange: TsCellRange; AFlags: TsRelFlags = rfAllRel; Compact: Boolean = false): String; @@ -1425,13 +1394,12 @@ end; {@@ ---------------------------------------------------------------------------- - Returns the error value code from a string. Result is false, if the string does + Returns the error value code from a string. Result is @false, if the string does not match one of the predefined error strings. - @param AErrorStr Error string - @param AErr Corresponding error value code (type TsErrorValue) - @result TRUE if error code could be determined from the error string, - FALSE otherwise. + @param AErrorStr Error string + @param AErr Corresponding error value code (type TsErrorValue) + @returns @TRUE if error code could be determined from the error string, @FALSE otherwise. -------------------------------------------------------------------------------} function TryStrToErrorValue(AErrorStr: String; out AErr: TsErrorValue): boolean; begin @@ -1453,8 +1421,8 @@ end; {@@ ---------------------------------------------------------------------------- Returns the message text assigned to an error value - @param AErrorValue Error code as defined by TsErrorvalue - @return Text corresponding to the error code. + @param AErrorValue Error code as defined by @link(TsErrorvalue) + @returns Text corresponding to the error code. -------------------------------------------------------------------------------} function GetErrorValueStr(AErrorValue: TsErrorValue): String; begin @@ -1477,12 +1445,9 @@ end; Returns the name of the given spreadsheet file format. @param AFormat Identifier of the file format - @return 'BIFF2', 'BIFF3', 'BIFF4', 'BIFF5', 'BIFF8', 'OOXML', 'Open Document', - 'CSV, 'WikiTable Pipes', or 'WikiTable WikiMedia" + @returns 'BIFF2', 'BIFF3', 'BIFF4', 'BIFF5', 'BIFF8', 'OOXML', 'Open Document', 'CSV, 'WikiTable Pipes', or 'WikiTable WikiMedia" - @Note This function is deprecated. Use GetSpreadFormatName or - GetSpreadTechnicalName of fpsRegFileformats instead in order to - be able to process user-defined formats as well. + @Note This function is deprecated. Use GetSpreadFormatName or GetSpreadTechnicalName of fpsRegFileformats instead in order to be able to process user-defined formats as well. -------------------------------------------------------------------------------} function GetFileFormatName(AFormat: TsSpreadsheetFormat): string; begin @@ -1492,8 +1457,8 @@ end; {@@ ---------------------------------------------------------------------------- Returns the default extension of each spreadsheet file format - @param AFormat Identifier of the file format - @retur File extension + @param AFormat Identifier of the file format + @returns File extension -------------------------------------------------------------------------------} function GetFileFormatExt(AFormat: TsSpreadsheetFormat): String; begin @@ -1511,12 +1476,13 @@ begin end; end; *) + {@@ ---------------------------------------------------------------------------- Determines the spreadsheet type from the file type extension - @param AFileName Name of the file to be considered - @param AFormatID File format ID found from analysis of the extension (output) - @return True if the file matches any of the registered formats, false otherwise + @param AFileName Name of the file to be considered + @param AFormatID File format ID found from analysis of the extension (output) + @returns @True if the file matches any of the registered formats, @false otherwise -------------------------------------------------------------------------------} function GetFormatFromFileName(const AFileName: TFileName; out AFormatID: TsSpreadFormatID): Boolean; @@ -1531,10 +1497,9 @@ end; {@@ ---------------------------------------------------------------------------- Determines the spreadsheet type from the file type extension - @param AFileName Name of the file to be considered - @param SheetType Built-in file format found from analysis of the extension - (output) - @return True if the file matches any of the built-in formats, false otherwise + @param AFileName Name of the file to be considered + @param SheetType Built-in file format found from analysis of the extension (output) + @returns @True if the file matches any of the built-in formats, @false otherwise -------------------------------------------------------------------------------} function GetFormatFromFileName(const AFileName: TFileName; out SheetType: TsSpreadsheetFormat): Boolean; @@ -1598,10 +1563,10 @@ end; Helper function to reduce typing: "if a conditions is true return the first number format, otherwise return the second format" - @param ACondition Boolean expression - @param AValue1 First built-in number format code - @param AValue2 Second built-in number format code - @return AValue1 if ACondition is true, AValue2 otherwise. + @param ACondition Boolean expression + @param AValue1 First built-in number format code + @param AValue2 Second built-in number format code + @returns AValue1 if ACondition is true, AValue2 otherwise. -------------------------------------------------------------------------------} function IfThen(ACondition: Boolean; AValue1, AValue2: TsNumberFormat): TsNumberFormat; @@ -1697,6 +1662,7 @@ end; {@@ ---------------------------------------------------------------------------- Converts a string to a floating point number. No assumption on decimal and thousand separator are made. + Is needed for reading CSV files. -------------------------------------------------------------------------------} function TryStrToFloatAuto(AText: String; out ANumber: Double; @@ -1868,14 +1834,13 @@ end; Returns also the maximum count of digits used in the numerator or denominator of the fraction + Example: AText := '1 3/4' --> ANumber = 1.75; AMaxDigits = 1; Result = true + @param AText String to be considered @param ANumber (out) value of the converted floating point number - @param AMaxDigits Maximum count of digits used in the numerator or - denominator of the fraction + @param AMaxDigits Maximum count of digits used in the numerator or denominator of the fraction - @return TRUE if a number value can be retrieved successfully, FALSE otherwise - - @example AText := '1 3/4' --> ANumber = 1.75; AMaxDigits = 1; Result = true + @returns @TRUE if a number value can be retrieved successfully, @FALSE otherwise -------------------------------------------------------------------------------} function TryFractionStrToFloat(AText: String; out ANumber: Double; out AIsMixed: Boolean; out AMaxDigits: Integer): Boolean; @@ -1946,8 +1911,8 @@ end; Excel's unit of row heights is "twips", i.e. 1/20 point. Converts Twips to points. - @param AValue Length value in twips - @return Value converted to points + @param AValue Length value in twips + @returns Value converted to points -------------------------------------------------------------------------------} function TwipsToPts(AValue: Integer): Single; begin @@ -1957,8 +1922,8 @@ end; {@@ ---------------------------------------------------------------------------- Converts points to twips (1 twip = 1/20 point) - @param AValue Length value in points - @return Value converted to twips + @param AValue Length value in points + @returns Value converted to twips -------------------------------------------------------------------------------} function PtsToTwips(AValue: Single): Integer; begin @@ -1968,8 +1933,8 @@ end; {@@ ---------------------------------------------------------------------------- Converts centimeters to points (72 pts = 1 inch) - @param AValue Length value in centimeters - @return Value converted to points + @param AValue Length value in centimeters + @returns Value converted to points -------------------------------------------------------------------------------} function cmToPts(AValue: Double): Double; begin @@ -1979,8 +1944,8 @@ end; {@@ ---------------------------------------------------------------------------- Converts points to centimeters - @param AValue Length value in points - @return Value converted to centimeters + @param AValue Length value in points + @returns Value converted to centimeters -------------------------------------------------------------------------------} function PtsToCm(AValue: Double): Double; begin @@ -1990,8 +1955,8 @@ end; {@@ ---------------------------------------------------------------------------- Converts inches to EMU (English metric units) - @param AValue Length value in inches - @return Value converted to EMU + @param AValue Length value in inches + @returns Value converted to EMU -------------------------------------------------------------------------------} function InToEMU(AValue: Double): Int64; begin @@ -2001,8 +1966,8 @@ end; {@@ ---------------------------------------------------------------------------- Converts EMU (English metric units) to inches - @param AValue Length value in EMU - @return Value converted to inches + @param AValue Length value in EMU + @returns Value converted to inches -------------------------------------------------------------------------------} function EMUToIn(AValue: Int64): Double; begin @@ -2013,8 +1978,8 @@ end; {@@ ---------------------------------------------------------------------------- Converts inches to millimeters - @param AValue Length value in inches - @return Value converted to mm + @param AValue Length value in inches + @returns Value converted to mm -------------------------------------------------------------------------------} function InToMM(AValue: Double): Double; begin @@ -2024,8 +1989,8 @@ end; {@@ ---------------------------------------------------------------------------- Converts millimeters to inches - @param AValue Length value in millimeters - @return Value converted to inches + @param AValue Length value in millimeters + @returns Value converted to inches -------------------------------------------------------------------------------} function mmToIn(AValue: Double): Double; begin @@ -2035,8 +2000,8 @@ end; {@@ ---------------------------------------------------------------------------- Converts inches to points (72 pts = 1 inch) - @param AValue Length value in inches - @return Value converted to points + @param AValue Length value in inches + @returns Value converted to points -------------------------------------------------------------------------------} function InToPts(AValue: Double): Double; begin @@ -2046,8 +2011,8 @@ end; {@@ ---------------------------------------------------------------------------- Converts points to inches (72 pts = 1 inch) - @param AValue Length value in points - @return Value converted to inches + @param AValue Length value in points + @returns Value converted to inches -------------------------------------------------------------------------------} function PtsToIn(AValue: Double): Double; begin @@ -2057,8 +2022,8 @@ end; {@@ ---------------------------------------------------------------------------- Converts EMU to millimeters - @param AValue Length value in EMU (1 cm = 360000 EMU) - @return Value converted to millimeters + @param AValue Length value in EMU (1 cm = 360000 EMU) + @returns Value converted to millimeters -------------------------------------------------------------------------------} function EMUToMM(AValue: Int64): Double; begin @@ -2068,8 +2033,8 @@ end; {@@ ---------------------------------------------------------------------------- Converts millimeters to EMU (english metric units, 1 cm = 360000 EMU) - @param AValue Length value in millimeters - @return Value converted to EMU + @param AValue Length value in millimeters + @returns Value converted to EMU -------------------------------------------------------------------------------} function mmToEMU(AValue: Double): Int64; inline; begin @@ -2079,8 +2044,8 @@ end; {@@ ---------------------------------------------------------------------------- Converts millimeters to points (72 pts = 1 inch) - @param AValue Length value in millimeters - @return Value converted to points + @param AValue Length value in millimeters + @returns Value converted to points -------------------------------------------------------------------------------} function mmToPts(AValue: Double): Double; begin @@ -2090,8 +2055,8 @@ end; {@@ ---------------------------------------------------------------------------- Converts points to millimeters - @param AValue Length value in points - @return Value converted to millimeters + @param AValue Length value in points + @returns Value converted to millimeters -------------------------------------------------------------------------------} function PtsToMM(AValue: Double): Double; const @@ -2103,9 +2068,9 @@ end; {@@ ---------------------------------------------------------------------------- Converts pixels to points. - @param AValue Length value given in pixels - @param AScreenPixelsPerInch Pixels per inch of the screen - @return Value converted to points + @param AValue Length value given in pixels + @param AScreenPixelsPerInch Pixels per inch of the screen + @returns Value converted to points -------------------------------------------------------------------------------} function pxToPts(AValue, AScreenPixelsPerInch: Integer): Double; begin @@ -2119,9 +2084,9 @@ end; {@@ ---------------------------------------------------------------------------- Converts points to pixels - @param AValue Length value given in points - @param AScreenPixelsPerInch Pixels per inch of the screen - @return Value converted to pixels + @param AValue Length value given in points + @param AScreenPixelsPerInch Pixels per inch of the screen + @returns Value converted to pixels -------------------------------------------------------------------------------} function PtsToPx(AValue: Double; AScreenPixelsPerInch: Integer): Integer; begin @@ -2132,13 +2097,9 @@ end; Converts a HTML length string to points. The units are assumed to be the last two digits of the string, such as '1.25in' - @param AValue HTML string representing a length with appended units code, - such as '1.25in'. These unit codes are accepted: - 'px' (pixels), 'pt' (points), 'in' (inches), 'mm' (millimeters), - 'cm' (centimeters). - @param DefaultUnits String identifying the units to be used if not contained - in AValue. - @return Extracted length in points + @param AValue HTML string representing a length with appended units code, such as '1.25in'. These unit codes are accepted: 'px' (pixels), 'pt' (points), 'in' (inches), 'mm' (millimeters), 'cm' (centimeters). + @param DefaultUnits String identifying the units to be used if not contained in AValue. + @returns Extracted length in points -------------------------------------------------------------------------------} function HTMLLengthStrToPts(AValue: String; DefaultUnits: String = 'pt'): Double; var @@ -2214,9 +2175,8 @@ end; {@@ ---------------------------------------------------------------------------- Converts a HTML color string to a TsColor alue. Needed for the ODS file format. - @param AValue HTML color string, such as '#FF0000' - @return rgb color value in little endian byte-sequence. This value is - compatible with the TColor data type of the graphics unit. + @param AValue HTML color string, such as '#FF0000' + @returns rgb color value in little endian byte-sequence. This value is compatible with the TColor data type of the graphics unit. -------------------------------------------------------------------------------} function HTMLColorStrToColor(AValue: String): TsColor; var @@ -2266,11 +2226,9 @@ end; {@@ ---------------------------------------------------------------------------- Converts an rgb color value to a string as used in HTML code (for ods) - @param AValue RGB color value (compatible with the TColor data type - of the graphics unit) - @param AExcelDialect If TRUE, returned string is in Excel's format for xlsx, - i.e. in AARRGGBB notation, like '00FF0000' for "red" - @return HTML-compatible string, like '#FF0000' (AExcelDialect = false) + @param AValue RGB color value (compatible with the TColor data type of the graphics unit) + @param AExcelDialect If @TRUE, returned string is in Excel's format for xlsx, i.e. in AARRGGBB notation, like '00FF0000' for "red" + @returns HTML-compatible string, like '#FF0000' (AExcelDialect = false) -------------------------------------------------------------------------------} function ColorToHTMLColorStr(AValue: TsColor; AExcelDialect: Boolean = false): String; @@ -2287,11 +2245,9 @@ end; Extracts compare information from an input string such as "<2.4". Is needed for some Excel-strings. - @param AString Input string starting with "<", "<=", ">", ">=", "<>" or "=" - If this start code is missing a "=" is assumed. - @param ACompareOp Identifier for the comparing operation extracted - - see TsCompareOperation - @return Input string with the comparing characters stripped. + @param AString Input string starting with "<", "<=", ">", ">=", "<>" or "=". If this start code is missing a "=" is assumed. + @param ACompareOp Identifier for the comparing operation extracted - see TsCompareOperation + @returns Input string with the comparing characters stripped. -------------------------------------------------------------------------------} function AnalyzeComparestr(AString: String; out ACompareOp: TsCompareOperation): String; @@ -2508,8 +2464,7 @@ end; found after searching will be replaced @param AReplaceText Is the text which will be inserted in the found cell - @param AOptions Defines options for the replacement (see - TsReplaceParams) + @param AOptions Defines options for the replacement (see TsReplaceParams) -------------------------------------------------------------------------------} function InitReplaceParams(AReplaceText: String = ''; AOptions: TsReplaceOptions = []): TsReplaceParams; @@ -2522,19 +2477,10 @@ end; Initializes a Sortparams record. This record sets paramaters used when cells are sorted. - @param ASortByCols If true sorting occurs along columns, i.e. the - ColRowIndex of the sorting keys refer to column indexes. - If False, sorting occurs along rows, and the - ColRowIndexes refer to row indexes - Default: true - @param ANumSortKeys Determines how many columns or rows are used as sorting - keys. (Default: 1). Every sort key is initialized for - ascending sort direction and case-sensitive comparison. - @param ASortPriority Determines the order or text and numeric data in - mixed content type cell ranges. - Default: spNumAlpha, i.e. numbers before text (in - ascending sort) - @return The initializaed TsSortParams record + @param ASortByCols If @true (default) sorting occurs along columns, i.e. the ColRowIndex of the sorting keys refer to column indexes. If @False, sorting occurs along rows, and the ColRowIndexes refer to row indexes + @param ANumSortKeys Determines how many columns or rows are used as sorting keys. (Default: 1). Every sort key is initialized for ascending sort direction and case-sensitive comparison. + @param ASortPriority Determines the order or text and numeric data in mixed content type cell ranges. Default: spNumAlpha, i.e. numbers before text (in ascending sort) + @returns The initializaed TsSortParams record -------------------------------------------------------------------------------} function InitSortParams(ASortByCols: Boolean = true; ANumSortKeys: Integer = 1; ASortPriority: TsSortPriority = spNumAlpha): TsSortParams; @@ -2589,7 +2535,7 @@ end; {@@ ---------------------------------------------------------------------------- Initalizes a new cell. - @return New cell record + @returns New cell record -------------------------------------------------------------------------------} procedure InitCell(out ACell: TCell); begin @@ -2601,10 +2547,10 @@ end; Initalizes a new cell and presets the row and column fields of the cell record to the parameters passed to the procedure. - @param AWorksheet Pointer to the worksheet containing the cell - @param ARow Row index of the new cell - @param ACol Column index of the new cell - @return New cell record with row and column fields preset to passed values. + @param AWorksheet Pointer to the worksheet containing the cell + @param ARow Row index of the new cell + @param ACol Column index of the new cell + @return New cell record with row and column fields preset to passed values. -------------------------------------------------------------------------------} procedure InitCell(AWorksheet: TsbasicWorksheet; ARow, ACol: Cardinal; out ACell: TCell); @@ -2664,13 +2610,11 @@ end; {@@ ---------------------------------------------------------------------------- Initializes the fields of a TsImage record - @param ARow Index of the anchor row - @param ACol Index of the anchor column - @param AOffsetX Distance of the left image edge from the left edge of the - anchor column. Measured in the units defined by the workbook. - @param AOffsetY Distance of the top image edge from the top edge of the - anchor row. Measured in the units defined by the workbook. - @return TsImage record containing these values. + @param ARow Index of the anchor row + @param ACol Index of the anchor column + @param AOffsetX Distance of the left image edge from the left edge of the anchor column. Measured in the units defined by the workbook. + @param AOffsetY Distance of the top image edge from the top edge of the anchor row. Measured in the units defined by the workbook. + @returns TsImage record containing these values. -------------------------------------------------------------------------------} procedure InitImageRecord(out AValue: TsImage; ARow, ACol: Cardinal; AOffsetX, AOffsetY, AScaleX, AScaleY: Double); @@ -2723,9 +2667,10 @@ begin end; *) {@@ ---------------------------------------------------------------------------- - Returns TRUE if the cell contains a formula. + Checks whether the specified cell contains a formula. - @param ACell Pointer to the cell checked + @param ACell Pointer to the cell checked + @returns @true if the cell contains a formula. -------------------------------------------------------------------------------} function HasFormula(ACell: PCell): Boolean; begin @@ -2733,7 +2678,11 @@ begin end; {@@ ---------------------------------------------------------------------------- - Returns TRUE if the cell has a 3D formula (i.e. reference to another sheet) + Checks whether the specified cell contains a 3D formula, i.e. a reference + to another sheet. + + @param ACell Pointer to the cell checked + @returns @true if the cell contains a 3D formula. -------------------------------------------------------------------------------} function Has3dFormula(ACell: PCell): Boolean; begin @@ -2741,7 +2690,7 @@ begin end; {@@ ---------------------------------------------------------------------------- - Returns true if the file begins with a ZIP header *PK'#03#04. + Returns @true if the file begins with a ZIP header *PK'#03#04. Needed for file format detection. -------------------------------------------------------------------------------} function HasZipHeader(AStream: TStream): Boolean; @@ -2840,7 +2789,7 @@ begin end; {@@ ---------------------------------------------------------------------------- - Creates a TsCellRange record from the coordinates of a single cell. + Creates a @link(TsCellRange) record from the coordinates of a single cell. -------------------------------------------------------------------------------} function Range(ARow, ACol: Cardinal): TsCellRange; begin @@ -2851,7 +2800,7 @@ begin end; {@@ ---------------------------------------------------------------------------- - Creates a TsCellRange record from the provided cell corner coordinates. + Creates a @link(TsCellRange) record from the provided cell corner coordinates. Puts the coordinates into right order if needed. -------------------------------------------------------------------------------} function Range(ARow1, ACol1, ARow2, ACol2: Cardinal): TsCellRange; @@ -3071,9 +3020,9 @@ end; The algorithm is described in http://msdn.microsoft.com/en-us/library/documentformat.openxml.spreadsheet.backgroundcolor.aspx - @param AColor rgb color to be modified - @param tint Factor (-1...+1) to be used for the operation - @return Modified color + @param AColor rgb color to be modified + @param tint Factor (-1...+1) to be used for the operation + @returns Modified color -------------------------------------------------------------------------------} function TintedColor(AColor: TsColor; tint: Double): TsColor; const @@ -3112,9 +3061,8 @@ end; Returns the color index for black or white depending on a color being "bright" or "dark". - @param AColor rgb color to be analyzed - @return The color index for black (scBlack) if AColorValue is a "bright" color, - or white (scWhite) if AColorValue is a "dark" color. + @param AColor rgb color to be analyzed + @returns The color index for black (scBlack) if AColorValue is a "bright" color, or white (scWhite) if AColorValue is a "dark" color. -------------------------------------------------------------------------------} function HighContrastColor(AColor: TsColor): TsColor; begin @@ -3129,8 +3077,8 @@ end; In other words: RGBA (where A is 0 and omitted in the function call) => ABGR Needed for conversion of palette colors. - @param RGB DWord value containing RGBA bytes in big endian byte-order - @return DWord containing RGB bytes in little-endian byte-order (A = 0) + @param RGB DWord value containing RGBA bytes in big endian byte-order + @returns DWord containing RGB bytes in little-endian byte-order (A = 0) -------------------------------------------------------------------------------} function LongRGBToExcelPhysical(const RGB: DWord): DWord; begin