fpc/docs/classes.xml

<?xml version="1.0" encoding="ISO8859-1"?>
<fpdoc-descriptions>
<package name="fcl">
<module name="classes">
<short>Basic classes for FCL </short>
<descr>
<p>This documentation describes the FPC <file>classes</file> unit. 
The <file>Classes</file> unit contains basic classes for the Free Component
Library (FCL):
</p>
<ul>
<li> a <link id="TList"/> class for maintaining lists of pointers, </li>
<li> <link id='TStringList'/> for lists of strings, </li>
<li> <link id='TCollection'/> to manage collections of objects </li>
<li> <link id="TStream"/> classes to support streaming.</li>
</ul>
<p>
Furthermore it introduces methods for object persistence, and classes
that understand an owner-owned relationship, with automatic memory 
management.
</p>
</descr>

<element name="TRTLCriticalSection">
<short>A class for managing multiple threads</short>
<descr>This class is not yet implemented.</descr>
</element>

<element name="HRSRC">
<short>Type to manage resources</short>
<descr>This type is provided for Delphi compatibilty, it is used for resource
streams.
</descr>
</element>

<element name="PStringItem">
<short>
Pointer to a <link id="TStringItem"/> record.
</short>
</element>

<element name="TStringItem">
<short>
The <var>TStringItem</var> is used to store the string and object items in a 
<link id="TStringList"/> string list instance. It should never be used
directly.
</short>
<seealso>
<link id="TStringList"/>
</seealso>
</element>

<element name="TStringItem.FString">
<short>
Contains the string.
</short>
</element>


<element name="TStringItem.FObject">
<short>
Contains the object, if any.
</short>
</element>

<element name="THandle">
<short>Type to manage streams.</short>
<descr>This type is used as the handle for <link
id='THandleStream'>THandleStream</link> stream descendents</descr>
</element>

<element name="TComponentName">
<short>Special type for component names.</short>
<descr>Names of components are of type <var>TComponentName</var>. By
specifying a different type, the Object inspector can handle this property
differently than a standard string property. 
</descr>
</element>

<element name="IUnknown">
<short><var>IUnknown</var> Interface</short>
<descr>IUknown is not yet implemented since interfaces are not yet supported
by FPC.
</descr>
</element>

<element name="TGUID">
<short>Special type for GUID's.</short>
<descr>FPC doesn't support GUID yet.
</descr>
</element>

<element name="HMODULE">
<short>Special type for handling modules.</short>
<descr>
FPC doesn't support modules yet, so this is a dummy type.
</descr>
</element>

<element name="TPoint">
<short>Special type to handle a fake <link id='TComponent'/>
position</short>
<descr>
<p>This record describes a coordinate. It is used to handle the <link
id='TComponent.Top'>Top</link> and <link id='TComponent.Left'>Left</link>
properties of <link id='TComponent'/>.
</p>
<p>
<var>X</var> represents the X-Coordinate of the point described by the record.
<var>Y</var> represents the Y-Coordinate of the point described by the record.
</p>
</descr>
</element>

<element name="TSmallPoint">
<short>Type to describe point in a small plane.</short>
<descr>Same as <link id='TPoint'/>, only the X and Y ranges are limited to 
2-byte integers instead of 4-byte integers.
</descr>
</element>

<element name="TRect">
<short>Descibes a rectangle</short>
<descr>
<var>TRect</var> describes a rectangle in space with its upper-left (in
(<var>Top</var>,<var>Left></var>)) and lower-right (in (<var>Bottom</var>
,<var>Right</var>)) corners.
</descr>
</element>

<element name="MaxListSize">
<short>
Maximum number of elemens in list.
</short>
<descr>
This constant sets the maximum number of elements in a <link id='TList'/>.
</descr>
</element>

<element name="scShift">
<short>
Indicates Shift key in a keyboard shortcut.
</short>
</element>

<element name="scCtrl">
<short>
indicates CTRL key in a keyboard shortcut.
</short>

</element>
<element name="scAlt">
<short>
Indicates ALT key in a keyboard shortcut.
</short>
</element>

<element name="scNone">
<short>
Indicates no special key is presed in a keyboard shortcut.
</short>
</element>

<element name="soFromBeginning">
<short>
<link id='TStream.Seek'>Seek</link> starts relative to the stream origin.
</short>
</element>

<element name="soFromCurrent">
<short>
<link id='TStream.Seek'>Seek</link> starts relative to the current position in
the stream.
</short>
</element>

<element name="soFromEnd">
<short>
<link id='TStream.Seek'>Seek</link> starts relative to the stream end.
</short>
</element>

<element name="fmCreate">
<short>
<link id='TFileStream.Create'/> creates a new file if needed.
</short>
</element>

<element name="fmOpenRead">
<short>
<link id='TFileStream.Create'/> opens a file with read-only access.
</short>
</element>

<element name="fmOpenWrite">
<short>
<link id='TFileStream.Create'/> opens a file with write-only access.
</short>
</element>

<element name="fmOpenReadWrite">
<short>
<link id='TFileStream.Create'/> opens a file with read-write access.
</short>
</element>

<element name="toEof">
<short>
Token returned by <link id='TParser.Token'/>, meaning the end of the input stream was reached. 
</short>
</element>

<element name="toEof">
<short>
Value returned by <link id='TParser.Token'/> when the end of the input stream was reached. 
</short>
</element>

<element name="toSymbol">
<short>
Value returned by <link id='TParser.Token'/> when a symbol was found in the input stream.
</short>
</element>

<element name="toString">
<short>
Value  returned by <link id='TParser.Token'/> when a string was found in the
input stream.
</short>
</element>

<element name="toInteger">
<short>
Value returned by <link id='TParser.Token'/> when an integer was found in the 
input stream.
</short>
</element>

<element name="toFloat">
<short>
Value returned by <link id='TParser.Token'/> when a floating point value was found in the 
input stream.
</short>
</element>

<element name="FilerSignature">
<short>
Constant that is found at the start of a binary stream containing a 
streamed component.
</short>
</element>

<element name="TAlignment">
<short>Type to specify text alignment in controls that display text.</short>
<descr>
<p>
The <var>TAlignment</var> type is used to specify the alignment of
the text in controls that display a text. 
</p>
</descr>
</element>

<element name="TAlignment.taLeftJustify">
<short>Text is displayed aligned to the left
</short>
</element>

<element name="TAlignment.taCenter">
<short>Text is displayed centered.
</short>
</element>

<element name="TAlignment.taRightJustify">
<short>Text is displayed aligned to the right.
</short>
</element>

<element name="TShiftState">
<short>
Indicates what special keys were pressed in combination with a normal key
</short>
<descr>
<p>
This type is used when describing a shortcut key or when describing what
special keys are pressed on a keyboard when a key event is generated.
</p>
<p>
The set contains the special keys that can be used in combination with a
'normal' key.
</p>
</descr>
</element>

<element name="TShiftState.ssShift">
<short>Either left or right shift key</short>
</element>

<element name="TShiftState.ssAlt">
<short>Either left or right ALT key</short>
</element>

<element name="TShiftState.ssCTRL">
<short>Either left or right CTRL key</short>
</element>

<element name="TShiftState.ssLeft">
<short>Either left or right shift key</short>
</element>

<element name="TShiftState.ssRight">
<short></short>
</element>

<element name="TShiftState.ssMiddle">
<short></short>
</element>

<element name="TShiftState.ssDouble">
<short></short>
</element>

<element name="TShiftState.ssMeta">
<short>The META key</short>
</element>

<element name="TShiftState.ssSuper">
<short></short>
</element>

<element name="TShiftState.ssHyper">
<short></short>
</element>

<element name="TShiftState.ssAltGr">
<short>The AltGr (right Alt) key</short>
</element>

<element name="TShiftState.ssCaps">
<short>The CapsLock key</short>
</element>

<element name="TShiftState.ssNum">
<short>The NumLock key</short>
</element>

<element name="TShiftState.ssScroll">
<short>The ScrollLock key</short>
</element>


<element name="TNotifyEvent">
<short>
Standard event handler type.
</short>
<descr>
Most event handlers are implemented as a property of type
<var>TNotifyEvent</var>. When this is set to a certain method of a class, 
when the event occurs, the method will be called, and the class that generated 
the event will pass itself along as the <var>Sender</var> argument.
</descr>
<seealso>
<link id="THelpEvent"/>
<link id="TGetStrProc"/>
</seealso>
</element>

<element name="THelpEvent">
<short>
Special event for display of online help.
</short>
<descr>
This event is used for display of online help. 
</descr>
<seealso>
<link id="TNotifyEvent"/>
<link id="TGetStrProc"/>
</seealso>
</element>

<element name="TGetStrProc">
<short>
Event for retrieving string values.
</short>
<descr> 
This event is used as a callback to retrieve string values. It is used,
among other things, to pass along string properties in property editors.
</descr> 
<seealso>
<link id="THelpEvent"/>
<link id="TNotifyEvent"/>
</seealso>
</element>

<element name="EStreamError">
<short>
Exception raised when an error occurs during read or write operations on a
stream.
</short>
<descr>
<p>
An <var>EStreamError</var> is raised when an error occurs during reading
from or writng to a stream: Possible causes are 
</p>
<ol>
<li>Not enough data is available in the stream.</li>
<li>Trying to seek beyond the beginning or end of the stream.</li>
<li>Trying to set the capacity of a memory stream and no memory is
available.</li>
<li>Trying to write to a resource stream.</li>
</ol>
</descr>
<seealso>
<link id="EFCreateError"/>
</seealso>
</element>


<element name="EFCreateError">
<short>
Exception raised when an error occurred during creation of a <link id="TFileStream"/>
stream.
</short>
<descr>
When the operating system reports an error during creation of a new file in 
the <link id="TFileStream.Create">Filestream Constructor</link>, a
<var>EFCreateError</var> is raised.
</descr>
<seealso>
<link id="EStreamError"/>
<link id="EFOpenError"/>
</seealso>
</element>

<element name="EFOpenError">
<short>
Exception raised when an error occurred during creation of a <link id="TFileStream"/>
</short>
<descr>
When the operating system reports an error during the opening of a file in 
the <link id="TFileStream.Create">Filestream Constructor</link>, a
<var>EFOpenError</var> is raised.
</descr>
<seealso>
<link id="EStreamError"/>
<link id="EFCreateError"/>
</seealso>
</element>


<element name="EFilerError">
<short>
Exception raised by the component streaming system if an error occurs.
</short>
<descr>
This class serves as an ancestor class for exceptions that are raised 
when an error occurs during component streaming.

A <var>EFilerError</var> exception is raised when a class is registered
twice.
</descr>
<seealso>
<link id="EStreamError"/>
<link id="EReadError"/>
</seealso>
</element>


<element name="EReadError">
<short>
Exception raised if an error occurs while reading from a stream.
</short>
<descr>
<p>If an error occurs when reading from a stream, a <var>EReadError</var>
exception is raised. Possible causes for this are:</p>
<ol>
<li> Not enough data is available when reading from a stream</li>
<li> The stream containing a component's data contains invalid data.
this will occurr only when reading a component from a stream.</li>
</ol>
</descr>
<seealso>
<link id="EFilerError"/>
<link id="EWriteError"/>
</seealso>
</element>

<element name="EWriteError">
<short>
Exception raised when an error occurs during writing to a stream.
</short>
<descr>
<p>If an error occurs when writing to a stream, a <var>EWriteError</var>
exception is raised. Possible causes for this are:
</p>
<ol>
<li> The stream doesn't allow writing.</li>
<li> An error occurred when writing a property to a stream.</li>
</ol>
</descr>
<seealso>
<link id="EFilerError"/>
<link id="EReadError"/>
</seealso>
</element>

<element name="EClassNotFound">
<short>
Exception raised when an unknown class is referenced in a streamed
component.
</short>
<descr>
When the streaming system needs to create a component, it looks for the
class pointer (VMT) in the list of registered classes by its name. If this
name is not found, then an <var>EClassNotFound</var> is raised.
</descr>
<seealso>
<link id="EFilerError"/>
</seealso>
</element>


<element name="EMethodNotFound">
<short>
This exception is no longer used.
</short>
<descr>
This exception is no longer used in the streaming system. This error is
replaced by a <link id="EReadError"/>.
</descr>
<seealso>
<link id="EFilerError"/>
<link id="EReadError"/>
</seealso>
</element>


<element name="EInvalidImage">
<short>
Exception raised when the resource header needed for streaming of a
component is invalid.
</short>
<descr>
This exception is not used by Free Pascal but is provided for Delphi
compatibility.
</descr>
</element>


<element name="EResNotFound">
<short>
Exception raised when a resource, needed to initialize a component, is not found.
</short>
<descr>
This exception is not used by Free Pascal but is provided for Delphi
compatibility.
</descr>
</element>


<element name="EListError">
<short>
Exception raised when an error occurs in lists handling.
</short>
<descr>
<p>
If an error occurs in one of the <link id='TList'/> or <link id='TStrings'/> 
methods, then a <var>EListError</var> exception is raised. This can occur in
one of the following cases:
</p>
<ol>
<li>There is not enough memory to expand the list.</li>
<li>The list tried to grow beyond its maximal capacity.</li>
<li>An attempt was made to reduce the capacity of the list below the
current element count.</li>
<li>An attempt was made to set the list count to a negative value.</li>
<li>A non-existent element of the list was referenced. (i.e. the list index
was out of bounds)</li>
<li>An attempt was made to move an item to a position outside the list's
bounds.</li>
</ol>
</descr>
<seealso>
<link id="TList"/>,
<link id="TStrings"/>
</seealso>
</element>


<element name="EBitsError">
<short>
Exception raised when an error occurs in a method of <link id="TBits"/>.
</short>
<descr>
When an index of a bit in a <link id="TBits"/> is out of the valid range 
(<var>0</var> to <var>Count-1</var>) then a <var>EBitsError</var> exception 
is raised.
</descr>
</element>


<element name="EStringListError">
<short>
Exception raised when an error occurs in a method of <link id="TStrings"/>.
</short>
<descr>
<p>
When an error occurs in one of the methods of <link id="TStrings"/> then
an <var>EStringListError</var> is raised. This can have one of the following
causes:
</p>
<ol>
<li>There is not enough memory to expand the list.</li>
<li>The list tried to grow beyond its maximal capacity.</li>
<li>A non-existent element of the list was referenced. (i.e. the list index
was out of bounds)</li>
<li>An attempt was made to add a duplicate entry to a <link
id="TStringList"/> when <link id="TStringList.AllowDuplicates"/> is
<var>False</var>.</li>
</ol>
</descr>
<seealso>
<link id="TStrings"/>
<link id="TStringList"/>
</seealso>
</element>


<element name="EComponentError">
<short>
Exception raised when an error occurs in the component registration
routines.
</short>
<descr>
<p>
When an error occurs during the registration of a component, or when naming
a component, then a <var>EComponentError</var> is raised. Possible causes
are:
</p>
<ol>
<li>An name with an illegal character was assigned to a component.</li>
<li>A component with the same name and owner already exists.</li>
<li>The component registration system isn't set up properly.</li>
</ol>
</descr>
<seealso>
<link id="TComponent"/>
<link id="TComponent.Name"/>
</seealso>
</element>


<element name="EParserError">
<short>
Exception raised when an error occurs during the parsing of streams.
</short>
<descr>
When an error occurs during the parsing of a stream, an <var>EParserError</var>
is raised. Usually this indicates that an invalid token was found on the
input stream, or the token read from the stream wasn't the expected token.
</descr>
<seealso>
<link id="TParser"/>
</seealso>
</element>


<element name="EOutOfResources">
<short>
Exception raised when the system is out of resources.
</short>
<descr>
This exception is not used in Free Pascal, it is defined for Delphi
compatibiliy purposes only.
</descr>
</element>


<element name="EInvalidOperation">
<short>
Exception raised when an invalid operation is performed. Obsolete.
</short>
<descr>
This exception is not used in Free Pascal, it is defined for Delphi
compatibiliy purposes only.
</descr>
</element>

<!--
 **********************************************************************
 TList
 **********************************************************************
-->

<element name="TList">
<short>Class to manage collections of pointers.</short>
<descr>
<p>
<var>TList</var> is a class that can be used to manage collections of
pointers. It introduces methods and properties to store the pointers, search
in the list of pointers, sort them. It manages its memory by itself, no
intervention for that is needed.
</p>
<p>
To manage collections of strings, it is better to use a <link
id="TStrings"/> descendent such as <link id="TStringList"/>. To manage
general objects, a <link id="TCollection"/> class exists, from which a
descendent can be made to manage collections of various kinds.
</p>
</descr>
<seealso>
<link id="TStrings"/>
<link id="TCollection"/>
</seealso>
</element>

<!-- To be documented later on maybe ?

    function Get(Index: Integer): Pointer;
<element name="">
<short>
</short>
<descr>
</descr>
</element>


    procedure Grow; virtual;
<element name="">
<short>
</short>
<descr>
</descr>
</element>


    procedure Put(Index: Integer; Item: Pointer);
<element name="">
<short>
</short>
<descr>
</descr>
</element>


    procedure SetCapacity(NewCapacity: Integer);
<element name="">
<short>
</short>
<descr>
</descr>
</element>


    procedure SetCount(NewCount: Integer);
<element name="">
<short>
</short>
<descr>
</descr>
</element>

-->

<element name="TList.Destroy">
<short>
Destroys the list and releases the memory used to store the list elements.
</short>
<descr>
<var>Destroy</var> destroys the list and releases the memory used to store 
the list elements. The elements themselves are in no way touched, i.e. any
meomory they point to must be explicitly released before calling the
destructor.
</descr>
</element>


<element name="TList.Add">
<short>
Adds a new pointer to the list.
</short>
<descr>
<p>
<var>Add</var> adds a new pointer to the list after the last pointer (i.e.
at position <var>Count</var>, thus increasing the item count with 1. 
If the list is at full capacity, the capacity of the list is expanded, 
using the <link id="TList.Grow">Grow</link> method.
</p>
<p>
To insert a pointer at a certain position in the list, use the <link
id="TList.Insert">Insert</link> method instead.
</p>
</descr>
<seealso>
<link id="TList.Delete">Delete</link>
<link id="TList.Grow">Grow</link>
<link id="TList.Insert">Insert</link>
</seealso>
</element>



<element name="TList.Clear">
<short>
Clears the pointer list.
</short>
<descr>
<var>Clear</var> removes all pointers from the list, and sets the capacity to
0, thus freeing any memory allocated to maintain the list.
</descr>
<seealso>
<link id="TList.Destroy">Destroy</link>
</seealso>
</element>


<!--    procedure Delete(Index: Integer); -->
<element name="TList.Delete">
<short>
Removes a pointer from the list.
</short>
<descr>
<p><var>Delete</var> removes the pointer at position <var>Index</var> from the
list, shifting all following pointers one position up (or to the left).
</p>
<p>
The memory the pointer is pointing to is <i>not</i> deallocated. 
</p>
</descr>
</element>


<element name="TList.Error">
<short>
Raises an <link id="EListError"/> exception.
</short>
<descr>
<var>Error</var> raises an <link id="EListError"/> exception, with a message
formatted with <var>Msg</var> and <var>Data</var>.
</descr>
</element>


<!--    procedure Exchange(Index1, Index2: Integer); -->
<element name="TList.Exchange">
<short>
Exchanges two pointers in the list.
</short>
<descr>
<var>Exchange</var> exchanges the pointers at positions <var>Index1</var>
and <var>Index2</var>. Both pointers must be withing the current range of
the list, or an <link id="EListError"/> exception will be raised.
</descr>
</element>


<element name="TList.Expand">
<short>
Increases the capacity of the list if needed.
</short>
<descr>
<p>
<var>Expand</var> increases the capacity of the list if the current element
count matches the current list capacity.
</p>
<p>
The capacity is increased according to the following algorithm:
</p>
<ol>
<li>If the capacity is less than 3, the capacity is increased with 4.</li>
<li>If the capacity is larger than 3 and less than 8, the capacity is increased with 8.</li>
<li>If the capacity is larger than 8, the capacity is increased with 16.</li>
</ol>
<p>
The return value is <var>Self</var>.
</p>
</descr>
<seealso>
<link id="TList.Capacity">Capacity</link>
<!-- <link id="Tlist.SetCapacity"> -->
</seealso>
</element>


<element name="TList.First">
<short>
Returns the first non-nil pointer in the list.
</short>
<descr>
<p>
<var>First</var> returns the value of the first non-nil pointer in the
list.
</p>
<p> If there are no pointers in the list or all pointers equal
<var>Nil</var>, then <var>Nil</var> is returned.
</p>
</descr>
<seealso>
<link id="TList.Last">Last</link>
</seealso>
</element>


<!--    function IndexOf(Item: Pointer): Integer; -->
<element name="TList.IndexOf">
<short>
Returns the index of a given pointer.
</short>
<descr>
<p>
<var>IndexOf</var> searches for the pointer <var>Item</var> in the list
of pointers, and returns the index of the pointer, if found. 
</p>
<p>
If no pointer with the value <var>Item</var> was found, -1 is returned.
</p>
</descr>
</element>


<element name="TList.Insert">
<short>
Inserts a new pointer in the list at a given position.
</short>
<descr>
<p>
<var>Insert</var> inserts pointer <var>Item</var> at position
<var>Index</var> in the list. All pointers starting from <var>Index</var>
are shifted to the right.
</p>
<p>
If <var>Index</var> is not a valid position, then a <link id="EListError"/>
exception is raised.
</p>
</descr>
<seealso>
<link id="TList.Add">Add</link>
<link id="Tlist.Delete">Delete</link>
</seealso>
</element>

<element name="TList.Insert.Item">
<short> Pointer to be inserted.</short>
</element>

<element name="TList.Insert.Index">
<short> Position where to insert</short>
</element>

<!--    function Last: Pointer; -->
<element name="TList.Last">
<short>
Returns the last non-nil pointer in the list.
</short>
<descr>
<p>
<var>Last</var> returns the value of the last non-nil pointer in the
list.
</p>
<p> If there are no pointers in the list or all pointers equal
<var>Nil</var>, then <var>Nil</var> is returned.
</p>
</descr>
<seealso>
<link id="TList.First">First</link>
</seealso>
</element>

<!--    procedure Move(CurIndex, NewIndex: Integer); -->
<element name="TList.Move">
<short>
Moves a pointer from one position in the list to another.
</short>
<descr>
<p>
<var>Move</var> moves the pointer at position <var>CurIndex</var>
to position <var>NewIndex</var>. This is done by storing the value 
at position <var>CurIndex</var>, deleting the pointer at position
<var>CurIndex</var>, and reinserting the value at position
<var>NewIndex</var>
</p>
<p>
If <var>CurIndex</var> or <var>Newindex</var> are not inside the valid
range of indices, an <link id="EListError"/> exception is raised.
</p>
</descr>
<seealso>
<link id="TList.Exchange">Exchange</link>
</seealso>
</element>

<!--    function Remove(Item: Pointer): Integer; -->
<element name="TList.Remove">
<short>
Removes a value from the list.
</short>
<descr>
<var>Remove</var> searches <var>Item</var> in the list, and, if it finds it,
deletes the item from the list. Only the first occurrence of <var>Item</var>
is removed.
</descr>
<seealso>
<link id="TList.Delete">Delete</link>
<link id="TList.IndexOf">IndexOf</link>
<link id="Tlist.Insert">Insert</link>
</seealso>
</element>

<!--    procedure Pack; -->
<element name="TList.Pack">
<short>
Removes <var>Nil</var> pointers from the list and frees unused memory.
</short>
<descr>
<var>Pack</var> removes all <var>nil</var> pointers from the list. 
The capacity of the list is then set to the number of pointers in the list.

This method can be used to free unused memory if the list has grown to
very large sizes and has a lot of unneeded nil pointers in it.
</descr>
<seealso>
<link id="TList.Clear"/>
</seealso>
</element>


<!--    procedure Sort(Compare: TListSortCompare); -->
<element name="TList.Sort">
<short>
Sorts the pointers in the list.
</short>
<descr>
<p>
<var>Sort></var> sorts the pointers in the list. Two pointers are compared
by passing them to the <var>Compare</var> function. The result of this
function determines how the pointers will be sorted:
</p>
<ul>
<li> If the result of this function is negative, the first pointer is 
assumed to be 'less' than the second and will be moved before the second 
in the list.</li>
<li> If the function result is positive, the first pointer is assumed to
be 'greater than' the second and will be moved after the second in the
list.</li>
<li> if the function result is zero, the pointers are assumed to be 'equal'
and no moving will take place. </li>
</ul>
<p>
The sort is done using a quicksort algorithm.
</p>
</descr>
</element>

<!--    property Capacity: Integer read FCapacity write SetCapacity; -->
<element name="TList.Capacity">
<short>
Current capacity (i.e. number of pointers that can be stored) of the list.
</short>
<descr>
<p><var>Capacity</var> contains the number of pointers the list can store
before it starts to grow. 
</p>
<p>
If a new pointer is added to the list using <link id="TList.Add">add</link>
or <link id="TList.Insert">insert</link>, and there is not enough memory to
store the new pointer, then the list will try to allocate more memory to
store the new pointer. Since this is a time consuming operation, it is
important that this operation be performed as little as possible. If
it is known how many pointers there will be before filling the list, it is
a good idea to set the capacity first before filling. This ensures that the
list doesn't need to grow, and will speed up filling the list.
</p>
</descr>
<seealso>
<link id="TList.SetCapacity">SetCapacity</link>
<link id="TList.Count">Count</link>
</seealso>
</element>

<!--    property Count: Integer read FCount write SetCount; -->
<element name="Tlist.Count">
<short>
Current number of pointers in the list.
</short>
<descr>
<var>Count</var> is the current number of (possibly <var>Nil</var>) pointers
in the list. Since the list is zero-based, the index of the largest pointer
is <var>Count-1</var>.
</descr>
<link id="TList.Capacity">Capacity</link>
</element>

<!--  property Items[Index: Integer]: Pointer read Get write Put; default; -->
<element name="TList.Items">
<short>
Probides access to the pointers in the list. 
</short>
<descr>
<p><var>Items</var> is used to access the pointers in the list. It is the
default property of the <var>TList</var> class, so it can be omitted. 
</p>
<p>
The list is zero-based, so Index must be in the range <var>0</var> to 
<var>Count-1</var>.
</p>
</descr>
</element>

<!--  property List: PPointerList read FList; -->

<element name="TList.List">
<short>
Memory array where pointers are stored.
</short>
<descr>
<var>List</var> points to the memory space where the pointers are stored.
This can be used to quickly copy the list of pinters to another location.
</descr>
</element>

<!--
 **********************************************************************
 ThreadList
 **********************************************************************
-->

<element name="TThreadList">  <!-- Class -->
<short>Thread-safe list object (not yet implemented).</short>
<descr>This class is not yet implemented in Free Pascal.</descr>
<errors></errors>
<seealso></seealso>
</element>

<element name="TThreadList.Create">  <!-- Constructor -->
<short>Creates a new thread-safe list.</short>
<descr>This class is not yet implemented in Free Pascal.</descr>
<errors></errors>
<seealso></seealso>
</element>

<element name="TThreadList.Destroy">  <!-- Destructor -->
<short>Destroys the list instance.</short>
<descr>This class is not yet implemented in Free Pascal.</descr>
<errors></errors>
<seealso></seealso>
</element>

<element name="TThreadList.Add">  <!-- Procedure -->
<short>Adds an element to the list.</short>
<descr>This class is not yet implemented in Free Pascal.</descr>
<errors></errors>
<seealso></seealso>
</element>

<element name="TThreadList.Clear">  <!-- Procedure -->
<short>Removes all emements from the list.</short>
<descr>This class is not yet implemented in Free Pascal.</descr>
<errors></errors>
<seealso></seealso>
</element>

<element name="TThreadList.LockList">  <!-- Function -->
<short>Locks the list for exclusive access.</short>
<descr>This class is not yet implemented in Free Pascal.</descr>
<errors></errors>
<seealso></seealso>
</element>

<element name="TThreadList.Remove">  <!-- Procedure -->
<short>Removes an item from the list.</short>
<descr>This class is not yet implemented in Free Pascal.</descr>
<errors></errors>
<seealso></seealso>
</element>

<element name="TThreadList.UnlockList">  <!-- Procedure -->
<short>Unlocks the list after it was locked.</short>
<descr>This class is not yet implemented in Free Pascal.</descr>
<errors></errors>
<seealso></seealso>
</element>

<!--
 **********************************************************************
 TBits helpers
 **********************************************************************
-->

<element name="BITSHIFT">  <!-- Constant -->
<short>Used to calculate the size of a bits array</short>
<seealso>
<link id="TBits"/>
<link id="TBits.Size"/>
</seealso>
</element>

<element name="MASK">  <!-- Constant -->
<short>Bitmask with all bits on.</short>
<seealso>
<link id="TBits"/>
</seealso>
</element>

<element name="MaxBitRec">  <!-- Constant -->
<short>Maximum number of bit records in TBits.</short>
<seealso>
<link id="TBits"/>
</seealso>
</element>

<element name="MaxBitFlags">  <!-- Constant -->
<short>Maximum number of bits in TBits collection.</short>
<seealso>
<link id="TBits"/>
</seealso>      
</element>

<element name="TBitArray">  <!-- Array type -->
<short>Array to store bits.</short>
<seealso>
<link id="TBits"/>
</seealso>
</element>

<!--
 **********************************************************************
 TBis
 **********************************************************************
-->


<element name="TBits">  <!-- Class -->
<short>Class to store collections of bits (binary values that can be 0 or 1)</short>
<descr>
<p><var>TBits</var> can be used to store collections of bits in an indexed
array. This is especially useful for storing collections of booleans:
Normally the size of a boolean is the size of the smallest enumerated type,
i.e. 1 byte. Since a bit can take 2 values it can be used to store a boolean
as well. Since TBits can store 8 bits in a byte, it takes 8 times less space
to store an array of booleans in a TBits class then it would take to stoe
them in a conventional array.
</p>
<p><var>TBits</var> introduces methods to store and retrieve bit values,
apply masks, and search for bits. 
</p>
</descr>
</element>

<element name="TBits.Create">  <!-- Constructor -->
<short>Creates a new bits collection.</short>
<descr>
<p>
<var>Create</var> creates a new bit collection with initial size <var>TheSize</var>.
The size of the collection can be changed later on. 
</p>
<p>All bits are initially set to zero.</p>
</descr>
<seealso>
<link id="TBits.Destroy">Destroy</link>
</seealso>
</element>

<element name="TBits.Destroy">  <!-- Destructor -->
<short>Destroys a bit collection</short>
<descr>
<p>
<var>Destroy</var> destroys a previously created bit collection and 
releases all memory used to store the bit collection.
</p>
<p>
<var>Destroy</var> should never be called directly, <var>Free</var>
should be used instead.
</p>
</descr>
<errors>
None.
</errors>
<seealso>
<link id="TBits.Create">Create</link>
</seealso>
</element>

<element name="TBits.getFSize">  <!-- Function -->
<short>Returns the number of records used to store the bits.</short>
<descr>
<var>GetFSize</var> returns the number of records used to store the current
number of bits.
</descr>
<errors>
None.
</errors>
<seealso>
<link id="TBits.Size">Size</link>
</seealso>
</element>

<element name="TBits.seton">  <!-- Procedure -->
<short>Turn a  particular bit on.</short>
<descr>
<var>SetOn</var> turns on the bit at position <var>bit</var>, i.e. sets it
to 1. 
If <var>bit</var> is at a position bigger than the current size, the collection
is expanded to the required size using <link id="TBits.grow">Grow</link>.
</descr>
<errors>
If <var>bit</var> is larger than the maximum allowed bits array size or
is negative, an <link id="EBitsError"/> exception is raised.
</errors>
<seealso>
<link id="TBits.Bits">Bits</link>
<link id="TBits.clear">Clear</link>
</seealso>
</element>

<element name="TBits.clear">  <!-- Procedure -->
<short>Clears a particular bit.</short>
<descr>
<var>Clear</var> clears the bit at position <var>bit</var>. If the array
If <var>bit</var> is at a position bigger than the current size, the collection
is expanded to the required size using <link id="TBits.grow">Grow</link>.
</descr>
<errors>
If <var>bit</var> is larger than the maximum allowed bits array size or
is negative, an <link id="EBitsError"/> exception is raised.
</errors>
<seealso>
<link id="TBits.Bits">Bits</link>
<link id="TBits.clear">seton</link>
</seealso>
</element>

<element name="TBits.clearall">  <!-- Procedure -->
<short>Clears all bits in the array.</short>
<descr>
<var>ClearAll</var> clears all bits in the array, i.e. sets them to zero. <var>
ClearAll</var> works faster than clearing all individual bits, since it 
uses the packed nature of the bits.
</descr>
<errors>
None.
</errors>
<seealso>
<link id="TBits.Bits">Bits</link>
<link id="TBits.clear">clear</link>
</seealso>
</element>

<element name="TBits.andbits">  <!-- Procedure -->
<short>Performs an <var>and</var> operation on the bits.</short>
<descr>
<var>andbits</var> performs an <var>and</var> operation on the bits in 
the array with the bits of array <var>BitSet</var>. If <var>BitSet</var>
contains less bits than the current array, then all bits which have no
counterpart in <var>BitSet</var> are cleared.
</descr>
<errors>
None.
</errors>
<seealso>
<link id="TBits.clearall">ClearAll</link>
<link id="TBits.orbits">OrBits</link>
<link id="TBits.xorbits">XOrBits</link>
<link id="TBits.notbits">NotBits</link>
</seealso>
</element>

<element name="TBits.orbits">  <!-- Procedure -->
<short>Performs an <var>or</var> operation on the bits.</short>
<descr>
<p>
<var>andbits</var> performs an <var>or</var> operation on the bits in 
the array with the bits of array <var>BitSet</var>. 
</p>
<p>
If <var>BitSet</var>
contains less bits than the current array, then all bits which have no
counterpart in <var>BitSet</var> are left untouched.
</p>
<p> 
If the current array contains less bits than <var>BitSet</var> then it is
grown to the size of <var>BitSet</var> before the <var>or</var> operation is
performed.
</p>
</descr>
<errors>
None.
</errors>
<seealso>
<link id="TBits.clearall">ClearAll</link>
<link id="TBits.andbits">andBits</link>
<link id="TBits.xorbits">XOrBits</link>
<link id="TBits.notbits">NotBits</link>
</seealso>
</element>

<element name="TBits.xorbits">  <!-- Procedure -->
<short>Performs a <var>xor</var> operation on the bits.</short>
<descr>
<p><var>XorBits</var> performs a <var>xor</var> operation on the bits in 
the array with the bits of array <var>BitSet</var>. 
</p>
<p>If <var>BitSet</var>
contains less bits than the current array, then all bits which have no
counterpart in <var>BitSet</var> are left untouched.
</p>
<p> 
If the current array contains less bits than <var>BitSet</var> then it is
grown to the size of <var>BitSet</var> before the <var>xor</var> operation is
performed.
</p>
</descr>
<errors>
None.
</errors>
<seealso>
<link id="TBits.clearall">ClearAll</link>
<link id="TBits.andbits">andBits</link>
<link id="TBits.orbits">OrBits</link>
<link id="TBits.notbits">NotBits</link>
</seealso>
</element>

<element name="TBits.notbits">  <!-- Procedure -->
<short>Performs a <var>not</var> operation on the bits.</short>
<descr>
<p><var>NotBits</var> performs a <var>not</var> operation on the bits in 
the array with the bits of array <var>Bitset</var>. 
</p>
<p>If <var>BitSet</var>
contains less bits than the current array, then all bits which have no
counterpart in <var>BitSet</var> are left untouched.
</p>
</descr>
<errors>
None.
</errors>
<seealso>
<link id="TBits.clearall">ClearAll</link>
<link id="TBits.andbits">andBits</link>
<link id="TBits.orbits">OrBits</link>
<link id="TBits.xorbits">XOrBits</link>
</seealso>
</element>

<element name="TBits.get">  <!-- Function -->
<short>Retrieve the value of a particular bit</short>
<descr>
<var>Get</var> returns <var>True</var> if the bit at position <var>bit</var>
is set, or <var>False</var> if it is not set.
</descr>
<errors>
If <var>bit</var> is not a valid bit index then an <link id="EBitsError"/>
exception is raised.
</errors>
<seealso>
<link id="TBits.Bits">Bits</link>
<link id="TBits.FindFirstBit">FindFirstBit</link>
<link id="TBits.seton">seton</link>
</seealso>
</element>

<element name="TBits.grow">  <!-- Procedure -->
<short>Expands the bits array to the requested size.</short>
<descr>
<var>Grow</var> expands the bit array so it can at least contain
<var>nbit</var> bits. If <var>nbit</var> is less than the current size,
nothing happens.
</descr>
<errors>
If there is not enough memory to complete the operation, then an
<link id="EBitsError"/>is raised.
</errors>
<seealso>
<link id="TBits.Size">Size</link>
</seealso>
</element>

<element name="TBits.equals">  <!-- Function -->
<short>Determines whether the bits of 2 arrays are equal.</short>
<descr>
<p><var>equals</var> returns <var>True</var> if all the bits in <var>BitSet</var>
are the same as the ones in the current BitSet; if not, <var>False</var> is
returned.
</p>
<p> 
If the sizes of the two BitSets are different, the arrays are still reported
equal when all the bits in the larger set, which are not present in the smaller 
set, are zero. 
</p>
</descr>
<errors>
None.
</errors>
<seealso>
<link id="TBits.clearall">ClearAll</link>
<link id="TBits.andbits">andBits</link>
<link id="TBits.orbits">OrBits</link>
<link id="TBits.xorbits">XOrBits</link>
</seealso>
</element>

<element name="TBits.SetIndex">  <!-- Procedure -->
<short>Sets the start position for <link
id="TBits.FindNextBit">FindNextBit</link> and <link
id="TBits.FindPrevBit">FindPrevBit</link></short>
<descr>
<p>
<var>SetIndex</var> sets the search start position for<link
id="TBits.FindNextBit">FindNextBit</link> and 
<link id="TBits.FindPrevBit">FindPrevBit</link> to <var>Index</var>.
This means that these calls will start searching from position
<var>Index</var>.
</p>
<p>This mechanism provides an alternative to <link
id="TBits.FindFirstBit">FindFirstBit</link> which can also be used to
position for the <var>FindNextBit</var> and <var>FindPrevBit</var> calls.
</p>
</descr>
<errors>
None.
</errors>
<seealso>
<link id="TBits.FindNextBit">FindNextBit</link>
<link id="TBits.FindPrevBit">FindPrevBit</link>
<link id="TBits.FindFirstBit">FindFirstBit</link>
<link id="TBits.OpenBit">OpenBit</link>
</seealso>
</element>

<element name="TBits.FindFirstBit">  <!-- Function -->
<short>Find first bit with a particular value</short>
<descr>
<p>
<var>FindFirstBit</var> searches for the first bit with value
<var>State</var>. It returns the position of this bit, or <var>-1</var> if
no such bit was found.
</p>
<p>The search starts at position 0 in the array. If the first search
returned a positive result, the found position is saved, and the
<link id="TBits.FindNextBit">FindNextBit</link> and <link
id="TBits.FindPrevBit">FindPrevBit</link> will use this position to resume the
search. To start a search from a certain position, the start position can be
set with the <link id="TBits.SetIndex">SetIndex</link> instead.
</p>
</descr>
<errors>
None.
</errors>
<seealso>
<link id="TBits.FindNextBit">FindNextBit</link>
<link id="TBits.FindPrevBit">FindPrevBit</link>
<link id="TBits.OpenBit">OpenBit</link>
<link id="TBits.SetIndex">SetIndex</link>
</seealso>
</element>

<element name="TBits.FindNextBit">  <!-- Function -->
<short>Searches the next bit with a particular value.</short>
<descr>
<p>
<var>FindNextBit</var> resumes a previously started search. It searches for
the next bit with the value specified in the <link
id="TBits.FindFirstBit">FindFirstBit</link>. The search is done towards the
end of the array and starts at the position last reported by one of the 
<var>Find</var> calls or at the position set with <link id="TBits.SetIndex">
SetIndex</link>.
</p>
<p>
If another bit with the same value is found, its position
is returned. If no more bits with the same value are present in the array,
<var>-1</var> is returned.
</p>
</descr>
<errors>
None.
</errors>
<seealso>
<link id="TBits.FindFirstBit">FindFirstBit</link>
<link id="TBits.FindPrevBit">FindPrevBit</link>
<link id="TBits.OpenBit">OpenBit</link>
<link id="TBits.SetIndex">SetIndex</link>
</seealso>
</element>

<element name="TBits.FindPrevBit">  <!-- Function -->
<short>Searches the previous bit with a particular value.</short>
<descr>
<p>
<var>FindPrevBit</var> resumes a previously started search. It searches for
the previous bit with the value specified in the <link
id="TBits.FindFirstBit">FindFirstBit</link>. The search is done towards the
beginning of the array and starts at the position last reported by one of the 
<var>Find</var> calls or at the position set with <link id="TBits.SetIndex">
SetIndex</link>.
</p>
<p>
If another bit with the same value is found, its position
is returned. If no more bits with the same value are present in the array,
<var>-1</var> is returned.
</p>
</descr>
<errors>
None.
</errors>
<seealso>
<link id="TBits.FindFirstBit">FindFirstBit</link>
<link id="TBits.FindNextBit">FindNextBit</link>
<link id="TBits.OpenBit">OpenBit</link>
<link id="TBits.SetIndex">SetIndex</link>
</seealso>
</element>

<element name="TBits.OpenBit">  <!-- Function -->
<short>Returns the position of the first bit that is set to <var>False</var>.</short>
<descr>
<var>OpenBit</var> returns the position of the first bit whose value is
<var>0</var> (<var>False</var>), or <var>-1</var> if no open bit was found. 
This call is equivalent to
<var>FindFirstBit(False)</var>, except that it doesn't set the position for
the next searches.
</descr>
<errors>
None.
</errors>
<seealso>
<link id="TBits.FindFirstBit">FindNextBit</link>
<link id="TBits.FindPrevBit">FindPrevBit</link>
<link id="TBits.FindFirstBit">FindFirstBit</link>
<link id="TBits.SetIndex">SetIndex</link>
</seealso>
</element>

<element name="TBits.Bits">  <!-- Property -->
<short>Access to all bits in the array.</short>
<descr>
<var>Bits</var> allows indexed access to all of the bits in the array. It
gives <var>True</var> if the bit is <var>1</var>, <var>False</var>
otherwise; Assigning to this property will set, respectively clear the bit.
</descr>
<errors>
If an index is specified which is out of the allowed range then an <link
id="EBitsError"/> exception is raised.
</errors>
<seealso>
<link id="TBits.Size">Size</link>
</seealso>
</element>

<element name="TBits.Size">  <!-- Property -->
<short>Current size of the array of bits.</short>
<descr>
<var>Size</var> is the current size of the bit array. Setting this property
will adjust the size; this is equivalent to calling <var>Grow(Value-1)</var>
</descr>
<errors>
If an invalid size (negative or too large) is specified, a <link
id="EBitsError"/> exception is raised.
</errors>
<seealso>
<link id="TBits.Bits">Bits</link>
</seealso>
</element>

<!--
  *********************************************************************
  TPersistent
  *********************************************************************
-->

<element name="TPersistent">  <!-- Class -->
<short>Base class for streaming system and persistent properties.</short>
<descr>
<p><var>TPersistent</var> is the basic class for the streaming system. Since it
is compiled in the <var>{$M+}</var> state, the compiler generates  RTTI
(Run-Time Type Information) for it and all classes that descend from it.
This information can be used to stream all properties of classes.
</p>
<p>
It also introduces functionality to assign the contents of 2 classes to 
each other.
</p>
</descr>
<seealso>
<link id="TComponent"/>
</seealso>
</element>

<element name="TPersistent.AssignError">  <!-- Procedure -->
<short>Raises an <var>EConvertError</var> when an error occurs during
assignment.</short>
<descr>
<var>AssignError</var> raises an <var>EConvertError</var> exception with
the classnames of the <var>Source</var> and destination classes. It is used
when two incompatible classes are assigned to each other.
</descr>
<seealso>
<link id="TPersistent.Assign">Assign</link>
<link id="TPersistent.AssignTo">AssignTo</link>
</seealso>
</element>

<element name="TPersistent.AssignTo">  <!-- Procedure -->
<short>Generic assignment function.</short>
<descr>
<p>
<var>AssignTo</var> is the generic function to assign the class' contents to 
another class. This method must be overridden by descendent classes to
actually assign the content of the source instance to the destination
instance. 
</p>
<p>
The <link id="TPersistent"/> implementation of <var>Assignto</var> raises 
an <var>EConvertError</var> exception. This is done for the following
reason: If the source class doesn't know how to assign itself to the
destination class (using <var>AssignTo</var>), the destination class may 
know how get the data from the source class (using <link
id="TPersistent.Assign">Assign</link>). If all descendent methods are
implemented correctly, then if neither of the two classes knows how to
assign their contents to each other, execution will end up at <link
id="TPersistent.Assign"/>, which will simply execute 
</p>
<code>
  Dest.AssignTo(Self);
</code>
<p>
If neither of the classes knows how to assign to/from each other, then
execution will end up at the <var>TPersistent</var> implementation of
<var>AssignTo</var>, and an exception will be raised.
</p>
</descr>
<seealso>
<link id="TPersistent.Assign">Assign</link>
</seealso>
</element>

<element name="TPersistent.DefineProperties">  <!-- Procedure -->
<short>Declare non-published properties that need to be streamed.</short>
<descr>
<p>
<var>DefineProperties</var> must be overridden by descendent classes to 
indicate to the streaming system which non-published properties must 
also be streamed.
</p>
<p>
The streaming systems stores only published properties in the stream.
Sometimes it is necessary to store additional data in the stream, data
which is not published. This can be done by overriding the
<var>DefineProperties</var> method. The <var>Filer</var> object is the
class that is responsible for writing all properties to the stream. 
</p>
<p>
To define new properties, two methods of the <link id="TFiler"/> class
should be used:
</p>
<ol>
<li><link id="TFiler.DefineProperty">DefineProperty</link>, to define a
property which can be represented as text.</li>
<li><link id="TFiler.DefineBinaryProperty">DefineProperty</link>, to define a
property which contains binary data.</li>
</ol>
<p>
On order for the streaming to work correctly, a call to the inherited 
<var>DefineProperties</var> is also needed, so ancestor objects also
get the possibility to read or write their private data to the stream.
Failure to call the inherited method will result in component properties not
being streamed correctly.
</p>
</descr>
<seealso>
<link id="TFiler.DefineProperties"/>
<link id="TFiler"/>
</seealso>
</element>

<element name="TPersistent.GetOwner">  <!-- Function -->
<short>Returns the owner of the component.</short>
<descr>
<var>GetOwner</var> returns the owning component of the classes instane. 
The <var>TPersistent</var> implementation of <var>GetOwner</var> returns
<var>Nil</var>. <link id="TComponent"/> overrides this method.
</descr>
<seealso>
<link id="TComponent"/>
</seealso>
</element>

<element name="TPersistent.Destroy">  <!-- Destructor -->
<short>Destroys the <var>TPersistent</var> instance. </short>
<descr>
<var>Destroy</var> disposes of the persistent object. This method should
never be called directly. Instead the <var>Free</var> method should be used.
</descr>
</element>

<element name="TPersistent.Assign">  <!-- Procedure -->
<short>Assign the contents of one class to another.</short>
<descr>
<p>
<var>Assign</var> copies the contents of <var>Source</var> to
<var>Self</var>, if the classes of the destination and source classes are
compatible.
</p>
<p>
The <var>TPersistent</var> implementation of <var>Assign</var> does nothing
but calling the <link id="TPersistent.AssignTo">AssignTo</link> method of
source. This means that if the destination class does not know how to assign
the contents of the source class, the source class instance is asked to assign
itself to the destination class. This means that it is necessary to
implement only one of the two methods so that two classes can be assiged to
one another.
</p>
<remark>
<p>
In general, a statement of the form
</p>
<code>
  Destination:=Source;
</code>
<p>
(where <var>Destination</var> and <var>Source</var> are classes) does not 
achieve the same as a statement of the form
</p>
<code>
  Destination.Assign(Source);
</code>
<p>After the former statement, both <var>Source</var> and
<var>Destination</var> will point to the same object. The latter statemtent
will copy the <i>contents</i> of the <var>Source</var> class to the
<var>Destination</var> class.
</p>
</remark>
</descr>
<seealso>
<link id="TPersistent.AssignTo">AssignTo</link>
</seealso>
</element>

<element name="TPersistent.GetNamePath">  <!-- Function -->
<short>Returns a string that can be used to identify the class instance.</short>
<descr>
<p>
<var>GetNamePath</var> returns a string that can be used to identify the
class instance. This can be used to display a name for this instance in a
Object designer.
</p>
<p>
<var>GetNamePath</var> constructs a name by recursively prepending the
<var>Classname</var> of the <var>Owner</var> instance to the
<var>Classname</var> of this instance, separated by a dot.
</p>
</descr>
<seealso>
<link id="TPersistent.GetOwner"/>
</seealso>
</element>

<element name="TPersistentClass">  <!-- "class of" type -->
<short>Class reference type for <link id="TPersistent"/>.</short>
<descr>
<var>TPersistentClass</var> is the class reference type for the <link id="TPersistent"/> class.
</descr>
<seealso>
<link id="TPersistent"/>
</seealso>
</element>

<!--
  *********************************************************************
  TCollectionItem
  *********************************************************************
-->

<element name="TCollectionItem">  <!-- Class -->
<short>Basic object that is managed by a <link id="TCollection"/> class.</short>
<descr>
<p><var>TCollectionItem</var> and <link id='TCollection'/> form a pair of base
classes that manage a collection of named objects. The
<var>TCollectionItem</var> is the named object that is managed, it
represents one item in the collection. An item in the collection is
represented by two properties: <link id="TCollectionItem.DisplayName"/>, 
<link id="TCollection.Index"/> and <link id="TCollectionItem.ID"/>.
</p>
<p>A <var>TCollectionItem</var> object is never created directly. To manage 
a set of named items, it is necessary to make a descendent of
<var>TCollectionItem</var> to which needed properties and methods are
added. This descendant can then be managed with a <link id="TCollection"/>
class. The managing collection will create and destroy it's items by itself,
it should therefore never be necessary to create <var>TCollectionItem</var>
descendents manually.
</p>
</descr>
<seealso>
<link id="TCollection"/>
</seealso>
</element>

<element name="TCollectionItem.Changed">  <!-- Procedure -->
<short>Method to notify the managing collection that the name or index of
this item has changed.
</short>
<descr>
This method is called when the <link id="TCollectionItem.DisplayName"/> is
set or when the <link id="TCollectionItem.Index"/> is changed.
</descr>
<seealso>
<link id="TCollectionItem.Id"/>
<link id="TCollectionItem.Index"/>
<link id="TCollection.Update"/>
</seealso>
</element>

<element name="TCollectionItem.GetNamePath">  <!-- Function -->
<short>Returns the namepath of this collection item.</short>
<descr>
<var>GetNamePath</var> overrides the <link id="TPersistent.GetNamePath"/>
method to return the name of the managing collection and appends its <link
id="TCollectionItem.Index"/> property.
</descr>
<seealso>
<link id="TCollectionItem.Collection"/>
<link id="TPersistent.GetNamePath"/>
<link id="TCollectionItem.Index"/>
</seealso>
</element>

<element name="TCollectionItem.GetOwner">  <!-- Function -->
<short>Returns the managing collection.</short>
<descr>
<var>TCollectionItem</var> overrides <link id="TPersistent.GetOwner"/> to
and returns the <link id="TCollectionItem.Collection"/> that manages it.
</descr>
<seealso>
<link id="TPersistent.GetOwner"/>
<link id="TCollectionItem.Collection"/>
</seealso>
</element>

<element name="TCollectionItem.GetDisplayName">  <!-- Function -->
<short>Returns the <link id="TCollectionItem.DisplayName"/> of the 
collectionitem</short>
<descr>
<p>
<var>GetDisplayName</var> returns the value of the 
<link id="TCollectionItem.DisplayName"/> property. 
By default, this is the classname of the actual <var>TCollectionItem</var> descendant.
</p>
<p>
Descendants of <var>TCollectionItem</var> can and should override this 
method to return a more meaningful value.
</p>
</descr>
<seealso>
<link id="TCollectionItem.DisplayName"/>
</seealso>
</element>

<element name="TCollectionItem.SetIndex">  <!-- Procedure -->
<short>Write method for the <link id="TCollectionItem.Index"/> property.</short>
<descr>
<var>SetIndex</var> implements the write handler for the <link
id="TCollectionItem.Index"/> property. It requests the managing collection to 
move this item to the desired index <var>value</var>.
</descr>
<seealso>
<link id="TCollectionItem.Index"/>
</seealso>
</element>

<element name="TCollectionItem.SetDisplayName">  <!-- Procedure -->
<short>Write method for the <link id="TCollectionItem.DisplayName"/> property</short>
<descr>
<p><var>SetDisplayName</var> is the write method for the <link
id="TCollectionItem.DisplayName"/> property. It does nothing but notifying
the managing collection that the displayname has changed. It does NOT store
the actual <var>Value</var>.
</p>
<p>
Descendants of <var>TCollectionItem</var> should override this method to 
store the actual displayname if this is required. 
</p>
</descr>
<seealso>
<link id="TCollectionItem.DisplayName"/>
</seealso>
</element>

<element name="TCollectionItem.Create">  <!-- Constructor -->
<short>Creates a new instance of this collection item.</short>
<descr>
<var>Create</var> instantiates a new item in a <link id="TCollection"/>. It
is called by the <link id="TCollection.Add"/> function and should under
normal circumstances never be called directly.
called 
</descr>
<seealso>
<link id="TCollectionItem.Destroy"/>
</seealso>
</element>

<element name="TCollectionItem.Destroy">  <!-- Destructor -->
<short>Destroyes this collection item.</short>
<descr>
<p><var>Destroy</var> removes the item from the managing collection 
and Destroys the item instance. 
</p>
<p>
This is the only way to remove items from a collection;
</p>
</descr>
<seealso>
<link id="TCollectionItem.Create"/>
</seealso>
</element>

<element name="TCollectionItem.Collection">  <!-- Property -->
<short>Pointer to the collection managing this item.</short>
<descr>
<var>Collection</var> points to the collection managing this item. This
property can be set to point to a new collection. If this is done, the old
collection will be notified that the item should no longer be managed, and
the new collection is notified that it should manage this item as well.
</descr>
<seealso>
<link id="TCollection"/>
</seealso>
</element>

<element name="TCollectionItem.ID">  <!-- Property -->
<short>Initial index of this item.</short>
<descr>
<p><var>ID</var> is the initial value of <link id="TCollectionItem.Index"/>;
it doesn't change after the index changes. It can be used to uniquely
identify the item. The <var>ID</var> property doesn't change as items are
added and removed from the collection.
</p>
<p>
While the <link id="TCollectionItem.Index"/> property forms a continuous 
series, <var>ID</var> does not. If items are removed from the collection, 
their <var>ID</var> is not used again, leaving gaps. Only when the
collection is initialiiy created, the <var>ID</var> and <var>Index</var>
properties will be equal.
</p>
</descr>
<seealso>
<link id="TCollection.Items"/>
<link id="TCollectionItem.Index"/>
</seealso>
</element>

<element name="TCollectionItem.Index">  <!-- Property -->
<short>Index of the item in its managing collection <link id="TCollection.Items"/> property.</short>
<descr>
<p>
<var>Index</var> is the current index of the item in its managing
collection's <link id="TCollection.Items"/> property. This property may
change as items are added and removed from the collection.
</p>
<p>The index of an item is zero-based, i.e. the first item has index zero.
The last item has index <var>Count-1</var> where <var>Count</var> is the
number of items in the collection.
</p>
<p>
The <var>Index</var> property of the items in a collection form a continuous
series ranging from <var>0</var> to <var>Count-1</var>. The <link
id="TCollectionItem.ID"/> property does not form a continuous series, but
can also be used to identify an item. 
</p>
</descr>
<seealso>
<link id="TCollectionItem.ID"/>
<link id="TCollection.Items"/>
</seealso>
</element>

<element name="TCollectionItem.DisplayName">  <!-- Property -->
<short>Name of the item, displayed in the object inspector.</short>
<descr>
<p>
<var>DisplayName</var> contains the name of this item as shown in the object
inspector. For <var>TCollectionItem</var> this returns always the class name 
of the managing collection, followed by the index of the item.
</p>
<p><var>TCollectionItem</var> does not implement any functionality to store
the <var>DisplayName</var> property. The property can be set, but this will
have no effect other than that the managing collection is notified of a
change. The actual displayname will remain unchanged. To store the
<var>DisplayName</var> property,<var>TCollectionItem</var> descendants
should override the <link id="TCollectionItem.SetDisplayName"/> and
<link id="TCollectionItem.GetDisplayName"/> to add storage functionality.
</p>
</descr>
<seealso>
<link id="TCollectionItem.Index"/>
<link id="TCollectionItem.ID"/>
<link id="TCollectionItem.GetDisplayName"/>
<link id="TCollectionItem.SetDisplayName"/>
</seealso>
</element>

<element name="TCollectionItemClass">  <!-- "class of" type -->
<short>Class reference for <link id="TCollectionItem"/>.</short>
<descr>
<var>TCollectionItemClass</var> is used by the 
<link id="TCollection.ItemClass"/> property of <link id="TCollection"/> to
identify the descendent class of <link id="TCollectionItem"/> which should
be created and managed.
</descr>
<seealso>
<link id="TCollectionItem"/>
<link id="TCollection.ItemClass"/>
</seealso>
</element>

<!--
  *********************************************************************
  TCollection
  *********************************************************************
-->

<element name="TCollection">  <!-- Class -->
<short>Base class to manage collections of named objects.</short>
<descr>
<p><var>TCollection</var> implements functionality to manage a collection
of named objects. Each of these objects needs to be a descendent of the 
<link id="TCollectionItem"/> class. Exactly which type of object is managed
can be seen from the <link id="TCollection.ItemClass"/> property.
</p>
<p>
Normally, no <var>TCollection</var> is created directly. Instead, a 
descendents of <var>TCollection</var> and <link id="TCollectionItem"/> 
are created as a pair.
</p>
</descr>
<seealso>
<link id="TCollectionItem"/>
</seealso>
</element>

<element name="TCollection.GetAttrCount">  <!-- Function -->
<short>Returns the count of attributes associated with each item.</short>
<descr>
<p>
<var>GetAttrCount</var> returns 0 in the <var>TCollection</var>
implementation. It can be used to determine the number of attributes
associated with each collection item. Descendent objects should override
this method to return the number of attributes.
</p>
<p>This method is provided for compatibility with Delphi only and is not
used in Free Pascal.
</p>
</descr>
<seealso>
<link id="TCollection.GetAttr"/>
<link id="TCollection.GetItemAttr"/>
</seealso>
</element>

<element name="TCollection.GetAttr">  <!-- Function -->
<short>Returns an attribute of the collection.</short>
<descr>
<p>This method is provided for compatibility with Delphi only and is not
used in Free Pascal.
</p>
</descr>
<seealso>
<link id="TCollection.GetAttrCount"/>
<link id="TCollection.GetItemAttr"/>
</seealso>
</element>

<element name="TCollection.GetItemAttr">  <!-- Function -->
<short>Returns the attributes of an item.</short>
<descr>
<p>This method is provided for compatibility with Delphi only and is not
used in Free Pascal.
</p>
</descr>
<seealso>
<link id="TCollection.GetAttr"/>
<link id="TCollection.GetAttrCount"/>
</seealso>
</element>

<element name="TCollection.GetNamePath">  <!-- Function -->
<short>Overrides <link id="TPersistent.GetNamePath"/> to return a proper
pathname.</short>
<descr>
<p>
<var>GetNamePath</var> returns the name path for this collection. If the
following conditions are satisfied:
</p>
<ol>
<li>There is an owner object.</li>
<li>The owner object returns a non-empty name path.</li>
<li>The <link id="TCollection.Propname"/> property is not empty</li>
</ol>
<p>
collection has an owner and the owning object has a name, then the function
returns the owner name, followed by the propname. If one of the conditions
is not satisfied, then the classname is returned.
</p>
</descr>
<seealso>
<link id="TCollection.GetOwner"/>
<link id="TCollection.Propname"/>
</seealso>
</element>

<element name="TCollection.Changed">  <!-- Procedure -->
<short>Procedure called if an item is added to or removed from the collection.</short>
<descr>
<var>Changed</var> is called if a change takes place in the collection
managed by the class. If the update count ghas reached zero, it 
calls <link id="TCollection.Update"/> with a nil argument.
</descr>
<seealso>
<link id="TCollection.Update"/>
<link id="TCollection.Add"/>
<link id="TCollection.Clear"/>
</seealso>
</element>

<element name="TCollection.GetItem">  <!-- Function -->
<short>Read handler for the <link id="TCollection.Items"/> property.</short>
<descr>
<var>GetItem</var> is the read handler for the <link
id="TCollection.Items"/> property. It returns the <var>Index</var>-th
element from the list of objects.
</descr>
<errors>
If <var>Index</var> is outside the allowed range, then an <link
id="EListError"/> exception is raised.
</errors>
<seealso>
<link id="TCollection.Items"/>
<link id="TCollection.Count"/>
<link id="TCollection.SetItem"/>
</seealso>
</element>

<element name="TCollection.SetItem">  <!-- Procedure -->
<short>Write handler for the <link id="TCollection.Items"/> property.</short>
<descr>
<var>SetItem</var> implements the write handler for the <link
id="TCollection.Items"/> property. It assignes <var>Value</var> to the 
<var>Index</var>-th element in the array. For this to work properly, the
<link id="TPersistent.Assign"/> method of the <var>Item</var> must work 
correctly.
</descr>
<errors>
If <var>Index</var> is outside the allowed range, then an <link
id="EListError"/> exception is raised.
</errors>
<seealso>
<link id="TCollection.Items"/>
<link id="TCollection.Count"/>
<link id="TCollection.GetItem"/>
</seealso>
</element>

<element name="TCollection.SetItemName">  <!-- Procedure -->
<short>Virtual method to set the name of the specified item</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TCollection.SetPropName">  <!-- Procedure -->
<short>Write handler for the <link id="TCollection.PropName"/> property</short>
<descr>
<var>SetPropName</var> must be overridden by descendent objects to set the 
<link id="TCollection.PropName"/> property to a suitable value. By default,
<var>SetPropName</var> sets the <var>PropName</var> property to empty.
</descr>
<seealso>
<link id="TCollection.PropName"/> 
</seealso>
</element>

<element name="TCollection.Update">  <!-- Procedure -->
<short>Hander called when an item in the collection has changed.</short>
<descr>
<p><var>Update</var> is called in the following cases:
</p>
<ol>
<li>An item is added to or removed from the collection.</li>
<li>An item is moved in the list, i.e. its <link id="TCollectionItem.Index"/>
property changes.</li>
<li>An item's <link id="TCollectionItem.DisplayName"/> property
changes.</li>
</ol>
<p>
Descendent classes can override this method to perform additional actions
when the collection changes. The <var>Item</var> parameter indicates the
item that was changed. This can be <var>Nil</var>
</p>
</descr>
<seealso>
<link id="TCollection.Changed"/>
</seealso>
</element>

<element name="TCollection.PropName">  <!-- Property -->
<short>Name of the property that this collection represents.</short>
<descr>
<var>PropName</var> indicates the name of the property that this collection
is supposed to represent. By default, this is the empty string. Descendents
can override this property to return the name of the property that is
represented by this collection.
</descr>
<seealso>
<link id="TCollection.SetPropName"/>
<link id="TCollection.GetPropName"/>
</seealso>
</element>

<element name="TCollection.Create">  <!-- Constructor -->
<short>Creates a new collection.</short>
<descr>
<var>Create</var> instantiates a new instance of the <var>TCollection</var> 
class which will manage objects of class <var>AItemClass</var>. 
It creates the list used to hold all objects, and stores the 
<var>AItemClass</var> for the adding of new objects to the collection.
</descr>
<seealso>
<link id="TCollection.ItemClass"/>
<link id="TCollection.Destroy"/>
</seealso>
</element>

<element name="TCollection.Destroy">  <!-- Destructor -->
<short>Destroys the collection and frees all the objects it manages.</short>
<descr>
<p>
<var>Destroy</var> first clears the collection, and then frees all memory
allocated to this instance. 
</p>
<p>
Don't call <var>Destroy</var> directly, call <var>Free</var> instead.
</p>
</descr>
<seealso>
<link id="TCollection.Create"/>
</seealso>
</element>

<element name="TCollection.Add">  <!-- Function -->
<short>Creates and adds a new item to the collection.</short>
<descr>
<var>Add</var> instantiates a new item of class <link
id="TCollection.ItemClass"/> and adds it to the list. The newly created
object is returned.
</descr>
<seealso>
<link id="TCollection.ItemClass"/>
<link id="TCollection.Clear"/>
</seealso>
</element>

<element name="TCollection.Assign">  <!-- Procedure -->
<short>Assigns one collection to another.</short>
<descr>
<p>
<var>Assign</var> assigns the contents of one collection to another.
It does this by clearing the items list, and adding as much elements as
there are in the <var>Source</var> collection; it assigns to each created
element the contents of it's counterpart in the <var>Source</var> element.
</p>
<p>
Two collections cannot be assigned to each other if instances of the
<var>ItemClass</var> classes cannot be assigned to each other. 
</p>
</descr>
<errors>
If the objects in the collections cannot be assigned to one another, then
an <var>EConvertError</var> is raised.
</errors>
<seealso>
<link id="TPersistent.Assign"/>
<link id="TCollectionItem"/>
</seealso>
</element>

<element name="TCollection.BeginUpdate">  <!-- Procedure -->
<short>Start an update batch.</short>
<descr>
<p>
<var>BeginUpdate</var> is called at the beginning of a batch update. It
raises the update count with 1.  
</p>
<p>
Call <var>BeginUpdate</var> at the beginning of a series of operations that
will change the state of the collection. This will avoid the call to 
<link id="TCollection.Update"/> for each operation.
At the end of the operations, a corresponding call to <var>EndUpdate</var> 
must be made. It is best to do this in the context of a 
<var>Try ... finally</var> block:
</p>
<code>
  With MyCollection Do
    try
      BeginUpdate;
      // Some Lengthy operations
    finally
      EndUpdate;
    end;  
</code>
<p>
This insures that the number of calls to <var>BeginUpdate</var> always
matches the number of calls to <link id="TCollection.EndUpdate"/>, even in
case of an exception.
</p>
</descr>
<seealso>
<link id="TCollection.EndUpdate"/>
<link id="TCollection.Changed"/>
<link id="TCollection.Update"/>
</seealso>
</element>

<element name="TCollection.Clear">  <!-- Procedure -->
<short>Removes all items from the collection.</short>
<descr>
<var>Clear</var> will clear the collection, i.e. each item in the collection
is destroyed and removed from memory. 
After a call to <var>Clear</var>, <var>Count</var> is zero.
</descr>
<seealso>
<link id="TCollection.Add"/>
<link id="TCollectionItem.Destroy"/>
<link id="TCollection.Destroy"/>
</seealso>
</element>

<element name="TCollection.EndUpdate">  <!-- Procedure -->
<short>Ends an update batch.</short>
<descr>
<var>EndUpdate</var> signals the end of a series of operations that change
the state of the collection, possibly triggering an update event. 
It does this by decreasing the update count with 1 and calling <link
id="TCollection.Changed"/> it should always be used in conjunction with
<link id="TCollection.BeginUpdate"/>, preferably in the <var>Finally</var>
section of a <var>Try ... Finally</var> block.
</descr>
<seealso>
<link id="TCollection.BeginUpdate"/>
<link id="TCollection.Changed"/>
<link id="TCollection.Update"/>
</seealso>
</element>

<element name="TCollection.FindItemID">  <!-- Function -->
<short>Searches for an Item in the collection, based on its
<link id="TCollectionItem.ID"/> property.</short>
<descr>
<p>
<var>FindItemID</var> searches through the collection for the item that has
a value of <var>ID</var> for its <link id="TCollectionItem.ID"/> property,
and returns the found item. If no such item is found in the collection, 
<var>Nil</var> is returned. 
</p>
<p>The routine performs a linear search, so this can be slow on very large
collections.
</p>
</descr>
<seealso>
<link id="TCollection.Items"/>
<link id="TCollectionItem.ID"/>
</seealso>
</element>

<element name="TCollection.Count">  <!-- Property -->
<short>Number of items in the collection.</short>
<descr>
<p>
<var>Count</var> contains the number of items in the collection. 
</p>
<remark>
The items in the collection are identified by their <link
id="TCollectionItem.Index"/> property, which is a zero-based index, meaning
that it can take values between <var>0</var> and <var>Count</var>.
</remark>
</descr>
<seealso>
<link id="TCollectionItem.Index"/>
<link id="TCollection.Items"/>
</seealso>
</element>

<element name="TCollection.ItemClass">  <!-- Property -->
<short>Class pointer for each item in the collection.</short>
<descr>
<var>ItemClass</var> is the class pointer with which each new item in the
collection is created. It is the value that was passed to the collection's
constructor when it was created, and does not change during the lifetime of
the collection.
</descr>
<seealso>
<link id="TCollectionItem"/>
<link id="TCollection.Items"/>
</seealso>
</element>

<element name="TCollection.Items">  <!-- Property -->
<short>Indexed array of items in the collection.</short>
<descr>
<p>
<var>Items</var> provides indexed access to the items in the collection.
Since the array is zero-based, <var>Index</var> should be an integer 
between <var>0</var> and <var>Count-1</var>.
</p>
<p>It is possible to set or retrieve an element in the array. When setting
an element of the array, the object that is assigned should be compatible
with the class of the objects in the collection, as given by the 
<link id="TCollection.ItemClass"/> property.
</p>
<p>Adding an element to the array can be done with the <link
id="TCollection.Add"/> method. The array can be cleared with the <link
id="TCollection.Clear"/> method. Removing an element of the array should
be done by freeing that element.
</p>
</descr>
<seealso>
<link id="TCollection.Count"/>
<link id="TCollection.ItemClass"/>
<link id="TCollection.Clear"/>
<link id="TCollection.Add"/>
</seealso>
</element>

<!--
  *********************************************************************
  IStringsAdapter
  *********************************************************************
-->

<element name="IStringsAdapter">  <!-- Class -->
<short>IStringsAdapter Interface declaration.</short>
<descr>Is not yet supported in Free Pascal.
</descr>
<seealso>
<link id="TStrings"/>
</seealso>
</element>

<!--
  *********************************************************************
  TStrings
  *********************************************************************
-->

<element name="TStrings">  <!-- Class -->
<short>Class to manage arrays or collections of strings</short>
<descr>
<p><var>TStrings</var> implements an abstract class to manage an array of
strings. It introduces methods to set and retrieve strings in the array,
searching for a particular string, concatenating the strings and so on.
It also allows an arbitrary object to be associated with each string.
</p>
<p>
It also introduces methods to manage a series of <var>name=value</var> 
settings, as found in many configuration files.
</p>
<p>An instance of <var>TStrings</var> is never created directly, instead a
descendent class such as <link id="TStringList"/> should be created. This is
because <var>TStrings</var> is an abstract class which does not implement
all methods; <var>TStrings</var> also doesn't store any strings, this is the
functionality introduced in descendents such as <link id="TStringList"/>.
</p>
</descr>
<seealso>
<link id="TStringList"/>
</seealso>
</element>

<element name="TStrings.DefineProperties">  <!-- Procedure -->
<short>Method to stream the contents of the string collection</short>
<descr>
<var>DefineProperties</var> allows the contents of the string collection
to be streamed. As such, it overrides <link id="TPersistent.DefineProperties"/>
</descr>
<seealso>
<link id="TPersistent.DefineProperties"/>
</seealso>
</element>

<element name="TStrings.Error">  <!-- Procedure -->
<short>Raises an <link id="EStringListError"/> exception.</short>
<descr>
<p>
<var>Error</var> raises an <link id="EStringListError"/> exception. It passes
<var>Msg</var> as a format with <var>Data</var> as the only argument.
</p>
<p> This method can be used by descendent objects to raise an error.</p>
</descr>
<seealso>
<link id="EStringListError"/>
</seealso>
</element>

<element name="TStrings.Get">  <!-- Function -->
<short>Abstract read handler for the <link id="TStrings.Strings"/> property.</short>
<descr>
<p>
<var>Get</var> is the abstract read handler for the <link id="TStrings.Strings"/> 
property. This is an abstract method, hence it is not implemented in 
<var>TStrings</var>.
</p>
<p>
Descendent classes, such as <link id="TStringList"/> must override this
method and implement a routine that retrieves the <var>Index</var>-th string
in the list. <var>Index</var> should have a value between <var>0</var> and
<var>Count-1</var>, in all other cases an error should be raised using
<link id="TStrings.Error"/>.
</p>
</descr>
<seealso>
<link id="TStrings.Strings"/>
<link id="TStrings.Put"/>
<link id="TStrings.GetObject"/>
</seealso>
</element>

<element name="TStrings.GetCapacity">  <!-- Function -->
<short>Abstract Read handler for the <link id="TStrings.Capacity"/> property.</short>
<descr>
<p>
<var>GetCapacity</var> is the read handler for the <link
id="TStrings.Capacity"/> property. The implementation in <var>TStrings</var>
will return 0. 
</p>
<p>Descendent classes can override this method. It should return the 
current number of strings that can be held by the stringlist before 
it attempts to expand it's storage space.
</p>
</descr>
<seealso>
<link id="TStrings.Capacity"/>
<link id="TStrings.SetCapacity"/>
</seealso>
</element>

<element name="TStrings.GetCount">  <!-- Function -->
<short>Abstract read handler for the <link id="TStrings.Count"/> property.</short>
<descr>
<p>
<var>GetCount</var> is the abstract read handler for the <link
id="TStrings.Count"/> property. This is an abstract method, hence it is not implemented in 
<var>TStrings</var>.
</p>
<p>
Descendent classes must override this method. It should return the 
current number of strings in the list. (empty strings included). 
</p>
</descr>
<seealso>
<link id="TStrings.Count"/>
</seealso>
</element>

<element name="TStrings.GetObject">  <!-- Function -->
<short>Abstract read handler for the <link id="TStrings.Objects"/> property.</short>
<descr>
<p>
<var>GetObject</var> is the read handler for the <link
id="TStrings.Objects"/> property. The <var>TStrings</var> implementation of
this method ignores the <var>Index</var> argument and simply 
returns <var>Nil</var>.
</p>
<p>
Descendent classes that should support object storage should override this
method and return the object associated to the <var>Index</var>-th string 
in the list. <var>Index</var> should have a value between <var>0</var> and
<var>Count-1</var>. If <var>Index</var> is outside the allowed range, an
error should be raised using <link id="TStrings.Error"/>.
</p>
</descr>
<seealso>
<link id="TStrings.Objects"/>
<link id="TStrings.PutObject"/>
<link id="TStrings.Get"/>
</seealso>
</element>

<element name="TStrings.GetTextStr">  <!-- Function -->
<short>Read handler for the <link id="TStrings.Text"/> property.</short>
<descr>
<p><var>GetTextStr</var> is the read handler for the <link id="TStrings.Text"/>
property. It simply concatenates all strings in the list with a linefeed between
them, and returns the resulting string.
</p>
<p>
Descendent classes may override this method to implement an efficienter
algorithm which is more suitable to their storage method. 
</p>
</descr>
<seealso>
<link id="TStrings.Text"/>
<link id="TStrings.SetTextStr"/>
</seealso>
</element>

<element name="TStrings.Put">  <!-- Procedure -->
<short>Write handler for the <link id="TStrings.Strings"/> property.</short>
<descr>
<p>
<var>Put</var> is the write handler for the <link id="TStrings.Strings"/> 
property. It does this by saving the object associated to the 
<var>Index</var>-th string, deleting the <var>Index</var>-th string, and
inserting <var>S</var> and the saved object at position <var>Index</var>
with <link id="TStrings.InsertObject"/>
</p>
<p>
Descendent classes may wish to override <var>Put</var> to implement a more
efficient method. 
</p>
</descr>
<seealso>
<link id="TStrings.Strings"/>
<link id="TStrings.Get"/>
<link id="TStrings.PutObject"/>
</seealso>
</element>

<element name="TStrings.PutObject">  <!-- Procedure -->
<short>Write handler for the <link id="TStrings.Objects"/> property.</short>
<descr>
<p>
<var>PutObject</var> is the write handler for the <link
id="TStrings.Objects"/> property. The <var>TStrings</var> implementation of 
<var>PutObject</var> does nothing.
</p>
<p>
Descendent objects that should support Object storage must override this
method to store the <var>AObject</var> so that it is associated with the
<var>Index</var>-th string in the list. <var>Index</var> should have a value
between <var>0</var> and <var>Count-1</var>. If the value of
<var>Index</var> is out of range, an error should be raised using <link
id="TStrings.Error"/>.
</p>
</descr>
<seealso>
<link id="TStrings.Objects"/>
<link id="TStrings.GetObject"/>
<link id="TStrings.Put"/>
</seealso>
</element>

<element name="TStrings.SetCapacity">  <!-- Procedure -->
<short>Write handler for the <link id="TStrings.Capacity"/> property.</short>
<descr>
<p>
<var>SetCapacity</var> is the write handler for the <link
id="TStrings.Capacity"/> property. The <var>TStrings</var> implementation
of <var>SetCapacity</var> does nothing.
</p>
<p>
Descendent classes can override this method to set the current capacity of
the stringlist to <var>NewCapacity</var>. The capacity is the number of strings the list can hold
before it tries to expand its storage space. <var>NewCapacity</var> should
be no less than <var>Count</var>. 
</p>
</descr>
<seealso>
<link id="TStrings.Capacity"/>
<link id="TStrings.GetCapacity"/>
</seealso>
</element>

<element name="TStrings.SetTextStr">  <!-- Procedure -->
<short>Write handler for the <link id="TStrings.Text"/> property.</short>
<descr>
<p>
<var>SetTextStr</var> is the write method for the <link id="TStrings.Text"/>
property. It does nothing other than calling <link id="TStrings.SetText"/>.
</p>
<p>
Descendent classes may override this method to implement a more efficient 
algoritm that fits their storage method better.
</p>
</descr>
<seealso>
<link id="TStrings.Text"/>
<link id="TStrings.GetTextStr"/>
</seealso>
</element>

<element name="TStrings.SetUpdateState">  <!-- Procedure -->
<short>Sets the update state. </short>
<descr>
<p>
<var>SetUpdateState</var> sets the update state to <var>Updating</var>. The
<var>TStrings</var> implementation of <var>SetUpdateState</var> does
nothing.
</p>
<p>
Descendent objects may override this method to implement optimizations. If
<var>Updating</var> is <var>True</var> then the list of strings is about to
be updated (possibly many times). If it is <var>False</var> no more updates
will take place till the next <var>SetUpdateState</var> call.
</p>
</descr>
<seealso>
<link id="TStrings.BeginUpdate"/>
<link id="TStrings.EndUpdate"/>
</seealso>
</element>

<element name="TStrings.Destroy">  <!-- Destructor -->
<short>Frees all strings and objects, and removes the list from memory.</short>
<descr>
<var>Destroy</var> is the destructor of <var>TStrings</var> it does nothing
except calling the inherited destructor.
</descr>
<seealso>
</seealso>
</element>

<element name="TStrings.Add">  <!-- Function -->
<short>Add a string to the list</short>
<descr>
<var>Add</var> adds <var>S</var> at the end of the list and returns the
index of <var>S</var> in the list (which should equal <link id="Tstrings.Count"/>
</descr>
<seealso>
<link id="TStrings.Items"/>
<link id="TStrings.AddObject"/>"
<link id="TStrings.Insert"/>
<link id="TStrings.Delete"/>
<link id="TStrings.Strings"/>
<link id="TStrings.Count"/>
</seealso>
</element>

<element name="TStrings.AddObject">  <!-- Function -->
<short>Add a string and associated object to the list.</short>
<descr>
<p>
<var>AddObject</var> adds <var>S</var> to the list of strings, and
associates <var>AObject</var> with it. It returns the index of <var>S</var>.
</p>
<remark>
An object added to the list is not automatically destroyed by the list of
the list is destroyed or the string it is associated with is deleted. It is
the responsibility of the application to destroy any objects associated with
strings.
</remark>
</descr>
<seealso>
<link id="TStrings.Add"/>
<link id="Tstrings.Items"/>
<link id="TStrings.Objects"/>
<link id="Tstrings.InsertObject"/>
</seealso>
</element>

<element name="TStrings.Append">  <!-- Procedure -->
<short>Add a string to the list.</short>
<descr>
<var>Append</var> does the same as <link id="TStrings.Add"/>, only it does
not return the index of the inserted string. 
</descr>
<seealso>
<link id="TStrings.Add"/>
</seealso>
</element>

<element name="TStrings.AddStrings">  <!-- Procedure -->
<short>Add contents of another stringlist to this list.</short>
<descr>
<var>AddStrings</var> adds the contents of <var>TheStrings</var> to the
stringlist. Any associated objects are added as well.
</descr>
<seealso>
<link id="TStrings.Add"/>
<link id="TStrings.Assign"/>
</seealso>
</element>

<element name="TStrings.Assign">  <!-- Procedure -->
<short>Assign the contents of another stringlist to this one.</short>
<descr>
<var>Assign</var> replaces the contents of the stringlist with the contents
of <var>Source</var> if <var>Source</var> is also of type
<var>TStrings</var>. Any associated objects are copied as well.
</descr>
<seealso>
<link id="TStrings.Add"/>
<link id="TStrings.AddStrings"/>
<link id="TPersistent.Assign"/>
</seealso>
</element>

<element name="TStrings.BeginUpdate">  <!-- Procedure -->
<short>Mark the beginning of an update batch.</short>
<descr>
<p>
<var>BeginUpdate</var> increases the update count by one. It is advisable to
call <var>BeginUpdate</var> before lengthy operations on the stringlist. At
the end of these operation, <link id="TStrings.EndUpdate"/> should be
called to mark the end of the operation.  Descendent classes may use this
information to perform optmizations. e.g. updating the screen only once
after many strings were added to the list.
</p>
<p>
All <var>TStrings</var> methods that modify the string list call
<var>BeginUpdate</var> before the actual operation, and call
<var>endUpdate</var> when the operation is finished. Descendent classes
should also call these methods when modifying the string list. 
</p>
<remark>
<p>
Always put the corresponding call to <link id="TStrings.EndUpdate"/> in the
context of a <var>Finally</var> block, to ensure that the update count is
always descreased at the end of the operation, even if an exception
occurred:
</p>
<code>
  With MyStrings do
    try
      BeginUpdate;
      // Some lengthy operation.
    Finally
      EndUpdate
    end;  
</code>
</remark>
</descr>
<seealso>
<link id="TStrings.EndUpdate"/>
</seealso>
</element>

<element name="TStrings.Clear">  <!-- Procedure -->
<short>Removes all strings and associated objects from the list.</short>
<descr>
<p>
<var>Clear</var> will remove all strings and their associated objects from
the list. After a call to clear, <link id="TStrings.Count"/> is zero.
</p>
<p>
Since it is an abstract method, <var>TStrings</var> itself does not implement 
<var>Clear</var>. Descendent classes such as <link
id="TStringList"/> implement this method.
</p>
</descr>
<seealso>
<link id="TStrings.Items"/>
<link id="TStrings.Delete"/>
<link id="TStrings.Count"/>"
</seealso>
</element>

<element name="TStrings.Delete">  <!-- Procedure -->
<short>Delete a string from the list.</short>
<descr>
<p>
<var>Delete</var> deletes the string at position <var>Index</var> from the
list. The associated object is also removed from the list, but not
destroyed. <var>Index</var> is zero-based, and should be in the range 
<var>0</var> to <var>Count-1</var>.
</p>
<p>
Since it is an abstract method, <var>TStrings</var> itself does not implement 
<var>Delete</var>. Descendent classes such as <link
id="TStringList"/> implement this method.
</p>
</descr>
<errors>
If <var>Index</var> is not in the allowed range, an <link
id="EStringListError"/> is raised.
</errors>
<seealso>
<link id="TStrings.Insert"/>
<link id="TStrings.Items"/>
<link id="TStrings.Clear"/>
</seealso>
</element>

<element name="TStrings.EndUpdate">  <!-- Procedure -->
<short>Mark the end of an update batch.</short>
<descr>
<p>
<var>EndUpdate</var> should be called at the end of a lengthy operation on
the stringlist, but only if there was a call to <var>BeginUpdate</var> before
the operation was started. It is best to put the call to
<var>EndUpdate</var> in the context of a <var>Finally</var> block, so it
will be called even if an exception occurs.
</p>
<p>
For more information, see <link id="TStrings.BeginUpdate"/>.
</p>
</descr>
<seealso>
<link id="TStrings.BeginUpdate"/>
</seealso>
</element>

<element name="TStrings.Equals">  <!-- Function -->
<short>Compares the contents of two stringlists.</short>
<descr>
<p>
<var>Equals</var> compares the contents of the stringlist with the contents
of <var>TheStrings</var>. If the contents match, i.e. the stringlist contain 
an equal amount of strings, and all strings match, then <var>True</var> is
returned. If the number of strings in the lists is is unequal, or they
contain one or more different strings, <var>False</var> is returned.
</p>
<remark>
<ol>
<li>The strings are compared case-insensitively.</li>
<li>The associated objects are not compared</li>
</ol>
</remark> 
</descr>
<seealso>
<link id="Tstrings.Items"/>
<link id="TStrings.Count"/>
<link id="TStrings.Assign"/>
</seealso>
</element>

<element name="TStrings.Exchange">  <!-- Procedure -->
<short>Exchanges two strings in the list.</short>
<descr>
<p>
<var>Exchange</var> exchanges the strings at positions <var>Index1</var>
and <var>Index2</var>. The associated objects are also exchanged.
</p>
<p>
Both indexes must be in the range of valid indexes, i.e. must have a
value between <var>0</var> and <var>Count-1</var>.
</p>
</descr>
<errors>
If either <var>Index1</var> or <var>Index2</var> is not in the range of valid
indexes, an <link id="EStringListError"/> exception is raised.
</errors>
<seealso>
<link id="TStrings.Move"/>
<link id="TStrings.Strings"/>
<link id="TStrings.Count"/>
</seealso>
</element>

<element name="TStrings.GetText">  <!-- Function -->
<short>Returns the contents as a PChar</short>
<descr>
<p>
<var>GetText</var> allocates a memory buffer and compies the contents of the
stringlist to this buffer as a series of strings, separated by an
end-of-line marker. The buffer is zero terminated.
</p>
<remark>
The caller is responsible for freeing the returned memory buffer. 
</remark>
</descr>
<seealso>
</seealso>
</element>

<element name="TStrings.IndexOf">  <!-- Function -->
<short>Find a string in the list and return its position.</short>
<descr>
<p>
<var>IndexOf</var> searches the list for <var>S</var>. The search is
case-insensitive. If a matching entry is found, its position is returned.
if no matching string is found, <var>-1</var> is returned.
</p>
<remark>
<ol>
<li>Only the first occurrence of the string is returned.</li>
<li>The returned position is zero-based, i.e. 0 indicates the first string
in the list.</li>
</ol>
</remark>
</descr>
<seealso>
<link id="TStrings.IndexOfObject"/>
<link id="TStrings.IndexOfName"/>
<link id="TStrings.Strings"/>
</seealso>
</element>

<element name="TStrings.IndexOfName">  <!-- Function -->
<short>Finds the index of a name in the name-value pairs.</short>
<descr>
<p>
<var>IndexOfName</var> searches in the list of strings for a name-value pair
with name part <var>Name</var>. If such a pair is found, it returns the
index of the pair in the stringlist. If no such pair is found, the function
returns <var>-1</var>. The search is done case-insensitive.
</p>
<remark>
<ol>
<li>Only the first occurrence of a matching name-value pair is returned.</li>
<li>The returned position is zero-based, i.e. 0 indicates the first string
in the list.</li>
</ol>
</remark>
</descr>
<seealso>
<link id="TStrings.IndexOf"/>
<link id="TStrings.IndexOfObject"/>
<link id="TStrings.Strings"/>
</seealso>
</element>

<element name="TStrings.IndexOfObject">  <!-- Function -->
<short>Finds an object in the list and returns its index.</short>
<descr>
<p>
<var>IndexOfObject</var> searchs through the list of strings till it find a
string associated with <var>AObject</var>, and returns the index of this
string. If no such string is found, <var>-1</var> is returned.
</p>
<remark>
<ol>
<li>Only the first occurrence of a string with associated object
<var>AObject</var> is returned; if more strings in the list can be
associated with <var>AObject</var>, they will not be found by this routine.</li>
<li>The returned position is zero-based, i.e. 0 indicates the first string
in the list.</li>
</ol>
</remark>
</descr>
<seealso>
</seealso>
</element>

<element name="TStrings.Insert">  <!-- Procedure -->
<short>Insert a string in the list.</short>
<descr>
<p>
<var>Insert</var> inserts the string <var>S</var> at position
<var>Index</var> in the list. <var>Index</var> is a zero-based position, 
and can have values from <var>0</var> to <var>Count</var>. If
<var>Index</var> equals <var>Count</var> then the string is appended to the
list.
</p>
<remark>
<ol>
<li>All methods that add strings to the list use <var>Insert</var> to add
a string to the list.</li>
<li>If the string has an associated object, use <link
id="TStrings.InsertObject"/> instead.</li>
</ol>
</remark>
</descr>
<errors>
If <var>Index</var> is less than zero or larger than <var>Count</var> then
an <link id="EStringListError"/> exception is raised.
</errors>
<seealso>
<link id="TStrings.Add"/>
<link id="TStrings.InsertObject"/>
<link id="TStrings.Append"/>
<link id="TStrings.Delete"/>
</seealso>

</element>

<element name="TStrings.InsertObject">  <!-- Procedure -->
<short>Insert a string and associated object in the list.</short>
<descr>
<p>
<var>InsertObject</var> inserts the string <var>S</var> and its associated
object<var>AObject</var> at position <var>Index</var> in the list. 
<var>Index</var> is a zero-based position, and can have values from 
<var>0</var> to <var>Count</var>. If <var>Index</var> equals 
<var>Count</var> then the string is appended to the list.
</p>
</descr>
<errors>
If <var>Index</var> is less than zero or larger than <var>Count</var> then
an <link id="EStringListError"/> exception is raised.
</errors>
<seealso>
<link id="TStrings.Insert"/>
<link id="TStrings.AddObject"/>
<link id="TStrings.Append"/>
<link id="TStrings.Delete"/>
</seealso>
</element>

<element name="TStrings.LoadFromFile">  <!-- Procedure -->
<short>Load the contents of a file as a series of strings.</short>
<descr>
<p>
<var>LoadFromFile</var> loads the contents of a file into the stringlist.
Each line in the file (as marked by the end-of-line marker of the
particular OS the application runs on) becomes one string in the stringlist. 
This action replaces
the contents of the stringlist, it does not append the strings to the
current content.
</p>
<p>
<var>LoadFromFile</var> simply creates a <link id="TFileStream">file
stream</link> with the given filename, and then executes 
<link id="TStrings.LoadfromStream"/>; after that the file stream object 
is destroyed again.
</p>
</descr>
<seealso>
<link id="TStrings.LoadFromStream"/>
<link id="TStrings.SaveToFile"/>
<link id="Tstrings.SaveToStream"/>
</seealso>
</element>

<element name="TStrings.LoadFromStream">  <!-- Procedure -->
<short>Load the contents of a stream as a series of strings.</short>
<descr>
<var>LoadFromStream</var> loads the contents of <var>Stream</var>
 into the stringlist.
Each line in the stream (as marked by the end-of-line marker of the
particular OS the application runs on) becomes one string in the stringlist. 
This action replaces
the contents of the stringlist, it does not append the strings to the
current content. 
</descr>
<seealso>
<link id="TStrings.LoadFromFile"/>
<link id="TStrings.SaveToFile"/>
<link id="Tstrings.SaveToStream"/>
</seealso>
</element>

<element name="TStrings.Move">  <!-- Procedure -->
<short>Move a string from one place in the list to another.</short>
<descr>
<p>
<var>Move</var> moves the string at position <var>CurIndex</var> so
it has position <var>NewIndex</var> after the move operation. The object
associated to the string is also moved. <var>CurIndex</var> and
<var>NewIndex</var> should be in the range of <var>0</var> to
<var>Count-1</var>.
</p>
<remark>
<p>
<var>NewIndex</var> is <em>not</em> the position in the stringlist before
the move operation starts. The move operation
</p>
<ol>
<li> removes the string from position <var>CurIndex</var></li>
<li> inserts the string at position <var>NewIndex</var></li>
</ol>
<p>
This may not lead to the desired result if <var>NewIndex</var> is bigger
than <var>CurIndex</var>. Consider the following example:
</p>
<code>
  With MyStrings do
    begin
    Clear;
    Add('String 0');
    Add('String 1');
    Add('String 2');
    Add('String 3');
    Add('String 4');
    Move(1,3);
    end;
</code>
<p>
After the <var>Move</var> operation has completed, 'String 1' will be between 'String 3'
and 'String 4'. 
</p>
</remark>
</descr>
<errors>
If either <var>CurIndex</var> or <var>NewIndex</var> is outside the allowed
range, an <link id="EStringListError"/> is raised.
</errors>
<seealso>
<link id="TStrings.Exchange"/>
</seealso>
</element>

<element name="TStrings.SaveToFile">  <!-- Procedure -->
<short>Save the contents of the list to a file.</short>
<descr>
<p>
<var>SaveToFile</var> saves the contents of the stringlist to the file with
name <var>FileName</var>. It writes the strings to the file, separated by
end-of-line markers, so each line in the file will contain 1 string from the
stringlist.
</p>
<p>
<var>SaveToFile</var> creates a <link id="TFileStream">file stream</link>
with name <var>FileName</var>, calls <link id="TStrings.SaveToStream"/>
and then destroys the file stream object.
</p>
</descr>
<errors>
An <link id="EStreamError"/> exception can be raised if the file <var>FileName</var> cannot be opened,
or if it cannot be written to.
</errors>
<seealso>
<link id="TStrings.SaveToStream"/>
<link id="Tstrings.LoadFromStream"/>
<link id="TStrings.LoadFromFile"/>
</seealso>
</element>

<element name="TStrings.SaveToStream">  <!-- Procedure -->
<short>Save the contents of the string to a stream.</short>
<descr>
<p>
<var>SaveToStream</var> saves the contents of the stringlist to
<var>Stream</var>. It writes the strings to the stream, separated by
end-of-line markers, so each 'line' in the stream will contain 1 string from the
stringlist.
</p>
</descr>
<errors>
An <link id="EStreamError"/> exception can be raised if the stream cannot be written to.
</errors>
<seealso>
<link id="TStrings.SaveToFile"/>
<link id="Tstrings.LoadFromStream"/>
<link id="TStrings.LoadFromFile"/>
</seealso>
</element>

<element name="TStrings.SetText">  <!-- Procedure -->
<short>Set the contents of the list from a PChar.</short>
<descr>
<var>SetText</var> parses the contents of <var>TheText</var> and fills the
stringlist based on the contents. It regards <var>TheText</var> as a series
of strings, separated by end-of-line markers. Each of these strings is added
to the stringlist.
</descr>
<seealso>
<link id="TStrings.Text"/>
</seealso>
</element>

<element name="TStrings.Capacity">  <!-- Property -->
<short>Capacity of the list, i.e. number of strings that the list can
currently hold before it tries to expand.</short>
<descr>
<p>
<var>Capacity</var> is the number of strings that the list can hold before
it tries to allocate more memory. 
</p>
<p><var>TStrings</var> returns <link id="TStrings.Count"/> when read. Trying
to set the capacity has no effect. Descendent classes such as 
<link id="TStringlist"/> can override this property such that it actually
sets the new capacity.
</p>
</descr>
<seealso>
<link id="TStringList"/>
<link id="TStrings.Count"/>
</seealso>
</element>

<element name="TStrings.CommaText">  <!-- Property -->
<short>Contents of the list as a comma-separated string.</short>
<descr>
<p>
<var>CommaText</var> represents the stringlist as a single string,
consisting of a comma-separated concatenation of the strings in the list. 
If one of the strings contains spaces, comma's or quotes it will be enclosed by 
double quotes. Any double quotes in a string will be doubled. For instance
the following strings:
</p>
<pre>
Comma,string
Quote"string
Space string
NormalSttring
</pre>
<p>
is converted to
</p>
<code>
"Comma,string","Quote""String","Space string",NormalString
</code>
<p>
Conversely, when setting the <var>CommaText</var> property, the text will be parsed
according to the rules outlined above, and the strings will be set
accordingly. Note that spaces will in this context be regarded as string
separators, unless the string as a whole is contained in double quotes.
Spaces that occur next to a delimiter will be ignored.
The following string:
</p>
<pre>
"Comma,string" , "Quote""String",Space string,, NormalString
</pre>
<p>
Will be converted to
</p>
<pre>
Comma,String
Quote"String
Space
String

NormalString
</pre>
</descr>
<seealso>
<link id="TStrings.Text"/>
<link id="TStrings.SetText"/>
</seealso>
</element>

<element name="TStrings.Count">  <!-- Property -->
<short>Number of strings in the list.</short>
<descr>
<p>
<var>Count</var> is the current number of strings in the list.
<var>TStrings</var> does not implement this property; descendent classes
should override the property read handler to return the correct value.
</p>
<p>
Strings in the list are always uniquely identified by their
<var>Index</var>; the index of a string is zero-based, i.e. it's supported
range is <var>0</var> to <var>Count-1</var>. trying to access a string with
an index larger than or equal to <var>Count</var> will result in an error.
Code that iterates over the list in a stringlist should always take into
account the zero-based character of the list index.
</p>
</descr>
<seealso>
<link id="TStrings.Strings"/>
<link id="TStrings.Objects"/>
<link id="TStrings.Capacity"/>
</seealso>
</element>

<element name="TStrings.Names">  <!-- Property -->
<short>Name parts of the name-value pairs in the list.</short>
<descr>
<p>
<var>Names</var> provides indexed access to the names of teh name-value
pairs in the list. It returns the name part of the <var>Index</var>-th
string in the list.
</p>
<remark>
The index is not an index based on the number of name-value pairs in the
list. It is the name part of the name-value pair a string <var>Index</var>
in the list. If the string at position <var>Index</var> is not a name-value
pair (i.e. does not contain the equal sign (=)), then an empty name is
returned.
</remark> 
</descr>
<seealso>
<link id="TStrings.Values"/>
<link id="TStrings.IndexOfName"/>
</seealso>
</element>

<element name="TStrings.Objects">  <!-- Property -->
<short>Indexed access to the objects associated with the strings in the
list.</short>
<descr>
<p>
<var>Objects</var> provides indexed access to the objects associated to
the strings in the list. <var>Index</var> is a  zero-based index and 
must be in the range of <var>0</var> to <var>Count-1</var>. 
</p>
<p>
Setting the <var>objects</var> property will not free the previously associated object,
if there was one. The caller is repsonsible for freeing the object that
was previously associated to the string.
</p>
<p>
<var>TStrings</var> does not implement any storage for objects. Reading the
<var>Objects</var> property will always return <var>Nil</var>, Setting the
property will have no effect. It is the responsability of the descendent
classes to provide storage for the associated objects.
</p>
</descr>
<errors>
If an <var>Index</var> outside the valid range is specified, an <link
id="EStringListError"/> exception will be raised.
</errors>
<seealso>
<link id="TStrings.Strings"/>
<link id="TStrings.IndexOfObject"/>
<link id="TStrings.Names"/>
<link id="TStrings.Values"/>
</seealso>
</element>

<element name="TStrings.Values">  <!-- Property -->
<short>Value parts of the name-value pairs in the list.</short>
<descr>
<p>
<var>Values</var> represents the value parts of the name-value pairs in the
list.
</p>
<p>
When reading this property, if there is a name-value pair in the list 
of strings that has name part <var>Name</var>, then the corresponding value 
is returned. If there is no such pair, an empty string is returned.
</p>
<p>
When writing this value, first it is checked whether there exists a 
name-value pair in the list with name <var>Name</var>. If such a pair is
found, it's value part is overwritten with the specified value. If no
such pair is found, a new name-value pair is added with the specified
<var>Name</var> and value.
</p>
<remark>
<ol>
<li>Names are compared case-insensitively.</li>
<li>Any character, including whitespace, up till the first equal (=) sign 
in a string is considered part of the name.</li>
</ol>
</remark>
</descr>
<seealso>
<link id="TStrings.Names"/>
<link id="TStrings.Strings"/>
<link id="TStrings.Objects"/>
</seealso>
</element>

<element name="TStrings.Strings">  <!-- Property -->
<short>Indexed access to teh strings in the list.</short>
<descr>
<p>
<var>Strings</var> is the default property of <var>TStrings</var>. It
provides indexed read-write access to the list of strings. Reading it will
return the string at position <var>Index</var> in the list. Writing it will
set the string at position <var>Index</var>. 
</p>
<p>
<var>Index</var> is the position of the string in the list. It is
zero-based, i.e. valued values range from <var>0</var> (the first string in
the list) till <var>Count-1</var> (the last string in the list). 
When browsing through the strings in the list, this fact must be taken into
account.
</p>
<p>
To access the objects associated with the strings in the list, use the <link
id="TStrings.Objects"/> property. The name parts of name-value pairs can be
accessed with the <link id="TStrings.Names"/> property, and the values can
be set or read through the <link id="TStrings.Values"/> property.
</p>
<p>
Searching through the list can be done using the <link
id="TStrings.IndexOf"/> method.
</p>
</descr>
<errors>
If <var>Index</var> is outside the allowed range, an <link
id="EStringListError"/> exception is raised.
</errors>
<seealso>
<link id="TStrings.Count"/>
<link id="TStrings.Objects"/>
<link id="TStrings.Names"/>
<link id="TStrings.Values"/>
<link id="TStrings.IndexOf"/>
</seealso>
</element>

<element name="TStrings.Text">  <!-- Property -->
<short>Contents of the list as one big string.</short>
<descr>
<p>
<var>Text</var> returns, when read, the contents of the stringlist as one 
big string consisting of all strings in the list, separated by an
end-of-line marker. When this property is set, the string will be cut into
smaller strings, based on the positions of end-of-line markers in the
string. Any previous content of the stringlist will be lost.
</p>
<remark>
If any of the strings in the list contains an end-of-line marker, then the
resulting string will appear to contain more strings than actually present
in the list. To avoid this ambiguity, use the <link id="TStrings.CommaText"/> 
property instead.
</remark>
</descr>
<seealso>
<link id="TStrings.Strings"/>
<link id="TStrings.Count"/>
<link id="TStrings.CommaText"/>
</seealso>
</element>

<element name="TStrings.StringsAdapter">  <!-- Property -->
<short>Not implemented in Free Pascal.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TDuplicates">  <!-- Enumeration type -->
<short>Type to describe what to do with duplicate values in a <link
id="TStringlist"/>.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TDuplicates.dupIgnore">  <!-- Enumeration value -->
<short>Duplicate values will not be be added to the list, but no error will
be triggered.</short>
<seealso>
</seealso>
</element>

<element name="TDuplicates.dupAccept">  <!-- Enumeration value -->
<short>Duplicate values can be added to the list.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TDuplicates.dupError">  <!-- Enumeration value -->
<short>If an attempt is made to add a duplicate value to the list, an
<link id="EStringListError"/> exception is raised.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TStringItemList">  <!-- Array type -->
<short>Array of <link id="TStringItem"/> records.</short>
<descr>
This declaration is provided for Delphi compatibility, it is not used in
Free Pascal.
</descr>
</element>

<!--
  *********************************************************************
  TStringList
  *********************************************************************
-->

<element name="TStringList">  <!-- Class -->
<short>Standard implementation of the <link id="TStrings"/> class.</short>
<descr>
<p>
<var>TStringList</var> is a descendent class of <link id="TStrings"/> that
implements all of the abstract methods introduced there. It also introduces 
some additional methods:
</p>
<ul>
<li>Sort the list, or keep the list sorted at all times</li>
<li>Special handling of duplicates in sorted lists</li>
<li>Notification of changes in the list</li>
</ul>
</descr>
<seealso>
<link id="TStrings"/>
<link id="TStrings.Duplicates"/>
<link id="TStrings.Sorted"/>
</seealso>
</element>

<element name="TStringList.Changed">  <!-- Procedure -->
<short>Called when the list of strings was modified.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TStringList.Changing">  <!-- Procedure -->
<short>Called when the list is changing.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TStringList.Get">  <!-- Function -->
<short>Overrides the standard read handler for the <link id="TStrings.Strings"/> property.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TStringList.GetCapacity">  <!-- Function -->
<short>Overrides the standard read handler for the <link
id="TStrings.Capacity"/> property.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TStringList.GetCount">  <!-- Function -->
<short>Overrides the standard read handler for the <link   
id="TStrings.Count"/> property.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TStringList.GetObject">  <!-- Function -->
<short>Overrides the standard read handler for the <link   
id="TStrings.Objects"/> property.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TStringList.Put">  <!-- Procedure -->
<short>Overrides the standard write handler for the <link   
id="TStrings.Strings"/> property.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TStringList.PutObject">  <!-- Procedure -->
<short>Overrides the standard write handler for the <link
id="TStrings.Objects"/> property.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TStringList.SetCapacity">  <!-- Procedure -->
<short>Overrides the standard write handler for the <link
id="TStrings.Capacity"/> property.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TStringList.SetUpdateState">  <!-- Procedure -->
<short>Overrides the standard <link id="TStrings.SetUpdateState"/>
call.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TStringList.Destroy">  <!-- Destructor -->
<short>Destroys the stringlist.</short>
<descr>
<p>
<var>Destroy</var> clears the stringlist, release all memory allocated for
the storage of the strings, and then calls the inherited destroy method.
</p>
<remark>
Any objects associated to strings in the list will <em>not</em> be
destroyed; it is the responsability of the caller to destroy all objects
associated with strings in the list.
</remark>
</descr>
</element>

<element name="TStringList.Add">  <!-- Function -->
<short>Implements the <link id="TStrings.Add"/> function.</short>
<descr>
<p>
<var>Add</var> will add <var>S</var> to the list. If the list is sorted and
the string <var>S</var> is already present in the list and 
<link id="TStringList.Duplicates"/> is <var>dupError</var> then an <link
id="EStringListError"/> exception is raised. If <var>Duplicates</var> is
set to <var>dupIgnore</var> then the return value is underfined.
</p>
<p>
If the list is sorted, new strings will not necessarily be added to the end
of the list, rather they will be inserted at their alphabetical position.
</p>
</descr>
<errors>
If the list is sorted and the string <var>S</var> is already present in the list and 
<link id="TStringList.Duplicates"/> is <var>dupError</var> then an <link
id="EStringListError"/> exception is raised.
</errors>
<seealso>
<link id="TStringList.Insert"/>
<link id="TStringList.Duplicates"/>
</seealso>
</element>

<element name="TStringList.Clear">  <!-- Procedure -->
<short>Implements the <link id="TStrings.Add"/> function.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TStringList.Delete">  <!-- Procedure -->
<short>Implements the <link id="TStrings.Delete"/> function.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TStringList.Exchange">  <!-- Procedure -->
<short>Implements the <link id="TStrings.Exchange"/> function.</short>
<descr>
<p>
<var>Exchange</var> will exchange two items in the list as described in 
<link id="TStrings.Exchange"/>. 
</p>
<remark>
<var>Exchange</var> will not check whether the list os sorted or not; 
if <var>Exchange</var> is called on a sorted list and the strings are not
identical, the sort order of the list will be destroyed.
</remark>
</descr>
<seealso>
<link id="TStringList.Sorted"/>
<link id="TStrings.Exchange"/>
</seealso>
</element>

<element name="TStringList.Find">  <!-- Function -->
<short>Locates the index for a given string in sorted lists.</short>
<descr>
<p>
<var>Find</var> returns <var>True</var> if the string <var>S</var> is present in the
list. Upon exit, the <var>Index</var> parameter will contain the position of
the string in the list. If the string is not found, the function will return
<var>False</var> and <var>Index</var> will contain the position where the
string will be inserted if it is added to the list.
</p>
<remark>
<ol>
<li> Use this method only on sorted lists. For unsorted lists, use <link
id="TStringList.IndexOf"/> instead.</li>
<li>Find uses a binary search method to locate the string</li>
</ol>
</remark>
</descr>
<seealso>
</seealso>
</element>

<element name="TStringList.IndexOf">  <!-- Function -->
<short>Overrides the <link id="TStrings.IndexOf"/> property.</short>
<descr>
<var>IndexOf</var> overrides the ancestor method <link
id="TStrings.indexOf"/>. It tries to optimize the
search by executing a binary search if the list is sorted. The function
returns the position of <var>S</var> if it is found in the list, or -1 if
the string is not found in the list.
</descr>
<seealso>
<link id="TStrings.IndexOf"/>
<link id="TStringList.Find"/>
</seealso>
</element>

<element name="TStringList.Insert">  <!-- Procedure -->
<short>Overrides the <link id="TStrings.Insert"/> method.</short>
<descr>
<var>Insert</var> will insert the string <var>S</var> at position
<var>Index</var> in the list. If the list is sorted, an <link
id="EStringListError"/> exception will be raised instead. <var>Index</var>
is a zero-based position. 
</descr>
<errors>
If <var>Index</var> contains an invalid value (less than zero or larger than
<var>Count</var>, or the list is sorted, an <link id="EStringListError"/>
exception will be raised.
</errors>
<seealso>
<link id="TStringList.Add"/>
<link id="TStrings.Insert"/>
<link id="TStringList.InsertObject"/>
</seealso>
</element>

<element name="TStringList.Sort">  <!-- Procedure -->
<short>Sorts the strings in the list.</short>
<descr>
<var>Sort</var> will sort the strings in the list using the quicksort
algorithm. If the list has its <link id="TStringList.Sorted"/> property set
to <var>True</var> then nothing will be done. 
</descr>
<seealso>
<link id="TStringList.Sorted"/>
</seealso>
</element>

<element name="TStringList.Duplicates">  <!-- Property -->
<short>Describes the behaviour of a sorted list with respect to duplicate
strings.</short>
<descr>
<p>
<var>Duplicates</var> describes what to do in case a duplicate value is
added to the list:
</p>
<table>
<tr><td>dupIgnore</td><td><printshort id="TDuplicates.dupIgnore"/></td></tr>
<tr><td>dupError</td><td><printshort id="TDuplicates.dupError"/></td></tr>
<tr><td>dupAccept</td><td><printshort id="TDuplicates.dupAccept"/></td></tr>
</table>
<p>
If the stringlist is not sorted, the <var>Duplicates</var> setting is
ignored.
</p>
</descr>
<seealso>
</seealso>
</element>

<element name="TStringList.Sorted">  <!-- Property -->
<short>Determines whether the list is sorted or not.</short>
<descr>
<p>
<var>Sorted</var> can be set to <var>True</var> in order to cause the list
of strings to be sorted. Further additions to the list will be inserted at
the correct position so the list remains sorted at all times. Setting the 
property to <var>False</var> has no immediate effect, but will allow strings
to be inserted at any position.
</p>
<remark>
<ol>
<li>
When <var>Sorted</var> is <var>True</var>, <link id="TStringList.Insert"/>
cannot be used. For sorted lists, <link id="TStringList.Add"/> should be
used instead.</li>
<li>If <var>Sorted</var> is <var>True</var>, the <link
id="TStringList.Duplicates"/> setting has effect. This setting is ignored
when <var>Sorted</var> is <var>False</var>.</li>
</ol>
</remark>
</descr>
<seealso>
<link id="TStringList.Sort"/>
<link id="TStringList.Duplicates"/>
<link id="TStringList.Add"/>
<link id="TstringList.Insert"/>
</seealso>
</element>

<element name="TStringList.OnChange">  <!-- Property -->
<short>Event triggered after the list was modified.</short>
<descr>
<p>
<var>OnChange</var> can be assigned to respond to changes that have occurred
in the list. The handler is called whenever strings are added, moved,
modified or deleted from the list. 
</p>
<p>
The <var>Onchange</var> event is triggered after the modification took place. 
When the modification is about to happen, an <link
id="TstringList.OnChanging"/> event occurs.
</p>
</descr>
<seealso>
<link id="TStringList.OnChanging"/>
</seealso>
</element>

<element name="TStringList.OnChanging">  <!-- Property -->
<short>Event triggered when the list is about to be modified.</short>
<descr>
<p>
<var>OnChanging</var> can be assigned to respond to changes that will occurred
in the list. The handler is called whenever strings will be added, moved,
modified or deleted from the list.
</p>
<p>
The <var>Onchanging</var> event is triggered before the modification will
take place. When the modification has happened, an <link           
id="TstringList.OnChange"/> event occurs.
</p>
</descr> 
<seealso>
<link id="TStringList.OnChange"/>
</seealso>
</element>

<!--
  *********************************************************************
  TStream
  *********************************************************************
-->

<element name="TStream">  <!-- Class -->
<short>Base class for streams.</short>
<descr>
<p>
<var>TStream</var> is the base class for all streaming classes. It defines
abstract methods for <link id="TStream.Read">reading</link>, <link
id="TStream.Write">writing</link> from and to streams, as well as functions to
determine the size of the stream as well as the current position of the
stream.
</p>
<p>Descendent classes such as <link id="TMemoryStream"/> or <link
id="TFileStream"/> then implement these abstract methods to write streams to
memory or file.
</p>
</descr>
<seealso>
<link id="TMemoryStream"/>
<link id="TFileStream"/>
<link id="TStringStream"/>
</seealso>
</element>

<element name="TStream.SetSize">  <!-- Procedure -->
<short>Sets the size of the stream</short>
<descr>
<var>SetSize</var> is the write handler for the <link id="TStream.Size"/>
property. The <var>TStream</var> implementation of <var>SetSize</var> does
nothing, but descendent classes may override this methods to allow
programmers to set the size of the stream.
</descr>
<seealso>
<link id="TStream.GetSize"/>
<link id="TStream.Size"/>
</seealso>
</element>

<element name="TStream.Read">  <!-- Function -->
<short>Reads data from the stream to a buffer and returns the number of
bytes read.</short>
<descr>
<p>
<var>Read</var> attempts to read <var>Count</var> from the stream to 
<var>Buffer</var> and returns the number of bytes actually read.
</p>
<p>This method should be used when the number of bytes is not determined. 
If a specific number of bytes is expected, use <link
id="TSTream.ReadBuffer"/> instead. 
</p>
<p>
<var>Read</var> is an abstract method that is overridden by descendent
classes to do the actual reading.
</p>
</descr>
<errors>
Descendent classes that do not allow reading from the stream may raise an
exception when the <var>Read</var> is used.
</errors>
<seealso>
<link id="TStream.Write"/>
<link id="TStream.ReadBuffer"/>
</seealso>
</element>

<element name="TStream.Write">  <!-- Function -->
<short>Writes data from the stream to the buffer and returns the number of
bytes written.</short>
<descr>
<p>
<var>Write</var> attempts to write <var>Count</var> bytes from
<var>Buffer</var> to the stream. It returns the actual number of bytes
written to the stream.
</p>
<p>This method should be used when the number of bytes that should be
written is not determined. If a specific number of bytes should be 
written, use <link id="TSTream.WriteBuffer"/> instead. 
</p>
<p>
<var>Write</var> is an abstract method that is overridden by descendent
classes to do the actual writinging.
</p>
</descr>
<errors>
Descendent classes that do not allow writing to the stream may raise an
exception when <var>Write</var> is used.
</errors>
<seealso>
<link id="TStream.Read"/>
<link id="TStream.WriteBuffer"/>
</seealso>
</element>

<element name="TStream.Seek">  <!-- Function -->
<short>Sets the current position in the stream</short>
<descr>
<p>
<var>Seek</var> sets the position of the stream to <var>Offset</var> bytes
from <var>Origin</var>. <var>Origin</var> can have one of the following
values:
</p>
<table>
<tr><td>Constant</td><td>Meaning</td></tr>
<tr><td>soFromBeginning</td><td>Set the position relative to the start of
the stream.</td></tr>
<tr><td>soFromCurrent</td><td>Set the position relative to the beginning of
the stream.</td></tr>
<tr><td>soFromEnd</td><td>Set the position relative to the end of the
stream.</td></tr>
</table>
<p>
<var>Offset</var> should be negative when the origin is <var>SoFromEnd</var>. 
It should be positive for <var>soFromBeginning</var> and can have both signs
for <var>soFromCurrent</var>
</p>
<p>
This is an abstract method, which must be overridden by descendent classes.
They may choose not to implement this method for all values of
<var>Origin</var> and <var>Offset</var>. 
</p>
</descr>
<errors>
An exception may be raised if this method is called with an invalid pair of
<var>Offset</var>,<var>Origin</var> values. e.g. a negative
<var>offset</var> for <var>soFromBeginning</var>.
</errors>
<seealso>
<link id="TStream.Position"/>
</seealso>
</element>

<element name="TStream.ReadBuffer">  <!-- Procedure -->
<short>Reads data from the stream to a buffer</short>
<descr>
<p>
<var>ReadBuffer</var> reads <var>Count</var> bytes of the stream into
<var>Buffer</var>. If the stream does not contain <var>Count</var> bytes,
then an exception is raised.
</p>
<p>
<var>ReadBuffer</var> should be used to read in a fixed number of bytes,
such as when reading structures or the content of variables. If the number
of bytes is not determined, use <link id="TStream.Read"/> instead.
<var>ReadBuffer</var> uses <var>Read</var> internally to do the actual
reading.
</p>
</descr>
<errors>
If the stream does not allow to read <var>Count</var> bytes, then an
exception is raised.
</errors>
<seealso>
<link id="TStream.Read"/>
<link id="TStream.WriteBuffer"/>
</seealso>
</element>

<element name="TStream.WriteBuffer">  <!-- Procedure -->
<short>Writes data from the stream to the buffer</short>
<descr>
<p>
<var>WriteBuffer</var> writes <var>Count</var> bytes to the stream from
<var>Buffer</var>. If the stream does not allow <var>Count</var> bytes to be
written, then an exception is raised.
</p>
<p>
<var>WriteBuffer</var> should be used to read in a fixed number of bytes,
such as when writing structures or the content of variables. If the number
of bytes is not determined, use <link id="TStream.Write"/> instead.
<var>WriteBuffer</var> uses <var>Write</var> internally to do the actual
reading.
</p>
</descr>
<errors>
If the stream does not allow to write <var>Count</var> bytes, then an
exception is raised.
</errors>
<seealso>
<link id="TStream.Write"/>
<link id="TStream.ReadBuffer"/>
</seealso>
</element>

<element name="TStream.CopyFrom">  <!-- Function -->
<short>Copy data from one stream to another</short>
<descr>
<p>
<var>CopyFrom</var> reads <var>Count</var> bytes from <var>Source</var> and
writes them to the current stream. This updates the current position in the
stream. After the action is completed, the number of bytes copied is
returned.
</p>
<p>
This can be used to quickly copy data from one stream to another or to copy
the whole contents of the stream.
</p>
</descr>
<seealso>
<link id="TStream.Read"/>
<link id="TStream.Write"/>
</seealso>
</element>

<element name="TStream.ReadComponent">  <!-- Function -->
<short>Reads component data from a stream</short>
<descr>
<p>
<var>ReadComponent</var> reads a component state from the stream and
transfers this state to <var>Instance</var>. If <var>Instance</var> is nil,
then it is created first based on the type stored in the stream.
<var>ReadComponent</var> returns the component as it is read from the stream.
</p>
<p>
<var>ReadComponent</var> simply creates a <link id="TReader"/> object and
calls its <link id="TReader.ReadRootComponent">ReadRootComponent</link>
method.
</p>
</descr>
<errors>
If an error occurs during the reading of the component, an <link
id="EFilerError"/> exception is raised.
</errors>
<seealso>
<link id="TStream.WriteComponent"/>
<link id="TStream.ReadComponentRes"/>
<link id="TReader.ReadRootComponent"/>
</seealso>
</element>

<element name="TStream.ReadComponentRes">  <!-- Function -->
<short>Reads component data and resource header from a stream</short>
<descr>
<p>
<var>ReadComponentRes</var> reads a resource header from the stream, and then
calls <link id="TStream.ReadComponent">ReadComponent</link> to read the
component state from the stream into <var>Instance</var>. 
</p>
<p>
This method is usually called by the global streaming method when
instantiating forms and datamodules as created by an IDE. It should be used
mainly on Windows, to store components in Windows resources.
</p>
</descr>
<errors>
If an error occurs during the reading of the component, an <link
id="EFilerError"/> exception is raised.
</errors>
<seealso>
<link id="TStream.ReadComponent"/>
<link id="TStream.WriteComponentRes"/>
</seealso>
</element>

<element name="TStream.WriteComponent">  <!-- Procedure -->
<short>Write component data to the stream</short>
<descr>
<p>
<var>WriteComponent</var> writes the published properties of
<var>Instance</var> to the stream, so they can later be read with <link
id="TStream.ReadComponent"/>. This method is intended to be used by an IDE,
to preserve the state of a form or datamodule as designed in the IDE.
</p>
<p>
<var>WriteComponent</var> simply calls <link
id="TStream.WriteDescendent">WriteDescendent</link> with <var>Nil</var>
ancestor.
</p>
</descr>
<seealso>
<link id="TStream.ReadComponent"/>
<link id="TStream.WriteComponentRes"/>
</seealso>
</element>

<element name="TStream.WriteComponentRes">  <!-- Procedure -->
<short>Write resource header and component data to a stream</short>
<descr>
<p>
<var>WriteComponentRes</var> writes a <var>ResName</var> resource header 
to the stream and then calls <link id="TStream.WriteComponent">WriteComponent</link> 
to write the published properties of <var>Instance</var> to the stream.
</p>
<p>
This method is intened for use by an IDE that can use it to store forms or
datamodules as designed in a Windows resource stream.
</p>
</descr>
<seealso>
<link id="TStream.WriteComponent"/>
<link id="TStream.ReadComponentRes"/>
</seealso>
</element>

<element name="TStream.WriteDescendent">  <!-- Procedure -->
<short>Write component data to a stream, relative to an ancestor</short>
<descr>
<p>
<var>WriteDescendent</var> writes the state of <var>Instance</var> to the
stream where it differs from <var>Ancestor</var>, i.e. only the changed 
properties are written to the stream.
</p>
<p>
<var>WriteDescendent</var> creates a <link id="TWriter"/> object and calls 
its <link id="TWriter.WriteDescendent">WriteDescendent</link> object. The
writer is passed a <link id="TBinaryObjectWriter">binary driver
object</link> by default. 
</p>
</descr>
<seealso>
</seealso>
</element>

<element name="TStream.WriteDescendentRes">  <!-- Procedure -->
<short>Write resource header and component data to a stream, relative to an ancestor</short>
<descr>
<p>
<var>WriteDescendentRes</var> writes a <var>ResName</var> resource header,
and then calls <link id="TStream.WriteDescendent">WriteDescendent</link> to
write the state of <var>Instance</var> to the
stream where it differs from <var>Ancestor</var>, i.e. only the changed
properties are written to the stream.
</p>
<p>
This method is intened for use by an IDE that can use it to store forms or
datamodules as designed in a Windows resource stream.
</p>
</descr>
<seealso>
</seealso>
</element>

<element name="TStream.WriteResourceHeader">  <!-- Procedure -->
<short>Write resource header to the stream</short>
<descr>
<p>
<var>WriteResourceHeader</var> writes a resource-file header for a resource
called <var>ResName</var>. It returns in <var>FixupInfo</var> the argument
that should be passed on to <link id="TStream.FixupResourceHeader"/>.
</p>
<p>
<var>WriteResourceHeader</var> should not be used directly. It is called by
the <link id="TStream.WriteComponentRes"/> and 
<link id="TStream.WriteDescendentRes"/>
methods.
</p>
</descr>
<seealso>
<link id="TStream.FixupResourceHeader"/>
<link id="TStream.WriteComponentRes"/>
<link id="TStream.WriteDescendentRes"/>
</seealso>
</element>

<element name="TStream.FixupResourceHeader">  <!-- Procedure -->
<short>Not implemented in FPC</short>
<descr>
<p>
<var>FixupResourceHeader</var> is used to write the size of the resource
after a component was written to stream. The size is determined from the
current position, and it is written at position <var>FixupInfo</var>. After
that the current position is restored.
</p>
<p>
<var>FixupResourceHeader</var> should never be called directly; it is
handled by the streaming system. 
</p>
</descr>
<seealso>
<link id="TStream.WriteResourceHeader"/>
<link id="TStream.WriteComponentRes"/>  
<link id="TStream.WriteDescendentRes"/>
</seealso>
</element>


<element name="TStream.ReadResHeader">  <!-- Procedure -->
<short>Read a resource header from the stream.</short>
<descr>
<p>
<var>ReadResourceHeader</var> reads a reasource file header from the stream.
It positions the stream just beyond the header.
</p>
<p>
<var>ReadResourceHeader</var> should not be called directly, it is called by
the streaming system when needed. 
</p>
</descr>
<errors>
If the resource header is invalid an <link id="EInvalidImage"/> exception is
raised.
</errors>
<seealso>
<link id="TStream.ReadComponentRes"/>
<link id="EInvalidImage"/>
</seealso>
</element>

<element name="TStream.ReadByte">  <!-- Function -->
<short>Read a byte from the stream and return its value.</short>
<descr>
<var>ReadByte</var> reads one byte from the stream and returns its value.
</descr>
<errors>
If the byte cannot be read, a <link id="EStreamError"/> exception will be
raised. This is a utility function which symply calls the
<link id="TStream.Read">Read</link> function.
</errors>
<seealso>
<link id="TStream.Read"/>
<link id="TStream.WriteByte"/>
<link id="TStream.ReadWord"/>
<link id="TStream.ReadDWord"/>
<link id="TStream.ReadAnsiString"/>
</seealso>
</element>


<element name="TStream.ReadWord">  <!-- Function -->
<short>Read a word from the stream and return its value.</short>
<descr>
<var>ReadWord</var> reads one Word (i.e. 2 bytes) from the stream 
and returns its value. This is a utility function which symply calls the
<link id="TStream.Read">Read</link> function.
</descr>
<errors>
If the word cannot be read, a <link id="EStreamError"/> exception will be
raised.
</errors>
<seealso>
<link id="TStream.Read"/>
<link id="TStream.WriteWord"/>
<link id="TStream.ReadByte"/>
<link id="TStream.ReadDWord"/>
<link id="TStream.ReadAnsiString"/>
</seealso>
</element>

<element name="TStream.ReadDWord">  <!-- Function -->
<short>Read a DWord from the stream and return its value.</short>
<descr>
<var>ReadDWord</var> reads one DWord (i.e. 4 bytes) from the stream 
and returns its value. This is a utility function which simply calls the
<link id="TStream.Read">Read</link> function.
</descr>
<errors>
If the DWord cannot be read, a <link id="EStreamError"/> exception will be
raised.
</errors>
<seealso>
<link id="TStream.Read"/>
<link id="TStream.WriteDWord"/>
<link id="TStream.ReadByte"/>
<link id="TStream.ReadWord"/>
<link id="TStream.ReadAnsiString"/>
</seealso>
</element>

<element name="TStream.ReadAnsiString">  <!-- Function -->
<short>Read an ansistring from the stream and return its value.</short>
<descr>
<var>ReadAnsiString</var> reads an ansistring from the stream 
and returns its value. This is a utility function which simply calls the
read function several times.

The Ansistring should be stored as 4 bytes (a DWord) representing the length
of the string, and then the string value itself. 
The <link id="TStream.WriteAnsiString">WriteAnsiString</link> function
writes an ansistring in such a format.
</descr>
<errors>
If the AnsiString cannot be read, a <link id="EStreamError"/> exception will be
raised.
</errors>
<seealso>
<link id="TStream.Read"/>
<link id="TStream.WriteAnsiString"/>
<link id="TStream.ReadByte"/>
<link id="TStream.ReadWord"/>
<link id="TStream.ReadDWord"/>
</seealso>
</element>

<element name="TStream.WriteByte">  <!-- Procedure -->
<short>Write a byte to the stream.</short>
<descr>
<var>WriteByte</var> writes the byte <var>B</var> to the stream. This is a
utility function which simply calls the <link
id="TStream.Write">Write</link> function.

The byte can be read from the stream using the <link
id="TStream.ReadByte">ReadByte</link> function.
</descr>
<errors>
If an error occurs when attempting to write, an <link id="EStreamError"/> exception will be raised.
</errors>
<seealso>
<link id="TStream.Write"/>
<link id="TStream.ReadByte"/>
<link id="TStream.WriteWord"/>
<link id="TStream.WriteDWord"/>
<link id="TStream.WriteAnsiString"/>
</seealso>
</element>

<element name="TStream.WriteWord">  <!-- Procedure -->
<short>Write a word to the stream.</short>
<descr>
<var>WriteWord</var> writes the word <var>W</var> (i.e. 2 bytes) to the stream. This is a
utility function which simply calls the <link
id="TStream.Write">Write</link> function.

The word can be read from the stream using the <link
id="TStream.ReadWord">ReadWord</link> function.
</descr>
<errors>
If an error occurs when attempting to write, an <link id="EStreamError"/> exception will be raised.
</errors>
<seealso>
<link id="TStream.Write"/>
<link id="TStream.ReadWord"/>
<link id="TStream.WriteByte"/>
<link id="TStream.WriteDWord"/>
<link id="TStream.WriteAnsiString"/>
</seealso>
</element>

<element name="TStream.WriteDWord">  <!-- Procedure -->
<short>Write a DWord to the stream.</short>
<descr>
<var>WriteDWord</var> writes the DWord <var>D</var> (i.e. 4 bytes) to the stream. This is a
utility function which simply calls the <link
id="TStream.Write">Write</link> function.

The DWord can be read from the stream using the <link
id="TStream.ReadDWord">ReadDWord</link> function.
</descr>
<errors>
If an error occurs when attempting to write, an <link id="EStreamError"/> exception will be raised.
</errors>
<seealso>
<link id="TStream.Write"/>
<link id="TStream.ReadDWord"/>
<link id="TStream.WriteByte"/>
<link id="TStream.WriteWord"/>
<link id="TStream.WriteAnsiString"/>
</seealso>
</element>

<element name="TStream.WriteAnsiString">  <!-- Procedure -->
<short>Write an ansistring to the stream.</short>
<descr>
<var>WriteAnsiString</var> writes the AnsiString <var>S</var> (i.e. 4 bytes) to the stream. This is a
utility function which simply calls the <link
id="TStream.Write">Write</link> function.

The ansistring is written as a 4 byte length specifier, followed by the
ansistring's content.

The ansistring can be read from the stream using the <link
id="TStream.ReadAnsiString">ReadAnsiString</link> function.
</descr>
<errors>
If an error occurs when attempting to write, an <link id="EStreamError"/> exception will be raised.
</errors>
<seealso>
<link id="TStream.Write"/>
<link id="TStream.ReadAnsiString"/>
<link id="TStream.WriteByte"/>
<link id="TStream.WriteWord"/>
<link id="TStream.WriteDWord"/>
</seealso>
</element>

<element name="TStream.Position">  <!-- Property -->
<short>The current position in the stream.</short>
<descr>
<p>
<var>Position</var> can be read to determine the current position in the
stream. It can be written to to set the (absolute) position in the stream.
The position is zero-based, so to set the position at the beginning of the
stream, the position must be set to zero. 
</p>
<remark>
Not all <var>TStream</var>  descendants support setting the position in the 
stream, so this should be used with care.
</remark>
</descr>
<errors>
Some descendents may raise an <link id="EStreamError"/> exception if they
do not support setting the stream position.
</errors>
<seealso>
<link id="TStream.Size"/>
<link id="TStream.Seek"/>
</seealso>
</element>

<element name="TStream.Size">  <!-- Property -->
<short>The current size of the stream.</short>
<descr>
<p>
<var>Size</var> can be read to determine the stream size or to set the
stream size. 
</p>
<remark>
Not all descendents of <var>TStream</var> support getting or setting the
stream size; they may raise an exception if the <var>Size</var> property 
is read or set.
</remark>
</descr>
<seealso>
<link id="TStream.Position"/>
<link id="TStream.Seek"/>
</seealso>
</element>

<!--
  *********************************************************************
  THandleStream
  *********************************************************************
-->

<element name="THandleStream">  <!-- Class -->
<short>Base clas for streams that are identified by an OS handle.</short>
<descr>
<p>
<var>THandleStream</var> is an abstract descendent of the <link
id="TStream"/>
class that provides methods for a stream to handle all reading and writing 
to and from a handle, provided by the underlying OS. To this end, it
overrides the <link id="THandleStream.Read">Read</link> and  <link
id="THandleStream.Write">Write</link> methods of TStream. 
</p>
<remark>
<ul>
<li>
<var>ThandleStream</var> does not obtain a handle from the OS by itself,
it just handles reading and writing to such a handle by wrapping the system
calls for reading and writing; 
Descendent classes should obtain a handle from the OS by themselves and pass it on in the inherited 
constructor.</li>
<li>
Contrary to Delphi, no seek is implemented for <var>THandleStream</var>,
since pipes and sockets do not support this. The seek is implemented in
descendent methods that support it.
</li>
</ul>
</remark>
</descr>
<seealso>
<link id="TStream"/>
<link id="TFileStream"/>
</seealso>
</element>

<element name="THandleStream.Create">  <!-- Constructor -->
<short>Create a handlestream from an OS Handle.</short>
<descr>
<var>Create</var> creates a new instance of a <var>THandleStream</var>
class. It stores <var>AHandle</var> in an internal variable and 
then calls the inherited constructor. 
</descr>
<seealso>
<link id="TStream"/>
</seealso>
</element>

<element name="THandleStream.Read">  <!-- Function -->
<short>Overrides standard read method.</short>
<descr>
<p>
<var>Read</var> implements the abstract <link id="TStream.Read">Read</link> 
method of <var>TStream</var>. It uses the <link
id="THandleStream.Handle">Handle</link> property to read the
<var>Count</var> bytes into <var>Buffer</var>
</p>
<p>
If no error occurs while reading, the number of bytes actually read will be
returned.
</p>
</descr>
<errors>
If the operating system reports an error while reading from the handle, -1
is returned.
</errors>
<seealso>
<link id="TStream.Read"/>
<link id="THandleStream.Write"/>
<link id="THandleStream.Handle"/>
</seealso>
</element>

<element name="THandleStream.Write">  <!-- Function -->
<short>Overrides standard write method.</short>
<descr>
<p>
<var>Write</var> implements the abstract <link id="TStream.Write">Write</link> 
method of <var>TStream</var>. It uses the <link
id="THandleStream.Handle">Handle</link> property to write the
<var>Count</var> bytes from <var>Buffer</var>. 
</p>
<p>
If no error occurs while writing, the number of bytes actually written will be
returned.
</p>
</descr>
<errors>
If the operating system reports an error while writing to handle, -1
is returned. 
</errors>
<seealso>
<link id="TStream.Read"/>
<link id="THandleStream.Write"/>
<link id="THandleStream.Handle"/>
</seealso>
</element>

<element name="THandleStream.Handle">  <!-- Property -->
<short>The OS handle of the stream.</short>
<descr>
<var>Handle</var> represents the Operating system handle to which reading 
and writing is done. The handle can be read only, i.e. it cannot be set
after the <var>THandlestream</var> instance  was created. It should be 
passed to the constructor <link id="THandleStream.Create"/>
</descr>
<seealso>
<link id="THandleStream"/>
<link id="THandleStream.Create"/>
</seealso>
</element>

<!--
  *********************************************************************
  TFileStream
  *********************************************************************
-->

<element name="TFileStream">  <!-- Class -->
<short>Stream that stores its data in a named file on disk.</short>
<descr>
<p>
<var>TFileStream</var> is a <link id="TStream"/> descdendent that
stores or reads it's data from a named file in the filesystem of 
the operating system.
</p>
<p>
To this end, it overrides some of the abstract methods in <var>TStream</var>
and implements them for the case of files on disk, and it adds the <link
id="TFileStream.Filename">FileName</link> property to the list of public
properties.
</p>
</descr>
<seealso>
<link id="TFileStream.Create"/>
<link id="TStream"/>
</seealso>
</element>

<element name="TFileStream.SetSize">  <!-- Procedure -->
<short>Sets the size of the file stream.</short>
<descr>
<p>
<var>SetSize</var> sets the size of the file at <var>NewSize</var> bytes.
Errors returned by the operating system call will be silently ignored.
</p>
<p>
This is the protected write method of the public <link id="TStream.Size"/>
property.
</p>
</descr>
<seealso>
<link id="TStream.Size"/>
</seealso>
</element>

<element name="TFileStream.Create">  <!-- Constructor -->
<short>Creates a file stream.</short>
<descr>
<p>
<var>Create</var> creates a new instance of a <var>TFileStream</var> class.
It opens the file <var>AFileName</var> with mode <var>Mode</var>, which can
have one of the following values:
</p>
<table>
<tr>
<td>fmCreate</td><td><printshort id="fmCreate"/></td>
</tr>
<tr>
<td>fmOpenRead</td><td><printshort id="fmOpenRead"/></td>
</tr>
<tr>
<td>fmOpenWrite</td><td><printshort id="fmOpenWrite"/></td>
</tr>
<tr>
<td>fmOpenReadWrite</td><td><printshort id="fmOpenReadWrite"/></td>
</tr>
</table>
<p>
After the file has been opened in the requested mode and a handle has been
obtained from the operating system, the inherited constructor is called.
</p>
</descr>
<errors>
If the file could not be opened in the requested mode, an <link
id="EFOpenError"/> exception is raised.
</errors>
<seealso>
<link id="TStream"/>
<link id="TFileStream.FileName"/>
<link id="THandleStream.Create"/>
</seealso>
</element>

<element name="TFileStream.Destroy">  <!-- Destructor -->
<short>Destroys the file stream.</short>
<descr>
<p>
<var>Destroy</var> closes the file (causing possible buffered data to be
written to disk) and then calls the inherited destructor.
</p>
<p>
Do not call <var>destroy</var> directly, instead call the <var>Free</var> 
method. Destroy does not check whether <var>Self</var> is nil, while
<var>Free</var> does.
</p>
</descr>
<seealso>
<link id="TFileStream.Create"/>
</seealso>
</element>

<element name="TFileStream.Seek">  <!-- Function -->
<short>Overrides the standard method.</short>
<descr>
<p>
<var>Seek</var> attempts to set the position of the stream at
<var>Offset</var> bytes from <var>Origin</var>. <var>Offset</var> can have
any integer value which would set the position within the boundaries of the
file, and thus the valid range depends on the value of <var>Origin</var>.
<var>Origin</var> can have one of the following values:
</p>
<table>
<tr>
<td>soFromBeginning</td><td><printshort id="soFromBeginning"/></td>
</tr>
<tr>
<td>soFromCurrent</td><td><printshort id="soFromCurrent"/></td>
</tr>
<tr>
<td>soFromEnd</td><td><printshort id="soFromEnd"/></td>
</tr>
</table>
<p>
<var>Seek</var> returns the new position in the file, or -1 on error.
</p>
</descr>
<errors>
On error, -1 is returned, and the position is not changed.
</errors>
<seealso>
<link id="TStream.Position"/>
<link id="TStream.Size"/>
</seealso>
</element>

<element name="TFileStream.FileName">  <!-- Property -->
<short>The filename of the stream.</short>
<descr>
<var>FileName</var> is the name of the file that the stream reads from or writes
to. It is the name as passed in the constructor of the stream; it cannot be
changed. To write to another file, the stream must be freed and created
again with the new filename.
</descr>
<seealso>
<link id="TFileStream.Create"/>
</seealso>
</element>

<!--
  *********************************************************************
  TCustomMemoryStream
  *********************************************************************
-->

<element name="TCustomMemoryStream">  <!-- Class -->
<short>Abstract stream that stores its data in memory.</short>
<descr>
<p>
<var>TCustomMemoryStream</var> is the parent class for streams that stored
their data in memory. It introduces all needed functions to handle reading
from and navigating through the memory, and introduces a 
<link id="TCustomMemoryStream.Memory">Memory</link> property which points to
the memory area where the stream data is kept. 
</p>
<p>
The only thing which <var>TCustomMemoryStream</var> does not do is obtain 
memory to store data when writing data  or the writing of data. This
functionality is implemented in descendent streams such as <link
id='TMemoryStream'/>. The reason for this approach is that this way it is
possible to create e.g. read-only descendents of
<var>TCustomMemoryStream</var> that point to a fixed part in memory which
can be read from, but not written to. 
</p>
<remark>
Since <var>TCustomMemoryStream</var> is an abstract class, do not create 
instances of <var>TMemoryStream</var> directly. Instead,
create instances of descendents such as <link id="TMemoryStream"/>. 
</remark>
</descr>
<seealso>
<link id="TMemoryStream"/>
<link id="TStream"/>
</seealso>
</element>

<element name="TCustomMemoryStream.SetPointer">  <!-- Procedure -->
<short>Sets the internal memory pointer and size of the memory block.</short>
<descr>
<p>
<var>SetPointer</var> updates the internal memory pointer and the size of
the memory area pointed to.  
</p>
<p>
Descendent memory streams should call this method whenever they set or reset
the memory the stream should read from or write to.
</p>
</descr>
<seealso>
<link id="TCustomMemoryStream.Memory"/>
<link id="TStream.Size"/>
</seealso>
</element>

<element name="TCustomMemoryStream.Read">  <!-- Function -->
<short>Reads <var>Count</var> bytes from the stream into <var>buffer</var>.</short>
<descr>
<p>
<var>Read</var> reads <var>Count</var> bytes from the stream into the memory
pointed to by <var>buffer</var>. It returns the number of bytes actually
read.
</p>
<p>
This method overrides the abstract <link id="TStream.Read"/> method of <link
id="TStream"/>. It will read as much bytes as are still available in the
memory area pointer to by <link id="TCustomMemoryStream.Memory">Memory</link>.
After the bytes are read, the internal stream position is updated.
</p>
</descr>
<seealso>
<link id="TCustomMemoryStream.Memory"/>
<link id="TStream.Read"/>
</seealso>
</element>

<element name="TCustomMemoryStream.Seek">  <!-- Function -->
<short>Sets a new position in the stream.</short>
<descr>
<var>Seek</var> overrides the abstract <link id="TStream.Seek"/> method.
It simply updates the internal stream position, and returns the new
position.
</descr>
<errors>
No checking is done whether the new position is still a valid position, i.e.
whether the position is still within the range <var>0..Size</var>.
Attempting a seek outside the valid memory range of the stream may result in
an exception at the next read or write operation.
</errors>
<seealso>
<link id="TStream.Position"/>
<link id="TStream.Size"/>
<link id="TCustomMemoryStream.Memory"/>
</seealso>
</element>

<element name="TCustomMemoryStream.SaveToStream">  <!-- Procedure -->
<short>Writes the contents of the memory stream to another stream.</short>
<descr>
<p>
<var>SaveToStream</var> writes the contents of the memory stream to  
<var>Stream</var>. The content of <var>Stream</var> is not cleared first.
The current position of the memory stream is not changed by this action.
</p>
<remark>
<p>
This method will work much faster than the use of the 
<link id="TStream.CopyFrom"/> method:
</p>
<code>
  Seek(0,soFromBeginning);
  Stream.CopyFrom(Self,Size);
</code>
<p>
because the <var>CopyFrom</var> method copies the contents in blocks, while
<var>SaveToStream</var> writes the contents of the memory as one big block.
</p>
</remark>
</descr>
<errors>
If an error occurs when writing to <var>Stream</var> an <link
id="EStreamError"/> exception will be raised.
</errors>
<seealso>
<link id="TCustomMemoryStream.SaveToFile"/>
<link id="TStream.CopyFrom"/>
</seealso>
</element>

<element name="TCustomMemoryStream.SaveToFile">  <!-- Procedure -->
<short>Writes the contents of the stream to a file.</short>
<descr>
<p>
<var>SaveToFile</var> writes the contents of the stream to a file with name
<var>FileName</var>.
It simply creates a filestream and writes the contents of the memorystream
to this file stream using <link id="TCustomMemoryStream.SaveToStream"/>.
</p>
<remark>
<p>
This method will work much faster than the use of the <link
id="TStream.CopyFrom"/> method:
</p>
<code>
  Stream:=TFileStream.Create(fmCreate,FileName);
  Seek(0,soFromBeginning);
  Stream.CopyFrom(Self,Size);
</code>
<p>
because the <var>CopyFrom</var> method copies the contents in blocks, while
<var>SaveToFile</var> writes the contents of the memory as one big block.
</p>
</remark>
</descr>
<errors>
If an error occurs when creating or writing to the file, an <link
id="EStreamError"/> exception may occur.
</errors>
<seealso>
<link id="TCustomMemoryStream.SaveToStream"/>
<link id="TFileStream"/>
<link id="TStream.CopyFrom"/>
</seealso>
</element>

<element name="TCustomMemoryStream.Memory">  <!-- Property -->
<short>Pointer to the data kept in the memory stream.</short>
<descr>
<p>
<var>Memory</var> points to the memory area where stream keeps it's data.
The property is read-only, so the pointer cannot be set this way.
</p>
<remark>
Do not write to the memory pointed to by <var>Memory</var>, since the memory
content may be read-only, and thus writing to it may cause errors.
</remark>
</descr>
<seealso>
<link id="TStream.Size"/>
</seealso>
</element>

<!--
  *********************************************************************
  TMemoryStream
  *********************************************************************
-->

<element name="TMemoryStream">  <!-- Class -->
<short>Standard implementation of a stream that stores its data in memory</short>
<descr>
<p>
<var>TMemoryStream</var> is a <link id="TStream"/> descendent that stores
it's data in memory. It descends directly from <link id="TCustomMemoryStream"/>
and implements the necessary to allocate and de-allocate memory diretly from
the heap. It implements the <link id="TMemoryStream.Write">Write</link> method
which is missing in <var>TCustomMemoryStream</var>.
</p>
<p>
<var>TMemoryStream</var> also introduces methods to load the contents of
another stream or a file into the memory stream.
</p>
<p>
It is not necessary to do any memory management manually, as the stream 
will allocate or de-allocate memory as needed. When the stream is freed, all
allocated memory will be freed as well.
</p>
</descr>
<seealso>
<link id="TCustomMemoryStream"/>
<link id="TStream"/>
</seealso>
</element>

<element name="TMemoryStream.Realloc">  <!-- Function -->
<short>Sets the new capacity for the memory stream</short>
<descr>
<p>
<var>SetCapacity</var> sets the capacity of the memory stream, i.e.
does the actual allocation or de-allocation of memory for the stream. It
allocates at least <var>NewCapacity</var> bytes on the heap, moves the 
current contents of the stream to this location (as much as fits in) and 
returns the new memory location. 
Extra allocated memory is not initialized, i.e. may contain garbage.
</p>
<p>
Memory is allocated in blocks of 4 Kb; this can be changed by overriding 
the method.
</p>
</descr>
<seealso>
<link id="TMemoryStream.Capacity"/>
</seealso>
</element>

<element name="TMemoryStream.Capacity">  <!-- Property -->
<short>Current capacity of the stream.</short>
<descr>
<p>
<var>Capacity</var> is the current capacity of the stream, this is the 
current size of the memory allocated to the stream. This is not necessarily
equal to the size of the stream, but will always be larger than or equal to
the size of the stream. When writing to the stream, the <link
id="TMemoryStream.Write"/> sets the capacity to the needed value.
</p>
<p>
If a lot of write operations will occur, performance may be improved by
setting the capacity to a large value, so less reallocations of memory will
occur while writing to the stream.
</p>
</descr>
<seealso>
<link id="TMemoryStream.ReAlloc"/>
</seealso>
</element>

<element name="TMemoryStream.Destroy">  <!-- Destructor -->
<short>Frees any allocated memory and destroys the memory stream.</short>
<descr>
<var>Free</var> clears the memory stream, thus in effect freeing any memory 
allocated for it, and then frees the memory stream.
</descr>
</element>

<element name="TMemoryStream.Clear">  <!-- Procedure -->
<short>Zeroes the position, capacity and size of the stream.</short>
<descr>
<var>Clear</var> sets the position and size to 0, and sets the capacity of
the stream to 0, thus freeing all memory allocated for the stream.
</descr>
<seealso>
<link id="TStream.Size"/>
<link id="TStream.Position"/>
<link id="TCustomMemoryStream.Memory"/>
</seealso>
</element>

<element name="TMemoryStream.LoadFromStream">  <!-- Procedure -->
<short>Loads the contents of a stream into memory.</short>
<descr>
<p>
<var>LoadFromStream</var> loads the contents of <var>Stream</var> into
the memorybuffer of the stream. Any previous contents of the memory 
stream are overwritten. Memory is allocated as needed.
</p>
<remark>
<p>
The <var>LoadFromStream</var> uses the <link id="TStream.Size">Size</link>
property of <var>Stream</var> to determine how much memory must be
allocated. Some streams do not allow the stream size to be determined, so
care must be taken when using this method.
</p>
<p>
This method will work much faster than the use of the <link
id="TStream.CopyFrom"/> method:
</p>
<code>
  Seek(0,soFromBeginning);
  CopyFrom(Stream,Stream.Size);
</code>
<p>
because the <var>CopyFrom</var> method copies the contents in blocks, while
<var>LoadFromStream</var> reads the contents of the stream as one big block.
</p>
</remark>
</descr>
<errors>
If an error occurs when reading from the stream, an <link
id="EStreamError"/> may occur.
</errors>
<seealso>
<link id="TStream.CopyFrom"/>
<link id="TMemoryStream.LoadFromFile"/>
</seealso>
</element>

<element name="TMemoryStream.LoadFromFile">  <!-- Procedure -->
<short>Loads the contents of a file into memory.</short>
<descr>
<p>
<var>LoadFromFile</var> loads the contents of the file with name
<var>FileName</var> into the memory stream. The current contents of the
memory stream is replaced by the contents of the file. Memory is allocated
as needed.
</p>
<p>
The <var>LoadFromFile</var> method simply creates a filestream and then
calls the <link id="TMemoryStream.LoadFromStream"/> method.
</p>
</descr>
If an error occurs when creating or reading from the stream, an <link
id="EStreamError"/> may occur.
<seealso>
<link id="TMemoryStream.LoadFromStream"/>
</seealso>
</element>

<element name="TMemoryStream.SetSize">  <!-- Procedure -->
<short>Sets the size for the memory stream.</short>
<descr>
<var>SetSize</var> sets the size of the memory stream to <var>NewSize</var>.
This will set the capacity of the stream to <var>NewSize</var> and correct
the current position in the stream when needed.
</descr>
<seealso>
<link id="TStream.Position"/>
<link id="TStream.Size"/>
</seealso>
</element>

<element name="TMemoryStream.Write">  <!-- Function -->
<short>Writes data to the stream's memory.</short>
<descr>
<p>
<var>Write</var> writes <var>Count</var> bytes from <var>Buffer</var>
to the stream's memory, starting at the current position in the stream.
If more memory is needed than currently allocated, more memory will be
allocated. Any contents in the memory stream at the current position will be
overwritten. The function returns the number of bytes actually written
(which should under normal circumstances always equal <var>Count</var>).
</p>
<p>
This method overrides the abstract <link id="TStream.Write"/> method.
</p>
</descr>
<errors>
If no more memory could be allocated, then an exception will be raised.
</errors>
<seealso>
<link id="TCustomMemoryStream.Read"/>
</seealso>

</element>

<!--
  *********************************************************************
  TStringStream
  *********************************************************************
-->

<element name="TStringStream">  <!-- Class -->
<short>Stream that stores its data in a string.</short>
<descr>
<p>
<var>TStringStream</var> stores its data in an ansistring. The contents of
this string is available as the 
<link id="TStringStream.DataString">DataString</link> property. It also
introduces some methods to read or write parts of the stringstream's data
as a string.
</p>
<p>The main purpose of a <var>TStringSTream</var> is to be able to treat a
string as a stream from which can be read.
</p>
</descr>
<seealso>
<link id="TStream"/>
<link id="TStringStream.DataString"/>
<link id="TStringStream.ReadString"/>
<link id="TStringStream.WriteString"/>
</seealso>
</element>

<element name="TStringStream.SetSize">  <!-- Procedure -->
<short>Sets the size of the stream.</short>
<descr>
<var>SetSize</var> sets the size of the stream to <var>newsize</var>. 
It does this by setting the size of the ansisting in which the stream 
is stored. <var>NewSize</var> can have any value greater than or equal to
zero.
</descr>
<errors>
In case there is not enough memory, an exception may be raised.
</errors>
<seealso>
<link id="TStream.Size"/>
</seealso>
</element>

<element name="TStringStream.Create">  <!-- Constructor -->
<short>Creates a new stringstream and sets its initial content.</short>
<descr>
<var>Create</var> creates a new <var>TStringStream</var> instance and
sets its initial content to <var>Astring</var>. The position is still 0 but
the size of the stream will equal the length of the string.
</descr>
<seealso>
<link id="TStringStream.DataString"/>
</seealso>
</element>

<element name="TStringStream.Read">  <!-- Function -->
<short>Reads from the stream.</short>
<descr>
<var>Read</var> implements the abstract <link id="TStream.Read">Read</link>
from <link id="TStream"/>. It tries to read <var>Count</var> bytes into
<var>Buffer</var>. It returns the number of bytes actually read. The
position of the stream is advanced with the number of bytes actually read;
When the reading has reached the end of the <link
id="TStringSTream.DataString">DataString</link>, then the reading stops,
i.e. it is not possible to read beyond the end of the datastring.
</descr>
<seealso>
<link id="TStream.Read"/>
<link id="TStringStream.Write"/>
<link id="TStringStream.DataString"/>
</seealso>
</element>

<element name="TStringStream.ReadString">  <!-- Function -->
<short>Reads a string of length <var>Count</var></short>
<descr>
<p>
<var>ReadString</var> reads <var>Count</var> bytes from the stream and
returns the read bytes as a string. If less than <var>Count</var> bytes 
were available, the string has as many characters as bytes could be read.
</p>
<p>The <var>ReadString</var> method is a wrapper around the <link
id="TStringStream.Read">Read</link> method. It does not do the same stringas
the <link id="TStream.ReadAnsiString"/> method, which first reads a length
integer to determine the length of the string to be read.
</p>
</descr>
<seealso>
<link id="TStringStream.Read"/>
<link id="TStream.ReadAnsiString"/>
</seealso>
</element>

<element name="TStringStream.Seek">  <!-- Function -->
<short>Sets the position in the stream.</short>
<descr>
<var>Seek</var> implements the abstract <link id="TStream.Seek">Seek</link>
method.
</descr>
<seealso>
</seealso>
</element>

<element name="TStringStream.Write">  <!-- Function -->
<short><var>Write</var> implements the abstract <link id="TStream.Write"/>
method.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TStringStream.WriteString">  <!-- Procedure -->
<short><var>WriteString</var> writes a string to the stream.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TStringStream.DataString">  <!-- Property -->
<short>Contains the contents of the stream in string form</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<!--
  *********************************************************************
  TResourceStream
  *********************************************************************
-->

<element name="TResourceStream">  <!-- Class -->
<short>Stream that reads its data from a resource object.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TResourceStream.Initialize">  <!-- Procedure -->
<short>Initializes the resource stream.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TResourceStream.Create">  <!-- Constructor -->
<short>Creates a new instance of a resource stream.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TResourceStream.CreateFromID">  <!-- Constructor -->
<short>Creates a new instance of a resource stream with resource</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TResourceStream.Destroy">  <!-- Destructor -->
<short>Destroys the instance of the resource stream.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TResourceStream.Write">  <!-- Function -->
<short><var>Write</var> implements the abstract <link id="TStream.Write"/>
method.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TValueType">  <!-- Enumeration type -->
<short>Enumerated type used to identify the kind of streamed property</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TValueType.vaNull">  <!-- Enumeration value -->
<short>Empty value. Ends a list.</short>
</element>

<element name="TValueType.vaList">  <!-- Enumeration value -->
<short>Identifies the start of a list of values</short>
</element>

<element name="TValueType.vaInt8">  <!-- Enumeration value -->
<short>Integer value, 8 bits long.</short>
</element>

<element name="TValueType.vaInt16">  <!-- Enumeration value -->
<short>Integer value, 16 bits long.</short>
</element>

<element name="TValueType.vaInt32">  <!-- Enumeration value -->
<short>Integer value, 32 bits long.</short>
</element>

<element name="TValueType.vaExtended">  <!-- Enumeration value -->
<short>Extended value.</short>
</element>

<element name="TValueType.vaString">  <!-- Enumeration value -->
<short>String value.</short>
</element>

<element name="TValueType.vaIdent">  <!-- Enumeration value -->
<short>Identifier.</short>
</element>

<element name="TValueType.vaFalse">  <!-- Enumeration value -->
<short>Boolean <var>False</var> value.</short>
</element>

<element name="TValueType.vaTrue">  <!-- Enumeration value -->
<short>Boolean <var>True</var> value.</short>
</element>

<element name="TValueType.vaBinary">  <!-- Enumeration value -->
<short>Binary data follows.</short>
</element>

<element name="TValueType.vaSet">  <!-- Enumeration value -->
<short>Set data follows.</short>
</element>

<element name="TValueType.vaLString">  <!-- Enumeration value -->
<short>Ansistring data follows.</short>
</element>

<element name="TValueType.vaNil">  <!-- Enumeration value -->
<short>Nil pointer.</short>
</element>

<element name="TValueType.vaCollection">  <!-- Enumeration value -->
<short>Collection follows</short>
</element>

<element name="TValueType.vaSingle">  <!-- Enumeration value -->
<short>Single type follows.</short>
</element>

<element name="TValueType.vaCurrency">  <!-- Enumeration value -->
<short>Currency value follows</short>
</element>

<element name="TValueType.vaDate">  <!-- Enumeration value -->
<short>Date value follows</short>
</element>

<element name="TValueType.vaWString">  <!-- Enumeration value -->
<short>Widestring value follows.</short>
</element>

<element name="TValueType.vaInt64">  <!-- Enumeration value -->
<short>Integer value, 64 bits long.</short>
</element>

<element name="TFilerFlag">  <!-- Enumeration type -->
<short>Flags used by the <link id="TFiler"/> class</short>
<descr>
The <var>TFiler</var> class uses this enumeration type to decide whether the
streamed object was streamed as part of an inherited form or not.
</descr>
<seealso>
<link id="TFiler"/>
</seealso>
</element>

<element name="TFilerFlag.ffInherited">  <!-- Enumeration value -->
<short>Stored object is an inherited object.</short>
</element>

<element name="TFilerFlag.ffChildPos">  <!-- Enumeration value -->
<short>The position of the child on it's parent is included.</short>
</element>

<element name="TFilerFlag.ffInline">  <!-- Enumeration value -->
<short>Used for frames.</short>
</element>

<element name="TFilerFlags">  <!-- Set type -->
<short>Set of <link id="TFilerFlag"/></short>
</element>

<element name="TReaderProc">  <!-- Procedure type -->
<short>Reader procedure used by <link id="TPersistent.DefineProperties">DefineProperties</link></short>
<descr>
The <var>TReaderProc</var> reader procedure is a callback procedure which 
will be used by a <link id="TPersistent"/> descendent to read user 
properties from a stream during the streaming process. The <var>Reader</var>
argument is the writer object which can be used read properties from the
stream.
</descr>
<seealso>
<Link id="TPersistent.DefineProperties"/>
</seealso>
</element>

<element name="TWriterProc">  <!-- Procedure type -->
<short>Writer procedure used by <link id="TPersistent.DefineProperties">DefineProperties</link></short>
<descr>
The <var>TWriterProc</var> writer procedure is a callback procedure which 
will be used by a <link id="TPersistent"/> descendent to write user 
properties from a stream during the streaming process. The <var>Writer</var>
argument is the writer object which can be used write properties to the
stream.
</descr>
<seealso>
<Link id="TPersistent.DefineProperties"/>
</seealso>
</element>

<element name="TStreamProc">  <!-- Procedure type -->
<short>Procedure type used in streaming.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<!--
  *********************************************************************
  TFiler
  *********************************************************************
-->

<element name="TFiler">  <!-- Class -->
<short>Class responsible for streaming of components.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TFiler.SetRoot">  <!-- Procedure -->
<short>Sets the root component which is being streamed.</short>
<descr>
Sets the root component. 
The root component is the initial component which is being streamed.
</descr>
<seealso>
</seealso>
</element>

<element name="TFiler.DefineProperty">  <!-- Procedure -->
<short></short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TFiler.DefineBinaryProperty">  <!-- Procedure -->
<short></short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TFiler.Root">  <!-- Property -->
<short>The root component is the initial component which is being streamed.
</short>
<descr>
The streaming process will stream a component and all the components which
it owns. The <var>Root</var> component is the component which is initially
streamed.
</descr>
<seealso>
<link id="TFiler.LookupRoot">LookupRoot</link>
</seealso>
</element>

<element name="TFiler.LookupRoot">  <!-- Property -->
<short>Component used to look up ancestor components.</short>
<descr>
When comparing inherited component's values against parent values, the
values are compared with the component in <var>LookupRoot</var>. Initially,
it is set to <link id="TFiler.Root">Root</link>.
</descr>
<seealso>
<link id="TFiler.Root">Root</link>
</seealso>
</element>

<element name="TFiler.Ancestor">  <!-- Property -->
<short>Ancestor component from which an inherited component is streamed.</short>
<descr>
When streaming a component, this is the parent component. Only properties
that differ from the parent's property value will be streamed.
</descr>
<seealso>
<link id="TFiler.Root">Root</link>
<link id="TFiler.LookupRoot">LookupRoot</link>
</seealso>
</element>

<element name="TFiler.IgnoreChildren">  <!-- Property -->
<short>Determines whether children will be streamed as well.</short>
<descr>
By default, all children (i.e. owned objects) will also be streamed when
streaming a component. This property can be used to prevent owned objects
from being streamed.
</descr>
</element>

<element name="TComponentClass">  <!-- "class of" type -->
<short>Class of TComponent</short>
<descr>
The <var>TComponentClass</var> type is used when constructing 
<link id="TComponent"/> descendent instances and when registering
components.
</descr>
<seealso>
<link id="TComponent"/>
</seealso>
</element>

<!--
  *********************************************************************
  TAbstractObjectReader
  *********************************************************************
-->

<element name="TAbstractObjectReader">  <!-- Class -->
<short>Abstract driver class to read stored component data.</short>
<descr>
<p>
The Free Pascal streaming mechanism, while compatible with Delphi's
mechanism, differs from it in the sense that the streaming mechanism uses
a driver class when streaming components. The <var>TAbstractObjectReader</var>
class is the base driver class for reading property values from streams.
It consists entirely of abstract methods, which must be implemented by
descendent classes.
</p>
<p>
Different streaming mechanisms can be implemented by making a descendent
from <var>TAbstractObjectReader</var>. The <link id="TBinaryObjectReader"/>
class is such a descendent class, which streams data in binary (Delphi
compatible) format.
</p>
<p>
All methods described in this class, mustbe implemented by descendent
classes.
</p>
</descr>
<seealso>
<link id="TBinaryObjectReader"/>
</seealso>
</element>

<element name="TAbstractObjectReader.NextValue">  <!-- Function -->
<short>Returns the type of the next value in the stream.</short>
<descr>
<p>
This function should return the type of the next value in the stream, 
but should not read it, i.e. the stream position should not be altered by
this method. This is used to 'peek' in the stream what value is next.
</p>
</descr>
<seealso>
<link id="TAbstractObjectReader.ReadValue"/>
</seealso>
</element>

<element name="TAbstractObjectReader.ReadValue">  <!-- Function -->
<short>Reads the type of the next value.</short>
<descr>
This function returns the type of the next value in the stream and reads it.
i.e. after the call to this method, the stream is positioned to read the
value of the type returned by this function.
</descr>
<seealso>
<link id="TAbstractObjectReader.ReadValue"/>
</seealso>
</element>

<element name="TAbstractObjectReader.BeginRootComponent">  <!-- Procedure -->
<short>Starts the reading of the root component.</short>
<descr>
This function can be used to initialize the driver class for reading a
component. It is called once at the beginning of the read process, and 
is immediatly followed by a call to <link
id="TAbstractObjectReader.BeginComponent">BeginComponent</link>.
</descr>
<seealso>
<link id="TAbstractObjectReader.BeginComponent"/>
</seealso>
</element>

<element name="TAbstractObjectReader.BeginComponent">  <!-- Procedure -->
<short>Marks the reading of a new component. </short>
<descr>
<p>
This method is called when the streaming process wants to start reading a 
new component. 
</p>
<p>
Descendent classes should override this method to read the start of a
component new component definition and return the needed arguments. 
<var>Flags</var> should be filled with any flags that were found at the
component definition, as well as <var>AChildPos</var>. The
<var>CompClassName</var> should be filled with the class name of the
streamed component, and the <var>CompName</var> argument should be filled
with the name of the component.
</p>
</descr>
<seealso>
<link id="TAbstractObjectReader.BeginRootComponent"/>
<link id="TAbstractObjectReader.BeginProperty"/>
</seealso>
</element>

<element name="TAbstractObjectReader.BeginProperty">  <!-- Function -->
<short>Marks the reading of a property value.</short>
<descr>
<var>BeginProperty</var> is called by the streaming system when it wants to
read a new property. The return value of the function is the name of the 
property which can be read from the stream.
</descr>
<seealso>
<link id="TAbstractObjectReader.BeginComponent"/>
</seealso>
</element>

<element name="TAbstractObjectReader.ReadBinary">  <!-- Procedure -->
<short>Read binary data from the stream.</short>
<descr>
<var>ReadBinary</var> is called when binary data should be read from the
stream 
(i.e. after <link id="TAbstractObjectReader.ReadValue">ReadValue</link> 
returned a valuetype of <var>vaBinary</var>). The data should be stored in the <var>DestData</var> memory stream
by descendent classes.
</descr>
<seealso>
<link id="TAbstractObjectReader.ReadFloat"/>
<link id="TAbstractObjectReader.ReadDate"/>
<link id="TAbstractObjectReader.ReadSingle"/>
<link id="TAbstractObjectReader.ReadIdent"/>
<link id="TAbstractObjectReader.ReadInt8"/>
<link id="TAbstractObjectReader.ReadInt16"/>
<link id="TAbstractObjectReader.ReadInt32"/>
<link id="TAbstractObjectReader.ReadInt64"/>
<link id="TabstractObjectReader.ReadSet"/>
<link id="TabstractObjectReader.ReadStr"/>
<link id="TabstractObjectReader.ReadString"/>
</seealso>
</element>

<element name="TAbstractObjectReader.ReadFloat">  <!-- Function -->
<short>Read a float value from the stream.</short>
<descr>
<var>ReadFloat</var> is called by the streaming system when it wants to read
a float from the stream (i.e. after <link id="TAbstractObjectReader.ReadValue">ReadValue</link> 
returned a valuetype of <var>vaExtended</var>). The return value should be the value of the float.
</descr>
<seealso>
<link id="TAbstractObjectReader.ReadFloat"/>
<link id="TAbstractObjectReader.ReadDate"/>
<link id="TAbstractObjectReader.ReadSingle"/>
<link id="TAbstractObjectReader.ReadIdent"/>
<link id="TAbstractObjectReader.ReadInt8"/>
<link id="TAbstractObjectReader.ReadInt16"/>
<link id="TAbstractObjectReader.ReadInt32"/>
<link id="TAbstractObjectReader.ReadInt64"/>
<link id="TabstractObjectReader.ReadSet"/>
<link id="TabstractObjectReader.ReadStr"/>
<link id="TabstractObjectReader.ReadString"/>
</seealso>
</element>

<element name="TAbstractObjectReader.ReadSingle">  <!-- Function -->
<short>Read a single (real-type) value from the stream.</short>
<descr>
<var>ReadSingle</var> is called by the streaming system when it wants to read
a single-type float from the stream  (i.e. after <link id="TAbstractObjectReader.ReadValue">ReadValue</link> 
returned a valuetype of <var>vaSingle</var>). The return value should be the value of 
the float.
</descr>
<seealso>
<link id="TAbstractObjectReader.ReadFloat"/>
<link id="TAbstractObjectReader.ReadDate"/>
<link id="TAbstractObjectReader.ReadSingle"/>
<link id="TAbstractObjectReader.ReadIdent"/>
<link id="TAbstractObjectReader.ReadInt8"/>
<link id="TAbstractObjectReader.ReadInt16"/>
<link id="TAbstractObjectReader.ReadInt32"/>
<link id="TAbstractObjectReader.ReadInt64"/>
<link id="TabstractObjectReader.ReadSet"/>
<link id="TabstractObjectReader.ReadStr"/>
<link id="TabstractObjectReader.ReadString"/>
</seealso>
</element>

<element name="TAbstractObjectReader.ReadDate">  <!-- Function -->
<short>Read a date value from the stream.</short>
<descr>
<var>ReadDate</var> is called by the streaming system when it wants to read
a date/time value from the stream  (i.e. after <link id="TAbstractObjectReader.ReadValue">ReadValue</link> 
returned a valuetype of <var>vaDate</var>). The return value should be the date/time
value. (This value can be stored as a float, since <var>TDateTime</var> is
nothing but a float.)
</descr>
<seealso>
<link id="TAbstractObjectReader.ReadFloat"/>
<link id="TAbstractObjectReader.ReadSingle"/>
<link id="TAbstractObjectReader.ReadIdent"/>
<link id="TAbstractObjectReader.ReadInt8"/>
<link id="TAbstractObjectReader.ReadInt16"/>
<link id="TAbstractObjectReader.ReadInt32"/>
<link id="TAbstractObjectReader.ReadInt64"/>
<link id="TabstractObjectReader.ReadSet"/>
<link id="TabstractObjectReader.ReadStr"/>
<link id="TabstractObjectReader.ReadString"/>
</seealso>
</element>

<element name="TAbstractObjectReader.ReadIdent">  <!-- Function -->
<short>Read an identifier from the stream.</short>
<descr>
<p>
<var>ReadIdent</var> is called by the streaming system if it expects to read
an identifier of type <var>ValueType</var> from the stream after a call to
<link id="TAbstractObjectReader.Readvalue">ReadValue</link> returned
<var>vaIdent</var>. The identifier 
should be returned as a string. Note that in some cases the identifier does 
not actually have to be in the stream;
</p>
<table>
<tr><td>ValueType</td><td>Expected value</td></tr>
<tr><td>vaIdent</td><td>Read from stream.</td></tr>
<tr><td>vaNil</td><td>'Nil'. This does not have to be read from the stream.</td></tr>
<tr><td>vaFalse</td><td>'False'. This does not have to be read from the stream.</td></tr>
<tr><td>vaTrue</td><td>'True'. This does not have to be read from the stream.</td></tr>
<tr><td>vaNull</td><td>'Null'. This does not have to be read from the stream.</td></tr>
</table>
</descr>
<seealso>
<link id="TAbstractObjectReader.ReadFloat"/>
<link id="TAbstractObjectReader.ReadDate"/>
<link id="TAbstractObjectReader.ReadSingle"/>
<link id="TAbstractObjectReader.ReadInt8"/>
<link id="TAbstractObjectReader.ReadInt16"/>
<link id="TAbstractObjectReader.ReadInt32"/>
<link id="TAbstractObjectReader.ReadInt64"/>
<link id="TabstractObjectReader.ReadSet"/>
<link id="TabstractObjectReader.ReadStr"/>
<link id="TabstractObjectReader.ReadString"/>
</seealso>
</element>

<element name="TAbstractObjectReader.ReadInt8">  <!-- Function -->
<short>Read an 8-bit integer from the stream.</short>
<descr>
<var>ReadInt8</var> is called by the streaming process if it expects to 
read an integer value with a size of 8 bits (1 byte) from the stream (i.e. after <link id="TAbstractObjectReader.ReadValue">ReadValue</link> 
returned a valuetype of <var>vaInt8</var>). 
The return value is the value if the integer. Note that the size of the
value in the stream does not actually have to be 1 byte.
</descr>
<seealso>
<link id="TAbstractObjectReader.ReadFloat"/>
<link id="TAbstractObjectReader.ReadDate"/>
<link id="TAbstractObjectReader.ReadSingle"/>
<link id="TAbstractObjectReader.ReadIdent"/>
<link id="TAbstractObjectReader.ReadInt16"/>
<link id="TAbstractObjectReader.ReadInt32"/>
<link id="TAbstractObjectReader.ReadInt64"/>
<link id="TabstractObjectReader.ReadSet"/>
<link id="TabstractObjectReader.ReadStr"/>
<link id="TabstractObjectReader.ReadString"/>
</seealso>
</element>

<element name="TAbstractObjectReader.ReadInt16">  <!-- Function -->
<short>Read a 16-bit integer from the stream.</short>
<descr>
<var>ReadInt16</var> is called by the streaming process if it expects to 
read an integer value with a size of 16 bits (2 bytes) from the stream (i.e. after <link id="TAbstractObjectReader.ReadValue">ReadValue</link> 
returned a valuetype of <var>vaInt16</var>). 
The return value is the value if the integer. Note that the size of the 
value in the stream does not actually have to be 2 bytes.
</descr>
<seealso>
<link id="TAbstractObjectReader.ReadFloat"/>
<link id="TAbstractObjectReader.ReadDate"/>
<link id="TAbstractObjectReader.ReadSingle"/>
<link id="TAbstractObjectReader.ReadIdent"/>
<link id="TAbstractObjectReader.ReadInt8"/>
<link id="TAbstractObjectReader.ReadInt32"/>
<link id="TAbstractObjectReader.ReadInt64"/>
<link id="TabstractObjectReader.ReadSet"/>
<link id="TabstractObjectReader.ReadStr"/>
<link id="TabstractObjectReader.ReadString"/>
</seealso>
</element>

<element name="TAbstractObjectReader.ReadInt32">  <!-- Function -->
<short>Read a 32-bit integer from the stream.</short>
<descr>
<var>ReadInt32</var> is called by the streaming process if it expects to 
read an integer value with a size of 32 bits (4 bytes) from the stream (i.e. after <link id="TAbstractObjectReader.ReadValue">ReadValue</link> 
returned a valuetype of <var>vaInt32</var>). 
The return value is the value of the integer. Note that the size of the 
value in the stream does not actually have to be 4 bytes.
</descr> 
<seealso>
<link id="TAbstractObjectReader.ReadFloat"/>
<link id="TAbstractObjectReader.ReadDate"/>
<link id="TAbstractObjectReader.ReadSingle"/>
<link id="TAbstractObjectReader.ReadIdent"/>
<link id="TAbstractObjectReader.ReadInt8"/>
<link id="TAbstractObjectReader.ReadInt16"/>
<link id="TAbstractObjectReader.ReadInt64"/>
<link id="TabstractObjectReader.ReadSet"/>
<link id="TabstractObjectReader.ReadStr"/>
<link id="TabstractObjectReader.ReadString"/>
</seealso>
</element>

<element name="TAbstractObjectReader.ReadInt64">  <!-- Function -->
<short>Read a 64-bit integer from the stream.</short>
<descr>
<var>ReadInt64</var> is called by the streaming process if it expects to 
read an int64 value with a size of 64 bits (8 bytes) from the stream (i.e. after <link id="TAbstractObjectReader.ReadValue">ReadValue</link> 
returned a valuetype of <var>vaInt64</var>). 
The return value is the value if the integer. Note that the size of the 
value in the stream does not actually have to be 8 bytes.
</descr>
<seealso>
<link id="TAbstractObjectReader.ReadFloat"/>
<link id="TAbstractObjectReader.ReadDate"/>
<link id="TAbstractObjectReader.ReadSingle"/>
<link id="TAbstractObjectReader.ReadIdent"/>
<link id="TAbstractObjectReader.ReadInt8"/>
<link id="TAbstractObjectReader.ReadInt16"/>
<link id="TAbstractObjectReader.ReadInt32"/>
<link id="TabstractObjectReader.ReadSet"/>
<link id="TabstractObjectReader.ReadStr"/>
<link id="TabstractObjectReader.ReadString"/>
</seealso>
</element>

<element name="TAbstractObjectReader.ReadSet">  <!-- Function -->
<short>Reads a set from the stream.</short>
<descr>
<p>
This method is called by the streaming system if it expects to read a 
set from the stream  (i.e. after <link id="TAbstractObjectReader.ReadValue">ReadValue</link> 
returned a valuetype of <var>vaSet</var>). The return value is the contents of the
set, encoded in a bitmask the following way:
</p>
<p> 
For each (enumerated) value in the set, the bit corresponding to the 
ordinal value of the enumerated value should be set. i.e. 
as <var>1 shl ord(value)</var>.
</p>
</descr>
<seealso>
<link id="TAbstractObjectReader.ReadFloat"/>
<link id="TAbstractObjectReader.ReadDate"/>
<link id="TAbstractObjectReader.ReadSingle"/>
<link id="TAbstractObjectReader.ReadIdent"/>
<link id="TAbstractObjectReader.ReadInt8"/>
<link id="TAbstractObjectReader.ReadInt16"/>
<link id="TAbstractObjectReader.ReadInt32"/>
<link id="TAbstractObjectReader.ReadInt64"/>
<link id="TabstractObjectReader.ReadStr"/>
<link id="TabstractObjectReader.ReadString"/>
</seealso>
</element>

<element name="TAbstractObjectReader.ReadStr">  <!-- Function -->
<short>Read a shortstring from the stream</short>
<descr>
<var>ReadStr</var> is called by the streaming system if it expects to read a
shortstring from the stream  (i.e. after <link id="TAbstractObjectReader.ReadValue">ReadValue</link> 
returned a valuetype of <var>vaLString</var>,<var>vaWstring</var> or 
<var>vaString</var>). The return value is the string.
</descr>
<seealso>
<link id="TAbstractObjectReader.ReadFloat"/>
<link id="TAbstractObjectReader.ReadDate"/>
<link id="TAbstractObjectReader.ReadSingle"/>
<link id="TAbstractObjectReader.ReadIdent"/>
<link id="TAbstractObjectReader.ReadInt8"/>
<link id="TAbstractObjectReader.ReadInt16"/>
<link id="TAbstractObjectReader.ReadInt32"/>
<link id="TAbstractObjectReader.ReadInt64"/>
<link id="TabstractObjectReader.ReadSet"/>
<link id="TabstractObjectReader.ReadString"/>
</seealso>
</element>

<element name="TAbstractObjectReader.ReadString">  <!-- Function -->
<short>Read a string of type <var>StringType</var> from the stream.</short>
<descr>
<var>ReadStr</var> is called by the streaming system if it expects to read a
string from the stream  (i.e. after <link id="TAbstractObjectReader.ReadValue">ReadValue</link> 
returned a valuetype of <var>vaLString</var>,<var>vaWstring</var> or 
<var>vaString</var>). The return value is the string.
</descr>
<seealso>
<link id="TAbstractObjectReader.ReadFloat"/>
<link id="TAbstractObjectReader.ReadDate"/>
<link id="TAbstractObjectReader.ReadSingle"/>
<link id="TAbstractObjectReader.ReadIdent"/>
<link id="TAbstractObjectReader.ReadInt8"/>
<link id="TAbstractObjectReader.ReadInt16"/>
<link id="TAbstractObjectReader.ReadInt32"/>
<link id="TAbstractObjectReader.ReadInt64"/>
<link id="TabstractObjectReader.ReadSet"/>
<link id="TabstractObjectReader.ReadStr"/>
</seealso>
</element>

<element name="TAbstractObjectReader.SkipComponent">  <!-- Procedure -->
<short>Skip till the end of the component.</short>
<descr>
This method is used to skip the entire declaration of a component in the
stream. Each descendent of <var>TAbstractObjectReader</var> should implement
this in a way which is optimal for the implemented stream format.
</descr>
<seealso>
<link id="TAbstractObjectReader.BeginComponent"/>
<link id="TAbstractObjectReader.SkipValue"/>
</seealso>
</element>

<element name="TAbstractObjectReader.SkipValue">  <!-- Procedure -->
<short>Skip the current value.</short>
<descr>
<var>SkipValue</var> should be used when skipping a value in the stream;
The method should determine the type of the value which should be skipped
by itself, if this is necessary.
</descr>
<seealso>
<link id="TAbstractObjectReader.SkipComponent"/>
</seealso>
</element>

<!--
  *********************************************************************
  TBinaryObjectReader
  *********************************************************************
-->

<element name="TBinaryObjectReader">  <!-- Class -->
<short>Driver class descendent which reads component data stored in binary format.</short>
<descr>
The <var>TBinaryObjectReader</var> class reads component data stored in 
binary form in a file. For this, it overrides or implements all abstract
methods from <link id="TAbstractObjectReader"/>. No new functionality is 
added by this class, it is a driver class for the streaming system.
</descr>
<seealso>
<link id="TAbstractObjectReader"/>
<link id="TBinaryObjectWriter"/>
</seealso>
</element>

<element name="TBinaryObjectReader.Create">  <!-- Constructor -->
<short>Creates a new binary data reader instance.</short>
<descr>
<var>Create</var> instantiates a new binary component data reader. The
<var>Stream</var> stream is the stream from which data will be read. The
<var>BufSize</var> argument is the size of the internal buffer that will be
used by the reader. This can be used to optimize the reading process.
</descr>
<seealso>
<link id="TAbstractObjectReader"/>
</seealso>
</element>

<element name="TBinaryObjectReader.Destroy">  <!-- Destructor -->
<short>Destroys the binary data reader.</short>
<descr>
<var>Destroy</var> frees the buffer allocated when the instance was created.
It also positions the stream on the last used position in the stream (the
buffering may cause the reader to read more bytes than were actually used.)
</descr>
<seealso>
<link id="TBinaryObjectReader.Create"/>
</seealso>
</element>

<element name="TFindMethodEvent">  <!-- Procedure type -->
<short>Occurs when the streaming process needs to locate a method</short>
<descr>
If a <link id="TReader"/> instance needs to locate a method and it doesn't
find it in the streamed form, then the <link
id="TReader.OnFindMethod">OnFindMethod</link> event handler will be called,
if one is installed. This event can be assigned in order to use different
locating methods. If a method is found, then its address should be returned
in <var>Address</var>. The <var>Error</var> should be set to <var>True</var> 
if the reader should raise an exception after the event was handled. If it 
is set to <var>False</var> no exception will be raised, even if no method
was found. On entry, <var>Error</var> will be set to <var>True</var>.
</descr>
</element>

<element name="TSetNameEvent">  <!-- Procedure type -->
<short>Occurs when the reader needs to set a component's name.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TReferenceNameEvent">  <!-- Procedure type -->
<short>Occurs when a named object needs to be looked up.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TAncestorNotFoundEvent">  <!-- Procedure type -->
<short>This event occurs when an ancestor component cannot be found.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TReadComponentsProc">  <!-- Procedure type -->
<short>Callback type when reading a component from a stream</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TReaderError">  <!-- Procedure type -->
<short>Event handler type, called when an error occurs during the streaming.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TFindComponentClassEvent">  <!-- Procedure type -->
<short>Event handler type, occurs when a component class pointer must be
found when reading a component from a stream.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TCreateComponentEvent">  <!-- Procedure type -->
<short>Event handler type, occurs when a component instance must be created
when a component is read from a stream.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<!--
  *********************************************************************
  TReader
  *********************************************************************
-->

<element name="TReader">  <!-- Class -->
<short>Generic reader object which reads component data from any given source.</short>
<descr>
The <var>TReader</var> class is a reader class that implements generic
component streaming capabilities, independent of the format of the data in
the stream. It uses a driver class <link id="TAbstractObjectReader"/> to
do the actual reading of data. The interface of the <var>TReader</var> class
should be identical to the interface in Delphi.
</descr>
<seealso>
<link id="TFiler"/>
<link id="TWriter"/>
<link id="TAbstractObjectReader"/>
</seealso>
</element>

<element name="TReader.Error">  <!-- Function -->
<short>Calls an installed error handler and passes it <var>Message</var></short>
<descr>
<p>
<var>Error</var> returns <var>False</var> if no <link id="TReader.OnError"/>
handler is installed. If one is installed, then it will be called, passing
the reader instance, message, and function return value as parameters.
</p>
<p>
If the function result <var>False</var>, i.e. when there is no handler
installed or the handler restured <var>False</var>, then the calling code
will raise an exception.
</p>
</descr>
<seealso>
<link id="TReader.FindMethod"/>
</seealso>
</element>

<element name="TReader.FindMethod">  <!-- Function -->
<short>Return the address of a published method.</short>
<descr>
<p>
<var>FindMethod</var> will search for the method in <var>ARoot</var>. If it
isn't found there, then it will call a <var>OnFindMethod</var> handler, if
one is installed, passing it the method name <var>AMethodName</var>, the
result pointer and a variable which says whether an exception should be
raised if no method with name <var>AMethodName</var> is found.
</p>
<p>
If the method cannot be found and the <link
id="TReader.OnFindMethod">OnFindMethod</link> returns <var>True</var>, then
an exception will be raised.
</p>
</descr>
<seealso>
<link id="TReader.OnFindMethod"/>
<link id="TFindMethodEvent"/>
</seealso>
</element>

<element name="TReader.ReadProperty">  <!-- Procedure -->
<short>Read and process a property name</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TReader.ReadPropValue">  <!-- Procedure -->
<short>Reads a property value for <var>PropInfo</var>.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TReader.PropertyError">  <!-- Procedure -->
<short>Skips a property value and raises an exception.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TReader.ReadData">  <!-- Procedure -->
<short>Reads the components data after it has been created.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TReader.PropName">  <!-- Property -->
<short>Name of the property being read at this moment.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TReader.CanHandleExceptions">  <!-- Property -->
<short>Indicates whether the reader is handling exceptions at this stage.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TReader.Create">  <!-- Constructor -->
<short>Creates a new reader class</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TReader.Destroy">  <!-- Destructor -->
<short>Destroys a reader class.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TReader.BeginReferences">  <!-- Procedure -->
<short>Initializes the component referencing mechanism.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TReader.CheckValue">  <!-- Procedure -->
<short>Raises an exception if the next value in the stream is not of type
<var>Value</var></short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TReader.DefineProperty">  <!-- Procedure -->
<short>Reads a user-defined property from the stream.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TReader.DefineBinaryProperty">  <!-- Procedure -->
<short>Reads a user-defined binary property from the stream.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TReader.EndOfList">  <!-- Function -->
<short>Returns true if the stream contains an end-of-list marker.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TReader.EndReferences">  <!-- Procedure -->
<short>Finalizes the component referencing mechanism.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TReader.FixupReferences">  <!-- Procedure -->
<short>Tries to resolve all unresolved component references.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TReader.NextValue">  <!-- Function -->
<short>Returns the type of the next value.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TReader.ReadBoolean">  <!-- Function -->
<short>Reads a boolean from the stream.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TReader.ReadChar">  <!-- Function -->
<short>Reads a character from the stream.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TReader.ReadCollection">  <!-- Procedure -->
<short>Reads a collection from the stream.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TReader.ReadComponent">  <!-- Function -->
<short>Starts reading a component from the stream.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TReader.ReadComponents">  <!-- Procedure -->
<short>Starts reading child components from the stream.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TReader.ReadFloat">  <!-- Function -->
<short>Reads a float from the stream.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TReader.ReadSingle">  <!-- Function -->
<short>Reads a single-type real from the stream.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TReader.ReadDate">  <!-- Function -->
<short>Reads a date from the stream</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TReader.ReadIdent">  <!-- Function -->
<short>Reads an identifier from the stream.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TReader.ReadInteger">  <!-- Function -->
<short>Reads an integer from the stream</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TReader.ReadInt64">  <!-- Function -->
<short>Reads a 64-bit integer from the stream.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TReader.ReadListBegin">  <!-- Procedure -->
<short>Checks for the beginning of a list.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TReader.ReadListEnd">  <!-- Procedure -->
<short>Checks for the end of a list.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TReader.ReadRootComponent">  <!-- Function -->
<short>Starts reading a root component.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TReader.ReadString">  <!-- Function -->
<short>Reads a string from the stream.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TReader.ReadValue">  <!-- Function -->
<short>Reads the next value type from the stream.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TReader.CopyValue">  <!-- Procedure -->
<short>Copy a value to a writer.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TReader.Owner">  <!-- Property -->
<short>Owner of the component being read</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TReader.Parent">  <!-- Property -->
<short>Parent of the component being read.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TReader.Driver">  <!-- Property -->
<short>The driver in use for streaming the data.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>



<element name="TReader.OnError">  <!-- Property -->
<short>Handler called when an error occurs.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TReader.OnFindMethod">  <!-- Property -->
<short>Handler to find or change a method address.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TReader.OnSetName">  <!-- Property -->
<short>Handler called when setting a component name.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TReader.OnReferenceName">  <!-- Property -->
<short>Handler called when another component is referenced.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TReader.OnAncestorNotFound">  <!-- Property -->
<short>Handler called when the ancestor component cannot be found.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TReader.OnCreateComponent">  <!-- Property -->
<short>Handler called when a component needs to be created.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TReader.OnFindComponentClass">  <!-- Property -->
<short>Handler called when a component class reference needs to be found.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<!--
  *********************************************************************
  TAbstractObjectWriter
  *********************************************************************
-->

<element name="TAbstractObjectWriter">  <!-- Class -->
<short>Abstract driver class for writing component data.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TAbstractObjectWriter.BeginCollection">  <!-- Procedure -->
<short>Start writing a collection.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TAbstractObjectWriter.BeginComponent">  <!-- Procedure -->
<short>Start writing a component</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TAbstractObjectWriter.BeginList">  <!-- Procedure -->
<short>Start writing a list.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TAbstractObjectWriter.EndList">  <!-- Procedure -->
<short>Mark the end of a list.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TAbstractObjectWriter.BeginProperty">  <!-- Procedure -->
<short>Start writing a property</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TAbstractObjectWriter.EndProperty">  <!-- Procedure -->
<short>Marks the end of writing of a property.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TAbstractObjectWriter.WriteBinary">  <!-- Procedure -->
<short>Writes binary data to the stream.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TAbstractObjectWriter.WriteBoolean">  <!-- Procedure -->
<short>Writes a boolean value to the stream.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TAbstractObjectWriter.WriteFloat">  <!-- Procedure -->
<short>Writes a float value to the stream.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TAbstractObjectWriter.WriteSingle">  <!-- Procedure -->
<short>Writes a single-type real value to the stream.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TAbstractObjectWriter.WriteDate">  <!-- Procedure -->
<short>Writes a date type to the stream.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TAbstractObjectWriter.WriteIdent">  <!-- Procedure -->
<short>Writes an identifier to the stream.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TAbstractObjectWriter.WriteInteger">  <!-- Procedure -->
<short>Writes an integer value to the stream</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TAbstractObjectWriter.WriteMethodName">  <!-- Procedure -->
<short>Writes a methodname to the stream.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TAbstractObjectWriter.WriteSet">  <!-- Procedure -->
<short>Writes a set value to the stream.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TAbstractObjectWriter.WriteString">  <!-- Procedure -->
<short>Writes a string value to the stream.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<!--
  *********************************************************************
  TBinaryObjectWriter
  *********************************************************************
-->

<element name="TBinaryObjectWriter">  <!-- Class -->
<short>Driver class which stores component data in binary form.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TBinaryObjectWriter.Create">  <!-- Constructor -->
<short>Creates a new instance of a binary object writer.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TBinaryObjectWriter.Destroy">  <!-- Destructor -->
<short>Destroys an instance of the binary object writer.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TBinaryObjectWriter.BeginCollection"
link="TAbstractObjectWriter.BeginCollection">  
<short>Start writing a collection.</short>
</element>

<element name="TBinaryObjectWriter.BeginComponent"
link="TAbstractObjectWriter.BeginComponent">  <!-- Procedure -->
<short>Start writing a component</short>
</element>

<element name="TBinaryObjectWriter.BeginList"
link="TAbstractObjectWriter.BeginList">  <!-- Procedure -->
<short>Start writing a list.</short>
</element>

<element name="TBinaryObjectWriter.EndList"
link="TAbstractObjectWriter.EndList">  <!-- Procedure -->
<short>Mark the end of a list.</short>
</element>

<element name="TBinaryObjectWriter.BeginProperty"
link="TAbstractObjectWriter.BeginProperty">  <!-- Procedure -->
<short>Start writing a property</short>
</element>

<element name="TBinaryObjectWriter.EndProperty"
link="TAbstractObjectWriter.EndProperty">  <!-- Procedure -->
<short>Marks the end of writing of a property.</short>
</element>

<element name="TBinaryObjectWriter.WriteBinary"
link="TAbstractObjectWriter.WriteBinary">  <!-- Procedure -->
<short>Writes binary data to the stream.</short>
</element>

<element name="TBinaryObjectWriter.WriteBoolean"
link="TAbstractObjectWriter.WriteBoolean">  <!-- Procedure -->
<short>Writes a boolean value to the stream.</short>
</element>

<element name="TBinaryObjectWriter.WriteFloat"
link="TAbstractObjectWriter.WriteFloat">  <!-- Procedure -->
<short>Writes a float value to the stream.</short>
</element>

<element name="TBinaryObjectWriter.WriteSingle"
link="TAbstractObjectWriter.WriteSingle">  <!-- Procedure -->
<short>Writes a single-type real value to the stream.</short>
</element>

<element name="TBinaryObjectWriter.WriteDate"
link="TAbstractObjectWriter.WriteDate">  <!-- Procedure -->
<short>Writes a date type to the stream.</short>
</element>

<element name="TBinaryObjectWriter.WriteIdent"
link="TAbstractObjectWriter.WriteIdent">  <!-- Procedure -->
<short>Writes an identifier to the stream.</short>
</element>

<element name="TBinaryObjectWriter.WriteInteger"
link="TAbstractObjectWriter.WriteInteger">  <!-- Procedure -->
<short>Writes an integer value to the stream.</short>
</element>

<element name="TBinaryObjectWriter.WriteMethodName"
link="TAbstractObjectWriter.WriteMethodName">  <!-- Procedure -->
<short>Writes a methodname to the stream.</short>
</element>

<element name="TBinaryObjectWriter.WriteSet"
link="TAbstractObjectWriter.WriteSet">  <!-- Procedure -->
<short>Writes a set value to the stream.</short>
</element>

<element name="TBinaryObjectWriter.WriteString"
link="TAbstractObjectWriter.WriteString">  <!-- Procedure -->
<short>Writes a string value to the stream.</short>
</element>

<!--
  *********************************************************************
  TTextObjectWriter
  *********************************************************************
-->

<element name="TTextObjectWriter">  <!-- Class -->
<short>Driver class which stores component data in text format.</short>
<descr>
Not yet implemented.
</descr>
<seealso>
</seealso>
</element>

<element name="TFindAncestorEvent">  <!-- Procedure type -->
<short>Event that occurs w</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<!--
  *********************************************************************
  TWriter
  *********************************************************************
-->

<element name="TWriter">  <!-- Class -->
<short>Object to write component data to an arbitrary format.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TWriter.SetRoot" link="TFiler.SetRoot">   <!-- Procedure -->
<short>Sets the root component</short>
</element>

<element name="TWriter.WriteBinary">  <!-- Procedure -->
<short>Writes binary data to the stream.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TWriter.WriteProperty">  <!-- Procedure -->
<short>Writes one property to the stream.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TWriter.WriteProperties">  <!-- Procedure -->
<short>Writes the published properties to the stream.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TWriter.Create">  <!-- Constructor -->
<short>Creates a new Writer instance with a driver.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TWriter.Create">  <!-- Constructor -->
<short>Creates a new Writer with a stream and bufsize.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TWriter.Destroy">  <!-- Destructor -->
<short>Destroys the writer instance.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TWriter.DefineProperty">  <!-- Procedure -->
<short>Callback used when defining and streaming custom properties.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TWriter.DefineBinaryProperty">  <!-- Procedure -->
<short>Callback used when defining and streaming custom properties.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TWriter.WriteBoolean">  <!-- Procedure -->
<short>Write boolean value to the stream.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TWriter.WriteCollection">  <!-- Procedure -->
<short>Write a collection to the stream.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TWriter.WriteComponent">  <!-- Procedure -->
<short>Stream a component to the stream.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TWriter.WriteChar">  <!-- Procedure -->
<short>Write a character to the stream.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TWriter.WriteDescendent">  <!-- Procedure -->
<short>Write a descendent component to the stream.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TWriter.WriteFloat">  <!-- Procedure -->
<short>Write a float to the stream.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TWriter.WriteSingle">  <!-- Procedure -->
<short>Write a single-type real to the stream.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TWriter.WriteDate">  <!-- Procedure -->
<short>Write a date to the stream.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TWriter.WriteIdent">  <!-- Procedure -->
<short>Write an identifier to the stream.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TWriter.WriteInteger">  <!-- Procedure -->
<short>Write an integer to the stream.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TWriter.WriteListBegin">  <!-- Procedure -->
<short>Write a start-of-list marker to the stream.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TWriter.WriteListEnd">  <!-- Procedure -->
<short>Write an end-of-list marker to the stream.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TWriter.WriteRootComponent">  <!-- Procedure -->
<short>Write a root component to the stream.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TWriter.WriteString">  <!-- Procedure -->
<short>Write a string to the stream.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TWriter.RootAncestor">  <!-- Property -->
<short>Ancestor of root component.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TWriter.OnFindAncestor">  <!-- Property -->
<short>Event occurring when an ancestor component must be found.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TWriter.Driver">  <!-- Property -->
<short>Driver used when writing to the stream.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<!--
  *********************************************************************
  TParser
  *********************************************************************
-->

<element name="TParser">  <!-- Class -->
<short>Class to parse the contents of a stream containing text data.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TParser.Create">  <!-- Constructor -->
<short>Creates a new parser instance.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TParser.Destroy">  <!-- Destructor -->
<short>Destroys the parser instance.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TParser.CheckToken">  <!-- Procedure -->
<short>Checks whether the token if of the given type.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TParser.CheckTokenSymbol">  <!-- Procedure -->
<short>Checks whether the token equals the given symbol</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TParser.Error">  <!-- Procedure -->
<short>Raises an <link id="EParserError"/> exception with the given message</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TParser.ErrorFmt">  <!-- Procedure -->
<short>Raises an <link id="EParserError"/> exception and formats the message.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TParser.ErrorStr">  <!-- Procedure -->
<short>Raises an <link id="EParserError"/> exception with the given message</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TParser.HexToBinary">  <!-- Procedure -->
<short>Writes hexadecimal data to the stream.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TParser.NextToken">  <!-- Function -->
<short>Reads the next token and returns its type.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TParser.SourcePos">  <!-- Function -->
<short>Returns the current position in the stream.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TParser.TokenComponentIdent">  <!-- Function -->
<short>Checks whether the current token is a component identifier.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TParser.TokenFloat">  <!-- Function -->
<short>Returns the current token as a float.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TParser.TokenInt">  <!-- Function -->
<short>Returns the current token as an integer.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TParser.TokenString">  <!-- Function -->
<short>Returns the current token as a string.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TParser.TokenSymbolIs">  <!-- Function -->
<short>Returns <var>True</var> if the current token is a symbol.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TParser.SourceLine">  <!-- Property -->
<short>Current source linenumber.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TParser.Token">  <!-- Property -->
<short>Contents of the current token.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<!--
  *********************************************************************
  EThread
  *********************************************************************
-->

<element name="EThread">  <!-- Class -->
<short>Thread error exception.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TThreadMethod">  <!-- Procedure type -->
<short>Procedure variable used when synchronizing threads.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TThreadPriority">  <!-- Enumeration type -->
<short>Enumeration specifying the priority at which a thread runs.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TThreadPriority.tpIdle">  <!-- Enumeration value -->
<short>Thread only runs when other processes are idle.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TThreadPriority.tpLowest">  <!-- Enumeration value -->
<short>Thread runs at the lowest priority.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TThreadPriority.tpLower">  <!-- Enumeration value -->
<short>Thread runs at a lower priority.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TThreadPriority.tpNormal">  <!-- Enumeration value -->
<short>Thread runs at normal process priority.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TThreadPriority.tpHigher">  <!-- Enumeration value -->
<short>Thread runs at high priority</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TThreadPriority.tpHighest">  <!-- Enumeration value -->
<short>Thread runs at highest possible priority.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TThreadPriority.tpTimeCritical">  <!-- Enumeration value -->
<short>Thread runs at realtime priority.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<!--
  *********************************************************************
  TThread
  *********************************************************************
-->
<element name="TThread">  <!-- Class -->
<short>Abstract Thread class.</short>
<descr>
The <var>TThread</var> class encapsulates the native thread support of the
operating system. To create a thread, declare a descendent of the
<var>TThread</var> object and override the <link
id="TThread.Execute">Execute</link> method. In this method, the thhread's
code should be executed. To run a thread, create an instance of the tthread
descendent, and call it's execute method.
</descr>
<seealso>
<link id="EThread"/>
<link id="TThread.Execute"/>
</seealso>
</element>

<element name="TThread.DoTerminate">  <!-- Procedure -->
<short>Terminates the thread.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TThread.Execute">  <!-- Procedure -->
<short>Execute method. Should be overridden in a descendent thread.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TThread.Synchronize">  <!-- Procedure -->
<short>Synchronizes the thread by executing the method in the main thread.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TThread.ReturnValue">  <!-- Property -->
<short>Return value of the thread when it stops executing.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TThread.Terminated">  <!-- Property -->
<short>Indicates whether the <link id="TThread.Terminate">Terminate</link>method was called by the user.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TThread.FStackPointer">  <!-- Variable -->
<short></short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TThread.FStackSize">  <!-- Variable -->
<short></short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TThread.FCallExitProcess">  <!-- Variable -->
<short></short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TThread.Create">  <!-- Constructor -->
<short>Creates a new thread.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TThread.Destroy">  <!-- Destructor -->
<short>Destroys the thread object.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TThread.Resume">  <!-- Procedure -->
<short>Resumes the thread's execution.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TThread.Suspend">  <!-- Procedure -->
<short>Suspends the thread's execution.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TThread.Terminate">  <!-- Procedure -->
<short>Signals the thread it should terminate.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TThread.WaitFor">  <!-- Function -->
<short>Waits for the thread to terminate and returns the exit status.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TThread.FreeOnTerminate">  <!-- Property -->
<short>Indicates whether the thread should free itself when it stops executing.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TThread.Handle">  <!-- Property -->
<short>Returns the thread handle.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TThread.Priority">  <!-- Property -->
<short>Returns the thread priority.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TThread.Suspended">  <!-- Property -->
<short>Indicates whether the thread is suspended.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TThread.ThreadID">  <!-- Property -->
<short>Returns the thread ID.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TThread.OnTerminate">  <!-- Property -->
<short>Event called when the thread terminates.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TOperation">  <!-- Enumeration type -->
<short>Operation of which a component is notified.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TOperation.opInsert">  <!-- Enumeration value -->
<short>A new component is being inserted in the child component list.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TOperation.opRemove">  <!-- Enumeration value -->
<short>A component is being removed from the child component list.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TComponentState">  <!-- Set type -->
<short>Indicates the state of the component during the streaming process.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TComponentState.csLoading">  <!-- Enumeration value -->
<short>The component is being loaded from the stream.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TComponentState.csReading">  <!-- Enumeration value -->
<short>Properties are being read from the stream.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TComponentState.csWriting">  <!-- Enumeration value -->
<short>Properties are being written to the stream.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TComponentState.csDestroying">  <!-- Enumeration value -->
<short>The component is being destroyed.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TComponentState.csDesigning">  <!-- Enumeration value -->
<short>The component is being designed in an IDE.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TComponentState.csAncestor">  <!-- Enumeration value -->
<short>The component is being streamed as part of a frame (?) </short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TComponentState.csUpdating">  <!-- Enumeration value -->
<short>The component is being updated.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TComponentState.csFixups">  <!-- Enumeration value -->
<short>The component's references to other components are being fixed.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TComponentState.csFreeNotification">  <!-- Enumeration value -->
<short>Indicates whether the component has freenotifications</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TComponentState.csInline">  <!-- Enumeration value -->
<short>Component is part of a frame (?).</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TComponentState.csDesignInstance">  <!-- Enumeration value -->
<short>??</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TComponentStyle">  <!-- Set type -->
<short>Describes the style of the component.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TComponentStyle.csInheritable">  <!-- Enumeration value -->
<short>The component can be on inherited forms.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TComponentStyle.csCheckPropAvail">  <!-- Enumeration value -->
<short>??</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TGetChildProc">  <!-- Procedure type -->
<short>Callback used when obtaining child components.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<!--
  *********************************************************************
  TComponent
  *********************************************************************
-->

<element name="TComponent">  <!-- Class -->
<short>Base class for all components that need owner-owned functionality.</short>
<descr>
<p>
<var>TComponent</var> is the base class for any set of classes that needs
owner-owned functionality, and which needs support for property streaming.
All classes that should be handled by an IDE (Integrated Development 
Environment) must descend from <var>TComponent</var>, as it includes all
support for streaming all its published properties.
</p>
<p>
Components can 'own' other components. <var>TComponent</var> introduces
methods for enumerating the child components. It also allows to name the
owned components with a unique name. Furthermore, functionality for 
sending notifications when a component is removed from the list or
removed from memory alltogether is also introduced in <var>TComponent</var>
</p>
<p>
<var>TComponent</var> introduces a form of automatic memory management: When
a component is destroyed, all its child components will be destroyed first.
</p>
</descr>
</element>


<element name="TComponent.FComponentStyle">  <!-- Variable -->
<short>Contains the component's style.</short>
<descr>
<var>FComponentStyle</var> is the location where the <link
id="TComponent.ComponentStyle">ComponentStyle</link> property is read from.
</descr>
<seealso>
</seealso>
<link id="TComponent.ComponentStyle">ComponentStyle</link>
</element>

<element name="TComponent.ChangeName">  <!-- Procedure -->
<short>Actually sets the component name.</short>
<descr>
<p>
<var>ChangeName</var> is called by the <link
id="TComponent.SetName">SetName</link> procedure when the component name is
set and the name has been verified. It actually sets  the name of the 
component to <var>NewName</var>, and can be used to bypass the name checks which are done when the
<link id="TComponent.Name">Name</link> property is set.
</p>
<p>
Application programmers should never use <var>SetName</var> directly.
</p>
</descr>
<seealso>
<link id="TComponent.SetName">SetName</link>
<link id="TComponent.Name">Name</link>
</seealso>
</element>

<element name="TComponent.DefineProperties">  <!-- Procedure -->
<short>Defines fake top,left properties for handling in the IDE.</short>
<descr>
<var>DefineProperties</var> overrides the standard <link
id="TPersistent.DefineProperties"/> to store the top/left properties used to
display an icon for a non-visual component in an IDE.
</descr>
<seealso>
<link id="TPersistent.DefineProperties"/>
</seealso>
</element>

<element name="TComponent.GetChildren">  <!-- Procedure -->
<short>Must be overridden by descendents to return all child components that must be streamed.</short>
<descr>
<p>
<var>GetChildren</var> is called by the streaming system to determine which
child components should be streamed as well when the component is being 
streamed. 
By default, no child components are streamed, i.e. the <var>TComponent</var>
implementation is empty.
</p>
<p>
<var>TComponent</var> descendents should override this method. For each
child that needs to be streamed, <var>Proc</var> should be called with as
an argument the child component that must be streamed. The <var>Root</var>
argument contains the root component relative to which all streaming is
done.
</p>
</descr>
<seealso>
<link id="TComponent.WriteState"/>
</seealso>
</element>

<element name="TComponent.GetChildOwner">  <!-- Function -->
<short>Returns the owner of any children.</short>
<descr>
<p>
<var>GetChildOwner</var> returns the owner of the children that are read from the stream.
If the method returns <var>Nil</var> (the default) this means that streamed
child components are owned by the root component of the streaming process
(usually a Form or Datamodule)
</p>
<p>
Application programmers should not call <var>GetChildOwner</var> directly,
it is called by the streaming system when needed.
</p>
</descr>
<seealso>
<link id="TComponent.WriteState"/>
<link id="TComponent.ReadState"/>
<link id="TComponent.Owner"/>
<link id="TComponent.GetChildParent"/>
</seealso>
</element>

<element name="TComponent.GetChildParent">  <!-- Function -->
<short>Returns the parent of any children.</short>
<descr>
<p>
<var>GetChildParent</var> returns the parent component of the child
components being streamed. The parent property is a visual property, which
is not always meaningful. If there is no parent component, the owner 
of child components that are streamed is returned. If <var>Nil</var> is
returned, then the root component of the streaming operation is assumed.
The <var>TComponent</var> implementation of this method returns
<var>Self</var>. 
</p>
<p>
Application programmers should not call this method, it is called
automatically by the streaming mechanism.
</p>
</descr>
<seealso>
<link id="TComponent.GetChildOwner"/>
</seealso>
</element>

<element name="TComponent.GetNamePath">  <!-- Function -->
<short>Returns the name path of this component.</short>
<descr>
<p>
<var>GetNamePath</var> returns the name of the component as it will be 
shown in the object inspector. 
</p>
<p>
<var>TComponent</var> overrides <var>GetNamePath</var> so it returns the
<link id="TComponent.Name">Name</link> property of the component.
</p>
</descr>
<seealso>
<link id="TComponent.Name">Name</link>
<link id="TPersistent.GetNamePath"/>
</seealso>
</element>

<element name="TComponent.GetOwner">  <!-- Function -->
<short>Returns the owner of this component.</short>
<descr>
<var>GetOwner</var> returns the owner of this component as indicated by the 
<link id="TComponent.Owner">Owner</link> property. The
<var>GetOwner</var> call is introduced in <link id="TPersistent"/>
and is used by the streaming system to determine the 'owner' of a component.
</descr>
<seealso>
<link id="TPersistent.GetOwner"/>
<link id="TComponent.Owner"/>
</seealso>
</element>

<element name="TComponent.Loaded">  <!-- Procedure -->
<short>Called when the component has finished loading.</short>
<descr>
<p>
<var>Loaded</var> is called by the streaming system when a root
component was completely read from a stream and all properties and 
references to other objects have been resolved by the streaming 
system. Descendents of <var>TComponent</var> should override this method to
do some additional processing of properties after all published 
properties have been set from values obtained from the stream.
</p>
<p>
Application programmers should never call <var>Loaded</var> directly, this
is done automatically by the streaming system.
</p>
</descr>
<seealso>
<link id="TComponent.ReadState"/>
<link id="TComponent.ComponentState"/>
</seealso>
</element>

<element name="TComponent.Notification">  <!-- Procedure -->
<short>Called by components that are freed and which received a FreeNotification.</short>
<descr>
<p>
<var>Notification</var> is called whenever a child component is destroyed,
inserted or removed from the list of owned component. Components that
were requested to send a notification when they are freed 
((with <link id="TComponent.FreeNotification">FreeNotification</link>)
will also call <var>Notification</var> when they are freed.
</p>
<p>The <var>AComponent</var> parameter specifies which component sends the
notification, and <var>Operation</var> specifies whether the component is
being inserted into or removed from the child component list, or whether it
is being destroyed.
</p>
<p>
Descendents of <var>TComponent</var> can use <link
id="TComponent.FreeNotification">FreeNotification</link> to request
notification of the destruction of another object. By overriding the
<var>Notification</var> method, they can do special processing (typically,
set a reference to this component to <var>Nil</var>) 
when this component is destroyed. The <var>Notification</var> method is
called quite often in the streaming process, so speed should be a
consideration when overriding this method.
</p> 
</descr>
<seealso>
<link id="TOperation"/>
<link id="TComponent.FreeNotification"/>
</seealso>
</element>

<element name="TComponent.ReadState">  <!-- Procedure -->
<short>Read the component's state from a stream.</short>
<descr>
<p>
<var>ReadState</var> reads the component's state from a stream through the
reader object <var>reader</var>. Values for all published properties of 
the component can be read from the stream. Normally there is no need to 
call <var>ReadState</var> directly. The streaming system calls 
<var>ReadState</var> itself. 
</p>
<p>
The <link id="TComponent"/> implementation of <var>ReadState</var> simply
calls <link id="TReader.ReadData"/> Descendent classes can, however, 
override  <var>ReadState</var>to provide additional processing of stream 
data.
</p>
</descr>
<seealso>
<link id="TComponent.WriteState">WriteState</link>
<link id="TStream.ReadComponent"/>
<link id="TReader.ReadData"/>
</seealso>
</element>

<element name="TComponent.SetAncestor">  <!-- Procedure -->
<short>Sets the <var>csAncestor</var> state of the component.</short>
<descr>
<p>
<var>SetAncestor</var> includes or excludes the <var>csAncestor</var> flag
in the <link id="TComponent.ComponentState">ComponentState</link> set property, 
depending on the boolean <var>Value</var>. The flag is set recursively for
all owned components as well.
</p>
<p>
This is normally only done during the streaming system, and should not be called 
directly by an application programmer.
</p>
</descr>
<seealso>
<link id="TComponent.ComponentState">ComponentState</link>
</seealso>
</element>

<element name="TComponent.SetDesigning">  <!-- Procedure -->
<short>Sets the <var>csDesigning</var> state of the component.</short>
<descr>
<p>
<var>SetDesigning</var> includes or excludes the <var>csDesigning</var> flag
in the <link id="TComponent.ComponentState">ComponentState</link> set property, 
depending on the boolean <var>Value</var>. The flag is set recursively for
all owned components as well.
</p>
<p>
This is normally only done during the streaming system, and should not be called 
directly by an application programmer.
</p>
</descr>
<seealso>
</seealso>
</element>

<element name="TComponent.SetName">  <!-- Procedure -->
<short>Write handler for <link id="TComponent.Name">Name</link> property.</short>
<descr>
<var>SetName</var> is the write handler for the <link
id="TComponent.Name">Name</link> property. It checks whether the desired
name is valid (i.e is a valid identifier) and is unique among the children
of the owner component. If either conditions is not satisfied, an exception
is raised.
</descr>
<seealso>
<link id="TComponent.Name">Name</link>
<link id="TComponent.ValidateRename">ValidateRename</link>
</seealso>
</element>

<element name="TComponent.SetChildOrder">  <!-- Procedure -->
<short>Determines the order in which children are streamed/created.</short>
<descr>
This method does nothing. It can be used to change the order in which child
components are streamed and created. This can be used by descendent classes
to optimize or correct the order in which child components are streamed.
</descr>
<seealso>
<link id="TComponent.ReadState"/>
</seealso>
</element>

<element name="TComponent.SetParentComponent">  <!-- Procedure -->
<short>Set the parent component.</short>
<descr>
<var>SetParentComponent</var> does nothing, but is called by the streaming
system to set the parent component of the current component. This method
can be overridden by descendent components to set the parent component of
the current component.
</descr>
<seealso>
<link id="TComponent.Owner">Owner</link>
</seealso>
</element>

<element name="TComponent.Updating">  <!-- Procedure -->
<short>Sets the state to <var>csUpdating</var></short>
<descr>
<p>
<var>Updating</var> includes <var>csUpdating</var> in the <link
id="TComponent.ComponentState">ComponentState</link> property of the
component.
</p>
<p>
Normally, an application programmer should not call this method directly, it
is called automatically by the streaming system.
</p>
</descr>
<seealso>
<link id="TComponent.Updated">Updated</link>
<link id="TComponent.ComponentState">ComponentState</link>
</seealso>
</element>

<element name="TComponent.Updated">  <!-- Procedure -->
<short>Ends the <var>csUpdating</var> state.</short>
<descr>
<p>
<var>Updated</var> excludes <var>csUpdating</var> from the <link
id="TComponent.ComponentState">ComponentState</link> property of the
component.
</p>
<p>
Normally, an application programmer should not call this method directly, it
is called automatically by the streaming system.
</p>
</descr>
<seealso>
<link id="TComponent.Updating">Updating</link>
<link id="TComponent.ComponentState">ComponentState</link>
</seealso>
</element>

<element name="TComponent.UpdateRegistry">  <!-- Procedure -->
<short>For compatibilty only.</short>
<descr>
This method does nothing, and is provided for compatibility only.
</descr>
<seealso>
</seealso>
</element>

<element name="TComponent.ValidateRename">  <!-- Procedure -->
<short>Called when a name change must be validated</short>
<descr>
<var>ValidateRename</var> checks whether <var>NewName</var> is a valid 
replacement for <var>CurName</var> for component <var>AComponent</var>.
Two owned components of a component can not have the same name. 
If a child component with the same name is found, then an exception 
is raised.
</descr>
<seealso>
<link id="TComponent.SetName">SetName</link>
<link id="TComponent.Name">Name</link>
</seealso>
</element>

<element name="TComponent.ValidateContainer">  <!-- Procedure -->
<short>??</short>
<descr>
<var>ValidateContainer</var> is provided for compatibility only. 
It doesn't do anything in Free Pascal.
</descr>
</element>

<element name="TComponent.ValidateInsert">  <!-- Procedure -->
<short>Called when an insert must be validated.</short>
<descr>
<p>
<var>ValidateInsert</var> should be implemented by descendent components to
see whether the <var>AComponent</var> component may be inserted in the list
of owned components. 
</p>
<p>
This procedure does nothing in the <var>TComponent</var> implementation, it
should be overridden by descendant components.
</p>
</descr>

<seealso>
<link id="TComponent.Insert">Insert</link>
</seealso>
</element>

<element name="TComponent.WriteState">  <!-- Procedure -->
<short>Writes the component to a stream.</short>
<descr>
<p>
<var>WriteState</var> writes the component's current state to a stream 
through the <link id="TWriter">writer</link> object <var>writer</var>. 
Values for all published properties of the component can be written to 
the stream. Normally there is no need to call <var>WriteState</var> directly. 
The streaming system calls  <var>WriteState</var> itself. 
</p>
<p>
The <link id="TComponent"/> implementation of <var>WriteState</var> simply
calls <link id="TWriter.WriteData"/>. Descendent classes can, however, 
override  <var>WriteState</var>to provide additional processing of stream 
data.
</p>
</descr>
<seealso>
<link id="TComponent.ReadState">ReadState</link>
<link id="TStream.WriteComponent"/>
<link id="TWriter.WriteData"/>
</seealso>
</element>

<element name="TComponent.Create">  <!-- Constructor -->
<short>Creates a new instance of the component.</short>
<descr>
<var>Create</var> creates a new instance of a <var>TComponent</var> class.
If <var>AOwner</var> is not <var>Nil</var>, the new component attempts to 
insert itself in the list of owned components of the owner.
</descr>
<seealso>
<link id="TComponent.Insert">Insert</link>
<link id="TComponent.Owner">Owner</link>
</seealso>
</element>

<element name="TComponent.Destroy">  <!-- Destructor -->
<short>Destroys the instance of the component.</short>
<descr>
<var>Destroy</var> sends a <var>opRemove</var> notification to all components 
in the free-notification list. After that, all owned components are
destroyed by calling <link id="TComponent.DestroyComponents">DestroyComponents</link> 
(and hence removed from the list of owned components). When this
is done, the component removes itself from its owner's child component list.
After that, the parent's destroy method is called.
</descr>
<seealso>
<link id="TComponent.Notification">Notification</link>
<link id="TComponent.Owner">Owner</link>
<link id="TComponent.DestroyComponents">DestroyComponents</link>
<link id="TComponent.Components">Components</link>
</seealso>
</element>

<element name="TComponent.DestroyComponents">  <!-- Procedure -->
<short>Destroy child components.</short>
<descr>
<p>
<var>DestroyComponents</var> calls the destructor of all owned components,
till no more components are left in the <link id="TComponent.Components">Components</link> array.
</p>
<p>
Calling the destructor of an owned component has as the effect that the
component will remove itself from the list of owned components, if nothing
has disrupted the sequence of destructors.
</p>
</descr>
<errors> 
If an overridden 'destroy' method does not call it's intherited 
destructor or raises an exception, it's <link id="TComponent.Destroy"/> 
destructor will not be called, which may result in an endless loop.
</errors>
<seealso>
<link id="TComponent.Destroy">Destroy</link>
<link id="TComponent.Components">Components</link>
</seealso>
</element>

<element name="TComponent.Destroying">  <!-- Procedure -->
<short>Called when the component is being destroyed</short>
<descr>
<p>
<var>Destroying</var> sets the <var>csDestroying</var> flag in the
component's <link id="TComponent.State">state</link> property, and does the
same for all owned components.
</p>
<p>
It is not necessary to call <var>Destroying</var> directly, the destructor <link
id="TComponent.Destroy">Destroy</link> does this automatically.
</p>
</descr>
<seealso>
<link id="TComponent.State">State</link>
<link id="TComponent.Destroy">Destroy</link>
</seealso>
</element>

<element name="TComponent.FindComponent">  <!-- Function -->
<short>Finds and returns the named component in the owned components.</short>
<descr>
<var>FindComponent</var> searches the component with name <var>AName</var>
in the list of owned components. If <var>AName</var> is empty, then
<var>Nil</var> is returned.
</descr>
<seealso>
<link id="TComponent.Components">Components</link>
<link id="TComponent.Name">Name</link>
</seealso>
</element>

<element name="TComponent.FreeNotification">  <!-- Procedure -->
<short>Ask the component to notify called when it is being destroyed.</short>
<descr>
<var>FreeNotification</var> inserts <var>AComponent</var> in the
freenotification list. When the component is destroyed, the <link
id="TComponent.Notification">Notification</link> method is called for all
components in the freenotification list.
</descr>
<seealso>
<link id="TComponent.Components">Components</link>
<link id="TComponent.Notification">Notification</link>
</seealso>
</element>

<element name="TComponent.FreeOnRelease">  <!-- Procedure -->
<short>Part of the <var>IVCLComObject</var> interface.</short>
<descr>
Provided for Delphi compatibility, but is not yet impltmentedd.
</descr>
</element>

<element name="TComponent.GetParentComponent">  <!-- Function -->
<short>Returns the parent component.</short>
<descr>
<var>GetParentComponent</var> can be implemented to return the parent
component of this component. The implementation of this method in
<var>TComponent</var> always returns <var>Nil</var>. Descendent classes must
override this method to return the visual parent of the component.
</descr>
<seealso>
<link id="TComponent.HasParent">HasParent</link>
<link id="TComponent.Owner">Owner</link>
</seealso>
</element>

<element name="TComponent.HasParent">  <!-- Function -->
<short>Does the component have a parent ?</short>
<descr>
<var>HasParent</var> can be implemented to return whether the parent of the
component exists. The implementation of this method in TComponent always
returns <var>False</var>, and should be overridden by descendent classes to
return <var>True</var> when a parent is available. If <var>HasParent</var>
returns <var>True</var>, then <link
id="TComponent.GetParentComponent">GetParentComponent</link> will return the
parent component.
</descr>
<seealso>
<link id="TComponent.HasParent">HasParent</link>
<link id="TComponent.Owner">Owner</link>
</seealso>
</element>

<element name="TComponent.InsertComponent">  <!-- Procedure -->
<short>Insert the given component in the list of owned components.</short>
<descr>
<var>InsertComponent</var> attempts to insert <var>AComponent</var> in the
list with owned components. It first calls <link
id="TComponent">ValidateComponent</link> to see whether the component can be
inserted. It then checks whether there are no name conflicts by calling
<link id="TComponent.ValidateRename">ValidateRename</link>. If neither of
these checks have raised an exception the component is inserted, and
notified of the insert.
</descr>
<seealso>
<link id="TComponent.RemoveComponent">RemoveComponent</link>
<link id="TComponent.Insert">Insert</link>
<link id="TComponent.ValidateContainer">ValidateContainer</link>
<link id="TComponent.ValidateRename">ValidateRename</link>
<link id="TComponent.Notification">Notification</link>
</seealso>
</element>

<element name="TComponent.RemoveComponent">  <!-- Procedure -->
<short>Remove the given component from the list of owned components.</short>
<descr>
<var>RemoveComponent</var> will send an <var>opRemove</var> notification to
<var>AComponent</var> and will then proceed to remove <var>AComponent</var> 
from the list of owned components. 
</descr>
<seealso>
<link id="TComponent.InsertComponent">InsertComponent</link>
<link id="TComponent.Remove">Remove</link>
<link id="TComponent.ValidateRename">ValidateRename</link>
<link id="TComponent.Notification">Notification</link>
</seealso>
</element>

<element name="TComponent.SafeCallException">  <!-- Function -->
<short>Part of the <var>IVCLComObject</var> Interface.</short>
<descr>
Provided for Delphi compatibility, but not implemented.
</descr>
<seealso>
</seealso>
</element>

<element name="TComponent.Components">  <!-- Property -->
<short>Indexed list (zero-based) of all owned components.</short>
<descr>
<var>Components</var> provides indexed access to the list of owned
components. <var>Index</var> can range from 0 to <link
id="TComponent.ComponentCount">ComponentCount-1</link>.
</descr>
<seealso>
<link id="TComponent.ComponentCount">ComponentCount</link>
<link id="TComponent.Owner">Owner</link>
</seealso>
</element>

<element name="TComponent.ComponentCount">  <!-- Property -->
<short>Count of owned components</short>
<descr>
<var>ComponentCount</var> returns the number of components that the current
component owns. It can be used to determine the valid index range in the
<link id="TComponent.Components">Component</link> array.
</descr>
<seealso>
<link id="TComponent.Components">Components</link>
<link id="TComponent.Owner">Owner</link>
</seealso>
</element>

<element name="TComponent.ComponentIndex">  <!-- Property -->
<short>Index of component in it's owner's list.</short>
<descr>
<var>ComponentIndex</var> is the index of the current component in its
owner's list of components. If the component has no owner, the value of this
property is -1.
</descr>
<seealso>
<link id="TComponent.Components">Components</link>
<link id="TComponent.ComponentCount">ComponentCount</link>
<link id="TComponent.Owner">Owner</link>
</seealso>
</element>

<element name="TComponent.ComponentState">  <!-- Property -->
<short>Current component's state.</short>
<descr>
<p>
<var>ComponentState</var> indicates the current state of the component. It
is a set of flags which indicate the various stages in the lifetime of a
component. The following values can occur in this set:
</p>
<table>
<caption>Component states</caption>
<th><td>Flag</td><td>Meaning</td></th>
<tr><td>csLoading</td><td>The component is being loaded from stream</td></tr>
<tr><td>csReading</td><td>Component properties are being read from stream.</td></tr>
<tr><td>csWriting</td><td>Component properties are weing written to stream.</td></tr>
<tr><td>csDestroying</td><td>The component or one of it's owners is being destoyed.</td></tr>
<tr><td>csAncestor</td><td>The component is being streamed as part of a frame </td></tr>
<tr><td>csUpdating</td><td>The component is being updated</td></tr>
<tr><td>csFixups</td><td>References to other components are being resolved</td></tr>
<tr><td>csFreeNotification</td><td>The component has freenotifications.</td></tr>
<tr><td>csInline</td><td>The component is being loaded as part of a frame</td></tr>
<tr><td>csDesignInstance</td><td>? not used.</td></tr>
</table>
<p>
The component state is set by various actions such as reading it from stream,
destroying it etc.
</p>
</descr>
<seealso>
<link id="TComponent.SetAncestor">SetAncestor</link>
<link id="TComponent.SetDesigning">SetDesigning</link>
<link id="TComponent.SetInline">SetInline</link>
<link id="TComponent.SetDesignInstance">SetDesignInstance</link>
<link id="TComponent.Updating">Updating</link>
<link id="TComponent.Updated">Updated</link>
<link id="TComponent.Loaded">Loaded</link>
</seealso>
</element>

<element name="TComponent.ComponentStyle">  <!-- Property -->
<short>Current component's style.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="TComponent.DesignInfo">  <!-- Property -->
<short>Information for IDE designer.</short>
<descr>
<var>DesignInformation</var> can be used by an IDE to store design
information in the component. It should not be used by an application
programmer. 
</descr>
<seealso>
<link id="TComponent.Tag">Tag</link>
</seealso>
</element>

<element name="TComponent.Owner">  <!-- Property -->
<short>Owner of this component.</short>
<descr>
<var>Owner</var> returns the owner of this component. The owner cannot be
set except by explicitly inserting the component in another component's
owned components list using that component's <link
id="TComponent.InsertComponent">InsertComponent</link> method, or by
removing the component from it's owner's owned component list using the
<link id="TComponent.RemoveComponent">RemoveComponent</link> method.
</descr>
<seealso>
<link id="TComponent.Components">Components</link>
<link id="TComponent.InsertComponent">InsertComponent</link>
<link id="TComponent.RemoveComponent">RemoveComponent</link>
</seealso>
</element>

<element name="TComponent.VCLComObject">  <!-- Property -->
<short>Not implemented.</short>
<descr>
<var>VCLComObject</var> is not yet implemented in Free Pascal.
</descr>
</element>

<element name="TComponent.Name">  <!-- Property -->
<short>Name of the component.</short>
<descr>
<var>Name</var> is the name of the component. This name should be a valid
identifier, i.e. must start with a letter, and can contain only letters,
numbers and the underscore character. When attempting to set the name of a
component, the name will be checked for validity. Furthermore, when a
component is owned by another component, the name must be either empty
or must be unique among the child component names.
</descr>
<errors>
Attempting to set the name to an invalid value will result in an exception
being raised.
</errors>
<seealso>
<link id="TComponent.ValidateRename">ValidateRename</link>
<link id="TComponent.Owner">Owner</link>
</seealso>
</element>

<element name="TComponent.Tag">  <!-- Property -->
<short>Tag value of the component.</short>
<descr>
<var>Tag</var> can be used to store an integer value in the component. This
value is streamed together with all other published properties. It can be
used for instance to quickly identify a component in an event handler.
</descr>
<seealso>
<link id="TComponent.Name">Name</link>
</seealso>
</element>

<!--
  *********************************************************************
  TBasicAction
  *********************************************************************
-->

<element name="TBasicAction">
<short>Abstract base class for all Actions.</short>
<descr>
<p>
<var>TBasicAction</var> implements a basic action class from which all
actions are derived. It introduces all basic methods of an action, and
implements functionality to maintain a list of clients, i.e. components that
are connected with this action.
</p>
<p>
Do not create instances of <var>TBasicAction</var>. Instead, create a
descendent class and create an instance of this class instead.
</p>
</descr>
<seealso>
<link id="TBasicActionLink"/>
<link id="TComponent"/>
</seealso>
</element>


<element name="TBasicAction.FClients">
<short>List with components linked to this action.
</short>
<descr>
<var>FClients</var> is a list of <link id="TBasicActionLink"/> classes which
represent links to various components that are connected to this action.
The elements in this list should not be manipulated directly, but should be
managed with the 
<link id="TBasicAction.RegisterChanges">RegisterChanges</link> and 
<link id="TBasicAction.UnRegisterChanges">UnRegisterChanges</link> methods.
</descr>
<seealso>
<link id="TBasicAction.RegisterChanges">RegisterChanges</link>
<link id="TBasicAction.UnRegisterChanges">UnRegisterChanges</link>
<link id="TBasicActionLink"/>
</seealso>
</element>

<element name="TBasicAction.Change">
<short>Calls the <link id="TBasicAction.OnChange">OnChange</link> handler.</short>
<descr>
<p>
<var>Change</var> calls the <link id="TBasicAction.OnChange">OnChange</link>
handler if one is assigned.
</p>
<p>
Application programmers should not call <var>Change</var> directly.
It is called automatically if a property of an action component changes.
</p>
<p>
Descendent classes of <var>TBasicAction</var> should call explicitly call
<var>Change</var> if one of their properties that affect client controls
changes its value.
</p>
</descr>
</element>

<element name="TBasicAction.SetOnExecute">
<short>Assigns an <link id="TBasicAction.OnExecute">OnExecute</link> event
handler</short>
<descr>
<var>SetOnExecute</var> sets the 
<link id="TBasicAction.OnExecute">OnExecute</link> handler of the component.
It also propagates this event to all client controls, and finally triggers
the <link id="TBasicAction.OnChange">OnChange</link> event.
</descr>
<seealso>
<link id="TBasicAction.OnExecute">OnExecute</link>
<link id="TBasicAction.OnChange">OnChange</link>
</seealso>
</element>

<element name="TBasicAction.OnChange">
<short>Occurs when one of the action's properties changes.
</short>
<descr>
<p>
<var>OnChange</var> is the event that is triggered when one of the
action's properties changes. This event should be used by client 
controls or descendent classes to respond to these changes in the properties
of the action.
</p>
<p>
Application programmers should never use the <var>OnChange</var> event
directly.
</p>
</descr>
</element>

<element name="TBasicAction.Create">
<short>Creates a new instance of a <link id="TBasicAction"/> class.
</short>
<descr>
<p>
<var>Create</var> calls the inherited constructor, and then initializes the 
list of clients controls (or action lists) by adding the <var>AClient</var>
argument to the list of client controls.
</p>
<p>
Under normal circumstances it should not be necessary to create a
<var>TBasicAction</var> descendent manually, actions are created in an IDE.
</p>
</descr>
<seealso>
<link id="TBasicAction.Destroy">Destroy</link>
<link id="TBasicAction.AssignClient">AssignClient</link>
</seealso>
</element>

<element name="TBasicAction.Destroy">
<short>Destroys the action.</short>
<descr>
<p>
<var>Destroy</var> cleans up the list of client controls and then calls the
inherited destructor.
</p>
<p>
An application programmer should not call <var>Destroy</var> directly;
Instead <var>Free</var> should be called, if it needs to be called at all.
Normally the controlling class (e.g. a TActionList) will destroy the action.
</p>
</descr>
</element>

<element name="TBasicAction.HandlesTarget">
<short>Determines whether <var>Target</var> can be handled by this action
</short>
<descr>
<p>
<var>HandlesTarget</var> returns <var>True</var> if <var>Target</var> is 
a valid client for this action and if so, if it is in a suitable state to
execute the action. An application programmer should never need to call
<var>HandlesTarget</var> directly, it will be called by the action itself
when needed.
</p>
<p>
In <var>TBasicAction</var> this method is empty; descendent classes should
override this method to implement appropriate checks.
</p>
</descr>
<seealso>
<link id="TBasicAction.UpdateTarget">UpdateTarget</link>
<link id="TBasicAction.ExecuteTarget">ExecuteTarget</link>
</seealso>
</element>

<element name="TBasicAction.UpdateTarget">
<short>Notify client controls when the action updates itself.</short>
<descr>
<p>
<var>UpdateTarget</var> should update the client control specified by
<var>Target</var> when the action updates itself. 
In <var>TBasicAction</var>, the implementation of <var>UpdateTarget</var> 
is empty. Descendent classes should override and implement 
<var>UpdateTarget</var> to actually update the <var>Target</var> object.
</p>
<p>
An application programmer should never need to call
<var>HandlesTarget</var> directly, it will be called by the action itself
when needed.
</p>
</descr>
<seealso>
<link id="TBasicAction.HandlesTarget">HandlesTarget</link>
<link id="TBasicAction.ExecuteTarget">ExecuteTarget</link>
</seealso>
</element>

<element name="TBasicAction.ExecuteTarget">
<short>Executes the action on the <var>Target</var> object</short>
<descr>
<p>
<var>ExecuteTarget</var> performs the action on the <var>Target</var>
object. In <var>TBasicAction</var> this method does nothing. Descendent
classes should implement the action to be performed. For instance an action
to post data in a dataset could call the <var>Post</var> method of the
dataset.
</p>
<p>
An application programmer should never call <var>ExecuteTarget</var>
directly.
</p>
</descr>
<seealso>
<link id="TBasicAction.HandlesTarget">HandlesTarget</link>
<link id="TBasicAction.ExecuteTarget">UpdateTarget</link>
<link id="TBasicAction.Execute">Execute</link>
</seealso>
</element>

<element name="TBasicAction.Execute">
<short>Triggers the <link id="TBasicAction.OnExecute">OnExecute</link> event</short>
<descr>
<var>Execute</var> triggers the <var>OnExecute</var> event, if one is
assigned. It returns <var>True</var> if the event handler was called,
<var>False</var> otherwise.
</descr>
</element>

<element name="TBasicAction.RegisterChanges">
<short>Registers a new client with the action.</short>
<descr>
<var>RegisterChanges</var> adds <var>Value</var> to the list of clients. 
</descr>
<seealso>
<link id="TBasicAction.UnregisterChanges">UnregisterChanges</link>
</seealso>
</element>

<element name="TBasicAction.UnregisterChanges">
<short>Unregisters a client from the list of clients</short>
<descr>
<var>UnregisterChanges</var> removes <var>Value</var> from the list of clients.
This is called for instance when the action is destroyed, or when the client
is assigned a new action.
</descr>
<seealso>
<link id="TBasicAction.UnregisterChanges">UnregisterChanges</link>
<link id="TBasicAction.Destroy">Destroy</link>
</seealso>
</element>

<element name="TBasicAction.Update">
<short>Triggers the <link id="TBasicAction.OnUpdate">OnUpdate</link> event</short>
<descr>
<p>
<var>Update</var> triggers the <var>OnUpdate</var> event, if one is
assigned. It returns <var>True</var> if the event was triggered, or
<var>False</var> if no event was assigned.
</p>
<p>
Application programmers should never run <var>Update</var> directly. The
<var>Update</var> method is called automatically by the action mechanism;
Normally this is in the Idle time of an application. An application
programmer should assign the <link id="TBasicAction.OnUpdate">OnUpdate</link>
event, and perform any checks in that handler.
</p>
</descr>
<seealso>
<link id="TBasicAction.OnUpdate">OnUpdate</link>
<link id="TBasicAction.Execute">Execute</link>
<link id="TBAsicAction.UpdateTarget">UpdateTarget</link>
</seealso>
</element>

<element name="TBasicAction.ActionComponent">
<short>Returns the component that initiated the action.</short>
<descr>
<var>ActionComponent</var> is set to the component that caused the action to
execute, e.g. a toolbutton or a menu item. 
The property is set just before the action executes, and is reset to nil 
after the action was executed.
</descr>
<seealso>
<link id="TBasicAction.Execute">Execute</link>
<link id="TBasicAction.OnExecute">OnExecute</link>
</seealso>
</element>

<element name="TBasicAction.OnExecute">
<short>Event triggered when the action executes.</short>
<descr>
<p>
<var>OnExecute</var> is the event triggered when the action is activated
(executed). The event is triggered e.g. when the user clicks e.g. on a menu
item or a button associated to the action. The application programmer 
should provide a <var>OnExecute</var> event handler to execute whatever code
is necessary when the button is pressed or the menu item is chosen.
</p>
<p>
Note that assigning an <var>OnExecute</var> handler will result in the
<link id="TBasicAction.Execute">Execute</link> method returning a
<var>True</var> value. Predefined actions (such as dataset actions)
will check the result of <var>Execute</var> and will not perform their 
normal task if the <var>OnExecute</var> handler was called.
</p>
</descr>
<seealso>
<link id="TBasicAction.Execute">Execute</link>
<link id="TBasicAction.OnUpdate">OnUpdate</link>
</seealso>
</element>

<element name="TBasicAction.OnUpdate">
<short>Event trigged when the application is idle.</short>
<descr>
<var>OnUpdate</var> is the event triggered when the application is idle, and
the action is being updated. The <var>OnUpdate</var> event can be used to
set the state of the action, for instance disable it if the action cannot be
executed at this point in time.
</descr>
<seealso>
<link id="TBasicAction.Update">Update</link>
<link id="TBasicAction.OnExecute">OnExecute</link>
</seealso>
</element>

<!--
  *********************************************************************
  TBasicActionLink
  *********************************************************************
-->

<element name="TBasicActionLink">
<short>Link between actions and action clients (e.g. controls)</short>
<descr>
<p>
<var>TBasicActionLink</var> links an Action to its clients. With each client
for an action, a <var>TBasicActionLink</var> class is instantiated to handle
the communication between the action and the client. It passes events
between the action and its clients, and thus presents the action with a
uniform interface to the clients.
</p>
<p>An application programmer should never use a <var>TBasicActionLink</var>
instance directly; They are created automatically when an action is
associated with a component. Component programmers should create specialized
descendents of <var>TBasicActionLink</var> which communicate changes in the
action to the component.
</p>
</descr>
<seealso>
<link id="TBasicAction"/>
</seealso>
</element>

<element name="TBasicActionLink.FAction">
<short>The action with which this link is associated</short>
<descr>
<var>FAction</var> contains a reference to the action with which this link
is associated. It should never be manipulated directly. It will be set
automatically by the <link id="TBasicActionLink.SetAction">SetAction</link> write method
for the <link id="TBasicActionLink.Action">Action</link> property.
</descr>
<seealso>
<link id="TBasicActionLink.SetAction">SetAction</link>
<link id="TBasicActionLink.Action">Action</link>
</seealso>
</element>

<element name="TBasicActionLink.AssignClient">
<short>Assigns a control (client) to the action link.</short>
<descr>
<var>AssignClient</var> assigns a control to the actionlink and hence to the
action. Descendent classes can override <var>AssignClient</var> to check
whether the new client is a suitable client for this action.
</descr>
<seealso>
<link id="TBasicActionLink.Action">Action</link>
</seealso>
</element>

<element name="TBasicActionLink.Change">
<short>Executed whenever the Action is changed.</short>
<descr>
<p>
<var>Change</var> is executed whenever the action changes. 
It executes the <link id="TBasicActionLink.OnChange">OnChange</link>
handler, if one is assigned.
</p>
<p>
Component programmers may decide to override the <var>Change</var>
procedure in descendent classes to perform aditional actions when 
the properties of the action changes.
</p>
</descr>
<seealso>
<link id="TBasicActionLink.OnChange">OnChange</link>
<link id="TBasicAction.Change"/>
</seealso>
</element>

<element name="TBasicActionLink.IsOnExecuteLinked">
<short>Returns whether the client has it's OnExecute property linked.</short>
<descr>
<var>IsOnExecuteLinked</var> always returns true in <var>TBasicActionLink</var>. 
Descendent classes can override this method to provide a different result.
</descr>
<link id="TBasicActionLink.OnExecute">OnExecute</link>
</element>

<element name="TBasicActionLink.SetAction">
<short>Sets the action with which the actionlink is associated.</short>
<descr>
<var>SetAction</var> is the write handler for the <link
id="TBasicActionLink.Action">Action</link> property. It sets the
<var>Action</var> property to it's new value, after unregistering itself 
with the old action, if there was one.
</descr>
<seealso>
<link id="TBasicActionLink.Action">Action</link>
<link id="TBasicAction"/>
</seealso>
</element>

<element name="TBasicActionLink.SetOnExecute">
<short>Assigns the <link id="TBasicAction.OnExecute">OnExecute</link> handler
to the client</short>
<descr>
<var>SetOnExecute</var> must be overridden by descendent classes to pass the
<var>OnExecute</var> handler of the associated action to the client control.
It will attach the <var>OnExecute</var> handler to whatever handler is
appropriate for the client control.
</descr>
<seealso>
<link id="TBasicAction.OnExecute">OnExecute</link>
<link id="TBasicAction"/>
</seealso>
</element>

<element name="TBasicActionLink.Create">
<short>Creates a new instance of the TBasicActionLink class</short>
<descr>
<p>
<var>Create</var> creates a new instance of a <var>TBasicActionLink</var>
and assigns <var>AClient</var> as the client of the link.
</p>
<p>
Application programmers should never instantiate <var>TBasicActionLink</var>
classes directly. An instance is created automatically when an action is
assigned to a control (client).
</p>
<p>
Component programmers can override the create constructor to initialize
further properties. 
</p>
</descr>
<seealso>
<link id="TBasicActionLink.Destroy">Destroy</link>
</seealso>
</element>

<element name="TBasicActionLink.Destroy">
<short>Destroys the TBasicActionLink instance.</short>
<descr>
<p>
<var>Destroy</var> unregisters the <var>TBasicActionLink</var> with the
action, and then calls the inherited destructor.
</p>
<p>
Application programmers should never call <var>Destroy</var> directly. If a
link should be destroyed at all, the <var>Free</var> method should be called
instead.
</p>
</descr>
<seealso>
<link id="TBasicActionLink.Create">Create</link>
</seealso>
</element>

<element name="TBasicActionLink.Execute">
<short>Calls the action's Execute method.</short>
<descr>
<p>
<var>Execute</var> sets the <link
id="TBasicAction.ActionComponent">ActionComponent</link> 
property of the associated <link id="TBasicActionLink.Action">Action</link> to 
<var>AComponent</var> and then calls the Action's  <link
id="TBasicAction.Execute">execute</link> method. After the action has 
executed, the <var>ActionComponent</var> property is cleared again.
</p>
<p>
The return value of the function is the return value of the Action's execute
method.
</p>
<p>
Application programmers should never call <var>Execute</var> directly. This
method will be called automatically when the associated control is
activated. (e.g. a button is clicked on)
</p>
<p>
Component programmers should call <var>Execute</var> whenever the action
should be activated.
</p>
</descr>
<seealso>
<link id="TBasicActionLink.Action">Action</link>
<link id="TBasicAction.ActionComponent"/>
<link id="TBasicAction.Execute"/>
<link id="TBasicAction.onExecute"/>
</seealso>
</element>

<element name="TBasicActionLink.Update">
<short>Calls the action's Update method</short>
<descr>
<p>
<var>Update</var> calls the associated Action's <link
id="TBasicAction.Update">Update</link> methoda.
</p>
<p>
Component programmers can override the <var>Update</var> method to provide
additional processing when the <var>Update</var> method occurs.
</p>
</descr>
</element>

<element name="TBasicActionLink.Action">
<short>The action to which the link was assigned.</short>
<descr>
<var>Action</var> represents the <link id="TBasicAction">Action</link> which
was assigned to the client. Setting this property will unregister the client
at the old action (if one existed) and registers the client at the new
action.
</descr>
<seealso>
<link id="TBasicAction"/>
</seealso>
</element>

<element name="TBasicActionLink.OnChange">
<short>Event handler triggered when the action's properties change</short>
<descr>
<p>
<var>OnChange</var> is the event triggered when the action's properties
change.
</p>
<p>
Application programmers should never need to assign this event. Component
programmers can assign this event to have a client control reflect any
changes in an Action's properties.
</p>
</descr>
<seealso>
<link id="TBasicActionLink.Change">Change</link>
<link id="TBasicAction.Change"/>
</seealso>
</element>

<!--
  *********************************************************************
  Various calls
  *********************************************************************
-->


<element name="TActiveXRegType">  <!-- Enumeration type -->
<short>Used when registering ActveX component types.</short>
<descr>
This type is provided for compatibility only, and is currently not used in
Free Pascal.
</descr>
<seealso>
</seealso>
</element>

<element name="TActiveXRegType.axrComponentOnly">  <!-- Enumeration value -->
<short></short>
</element>

<element name="TActiveXRegType.axrIncludeDescendants">  <!-- Enumeration value -->
<short></short>
</element>

<element name="RegisterComponentsProc">  <!-- Variable -->
<short>Callback procedure used when handling component registration.</short>
<descr>
<var>RegisterComponentsProc</var> can be set by an IDE to be notified when
new components are being registered. Application programmers should never
have to set <var>RegisterComponentsProc</var>
</descr>
<seealso>
<link id="RegisterNoIconProc"/>
<link id="RegisterComponents"/>
</seealso>
</element>

<element name="RegisterNoIconProc">  <!-- Variable -->
<short>Callback procedure used when handling iconless component registration.</short>
<descr>
<var>RegisterNoIconProc</var> can be set by an IDE to be notified when
new components are being registered, and which do not need an Icon in the
component palette. Application programmers should never
have to set <var>RegisterComponentsProc</var>
</descr>
<seealso>
</seealso>
</element>

<element name="Point">  <!-- Function -->
<short>Returns a <var>TPoint</var> record with the given coordinates.</short>
<descr>
<var>Point</var> returns a <link id="TPoint"/> record with the given
coordinates <var>AX</var> and <var>AY</var> filled in.
</descr>
<seealso>
<link id="TPoint"/>
<link id="SmallPoint"/>
<link id="Rect"/>
<link id="Bounds"/>
</seealso>
</element>

<element name="SmallPoint">  <!-- Function -->
<short>Returns a <var>TSmallPoint</var> record with the given coordinates.</short>
<descr>
<var>SmallPoint</var> returns a <link id="TSmallPoint"/> record with the given
coordinates <var>AX</var> and <var>AY</var> filled in.
</descr>
<seealso>
<link id="TSmallPoint"/>
<link id="Point"/>
<link id="Rect"/>
<link id="Bounds"/>
</seealso>
</element>

<element name="Rect">  <!-- Function -->
<short>Returns a <var>TRect</var> record with the given coordinates.</short>
<descr>
<p>
<var>Rect</var> returns a <link id="TRect"/> record with the given
top-left <var>(ALeft,ATop)</var> and bottom-right <var>(ABottom,ARight)</var>
corners filled in.
</p>
<p>
No checking is done to see whether the coordinates are valid.
</p>
</descr>
<seealso>
<link id="TRect"/>
<link id="Point"/>
<link id="SmallPoint"/>
<link id="Bounds"/>
</seealso>
</element>

<element name="Bounds">  <!-- Function -->
<short>Returns a <var>TRect</var> structure with the bounding rect of the
given location and size.</short>
<descr>
<var>Bounds</var> returns a <link id="TRect"/> record with the given
origin <var>(ALeft,ATop)</var> and dimensions <var>(AWidth,AHeight)</var> 
filled in.
</descr>
<seealso>
</seealso>
</element>

<element name="RegisterClass">  <!-- Procedure -->
<short>Registers a class with the streaming system.</short>
<descr>
<var>RegisterClass</var> registers the class <var>AClass</var> in the
streaming system. After the class has been registered, it can be read from
a stream when a reference to this class is encountered.
</descr>
<seealso>
<link id="RegisterClasses"/>
<link id="RegisterClassAlias"/>
<link id="RegisterComponents"/>
<link id="UnregisterClass"/>
</seealso>
</element>

<element name="RegisterClasses">  <!-- Procedure -->
<short>Registers multiple classes with the streaming system.</short>
<descr>
<var>RegisterClasses</var> registers the specified classes <var>AClass</var> in the
streaming system. After the classes have been registered, they can be read from
a stream when a reference to this class is encountered.
</descr>
<seealso>
<link id="RegisterClass"/>
<link id="RegisterClassAlias"/>
<link id="RegisterComponents"/>
<link id="UnregisterClass"/>
</seealso>
</element>

<element name="RegisterClassAlias">  <!-- Procedure -->
<short>Registers a class alias with the streaming system.</short>
<descr>
<var>RegisterClassAlias</var> registers a class alias in the streaming
system. If a reference to a class <var>Alias</var> is encountered in a
stream, then an instance of the class <var>AClass</var> will be created 
instead by the streaming code.
</descr>
<seealso>
<link id="RegisterClass"/>
<link id="RegisterClasses"/>
<link id="RegisterComponents"/>
<link id="UnregisterClass"/>
</seealso>
</element>

<element name="UnRegisterClass">  <!-- Procedure -->
<short>Unregisters a class from the streaming system.</short>
<descr>
<var>UnregisterClass</var> removes the class <var>AClass</var> from the
class definitions in the streaming system.
</descr>
<seealso>
<link id="UnRegisterClasses"/>
<link id="UnRegisterModuleClasses"/>
<link id="RegisterClass"/>
</seealso>
</element>

<element name="UnRegisterClasses">  <!-- Procedure -->
<short>Unregisters multiple classes from the streaming system.</short>
<descr>
<var>UnregisterClasses</var> removes the classes in <var>AClasses</var> from the
class definitions in the streaming system.
</descr>
<link id="UnRegisterClass"/>
<link id="UnRegisterModuleClasses"/>
<link id="RegisterClasses"/>
<seealso>
</seealso>
</element>

<element name="UnRegisterModuleClasses">  <!-- Procedure -->
<short>Unregisters classes registered by module.</short>
<descr>
<var>UnRegisterModuleClasses</var> unregisters all classes which reside in 
the module <var>Module</var>. For each registered class, the definition
pointer is checked to see whether it resides in the module, and if it does,
the definition is removed.
</descr>
<seealso>
<link id="UnRegisterClass"/>
<link id="UnRegisterClasses"/>
<link id="RegisterClasses"/>
</seealso>
</element>

<element name="FindClass">  <!-- Function -->
<short>Returns the class pointer of a class with given name.</short>
<descr>
<p>
<var>FindClass</var> searches for the class named <var>ClassName</var>
in the list of registered classes and returns a class pointer to the
definition. If no class with the given name could be found, an exception is
raised.
</p>
<p>The <link id="GetClass"/> function does not raise an exception when it
does not find the class, but returns a <var>Nil</var> pointer instead.
</p>
</descr>
<seealso>
<link id="RegisterClass"/>
<link id="GetClass"/>
</seealso>
</element>

<element name="GetClass">  <!-- Function -->
<short>Returns the class pointer of a class with given name.</short>
<descr>
<p>
<var>GetClass</var> searches for the class named <var>ClassName</var>
in the list of registered classes and returns a class pointer to the
definition. If no class with the given name could be found, <var>Nil</var>
is returned.
</p>
<p>The <link id="FindClass"/> function will raise an exception if the 
does not find the class.
</p>
</descr>
<seealso>
<link id="RegisterClass"/>
<link id="GetClass"/>
</seealso>
</element>

<element name="RegisterComponents">  <!-- Procedure -->
<short>Registers components for the component palette.</short>
<descr>
<p>
<var>RegisterComponents</var> registers the component on the appropriate
component page. The component pages can be used by an IDE to display the
known components so an application programmer may pick and use the
components in his programs.
</p>
<p>
Registercomponents inserts the component class in the correct component
page. If the <var>RegisterComponentsProc</var> procedure is set, this is
called as well. Note that this behaviour is different from Delphi's
behaviour where an exception will be raised if the procedural variable is
not set.
</p>
</descr>
<seealso>
<link id="RegisterClass"/>
<link id="RegisterNoIcon"/>
</seealso>
</element>

<element name="RegisterNoIcon">  <!-- Procedure -->
<short>Registers components that have no icon on the component palette.</short>
<descr>
<var>RegisterNoIcon</var> performs the same function as <link
id="RegisterComponents"/> except that it calls <link
id="RegisterNoIconProc"/>
instead of <link id="RegisterComponentsProc"/>
</descr>
<seealso>
<link id="RegisterNoIconProc"/>
<link id="RegisterComponents"/>
</seealso>
</element>

<element name="RegisterNonActiveX">  <!-- Procedure -->
<short>Register non-activex component.</short>
<descr>
Not yet implemented in Free Pascal
</descr>
<seealso>
</seealso>
</element>

<element name="TIdentMapEntry">  <!-- Record type -->
<short>Record used when associating names with integer values.</short>
<descr>
<var>TIdentMapEntry</var> is used internally by the <link id="IdentToInt"/>
and <link id="IntToIdent"/> calls to store the mapping between the
identifiers and the integers they represent.
</descr>
<seealso>
<link id="IntToIdent"/>
<link id="IdentToInt"/>
</seealso>
</element>

<element name="TIdentMapEntry.Value">  <!-- Variable -->
<short>Integer value</short>
</element>

<element name="TIdentMapEntry.Name">  <!-- Variable -->
<short>Name of the integer value.</short>
</element>

<element name="TIdentToInt">  <!-- Function type -->
<short>Callback for converting identifiers to integers.</short>
<descr>
<p>
<var>TIdentToInt</var> is a callback used to look up identifiers 
(<var>Ident</var>) and return an integer value corresponding to this
identifier (<var>Int</var>). The callback should return <var>True</var> if a
value corresponding to integer <var>Ident</var> was found, <var>False</var>
if not.
</p>
<p>
A callback of type <var>TIdentToInt</var> should be specified when an
integer is registered using the <link id="RegisterIntegerConsts"/> call.
</p>
</descr>
<seealso>
<link id="RegisterIntegerConsts"/>
<link id="TIntToIdent"/>
</seealso>
</element>

<element name="TIntToIdent">  <!-- Function type -->
<short>Callback for converting integers to identifiers.</short>
<descr>
<p>
<var>TIdentToInt</var> is a callback used to look up integers 
(<var>Ident</var>) and return an identifier (<var>Ident</var>) 
that can be used to represent this integer value in an IDE.
The callback should return <var>True</var> if a value corresponding 
to integer <var>Ident</var> was found, <var>False</var> if not.
</p>
<p>
A callback of type <var>TIntToIdent</var> should be specified when an
integer is registered using the <link id="RegisterIntegerConsts"/> call.
</p>
</descr>
<seealso>
<link id="RegisterIntegerConsts"/>
<link id="TIdentToInt"/>
</seealso>
</element>

<element name="TFindGlobalComponent">  <!-- Function type -->
<short>Callback type to search for a component.</short>
<descr>
<p>
<var>TFindGlobalComponent</var> is a callback used to find a component in a
global scope. It is used when the streaming system needs to find a component
which is not part of the component which is currently being streamed. It
should return the component with name <var>Name</var>, or <var>Nil</var> if
none is found.
</p>
<p>
The variable <link id="FindGlobalComponent"/> is a callback of type
<var>TFindGlobalComponent</var>. It can be set by the IDE when an unknown
reference is found, to offer the designer to redirect the link to a new
component.
</p>
</descr>
<seealso>
<link id="FindGlobalComponent"/>
</seealso>
</element>

<element name="MainThreadID">  <!-- Variable -->
<short>ID of main thread. Unused at this point.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="FindGlobalComponent">  <!-- Variable -->
<short>Callback used when a component must be found.</short>
<descr>
<p>
<var>FindGlobalComponent</var> is a callback of type
<link id="TFindGlobalComponent"/>. It can be set by the IDE when an unknown
reference is found, to offer the user to redirect the link to a new
component.
</p>
<p>
It is a callback used to find a component in a
global scope. It is used when the streaming system needs to find a component
which is not part of the component which is currently being streamed. It
should return the component with name <var>Name</var>, or <var>Nil</var> if
none is found.
</p>
</descr>
<seealso>
<link id="TFindGlobalComponent"/>
</seealso>
</element>

<element name="RegisterIntegerConsts">  <!-- Procedure -->
<short>Registers some integer-to-identifier mappings.</short>
<descr>
<p>
<var>RegisterIntegerConsts</var> registers a pair of callbacks to be used
when an integer of type <var>IntegerType</var> must be mapped to an
identifier (using <var>IntToIdentFn</var>) or when an identifier must be
mapper to an integer (using <var>IdentToIntFn</var>). 
</p>
<p>
Component programmers can use <var>RegisterIntegerConsts</var> to associate
a series of identifier strings with integer values for a property. A
necessary condition is that the property should have a separate type
declared using the <var>type integer</var> syntax. If a type of integer is
defined in this way, an IDE can show symbolic names for the values of these 
properties.
</p>
<p>
The <var>IntegerType</var> should be a pointer to the type information of
the integer type. The <var>IntToIdentFn</var> and <var>IdentToIntFn</var>
are two callbacks that will be used when converting between the identifier
and integer value and vice versa. The functions <link id="IdentToInt"/>
and <link id="IntToIdent"/> can be used to implement these callback
functions.
</p>
</descr>
<seealso>
<link id="TIdentToInt"/>
<link id="TIntToIdent"/>
<link id="IdentToInt"/>
<link id="IntToIdent"/>
</seealso>
</element>

<element name="IdentToInt">  <!-- Function -->
<short>Looks up an integer value in a integer-to-identifier map list.</short>
<descr>
<var>IdentToInt</var> searches <var>Map</var> for an entry whose
<var>Name</var> field matches <var>Ident</var> and returns the corresponding
integer value in <var>Int</var>. If a match was found, the function returns
<var>True</var>, otherwise, <var>False</var> is returned.
</descr>
<seealso>
<link id="TIdentToInt"/>
<link id="TIntToIdent"/>
<link id="IntToIdent"/>
<link id="TIdentMapEntry"/>
</seealso>
</element>

<element name="IntToIdent">  <!-- Function -->
<short>Looks up an identifier for an integer value in a identifier-to-integer map list.</short>
<descr>
<var>IdentToInt</var> searches <var>Map</var> for an entry whose
<var>Value</var> field matches <var>Int</var> and returns the corresponding
identifier in <var>Ident</var>. If a match was found, the function returns
<var>True</var>, otherwise, <var>False</var> is returned.
</descr>
<seealso>
<link id="TIdentToInt"/>
<link id="TintToIdent"/>
<link id="IdentToInt"/>
<link id="TIdentMapEntry"/>
</seealso>
</element>

<element name="InitInheritedComponent">  <!-- Function -->
<short>Initializes a component descending from <var>RootAncestor</var></short>
<descr>
<p>
<var>InitInheritedComponent</var> should be called from a constructor to
read properties of the component <var>Instance</var> from the streaming
system. The <var>RootAncestor</var> class is the root class from which
<var>Instance</var> is a descendent. This must be one of
<var>TDatamodule</var>, <var>TCustomForm</var> or <var>TFrame</var>.
</p>
<p>
The function returns <var>True</var> if the properties were successfully
read from a stream or <var>False</var> if some error occurred.
</p>
</descr>
<seealso>
<link id="ReadComponentRes"/>
<link id="ReadComponentResEx"/>
<link id="ReadComponentResFile"/>
</seealso>
</element>

<element name="InitComponentRes">  <!-- Function -->
<short>Provided for Delphi compatibility only</short>
<descr>
This function is provided for Delphi compatibility. 
It always returns <var>false</var>.
</descr>
<seealso>
<link id="ReadComponentRes"/>
</seealso>
</element>

<element name="ReadComponentRes">  <!-- Function -->
<short>Read component properties from a resource in the current module</short>
<descr>
This function is provided for Delphi compatibility. 
It always returns <var>Nil</var>.
</descr>
</element>

<element name="ReadComponentResEx">  <!-- Function -->
<short>Read component properties from a resource in the specified module</short>
<descr>
This function is provided for Delphi compatibility. 
It always returns <var>Nil</var>.
</descr>
</element>

<element name="ReadComponentResFile">  <!-- Function -->
<short>Read component properties from a specified resource file</short>
<descr>
<var>ReadComponentResFile</var> starts reading properties for
<var>Instance</var> from the file <var>FileName</var>. It creates a
filestream from <var>FileName</var> and then calls the <link
id="TStream.ReadComponentRes"/> method to read the state of the component from the
stream.
</descr>
<seealso>
<link id="TStream.ReadComponentRes"/>
<link id="WriteComponentResFile"/>
</seealso>
</element>

<element name="WriteComponentResFile">  <!-- Procedure -->
<short>Write component properties to a specified resource file</short>
<descr>
<var>WriteComponentResFile</var> starts writing properties of
<var>Instance</var> to the file <var>FileName</var>. It creates a
filestream from <var>FileName</var> and then calls <link
id="TStream.WriteComponentRes"/> method to write the state of 
the component to the stream.
</descr>
<seealso>
<link id="TStream.WriteComponentRes"/>
<link id="ReadComponentResFile"/>
</seealso>
</element>

<element name="GlobalFixupReferences">  <!-- Procedure -->
<short>Called to resolve unresolved references after forms are loaded.</short>
<descr>
<var>GlobalFixupReferences</var> runs over the list of unresolved references
and tries to resolve them. This routine should under normal circumstances
not be called in an application programmer's code. It is called
automatically by the streaming system after a component has been
instantiated and its properties read from a stream. It will attempt to
resolve references to other global components. 
</descr>
<seealso>
<link id="GetFixupReferenceNames"/>
<link id="GetFixupInstanceNames"/>
</seealso>
</element>

<element name="GetFixupReferenceNames">  <!-- Procedure -->
<short>Returns the names of elements that need to be resolved for the
<var>root</var> component.</short>
<descr>
<var>GetFixupReferenceNames</var> examines the list of unresolved references
and returns the names of properties that must be resolved for the
component <var>Root</var> in the list <var>Names</var>. The list is not
cleared prior to filling it.
</descr>
<seealso>
<link id="GetFixupInstanceNames"/>
<link id="GlobalFixupReferences"/>
</seealso>
</element>

<element name="GetFixupInstanceNames">  <!-- Procedure -->
<short>Returns the names of elements that need to be resolved for the
<var>root</var> component, whose reference contains <var>ReferenceRootName</var></short>
<descr>
<var>GetFixupInstanceNames</var> examines the list of unresolved references
and returns the names of classes that contain unresolved references to the
<var>Root</var> component in the list <var>Names</var>. The list is not
cleared prior to filling it.
</descr>
<seealso>
<link id="GetFixupReferenceNames"/>
<link id="GlobalFixupReferences"/>
</seealso>
</element>

<element name="RedirectFixupReferences">  <!-- Procedure -->
<short>Redirects references under the <var>root</var> object from
<var>OldRootName</var> to <var>NewRootName</var></short>
<descr>
<p>
<var>RedirectFixupReferences</var> examines the list of unresolved
references and replaces references to a root object named
<var>OldRootName</var> with references to root object 
<var>NewRootName</var>.
</p>
<p>
An application programmer should never need to call 
<var>RedirectFixupReferences</var>.
This function can be used by an IDE to support redirection of broken
component links.
</p>
</descr>
<seealso>
<link id="RemoveFixupReferences"/>
</seealso>
</element>

<element name="RemoveFixupReferences">  <!-- Procedure -->
<short>Removes references to rootname from the fixup list.</short>
<descr>
<p>
<var>RemoveFixupReferences</var> examines the list of unresolved
references and removes references to a root object pointing at
<var>Root</var> or a root component named <var>RootName</var>.
</p>
<p>
An application programmer should never need to call 
<var>RemoveFixupReferences</var>.
This function can be used by an IDE to support removal of broken
component links.
</p>
</descr>
<seealso>
<link id="RedirectFixupReferences"/>
</seealso>
</element>

<element name="RemoveFixups">  <!-- Procedure -->
<short>Removes <var>Instance</var> from the fixup list.</short>
<descr>
<var>RemoveFixups</var> removes all entries for component
<var>Instance</var> from the list of unresolved references.a
</descr>
<seealso>
<link id="RedirectFixupReferences"/>
<link id="RemoveFixupReferences"/>
</seealso>
</element>

<element name="FindNestedComponent">  <!-- Function -->
<short>Finds the component with name path starting at the indicated root
component.</short>
<descr>
<var>FindNestedComponent</var> will descend through the list of owned
components (starting at <var>Root</var>) and will return the component whose
name path matches <var>NamePath</var>. As a path separator the characters .
(dot), - (dash) and > (greater than) can be used
</descr>
<seealso>
<link id="GlobalFixupReferences"/>
</seealso>
</element>

<element name="BeginGlobalLoading">  <!-- Procedure -->
<short>Not yet implemented</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="NotifyGlobalLoading">  <!-- Procedure -->
<short>Not yet implemented.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="EndGlobalLoading">  <!-- Procedure -->
<short>Not yet implemented.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="CollectionsEqual">  <!-- Function -->
<short>Returns <var>True</var> if two collections are equal.</short>
<descr>
<var>CollectionsEqual</var> is not yet implemented. It simply returns
<var>False</var>
</descr>
</element>

<element name="ObjectBinaryToText">  <!-- Procedure -->
<short>Converts an object stream from a binary to a text format.</short>
<descr>
<var>ObjectBinaryToText</var> reads an object stream in binary format from
<var>Input</var> and writes the object stream in text format to
<var>Output</var>. No components are instantiated during the process, 
this is a pure conversion routine.
</descr>
<seealso>
<link id="ObjectTextToBinary"/>
</seealso>
</element>

<element name="ObjectTextToBinary">  <!-- Procedure -->
<short>Converts an object stream from a text to a binary format.</short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="ObjectResourceToText">  <!-- Procedure -->
<short>Converts an object stream from a (windows) resource to a text format.</short>
<descr>
<var>ObjectResourceToText</var> reads the resource header from the
<var>Input</var> stream and then passes the streams to
<link id="ObjectBinaryToText"/>
</descr>
<seealso>
<link id="ObjectBinaryToText"/>
<link id="ObjectTextToResource"/>
</seealso>
</element>

<element name="ObjectTextToResource">  <!-- Procedure -->
<short>Converts an object stream from a text to a (windows) resource  format.</short>
<descr>
<p>
<var>ObjectTextToResource</var> reads an object stream in text format from
<var>Input</var> and writes a resource stream to <var>Output</var>.
</p>
<p>
Note that for the current implementation of this method in Free Pascal, 
the output stream should support positioning. (e.g. it should not be a pipe)
</p> 
</descr>
<seealso>
<link id="ObjectBinaryToText"/>
<link id="ObjectResourceToText"/>
</seealso>
</element>

<element name="LineStart">  <!-- Function -->
<short>Finds the start of a line in <var>Buffer</var> before
<var>BufPos</var>.</short>
<descr>
<var>LineStart</var> reversely scans <var>Buffer</var> starting at
<var>BufPos</var> for a linefeed character. It returns a pointer at the
linefeed character.
</descr>
</element>

<element name="TPointerList">
<short>Type for an Array of pointers.</short>
</element>

<element name="PPointerList">
<short>Pointer to an array of pointers.</short>
</element>

<element name="THelpContext">
<short>Range type to specify help contexts.</short>
</element>

<element name="THelptype">
<short>Enumeration type specifying the kind of help requested.</short>
</element>

<element name="PStringItemList">
<short>Pointer to a <link id="TStringItemList"/>.</short>
</element>

<element name="TBasicActionClass">
<short><link id="TBasicAction"/> class reference.</short>
</element>

<element name="TBAsicActionLinkClass">
<short><link id="TBasicActionLink"/> class reference.</short>
</element>

<element name="TListNotification">
<short>Kind of list notification event.</short>
</element>


<element name="TListSortCompare">
<short>Callback type for the list sort algorithm.</short>
</element>


<element name="TSeekOrigin">
<short>Specifies the origin of the <link id="TStream.Seek"/> method.</short>
</element>

<element name="TSeekOrigin.soBeginning">
<short>Offset is interpreted relative to the start of the stream.</short>
</element>

<element name="TSeekOrigin.SoEnd">
<short>Offset is interpreted relative to the end of the stream.</short>
</element>

<element name="TSeekOrigin.soCurrent">
<short>Offset is interpreted relative to the current position in the stream.</short>
</element>

<element name="TShortCut">
<short>Enumeration type to identify shortcut key combinations.</short>
</element>

<element name="TStringListSortCompare">
<short>Callback type used in stringlist compares.</short>
</element>


<!-- Template for copy&paste:
<element name="">
<short>
</short>
<descr>
</descr>
</element>
-->

</module>
</package>
</fpdoc-descriptions>