paweld/lazarus
1
0
Fork 0
mirror of https://gitlab.com/freepascal.org/lazarus/lazarus.git synced 2025-04-26 10:19:14 +02:00
Code Issues Packages Projects Releases Wiki Activity

Docs: Documentation updates for LazUtils and LCL, especially ComCtrls. Issue , patch from Don Siders.

Browse Source 
git-svn-id: trunk@64771 -
This commit is contained in:
juha 2021-03-09 14:06:40 +00:00
parent 2f12a0e5c0
commit 14636b8c38
8 changed files with 3787 additions and 2292 deletions

170
docs/xml/lazutils/lazstringutils.xml
View File

@ -80,6 +80,118 @@
</seealso>
</element>
<element name="LazStartsStr">
<short>Determines if a string starts wih the specified value</short>
<descr>
<p>
<var>LazStartsStr</var> is a <var>Boolean</var> function used to determine if the string in <var>AText</var> starts wih the text specified in <var>ASubText</var>. It is a modified version of <var>StartsStr</var> from the RTL <file>strutils.pp</file> unit.
</p>
<p>
LazStartsStr casts the values in ASubText and AText to PChar types, and calls <var>StrLComp</var> to perform the comparison.
</p>
<p>
The returns value is <b>True</b> when AText begins with the specified sub-text. It also returns <b>True</b> when ASubText is an empty string (<b>''</b>), which is Delphi compatible.
</p>
</descr>
<seealso>
<link id="LazEndsStr"/>
<link id="LazStartsText"/>
</seealso>
</element>
<element name="LazStartsStr.Result">
<short>True when the string starts with the specified sub-text</short>
</element>
<element name="LazStartsStr.ASubText">
<short>Value to look for at the start of the text</short>
</element>
<element name="LazStartsStr.AText">
<short>Text examined in the routine</short>
</element>
<element name="LazEndsStr">
<short>Determines if a string ends wih the specified value</short>
<descr>
<p>
<var>LazEndsStr</var> is a <var>Boolean</var> function used to determine if the string in <var>AText</var> ends wih the text specified in <var>ASubText</var>. It is a modified version of <var>EndsStr</var> from the RTL <file>strutils.pp</file> unit.
</p>
<p>
LazEndsStr casts the values in ASubText and AText to PChar types, and calls <var>StrLComp</var> to perform the comparison.
</p>
<p>
The returns value is <b>True</b> when AText ends with the specified sub-text. It also returns <b>True</b> when ASubText is an empty string (<b>''</b>), which is Delphi compatible.
</p>
</descr>
<seealso>
<link id="LazStartsStr"/>
<link id="LazEndsText"/>
</seealso>
</element>
<element name="LazEndsStr.Result">
<short>True when the string ends with the specified value</short>
</element>
<element name="LazEndsStr.ASubText">
<short>Text to look for at the end of the string</short>
</element>
<element name="LazEndsStr.AText">
<short>String examined in the routine</short>
</element>
<element name="LazStartsText">
<short>Determines if a string occurs at the beginning of the specified text</short>
<descr>
<p>
<var>LazStartsText</var> is a fast implementation of <var>StartsText</var>. The version in the RTL <file>strutils.pp</file> unit calls <var>AnsiCompareText</var> and is <b>very</b> slow.
</p>
<p>
LazStartsText casts the values in <var>ASubText</var> and <var>AText</var> to <var>PChar</var> types, and calls <var>StrLIComp</var> to perform a case-insensitive comparison for the number of characters in ASubText.
</p>
<p>
The return value is <b>True</b> when ASubText and AText start with the same values. The return value is also <b>True</b> when ASubText is an empty string (<b>''</b>); this is Delphi compatible. The return value is <b>False</b> when StrLIComp returns a non-zero value.
</p>
</descr>
<seealso>
<link id="#rtl.strutils.StartsText">StartsText</link>
<link id="#rtl.sysutils.StrLIComp">StrLIComp</link>
</seealso>
</element>
<element name="LazStartsText.Result">
<short>True when the sub-text is at the start of the string value</short>
</element>
<element name="LazStartsText.ASubText">
<short>Value to locate at the start of the string</short>
</element>
<element name="LazStartsText.AText">
<short>String value used in the comparison</short>
</element>
<element name="LazEndsText">
<short>Determines if a string occurs at the end of the specified text</short>
<descr>
<p>
<var>LazEndsText</var> is a fast implementation of <var>EndsText</var>. The version in the RTL <file>strutils.pp</file> unit calls <var>AnsiCompareText</var> and is <b>very</b> slow.
</p>
<p>
LazEndsText casts the values in <var>ASubText</var> and <var>AText</var> to PChar types, and calls <var>StrLIComp</var> to perform a case-insensitive comparison for the number of characters in ASubText at the end of the value in AText.
</p>
<p>
The return value is <b>True</b> when AText ends with the value in ASubText. The return value is <b>True</b> when ASubText is an empty string (<b>''</b>); this is Delphi compatible. It is False when StrLIComp returns a non-zero value, or when ASubText is longer than AText.
</p>
</descr>
<seealso>
<link id="#rtl.strutils.EndsText">EndsText</link>
<link id="#rtl.sysutils.StrLIComp">StrLIComp</link>
</seealso>
</element>
<element name="LazEndsText.Result">
<short>True when the sub-text is at the end of the string value</short>
</element>
<element name="LazEndsText.ASubText">
<short>Value to locate at the end of the string</short>
</element>
<element name="LazEndsText.AText">
<short>String value used in the comparison</short>
</element>
<element name="PosI">
<short>A case-insensitive optimized version of the Pos routine</short>
<descr>
@ -114,62 +226,6 @@
<short>Value searched for the specified sub-string</short>
</element>
<element name="LazStartsText">
<short>Determines if a string occurs at the beginning of the specified text</short>
<descr>
<p>
<var>LazStartsText</var> is a fast implementation of <var>StartsText</var>. The version in the RTL <file>strutils.pp</file> unit calls <var>AnsiCompareText</var> and is <b>very</b> slow.
</p>
<p>
LazStartsText calls <var>StrLIComp</var> to perform a case-insensitive comparison between <var>ASubText</var> and <var>AText</var> for the number of characters in ASubText.
</p>
<p>
The return value is <b>True</b> when ASubText and AText start with the same values. It is False when StrLIComp returns a non-zero value, when ASubText is an empty string, or when ASubText is longer than AText.
</p>
</descr>
<seealso>
<link id="#rtl.strutils.StartsText">StartsText</link>
<link id="#rtl.sysutils.StrLIComp">StrLIComp</link>
</seealso>
</element>
<element name="LazStartsText.Result">
<short>True when the sub-text is at the start of the string value</short>
</element>
<element name="LazStartsText.ASubText">
<short>Value to locate at the start of the string</short>
</element>
<element name="LazStartsText.AText">
<short>String value used in the comparison</short>
</element>
<element name="LazEndsText">
<short>Determines if a string occurs at the end of the specified text</short>
<descr>
<p>
<var>LazEndsText</var> is a fast implementation of <var>EndsText</var>. The version in the RTL <file>strutils.pp</file> unit calls <var>AnsiCompareText</var> and is <b>very</b> slow.
</p>
<p>
LazEndsText calls <var>StrLIComp</var> to perform a case-insensitive comparison between <var>ASubText</var> and <var>AText</var> for the number of characters in ASubText at the end of the value in AText.
</p>
<p>
The return value is <b>True</b> when AText ends with the value in ASubText. It is False when StrLIComp returns a non-zero value, when ASubText is an empty string, or when ASubText is longer than AText.
</p>
</descr>
<seealso>
<link id="#rtl.strutils.EndsText">EndsText</link>
<link id="#rtl.sysutils.StrLIComp">StrLIComp</link>
</seealso>
</element>
<element name="LazEndsText.Result">
<short>True when the sub-text is at the end of the string value</short>
</element>
<element name="LazEndsText.ASubText">
<short>Value to locate at the end of the string</short>
</element>
<element name="LazEndsText.AText">
<short>String value used in the comparison</short>
</element>
<element name="IsNumber">
<short>True when characters in S are in the range <b>'0'..'9'</b></short>
<descr/>
@ -441,7 +497,7 @@
<p>
<var>BeautifyLineXY</var> is a <var>String</var> function used to combine the values in the <var>Filename</var>, <var>Line</var>, <var>X</var> and <var>Y</var> arguments into a formatted message. The message is in the form:
</p>
<code>examplefile.pas (123, 1) The error message goes here.</code>
<pre>examplefile.pas (123, 1) The error message goes here.</pre>
<p>
<var>Filename</var> contains a file name used at the start of the formatted message.
</p>

13
docs/xml/lazutils/lconvencoding.xml
View File

@ -404,14 +404,21 @@
<element name="UTF8BOMToUTF8">
<short>Removes the UTF-8 BOM from the UTF-8 encoded value</short>
<descr/>
<descr>
<p>
The return value is the value in <var>s</var> after removing the Byte Order Mark in <var>UTF8BOM</var> from the start of the string. The return value is the same as the value in s when UTF8BOM is not found in the string.
</p>
<p>
No actions are performed in the routine when <var>s</var> is an empty string (<b>''</b>). The return value is also an empty string.
</p>
</descr>
<seealso/>
</element>
<element name="UTF8BOMToUTF8.Result">
<short/>
<short>Value after removing the UTF-8 BOM</short>
</element>
<element name="UTF8BOMToUTF8.s">
<short/>
<short>UTF-8-encoded value examined in the routine</short>
</element>
<element name="ISO_8859_1ToUTF8">

47
docs/xml/lazutils/masks.xml
View File

@ -70,8 +70,26 @@
<descr/>
<seealso/>
</element>
<element name="EMaskError">
<short>Exception raised for an invalid character in TMask</short>
<descr>
<p>
<var>EMaskError</var> is a <var>EConvertError</var> descendant representing the exception raised when an invalid character is found in a value passed to the <var>TMask.Create</var> constructor.
</p>
<p>
Mask specifications in TMask are limited to the single-byte code points in the UTF-8 character set. EMaskError is raised when a value with a muti-byte code point is encountered.
</p>
</descr>
<seealso>
<link id="TMask.Create"/>
<link id="#rtl.sysutils.EConvertError">EConvertError</link>
<link id="#lazutils.lazutilsstrconsts.lrsInvalidCharSet">lrsInvalidCharSet</link>
</seealso>
</element>
<element name="TMaskChar">
<short>Represent details for mask character types in the TMaskCharType enumeration</short>
<short>Represents details for mask character types in the TMaskCharType enumeration</short>
<descr>
<p>
<var>TMaskChar</var> is a variant record type with members used to represent details for mask character types in the <var>TMaskCharType</var> enumeration. TMaskChar is used to implement the <var>Chars</var> member in the <var>TMaskString</var> record type.
@ -131,20 +149,21 @@
<descr/>
<seealso/>
</element>
<element name="TMask">
<short>The TMask class represents a mask and performs comparisons</short>
<descr>
<p>
A mask is a comparison pattern built using wildcards, sets and/or literal characters.
A mask is a comparison pattern built using wildcards, sets and/or literal characters. The mask is limited to the single-byte code points in the UTF-8 encoding. Using multi-byte code points in TMask causes an <var>EMaskError</var> exception to be raised.
</p>
<p>
Each <b>literal character</b> must match a single character in the string. Case sensitivity requires the value <link id="TMaskOption">moCaseSensitive</link> in the options passed to the constructor.
</p>
<p>
A <b>set</b> starts with "<b>[</b>" and ends with "<b>]</b>". Each element of a set is a literal character and or a range. A range is defined as first-last literal character. One character of a set must match a single character in the string. A set [!...] matches if the character is not in the set. The option value <link id="TMaskOption">moDisableSets</link> passed to the constructor disables set processing.
A <b>set</b> starts with "<b>[</b>" and ends with "<b>]</b>". Each element of a set is a literal character and or a range. A range is defined as a first-to-last literal character string. One character of a set must match a single character in the string. A set [!...] matches if the character is not in the set. The option value <link id="TMaskOption">moDisableSets</link> passed to the constructor disables set processing.
</p>
<p>
<b>Wildcards</b> are the * and ? characters. An asterisk matches any number of characters. A question mark matches a single character.
<b>Wildcards</b> are the <b>*</b> and <b>?</b> characters. An asterisk matches any number of characters. A question mark matches a single character.
</p>
<p>
For example: 'Hello world' matches to the mask 'H?ll[xoy] w*d'.
@ -152,8 +171,22 @@
</descr>
<seealso>
<link id="MasksOverview"/>
<link id="EMaskError"/>
</seealso>
</element>
<element name="TMask.FMask"/>
<element name="TMask.FInitialMask"/>
<element name="TMask.FOptions"/>
<element name="TMask.InitMaskString">
<short>Initializes the internal TMaskString instance used in the class</short>
</element>
<element name="TMask.ClearMaskString">
<short>Frees resources allocated in the internal TMaskString instance</short>
</element>
<element name="TMask.Create">
<short>Constructor for the class instance</short>
<descr>
@ -161,7 +194,7 @@
<var>Create</var> is the overloaded constructor for the class instance. Overloaded variants are provided with parameter values that are used to configure the class instance.
</p>
<p>
<var>AValue</var> contain the mask value compared to a given file name in the method for the class.
<var>AValue</var> contains the pattern compared to a given file name in methods for the class. While defined as a <var>String</var> type, AValue is limited to the single-byte code points in the UTF-8 encoding. Using a multi-byte UTF-8 code point in AValue causes an <var>EMaskError</var> exception to be raised.
</p>
<p>
Each UTF-8 code point in AValue is examined, and the internal TMaskString is updated to reflect how the mask character is applied. For example:
@ -183,7 +216,7 @@
<var>AOptions</var> contains zero or more TMaskOption values which enable or disable features in the methods for the class instance.
</p>
<p>
Create calls the <var>InitMaskString</var> method to initial the internal <var>TMaskString</var> instance used in the class.
Create calls the private <var>InitMaskString</var> method to initialize the internal <var>TMaskString</var> instance used in the class.
</p>
<remark>
The overloaded variant which does not have an AOptions parameter has been deprecated. It will be removed in a future Lazarus version.
@ -193,6 +226,8 @@
<link id="TMaskString"/>
<link id="TMaskOptions"/>
<link id="TMaskOption"/>
<link id="EMaskError"/>
<link id="#lazutils.lazutilsstrconsts.lrsInvalidCharSet">lrsInvalidCharSet</link>
</seealso>
</element>
<element name="TMask.Create.AValue">

1
docs/xml/lcl/colorbox.xml
View File

@ -29,7 +29,6 @@
<element name="SysUtils"/>
<element name="Types"/>
<element name="Classes"/>
<element name="StrUtils"/>
<element name="LCLProc"/>
<element name="LCLType"/>
<element name="LCLStrConsts"/>

5147
docs/xml/lcl/comctrls.xml
View File

File diff suppressed because it is too large Load Diff

7
docs/xml/lcl/forms.xml
View File

@ -7601,7 +7601,12 @@
</p>
</descr>
<errors>
Destroy calls <var>RaiseGDBException</var> to raise an exception if the current class instance is unassigned (contains <b>Nil</b>). Uses the exception message 'TApplication.Destroy Self=nil'.
<p>
Destroy calls <var>RaiseGDBException</var> to raise an exception if the current class instance is unassigned (contains <b>Nil</b>). Uses the exception message 'TApplication.Destroy Self=nil'.
</p>
<p>
Raises an <var>EAssertFalied</var> exception if the CustomApplication and Application variables do not contain the same TCustomApplication instance.
</p>
</errors>
<seealso/>
</element>

591
docs/xml/lcl/maskedit.xml
View File

File diff suppressed because it is too large Load Diff

103
docs/xml/lcl/shellctrls.xml
View File

@ -444,9 +444,7 @@
<!--
<element name="TCustomShellTreeView.FBuiltinIconSize">
<descr>Defined for the Windows platform only.</descr>
</element>
The code is stil a Work-In-Progress, and these items were reverted. I expect they will return at some point - so these topics are commented instead of deleted.
<element name="TCustomShellTreeView.DrawBuiltInIcon">
<short>Draws the Shell Icon for the specified tree node</short>
@ -953,6 +951,7 @@
<element name="TCustomShellListView.FObjectTypes"/>
<element name="TCustomShellListView.FRoot"/>
<element name="TCustomShellListView.FShellTreeView"/>
<element name="TCustomShellListView.FUseBuiltInIcons"/>
<element name="TCustomShellListView.FOnAddItem"/>
<element name="TCustomShellListView.FOnFileAdded"/>
@ -1010,6 +1009,24 @@
<short>New value for the property</short>
</element>
<element name="TCustomShellListView.WSRegisterClass" link="#lcl.controls.TWinControl.WSRegisterClass">
<short/>
<descr>
<p>
<var>WSRegisterClass</var> is an overridden class method in <var>TCustomShellListView</var>. It registers properties that are ignored in the class instance during LCL component streaming, including:
</p>
<ul>
<li>ItemIndex (Used in older LCL versions)</li>
<li>BevelKind (Provided for Delphi compatibility)</li>
<li>TListItem.OverlayIndex (Provided for Delphi compatibility)</li>
</ul>
<p>
It calls the inherited method, and registers the companion widgetset class instance.
</p>
</descr>
<seealso/>
</element>
<element name="TCustomShellListView.PopulateWithRoot">
<short>Fills the list view with file system information for the root directory</short>
<descr>
@ -1020,7 +1037,13 @@
No actions are performed in the method at design-time, or when <var>Root</var> contains an empty string (<b>''</b>).
</p>
<p>
<var>PopulateWithRoot</var> calls the internal <var>GetFilesInDir</var> helper to get a list of file system items for the path which match the <var>Mask</var> and <var>ObjectTypes</var> specified for the control. Each of the files in the list are passed to <var>DoAddItem</var> and <var>OnAddItem</var> to determine if they can be added to the <var>Items</var> in the control. The <var>OnFileAdded</var> event handler is signalled (when assigned) for each new entry added to Items.
<var>PopulateWithRoot</var> calls the internal <var>GetFilesInDir</var> helper to get a list of file system items for the path which match the <var>Mask</var> and <var>ObjectTypes</var> specified for the control. Each of the files in the list are passed to <var>DoAddItem</var> / <var>OnAddItem</var> to determine if they can be added to the <var>Items</var> in the control.
</p>
<p>
A <var>TListItem</var> instance is added to Items to represent the files or directories. The <var>Data</var> property in the list item is used to store a pointer to the file size. Values are added to SubItems with the string representation for the file size, and the file extension. When <var>UseBuiltInIcons</var> is set to <b>True</b>, the <var>GetBuiltInImageIndex</var> method is called to get the <var>ImageIndex</var> for the built-in icon used for the list item.
</p>
<p>
The <var>OnFileAdded</var> event handler is signalled (when assigned) for each new entry added to Items.
</p>
<p>
The <var>Sort</var> method is called prior to exit to order the Items in the control using the option specified in the <var>FileSortType</var> property.
@ -1031,6 +1054,7 @@
<link id="TCustomShellListView.Items"/>
<link id="TCustomShellListView.Mask"/>
<link id="TCustomShellListView.ObjectTypes"/>
<link id="TCustomShellListView.UseBuiltInIcons"/>
<link id="TCustomShellTreeView.FileSortType"/>
<link id="TCustomShellListView.DoAddItem"/>
<link id="TCustomShellListView.OnAddItem"/>
@ -1083,6 +1107,47 @@
</short>
</element>
<element name="TCustomShellListView.GetBuiltinImageIndex">
<short>
Gets the index position for the built-in icon used for the specified path or file name
</short>
<descr>
<p>
<var>GetBuiltinImageIndex</var> is an <var>Integer</var> function used to get the image index for a built-in icon provided by the operating system or platform.
</p>
<p>
The return value contains the ordinal position for the image used for the file name or path specified in <var>AFilename</var>. The return value is <b>-1</b> if an image could not be selected for the value in AFileName.
</p>
<p>
When <var>ALargeImage</var> is <b>True</b>, the index value refers to a large image as used in the vsIcon view style. When set to <b>False</b>, it refers to a small image as used in the other view styles.
</p>
<p>
GetBuiltinImageIndex calls the GetBuiltInImageIndex method in the widgetset class to get the return value for the method. The widgetset class handles storing the built-in image to the correct image list when the handle for the image list has not already been assigned.
</p>
<p>
GetBuiltinImageIndex is called from the <var>PopulateWithRoot</var> method when <var>UseBuiltInIcons</var> is set to <b>True</b>.
</p>
<remark>
In the current LCL version, GetBuiltinImageIndex is implemented for the Windows platform only.
</remark>
</descr>
<seealso>
<link id="TCustomShellListView.UseBuiltInIcons"/>
<link id="TCustomShellListView.PopulateWithRoot"/>
<link id="#lcl.comctrls.TCustomListView.LargeImages">TCustomListView.LargeImages</link>
<link id="#lcl.comctrls.TCustomListView.SmallImages">TCustomListView.SmallImages</link>
</seealso>
</element>
<element name="TCustomShellListView.GetBuiltinImageIndex.Result">
<short>Ordinal position for the built-in image</short>
</element>
<element name="TCustomShellListView.GetBuiltinImageIndex.AFileName">
<short>File name or path used to find the associated image</short>
</element>
<element name="TCustomShellListView.GetBuiltinImageIndex.ALargeImage">
<short>True if the large image list is used for the image</short>
</element>
<element name="TCustomShellListView.OnFileAdded">
<short>
Event handler signalled when a file is added to the Items in the control
@ -1111,6 +1176,8 @@
<var>Create</var> is the overridden constructor for the class instance. <var>Create</var> calls the inherited method using <var>AOwner</var> as the owner of the class instance. <var>Create</var> sets the default values for properties in the class instance, including:
</p>
<dl>
<dt>UseBuiltInIcons</dt>
<dd>True</dd>
<dt>ViewStyle</dt>
<dd>vsReport view style</dd>
<dt>ObjectTypes</dt>
@ -1257,6 +1324,34 @@
</seealso>
</element>
<element name="TCustomShellListView.UseBuiltInIcons">
<short>
Indicates if icons provided by the OS or platform are used for items in the list
</short>
<descr>
<p>
<var>UseBuiltInIcons</var> is a <var>Boolean</var> property which indicates if icons provided by the OS or platform are used for the <var>Items</var> in the list view control. The default value for the property is <b>True</b>.
</p>
<p>
UseBuiltInIcons is used when the list view control is populated with the names for the file and/or directories on the local file system. When set to <b>True</b>, the <var>GetBuiltInImageIndex</var> method is called to get the image index for a <var>TListItem</var> stored in the <var>Items</var> property.
</p>
<p>
Set UseBuiltInIcons to <b>False</b> to use custom images provided in the <var>LargeImages</var> or <var>SmallImages</var> properties.
</p>
<remark>
UseBuiltInIcons and GetBuiltInImageIndex require support in the widgetset class to use system-provided icons. This support is currently implemented for the Windows platform only.
</remark>
</descr>
<seealso>
<link id="TCustomShellListView.GetBuiltInImageIndex"/>
<link id="TCustomShellListView.Items"/>
<link id="TCustomShellListView.PopulateWithRoot"/>
<link id="TListItem.ImageIndex"/>
<link id="#lcl.comctrls.TCustomListView.LargeImages">TCustomListView.LargeImages</link>
<link id="#lcl.comctrls.TCustomListView.SmallImages">TCustomListView.SmallImages</link>
</seealso>
</element>
<element name="TCustomShellListView.OnAddItem">
<short>
Event handler signalled to determine if the specified file information can be added to the Items for the list view.