lazarus/docs/xml/lazutils/textstrings.xml

<?xml version="1.0" encoding="UTF-8"?>
<!--

Documentation for LCL (Lazarus Component Library) and LazUtils (Lazarus 
Utilities) are published under the Creative Commons Attribution-ShareAlike 4.0 
International public license.

https://creativecommons.org/licenses/by-sa/4.0/legalcode.txt
https://gitlab.com/freepascal.org/lazarus/lazarus/-/blob/main/docs/cc-by-sa-4-0.txt

Copyright (c) 1997-2025, by the Lazarus Development Team.

-->
<fpdoc-descriptions>
<package name="lazutils">
<!--
====================================================================
TextStrings
====================================================================
-->
<module name="TextStrings">
<short>
<var>TTextStrings</var> describes TStrings descendants optimized for handling 
their complete text as a whole (instead of line by line).
</short>
<descr>
<p>
<file>textstrings.pas</file> contains <var>TStrings</var> descendants 
optimized for handling their complete text as a whole (instead of line by 
line).
</p>
<p>
<file>textstrings.pas</file> is part of the <file>lazutils</file> package.
</p>
</descr>

<!-- unresolved type references -->
<element name="Classes"/>
<element name="SysUtils"/>
<element name="LazUtilsStrConsts"/>

<element name="TTextLineRange">
<short>
<var>TTextLineRange</var> - record structure showing start and end of line in 
text, the line as a string, and any user data.
</short>
<descr>
<var>TTextLineRange</var> is a record type with information about lines of 
text in the TTextStrings component.
</descr>
<seealso>
<link id="TTextStrings"/>
<link id="#rtl.classes.TStrings.Strings">TStrings.Strings</link>
<link id="#rtl.classes.TStrings.Objects">TStrings.Objects</link>
</seealso>
</element>
<element name="TTextLineRange.StartPos">
<short>Offset to the start of the line in Text.</short>
</element>
<element name="TTextLineRange.EndPos">
<short>End of the line in Text (the end-of-line sequence).</short>
</element>
<element name="TTextLineRange.Line">
<short>Cached line as a String type.</short>
</element>
<element name="TTextLineRange.TheObject">
<short>User object.</short>
</element>

<element name="PTextLineRange">
<short>Pointer to a TTextLineRange type.</short>
</element>

<element name="TCustomMemoStrings">
<short>Implements a string list used in Memo controls.</short>
<descr>
<p>
<var>TCustomMemoStrings</var> is a <var>TStrings</var> descendant which works 
around the behavior of <var>TMemo.Lines</var>. In TMemo, Lines contains the 
text with wordwrap line endings. TCustomMemoStrings stores the text in an LFM 
without those wordwrap line endings.
</p>
</descr>
<seealso>
<link id="TTextStrings"/>
<link id="#rtl.classes.TStrings">TStrings</link>
<link id="#lcl.stdctrls.TCustomMemo">TCustomMemo</link>
<link id="#lcl.stdctrls.TMemo">TMemo</link>
</seealso>
</element>

<element name="TCustomMemoStrings.DoReadData">
<short>Reads and stores the values used in the Strings property.</short>
<descr>
Used to read values for the component during LCL component streaming.
</descr>
<seealso/>
</element>
<element name="TCustomMemoStrings.DoReadData.Reader">
<short>TReader instance used to load the values for the component.</short>
</element>

<element name="TCustomMemoStrings.DoWriteData">
<short>Writes the values in the Strings property.</short>
<descr>
Used to write values for the component during LCL component streaming.
</descr>
<seealso/>
</element>
<element name="TCustomMemoStrings.DoWriteData.Writer">
<short>TWriter instance used to write the values in the component.</short>
</element>

<element name="TCustomMemoStrings.DefineProperties">
<short>
Defines the Strings property and the read and write procedures for its data.
</short>
<descr/>
<seealso/>
</element>
<element name="TCustomMemoStrings.DefineProperties.Filer">
<short>TFiler instance used to read or write values for the component.</short>
</element>

<element name="TTextStrings">
<short>
Implements a string list optimized to handle the complete text as a whole 
(instead of line by line as in <var>TStringList</var>).
</short>
<descr>
<p>
TTextStrings is a <var>TCustomMemoStrings</var> descendant which implements a 
string list optimized for handling the complete text in the list (rather than 
on a line by line basis).
</p>
<p>
The ancestor class ensures that lines of text with wordwrap line endings are 
handled in the component. TTextString uses an internal array of 
<var>TTextLineRange</var> instances to represent the lines of text. 
Overridden methods are provided to ensure that the internal line ranges are 
used to implement property values.
</p>
<p>
TTextStrings is the type instantiated for use in the <var>Lines</var> 
property in <var>TCustomMemo</var>.
</p>
</descr>
<seealso>
<link id="TCustomMemoStrings"/>
<link id="#lcl.stdctrls.TCustomMemo.Create">TCustomMemo.Create</link>
<link id="#lcl.stdctrls.TMemo">TMemo</link>
</seealso>
</element>

<element name="TTextStrings.FOnChange"/>
<element name="TTextStrings.FOnChanging"/>

<element name="TTextStrings.FArraysValid">
<short>
Boolean flag which indicates whether the array of line ranges is valid.
</short>
</element>

<element name="TTextStrings.FLineCount">
<short>Number of lines in the array of line ranges.</short>
</element>

<element name="TTextStrings.FLineCapacity">
<short>Number of line ranges allocated for the component.</short>
</element>

<element name="TTextStrings.FLineRanges">
<short>
Pointer to an array of <var>TTextLineRange</var> instances used for the 
Strings in the component.
</short>
</element>

<element name="TTextStrings.FText">
<short>Member variable used to store the Text in the component.</short>
</element>

<element name="TTextStrings.FUpdateCount">
<short>
Number of times BeginUpdate has been called without a corresponding EndUpdate.
</short>
</element>

<element name="TTextStrings.FChangedWhileUpdate">
<short>Indicates if Changed was called after calling BeginUpdate.</short>
</element>

<element name="TTextStrings.GetTextStr">
<short>Gets the value for the Text property.</short>
<descr>
<p>
Overridden to re-implement the method from the ancestor class.
</p>
</descr>
<seealso>
<link id="#rtl.classes.TStrings.Text">TStrings.Text</link>
</seealso>
</element>
<element name="TTextStrings.GetTextStr.Result">
<short>Value for the Text property.</short>
</element>

<element name="TTextStrings.SetTextStr">
<short>Sets the value for the Text property.</short>
<descr>
<p>
Overridden to re-implement the method from the ancestor class.
</p>
</descr>
<seealso>
<link id="#rtl.classes.TStrings.Text">TStrings.Text</link>
</seealso>
</element>
<element name="TTextStrings.SetTextStr.AValue">
<short>New value for the Text property.</short>
</element>

<element name="TTextStrings.BuildArrays">
<short>
Clears and builds the array with the line ranges for the values in Text.
</short>
<descr>
<p>
<var>BuildArrays</var> is a method used to clear and build the internal array 
with the line ranges for the values in <var>Text</var>. BuildArrays detects 
the number of end-of-line sequences in Text, allocates memory for the dynamic 
array, and fills the <var>TTextLineRange</var> instances with their values.
</p>
<p>
BuildArrays is called from methods used to read or write values in the 
<var>Strings</var>, <var>Objects</var>, or <var>Count</var> properties. It is 
called when the internal flag that indicates the array is valid has not been 
set.
</p>
</descr>
<seealso>
<link id="TTextStrings.ClearArrays"/>
<link id="TTextStrings.Text"/>
<link id="TTextStrings.GetCount"/>
<link id="TTextStrings.GetLineEnd"/>
<link id="TTextStrings.Insert"/>
<link id="TTextStrings.Delete"/>
<link id="TTextStrings.Exchange"/>
<link id="TTextStrings.Move"/>
<link id="TTextStrings.AddObject"/>
<link id="TTextStrings.AddStrings"/>
<link id="TTextLineRange"/>
<link id="#rtl.classes.TStrings.Strings">TStrings.Strings</link>
<link id="#rtl.classes.TStrings.Objects">TStrings.Objects</link>
<link id="#rtl.classes.TStrings.Count">TStrings.Count</link>
</seealso>
</element>

<element name="TTextStrings.GetCount">
<short>Gets the value for the Count property.</short>
<descr>
<p>
<var>GetCount</var> is overridden in <var>TTextStrings</var> to re-implement 
the method. It ensures that the internal array of line ranges is valid, and 
calls <var>BuildArrays</var> when the validity flag has not been set.
</p>
<p>
The property value is set to the member value used to store the line count.
</p>
<p>
GetCount does not call the inherited method.
</p>
</descr>
<seealso>
<link id="#rtl.classes.TStrings.Count">TStrings.Count</link>
</seealso>
</element>
<element name="TTextStrings.GetCount.Result">
<short>Value for the property.</short>
</element>

<element name="TTextStrings.Changed">
<short>Performs actions needed after the value in Text is changed.</short>
<descr>
<p>
<var>Changed</var> is a method used to perform actions needed <b>after</b> 
the value in the <var>Text</var> property has been changed. If 
<var>BeginUpdate</var> has been called without a corresponding 
<var>EndUpdate</var> call, no actions are performed in the method. Otherwise, 
the <var>OnChange</var> event handler is signalled (when assigned).
</p>
<p>
Changed is called from the EndUpdate method when Text was modified following 
assignments to property values.
</p>
</descr>
<seealso/>
</element>

<element name="TTextStrings.Changing">
<short>
Performs action needed when properties in the component are being updated.
</short>
<descr>
<p>
<var>Changing</var> is a method used to perform actions needed when property 
values in the component are being updated. It mimics the Changing behavior 
implemented in <var>TStringList</var>, where methods call Changing prior to 
updates to the <var>Strings</var> or <var>Objects</var> properties.
</p>
<p>
In <var>TTextStrings</var>, the method signals the <var>OnChanging</var> 
event handler (when assigned) if there are no updates already in progress.
</p>
<p>
See <var>Changed</var> for the actions performed after property values have 
been updated.
</p>
</descr>
<seealso>
<link id="TTextStrings.OnChanging"/>
<link id="TTextStrings.Changed"/>
<link id="TTextStrings.Clear"/>
<link id="#rtl.classes.TStrings.Strings">TStrings.Strings</link>
<link id="#rtl.classes.TStrings.Objects">TStrings.Objects</link>
</seealso>
</element>

<element name="TTextStrings.Get">
<short>Gets the value for the indexed Strings property.</short>
<descr/>
<seealso>
<link id="#rtl.classes.TStrings.Strings">TStrings.Strings</link>
</seealso>
</element>
<element name="TTextStrings.Get.Result">
<short>Value for the indexed property.</short>
</element>
<element name="TTextStrings.Get.Index">
<short>Ordinal position for the property value.</short>
</element>

<element name="TTextStrings.ClearArrays">
<short>Clears the internal array of line ranges used in the component.</short>
<descr>
<p>
<var>ClearArrays</var> is a method used to free resources allocated to the 
internal array with the line ranges for the component. ClearArrays frees 
memory allocated for the <var>TTextLineRange</var> instances in the array, 
and sets the references to <b>Nil</b>.
</p>
<p>
The internal validity flag and the line counter are both reset to indicate 
that the array has not not been allocated.
</p>
<p>
ClearArrays is called from the <var>BuildArrays</var>, <var>Clear</var>, and 
<var>AddStrings</var> methods.
</p>
</descr>
<seealso>
<link id="TTextStrings.BuildArrays"/>
<link id="TTextStrings.Clear"/>
<link id="TTextStrings.AddStrings"/>
<link id="TTextLineRange"/>
</seealso>
</element>

<element name="TTextStrings.GetObject">
<short>Gets the value for the indexed Objects property.</short>
<descr/>
<seealso>
<link id="#rtl.classes.TStrings.Objects">TStrings.Objects</link>
</seealso>
</element>
<element name="TTextStrings.GetObject.Result">
<short>Value for the indexed property.</short>
</element>
<element name="TTextStrings.GetObject.Index">
<short>Ordinal position in Objects with the property value.</short>
</element>

<element name="TTextStrings.Put">
<short>Sets the value for the indexed Strings property.</short>
<descr/>
<seealso>
<link id="#rtl.classes.TStrings.Strings">TStrings.Strings</link>
</seealso>
</element>
<element name="TTextStrings.Put.Index">
<short>Ordinal position for the new property value.</short>
</element>
<element name="TTextStrings.Put.S">
<short>New value in the indexed property.</short>
</element>

<element name="TTextStrings.PutObject">
<short>Sets a value in the indexed Objects property.</short>
<descr/>
<seealso/>
</element>
<element name="TTextStrings.PutObject.Index">
<short>Ordinal position for the indexed property value.</short>
</element>
<element name="TTextStrings.PutObject.AnObject">
<short>TObject instance stored in the indexed property.</short>
</element>

<element name="TTextStrings.GetLineLen">
<short>
Gets the length of a line (including optional end-of-line characters) at the 
specified position.
</short>
<descr/>
<seealso/>
</element>
<element name="TTextStrings.GetLineLen.Result">
<short>Length of the specified line.</short>
</element>
<element name="TTextStrings.GetLineLen.Index">
<short>Ordinal position for the line examined in the method.</short>
</element>
<element name="TTextStrings.GetLineLen.IncludeNewLineChars">
<short>
<b>True</b> to include end-of-line characters in the line length.
</short>
</element>

<element name="TTextStrings.GetLineEnd">
<short>
Gets the ordinal position where the specified line ends in the Text property.
</short>
<descr>
Calls BuildArrays if the internal validity flag is not set.
</descr>
<seealso/>
</element>
<element name="TTextStrings.GetLineEnd.Result">
<short>Offset in Text where the end of the specified line is located.</short>
</element>
<element name="TTextStrings.GetLineEnd.Index">
<short>Ordinal position for the line examined in the method.</short>
</element>
<element name="TTextStrings.GetLineEnd.IncludeNewLineChars">
<short>
<b>True</b> to include end-of-line character(s) in the return value.
</short>
</element>

<element name="TTextStrings.CountLineEndings">
<short>
Gets the number of end-of-line sequences found in the specified string.
</short>
<descr/>
<seealso/>
</element>
<element name="TTextStrings.CountLineEndings.Result">
<short>Number of end-of-line sequences found in s.</short>
</element>
<element name="TTextStrings.CountLineEndings.s">
<short>String with the values examined in the method.</short>
</element>

<element name="TTextStrings.Create">
<short>Constructor for the class instance.</short>
<descr>
<p>
<var>Create</var> is the overridden constructor for the class instance, and 
calls the inherited method on entry. Create calls the 
<var>CheckSpecialChars</var> method (in the ancestor) to ensure that default 
values have assigned for the following properties:
</p>
<ul>
<li>QuoteChar (")</li>
<li>Delimiter (,)</li>
<li>NameValueSeparator (=)</li>
<li>TextLineBreakStyle (platform specific)</li>
</ul>
</descr>
<seealso/>
</element>

<element name="TTextStrings.Destroy">
<short>Destructor for the class instance.</short>
<descr>
<p>
<var>Destroy</var> is the overridden destructor for the class instance. It 
calls the <var>Clear</var> method to remove the values in the component, and 
free the resources allocated to the internal array of line ranges.
</p>
<p>
Destroy calls the inherited destructor prior to exiting from the method.
</p>
</descr>
<seealso>
<link id="TTextStrings.Clear"/>
<link id="#rtl.classes.TStrings.Destroy">TStrings.Destroy</link>
</seealso>
</element>

<element name="TTextStrings.Clear">
<short>Clears the text and internal line ranges for the component.</short>
<descr>
<p>
<var>Clear</var> is an overridden method which implements the abstract 
virtual method declared in the ancestor. It is used to remove the 
<var>Text</var> and line range information used in the component.
</p>
<p>
Clear calls the <var>ClearArrays</var> method to free 
<var>TTextLineRange</var> resources allocated to the internal dynamic array. 
The internal line counter is reset to <b>0</b> (<b>zero</b>), and the Text 
property is set to an empty string (<b>''</b>).
</p>
<p>
Clear is called when the component is freed, and before reading string values 
in the LCL component streaming mechanism.
</p>
</descr>
<seealso>
<link id="TTextStrings.Text"/>
<link id="TTextStrings.ClearArrays"/>
<link id="TTextStrings.Destroy"/>
<link id="TTextLineRange"/>
<link id="TCustomMemoStrings"/>
<link id="#rtl.classes.TStrings.Clear">TStrings.Clear</link>
</seealso>
</element>

<element name="TTextStrings.SetText">
<short>Sets the value for the Text property from a PChar type.</short>
<descr>
<p>
<var>SetText</var> is an overridden method used to set the value for the 
<var>Text</var> property using the specified <var>PChar</var> value.
</p>
<p>
SetText stores the value in <var>TheText</var> to the member used for the 
Text property. It also resets the internal validity flag for the array of of 
line ranges. This forces the <var>TTextLineRange</var> instances to be 
re-populated during the next read access to <var>Strings</var> or 
<var>Objects</var>.
</p>
<p>
SetText re-implements the method from the ancestor, and does <b>not</b> call 
the inherited method.
</p>
</descr>
<seealso>
<link id="#rtl.classes.TStrings.SetText">TStrings.SetText</link>
</seealso>
</element>
<element name="TTextStrings.SetText.TheText">
<short>New value for the property.</short>
</element>

<element name="TTextStrings.Insert">
<short>Inserts the line of text in S at the specified position.</short>
<descr>
<p>
<var>Insert</var> is an overridden method used to insert the line of text in 
S at the position specified in Index.
</p>
<p>
<var>Index</var> contains the ordinal position in Strings where the line of 
text is inserted. Index must be in the range <b>0..<var>Count</var>-1</b> or 
an <var>EListError</var> exception is raised.
</p>
<p>
<var>S</var> contains the line of text inserted in the method. S can contain 
an end-of-line sequence, but it is not required. The <var>LineEnding</var> 
for the platform is appended to the value in S if it is not already present.
</p>
<p>
Insert calls <var>BuildArrays</var> to populate the array of TTextLineRange 
instances when the internal validity flag is not set. It also ensures that 
the internal array is re-allocated when the number of lines reaches the line 
capacity. Line capacity starts at eight (<b>8</b>), and doubles each time the 
capacity is filled.
</p>
<p>
Memory allocated for the TTextLineRange instances is shifted when Index is 
not the last line of text in the component. The text in S, and the start and 
end positions in Text are stored in the line range information. The range 
information for lines after Index is adjusted to reflect the length of the 
inserted text.
</p>
<p>
Insert re-implements the method defined in the ancestor, and does <b>not</b> 
call the inherited method.
</p>
<p>
Use <var>Add</var> or <var>AddStrings</var> to append one or more lines of 
text to the values in Strings.
</p>
</descr>
<errors>
Raises an EListError exception if Index contains an invalild position in the 
list of string values.
</errors>
<seealso>
<link id="#rtl.classes.TStrings.Insert">TStrings.Insert</link>
</seealso>
</element>
<element name="TTextStrings.Insert.Index">
<short>Ordinal position where the line of text is inserted.</short>
</element>
<element name="TTextStrings.Insert.S">
<short>Value for the line of text inserted in the method.</short>
</element>

<element name="TTextStrings.Delete">
<short>Deletes the line of text at the specified position.</short>
<descr>
<p>
<var>Delete</var> is an overridden method used to delete the line of text at 
the specified position. <var>BuildArrays</var> is called to populate the 
internal array of <var>TTextLineRange</var> instances when the internal 
validity flag is not set.
</p>
<p>
<var>Index</var> contains the ordinal position in <var>Strings</var> for the 
line of text removed in the method. Index must be in the range 
<b>0..<var>Count</var>-1</b> or an <var>EStringListError</var> exception is 
raised.
</p>
<p>
Line range information is used to adjust both <var>Text</var> and the 
internal array of TTextLineRange instance. The line, including end-of-line 
characters, is removed from Text. The line counter is decremented, and the 
array of line ranges is updated. Line ranges after Index are updated to move 
their start and end positions downward by the length of the removed line. The 
memory at the end of the line ranges is zero-filled to prevent corruption.
</p>
</descr>
<errors>
Raises an EStringListError exception when Index is not a valid position in 
the list of string values.
</errors>
<seealso>
<link id="TTextStrings.BuildArrays"/>
<link id="TTextStrings.Text"/>
<link id="TTextLineRange"/>
<link id="EStringListError"/>
<link id="#rtl.classes.TStrings.Count">TStrings.Count</link>
<link id="#rtl.classes.TStrings.Delete">TStrings.Delete</link>
<link id="#rtl.classes.TStrings.Strings">TStrings.Strings</link>
</seealso>
</element>
<element name="TTextStrings.Delete.Index">
<short>
Ordinal position for the value removed from the Strings property.
</short>
</element>

<element name="TTextStrings.Exchange">
<short>Swaps the line values at the specified positions.</short>
<descr>
<p>
<var>Exchange</var> is an overridden method used to swap the line values at 
the positions specified in Index1 and Index2. No actions are performed in the 
method when Index1 and Index2 contain the same value.
</p>
<p>
Values in Index1 and Index2 must be in the range 0..Count-1 or an 
EStringListError exception is raised.
</p>
<p>
<var>BuildArrays</var> is called to populate the internal array of 
<var>TTextLineRange</var> instances when the internal validity flag is not 
set. <var>MakeTextBufferUnique</var> is called to ensure that the reference 
count for the <var>Text</var> member is <b>1</b>.
</p>
<p>
When <var>Index2</var> is the last line of text, a LineEnding sequence is 
added to Text when not already present.
</p>
<p>
GetLineLen is called to get the length for both lines including end-of-line 
characters. Temporary buffers are allocated for both TTextLineRange 
instances, and a memory buffer is allocated using the size for the larger of 
the two lines. The largest line is saved to the memory buffer, and used to 
shift the values in Text as needed. Range information for lines between 
Index1 and Index2 are adjusted to reflect their new start and end positions.
</p>
<p>
Exchange also swaps the values in the Objects property at the specified index 
positions.
</p>
<p>
Exchange re-implements the method defined in the ancestor, and does 
<b>not</b> call the inherited method.
</p>
</descr>
<seealso>
<link id="#rtl.classes.TStrings.Exchange">TStrings.Exchange</link>
</seealso>
</element>
<element name="TTextStrings.Exchange.Index1">
<short>First position for the value exchange.</short>
</element>
<element name="TTextStrings.Exchange.Index2">
<short>Second position for the value exchange.</short>
</element>

<element name="TTextStrings.Move">
<short>
Moves a String value from the current position to the new position.
</short>
<descr/>
<seealso>
<link id="#rtl.classes.TStrings.Move">TStrings.Move</link>
</seealso>
</element>
<element name="TTextStrings.Move.CurIndex">
<short>Current ordinal position for the string.</short>
</element>
<element name="TTextStrings.Move.NewIndex">
<short>New ordinal position for the string.</short>
</element>

<element name="TTextStrings.MakeTextBufferUnique">
<short>Ensures that the reference count for the Text member is 1.</short>
<descr>
<p>
Calls the UniqueString routine from the RTL <file>system</file> unit.
</p>
</descr>
<seealso>
<link id="#rtl.system.UniqueString">UniqueString</link>
</seealso>
</element>

<element name="TTextStrings.BeginUpdate">
<short>Starts an update process for the component.</short>
<descr>
<p>
<var>BeginUpdate</var> is a method used to start an update process for the 
component. It increments an internal update counter used to consolidate 
<var>OnChanging</var> and <var>OnChange</var> event notifications. The 
counter value is used in the <var>Changing</var> and <var>Changed</var> 
methods, and controls when the event notifications are enabled and performed.
</p>
<p>
Use EndUpdate to decrement the internal update counter.
</p>
</descr>
<seealso>
<link id="TTextStrings.OnChanging"/>
<link id="TTextStrings.OnChange"/>
<link id="TTextStrings.Changing"/>
<link id="TTextStrings.Changed"/>
<link id="TTextStrings.EndUpdate"/>
<link id="#rtl.classes.TStrings.BeginUpdate">TStrings.BeginUpdate</link>
</seealso>
</element>

<element name="TTextStrings.EndUpdate">
<short>Finishes an update process for the component.</short>
<descr>
<p>
<var>EndUpdate</var> is a method used to finish an active update process for 
the component.
</p>
<p>
For each call to <var>BeginUpdate</var>, there needs to be a corresponding 
call to EndUpdate. The methods are used as a pair to consolidate 
<var>OnChanging</var> and <var>OnChange</var> event notifications.
</p>
<p>
EndUpdate decrements the internal update counter incremented by calling 
BeginUpdate. When the update counter is a positive non-zero value, the 
<var>Changed</var> method is not called and the <var>OnChange</var> event 
handler is not signalled.
</p>
<p>
An <var>Exception</var> is raised if the internal update counter is &lt;= 0 
when the method is called. When the counter value reaches 0, the Changed 
method is called to signal the OnChange event handler (when assigned).
</p>
<p>
Use BeginUpdate to start an update process by incrementing the value for the 
internal counter.
</p>
</descr>
<errors>
Raises an Exception if the internal update counter is &lt;;= 0 when the 
method is called.
</errors>
<seealso>
<link id="TTextStrings.BeginUpdate"/>
<link id="#rtl.classes.TStrings.EndUpdate">TStrings.EndUpdate</link>
</seealso>
</element>

<element name="TTextStrings.GetText">
<short>Gets the value for the Text property as a PChar type.</short>
<descr/>
<seealso>
<link id="TTextStrings.Text"/>
<link id="#rtl.classes.TStrings.GetText">TStrings.GetText</link>
</seealso>
</element>
<element name="TTextStrings.GetText.Result">
<short>Value for the property as a PChar type.</short>
</element>

<element name="TTextStrings.IndexOf">
<short>Gets the ordinal position for the specified String value.</short>
<descr/>
<seealso>
<link id="#rtl.classes.TStrings.IndexOf">TStrings.IndexOf</link>
</seealso>
</element>
<element name="TTextStrings.IndexOf.Result">
<short>Ordinal position for the requested value.</short>
</element>
<element name="TTextStrings.IndexOf.S">
<short>Value to locate in the method.</short>
</element>

<element name="TTextStrings.Add">
<short>Appends the specified text to the values in Strings.</short>
<descr>
<p>
Calls <var>AddObject</var> to append the value in <var>S</var>. <b>Nil</b> is 
used as the value for the object parameter.
</p>
</descr>
<seealso>
<link id="#rtl.classes.TStrings.Add">TStrings.Add</link>
</seealso>
</element>
<element name="TTextStrings.Add.Result">
<short>Ordinal position in Strings where the value was stored.</short>
</element>
<element name="TTextStrings.Add.S">
<short>String appended to the Strings property.</short>
</element>

<element name="TTextStrings.AddObject">
<short>Adds a String and Object pair to the string list.</short>
<descr>
<p>
Adds a <var>LineEnding</var> if the value in <var>Text</var> does not already 
end with one of the end-of-line characters.
</p>
<p>
Calls <var>BuildArrays</var> when an object instance has been assigned to 
<var>AObject</var>.
</p>
<p>
Recalculates the number of lines in the internal line ranges array. If the 
number of lines is larger than the current capacity for the array, the 
capacity is doubled. The memory for the line range array is re-allocated to 
the new capacity, and the unused portion is zero-filled.
</p>
<p>
The value in AObject is stored in the <var>TTextLineRange</var> instance for 
the new line. The start and end positions, and the text are stored in the 
line range information.
</p>
<p>
The internal line count is incremented prior to exiting from the method.
</p>
</descr>
<seealso/>
</element>
<element name="TTextStrings.AddObject.Result">
<short>Ordinal position where the string and object were stored.</short>
</element>
<element name="TTextStrings.AddObject.S">
<short>String value added to component.</short>
</element>
<element name="TTextStrings.AddObject.AObject">
<short>TObject instance (or Nil) added to the component.</short>
</element>

<element name="TTextStrings.AddStrings">
<short>
Adds the lines of text in TheStrings to the current class instance.
</short>
<descr>
<p>
<var>AddStrings</var> is an overridden method in <var>TTextStrings</var> used 
to add the lines of text in <var>TheStrings</var> to the current class 
instance. No actions are performed in the method when <var>TheStrings</var> 
does not contain any lines of text.
</p>
<p>
Builds (or re-builds) the internal array of line ranges for the class 
instance. Values from the Objects property in TheStrings are also copied in 
the method.
</p>
</descr>
<seealso>
<link id="TTextStrings.AddObject"/>
<link id="#rtl.classes.TStrings.Objects">TStrings.Objects</link>
<link id="#rtl.classes.TStrings.AddStrings">TStrings.AddStrings</link>
</seealso>
</element>
<element name="TTextStrings.AddStrings.TheStrings">
<short>String list with the values added in the method.</short>
</element>

<element name="TTextStrings.LoadFromFile">
<short>
Loads the content in the string list from the specified file name.
</short>
<descr>
<p>
Creates a temporary <var>TFileStream</var> instance for the 
<var>FileName</var> argument. The file handle is opened for reading, and 
shared write access is denied. The inherited <var>LoadFromStream</var> method 
is called to load the values in the string list from the file stream.
</p>
</descr>
<seealso>
<link id="TTextStrings.SaveToFile"/>
<link id="#rtl.classes.TStrings.LoadFromFile">TStrings.LoadFromFile</link>
</seealso>
</element>
<element name="TTextStrings.LoadFromFile.FileName">
<short>File name with the values loaded in the method.</short>
</element>

<element name="TTextStrings.SaveToFile">
<short>
Saves the content in the string list to the specified file name.
</short>
<descr>
<p>
Creates a temporary <var>TFileStream</var> instance for the 
<var>FileName</var> argument. The file is created if it does not already 
exist. The inherited <var>SaveToStream</var> method is called to store 
content in the string list to the file stream.
</p>
</descr>
<seealso>
<link id="TTextStrings.LoadFromFile"/>
<link id="#rtl.classes.TStrings.SaveToFile">TStrings.SaveToFile</link>
</seealso>
</element>
<element name="TTextStrings.SaveToFile.FileName">
<short>File name where the content is stored.</short>
</element>

<element name="TTextStrings.Text">
<short>Contains the textual representation for the values in Strings.</short>
<descr>
<p>
<var>Text</var> is a <var>String</var> property which contains the textual 
representation for the values in the <var>Strings</var> property. 
<var>TTextStrings</var> re-implements the Text property as defined in 
<var>TStrings</var>. The write specifier (<var>SetTextStr</var>) is 
overridden, and forces the internal array of line ranges to be rebuilt during 
the next read access.
</p>
</descr>
<seealso>
<link id="#rtl.classes.TStrings.Text">TStrings.Text</link>
</seealso>
</element>

<element name="TTextStrings.OnChange">
<short>
Event handler signalled when values in Strings or Objects have been changed.
</short>
<descr>
<p>
<var>OnChange</var> is a <var>TNotifyEvent</var> property with the event 
handler signalled when values in the <var>Strings</var> and/or 
<var>Objects</var> properties have been changed.
</p>
<p>
OnChange is signalled from the <var>Changed</var> method, and occurs after 
the property value(s) are stored in the component.
</p>
</descr>
<seealso>
<link id="TTextStrings.Changed"/>
<link id="#rtl.classes.TStrings.Strings">TString.Strings</link>
<link id="#rtl.classes.TStrings.Objects">TStrings.Objects</link>
<link id="#rtl.classes.TNotifyEvent">TNotifyEvent</link>
</seealso>
</element>

<element name="TTextStrings.OnChanging">
<short>
Event handler signalled before properties are updated in the component.
</short>
<descr>
<p>
<var>OnChanging</var> is a <var>TNotifyEvent</var> property with the event 
handler signalled before the <var>Strings</var> or <var>Objects</var> 
properties are updated in the component.
</p>
<p>
OnChanging is signalled from the <var>Changing</var> method when an update 
process in not already active.
</p>
</descr>
<seealso>
<link id="TTextStrings.Changing"/>
<link id="#rtl.classes.TStrings.Strings">TString.Strings</link>
<link id="#rtl.classes.TStrings.Objects">TStrings.Objects</link>
<link id="#rtl.classes.TNotifyEvent">TNotifyEvent</link>
</seealso>
</element>
</module>
<!-- TextStrings -->
</package>
</fpdoc-descriptions>