This record describes a coordinate. It is used to handle the Top and Left properties of .

X represents the X-Coordinate of the point described by the record. Y represents the Y-Coordinate of the point described by the record.

The TAlignment type is used to specify the alignment of the text in controls that display a text.

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.

The set contains the special keys that can be used in combination with a 'normal' key.

An EStreamError is raised when an error occurs during reading from or writng to a stream: Possible causes are

1. Not enough data is available in the stream.
2. Trying to seek beyond the beginning or end of the stream.
3. Trying to set the capacity of a memory stream and no memory is available.
4. Trying to write to a read-only stream, such as a resource stream.
5. Trying to read from a write-only stream.

If an error occurs when reading from a stream, a EReadError exception is raised. Possible causes for this are:

1. Not enough data is available when reading from a stream
2. The stream containing a component's data contains invalid data. this will occurr only when reading a component from a stream.

If an error occurs when writing to a stream, a EWriteError exception is raised. Possible causes for this are:

1. The stream doesn't allow writing.
2. An error occurred when writing a property to a stream.

If an error occurs in one of the or methods, then a EListError exception is raised. This can occur in one of the following cases:

1. There is not enough memory to expand the list.
2. The list tried to grow beyond its maximal capacity.
3. An attempt was made to reduce the capacity of the list below the current element count.
4. An attempt was made to set the list count to a negative value.
5. A non-existent element of the list was referenced. (i.e. the list index was out of bounds)
6. An attempt was made to move an item to a position outside the list's bounds.

When an error occurs in one of the methods of then an EStringListError is raised. This can have one of the following causes:

1. There is not enough memory to expand the list.
2. The list tried to grow beyond its maximal capacity.
3. A non-existent element of the list was referenced. (i.e. the list index was out of bounds)
4. An attempt was made to add a duplicate entry to a when is False.

When an error occurs during the registration of a component, or when naming a component, then a EComponentError is raised. Possible causes are:

1. An name with an illegal character was assigned to a component.
2. A component with the same name and owner already exists.
3. The component registration system isn't set up properly.

TList 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. It has an event notification mechanism which allows to notify of list changes. This slows down some of TList mechanisms, and if no notification is used, may be used instead.

To manage collections of strings, it is better to use a descendent such as . To manage general objects, a class exists, from which a descendent can be made to manage collections of various kinds.

TList.Create creates a new instance of TList. It clears the list and prepares it for use.

Add adds a new pointer to the list after the last pointer (i.e. at position Count, thus increasing the item count with 1. If the list is at full capacity, the capacity of the list is expanded, using the Grow method.

To insert a pointer at a certain position in the list, use the Insert method instead.

Delete removes the pointer at position Index from the list, shifting all following pointers one position up (or to the left).

The memory the pointer is pointing to is not deallocated.

Expand increases the capacity of the list if the current element count matches the current list capacity.

The capacity is increased according to the following algorithm:

1. If the capacity is less than 3, the capacity is increased with 4.
2. If the capacity is larger than 3 and less than 8, the capacity is increased with 8.
3. If the capacity is larger than 8, the capacity is increased with 16.

The return value is Self.

First returns the value of the first non-nil pointer in the list.

If there are no pointers in the list or all pointers equal Nil, then Nil is returned.

IndexOf searches for the pointer Item in the list of pointers, and returns the index of the pointer, if found.

If no pointer with the value Item was found, -1 is returned.

Insert inserts pointer Item at position Index in the list. All pointers starting from Index are shifted to the right.

If Index is not a valid position, then a exception is raised.

Last returns the value of the last non-nil pointer in the list.

If there are no pointers in the list or all pointers equal Nil, then Nil is returned.

Move moves the pointer at position CurIndex to position NewIndex. This is done by storing the value at position CurIndex, deleting the pointer at position CurIndex, and reinserting the value at position NewIndex

If CurIndex or Newindex are not inside the valid range of indices, an exception is raised.

Sort> sorts the pointers in the list. Two pointers are compared by passing them to the Compare function. The result of this function determines how the pointers will be sorted:

• 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.
• 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.
• if the function result is zero, the pointers are assumed to be 'equal' and no moving will take place.

The sort is done using a quicksort algorithm.

Capacity contains the number of pointers the list can store before it starts to grow.

If a new pointer is added to the list using add or insert, 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.

Items is used to access the pointers in the list. It is the default property of the TList class, so it can be omitted.

The list is zero-based, so Index must be in the range 0 to Count-1.

TFPList 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. Contrary to , TFPList has no notification mechanism. If no notification mechanism is used, it is better to use TFPList instead of TList, as the performance of TFPList is much higher.

To manage collections of strings, it is better to use a descendent such as . To manage general objects, a class exists, from which a descendent can be made to manage collections of various kinds.

Add adds a new pointer to the list after the last pointer (i.e. at position Count, thus increasing the item count with 1. If the list is at full capacity, the capacity of the list is expanded, using the Expand method.

To insert a pointer at a certain position in the list, use the Insert method instead.

Delete removes the pointer at position Index from the list, shifting all following pointers one position up (or to the left).

The memory the pointer is pointing to is not deallocated.

Expand increases the capacity of the list if the current element count matches the current list capacity.

The capacity is increased according to the following algorithm:

1. If the capacity is less than 3, the capacity is increased with 4.
2. If the capacity is larger than 3 and less than 8, the capacity is increased with 8.
3. If the capacity is larger than 8, the capacity is increased with 16.

The return value is Self.

First returns the value of the first non-nil pointer in the list.

If there are no pointers in the list or all pointers equal Nil, then Nil is returned.

IndexOf searches for the pointer Item in the list of pointers, and returns the index of the pointer, if found.

If no pointer with the value Item was found, -1 is returned.

Insert inserts pointer Item at position Index in the list. All pointers starting from Index are shifted to the right.

If Index is not a valid position, then a exception is raised.

Last returns the value of the last non-nil pointer in the list.

If there are no pointers in the list or all pointers equal Nil, then Nil is returned.

Move moves the pointer at position CurIndex to position NewIndex. This is done by storing the value at position CurIndex, deleting the pointer at position CurIndex, and reinserting the value at position NewIndex

If CurIndex or Newindex are not inside the valid range of indices, an exception is raised.

Sort> sorts the pointers in the list. Two pointers are compared by passing them to the Compare function. The result of this function determines how the pointers will be sorted:

• 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.
• 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.
• if the function result is zero, the pointers are assumed to be 'equal' and no moving will take place.

The sort is done using a quicksort algorithm.

Capacity contains the number of pointers the list can store before it starts to grow.

If a new pointer is added to the list using add or insert, 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.

Items is used to access the pointers in the list. It is the default property of the TFPList class, so it can be omitted.

The list is zero-based, so Index must be in the range 0 to Count-1.

TBits 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 store them in a conventional array.

TBits introduces methods to store and retrieve bit values, apply masks, and search for bits.

Create creates a new bit collection with initial size TheSize. The size of the collection can be changed later on.

All bits are initially set to zero.

Destroy destroys a previously created bit collection and releases all memory used to store the bit collection.

Destroy should never be called directly, Free should be used instead.

andbits performs an or operation on the bits in the array with the bits of array BitSet.

If BitSet contains less bits than the current array, then all bits which have no counterpart in BitSet are left untouched.

If the current array contains less bits than BitSet then it is grown to the size of BitSet before the or operation is performed.

XorBits performs a xor operation on the bits in the array with the bits of array BitSet.

If BitSet contains less bits than the current array, then all bits which have no counterpart in BitSet are left untouched.

If the current array contains less bits than BitSet then it is grown to the size of BitSet before the xor operation is performed.

NotBits performs a not operation on the bits in the array with the bits of array Bitset.

If BitSet contains less bits than the current array, then all bits which have no counterpart in BitSet are left untouched.

equals returns True if all the bits in BitSet are the same as the ones in the current BitSet; if not, False is returned.

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.

SetIndex sets the search start position forFindNextBit and FindPrevBit to Index. This means that these calls will start searching from position Index.

This mechanism provides an alternative to FindFirstBit which can also be used to position for the FindNextBit and FindPrevBit calls.

FindFirstBit searches for the first bit with value State. It returns the position of this bit, or -1 if no such bit was found.

The search starts at position 0 in the array. If the first search returned a positive result, the found position is saved, and the FindNextBit and FindPrevBit will use this position to resume the search. To start a search from a certain position, the start position can be set with the SetIndex instead.

FindNextBit resumes a previously started search. It searches for the next bit with the value specified in the FindFirstBit. The search is done towards the end of the array and starts at the position last reported by one of the Find calls or at the position set with SetIndex.

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, -1 is returned.

FindPrevBit resumes a previously started search. It searches for the previous bit with the value specified in the FindFirstBit. The search is done towards the beginning of the array and starts at the position last reported by one of the Find calls or at the position set with SetIndex.

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, -1 is returned.

TPersistent is the basic class for the streaming system. Since it is compiled in the {$M+} 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.

It also introduces functionality to assign the contents of 2 classes to each other.

TPersistent implements the interface for the benefit of descendent classes, but does not call . Descendents such as and and do use it.

AssignTo 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.

The implementation of Assignto raises an EConvertError exception. This is done for the following reason: If the source class doesn't know how to assign itself to the destination class (using AssignTo), the destination class may know how get the data from the source class (using Assign). 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 , which will simply execute

If neither of the classes knows how to assign to/from each other, then execution will end up at the TPersistent implementation of AssignTo, and an exception will be raised.

DefineProperties must be overridden by descendent classes to indicate to the streaming system which non-published properties must also be streamed.

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 DefineProperties method. The Filer object is the class that is responsible for writing all properties to the stream.

To define new properties, two methods of the class should be used:

1. DefineProperty, to define a property which can be represented as text.
2. DefineProperty, to define a property which contains binary data.

On order for the streaming to work correctly, a call to the inherited DefineProperties 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.

Assign copies the contents of Source to Self, if the classes of the destination and source classes are compatible.

The TPersistent implementation of Assign does nothing but calling the AssignTo 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.

GetNamePath 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.

GetNamePath constructs a name by recursively prepending the Classname of the Owner instance to the Classname of this instance, separated by a dot.

TCollectionItem and form a pair of base classes that manage a collection of named objects. The TCollectionItem is the named object that is managed, it represents one item in the collection. An item in the collection is represented by three properties: , and .

A TCollectionItem object is never created directly. To manage a set of named items, it is necessary to make a descendent of TCollectionItem to which needed properties and methods are added. This descendant can then be managed with a class. The managing collection will create and destroy it's items by itself, it should therefore never be necessary to create TCollectionItem descendents manually.

GetDisplayName returns the value of the property. By default, this is the classname of the actual TCollectionItem descendant.

Descendants of TCollectionItem can and should override this method to return a more meaningful value.

SetDisplayName is the write method for the property. It does nothing but notifying the managing collection that the displayname has changed. It does NOT store the actual Value.

Descendants of TCollectionItem should override this method to store the actual displayname if this is required.

Destroy removes the item from the managing collection and Destroys the item instance.

This is the only way to remove items from a collection;

ID is the initial value of ; it doesn't change after the index changes. It can be used to uniquely identify the item. The ID property doesn't change as items are added and removed from the collection.

While the property forms a continuous series, ID does not. If items are removed from the collection, their ID is not used again, leaving gaps. Only when the collection is initialiiy created, the ID and Index properties will be equal.

Index is the current index of the item in its managing collection's property. This property may change as items are added and removed from the collection.

The index of an item is zero-based, i.e. the first item has index zero. The last item has index Count-1 where Count is the number of items in the collection.

The Index property of the items in a collection form a continuous series ranging from 0 to Count-1. The property does not form a continuous series, but can also be used to identify an item.

DisplayName contains the name of this item as shown in the object inspector. For TCollectionItem this returns always the class name of the managing collection, followed by the index of the item.

TCollectionItem does not implement any functionality to store the DisplayName 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 DisplayName property,TCollectionItem descendants should override the and to add storage functionality.

TCollection implements functionality to manage a collection of named objects. Each of these objects needs to be a descendent of the class. Exactly which type of object is managed can be seen from the property.

Normally, no TCollection is created directly. Instead, a descendents of TCollection and are created as a pair.

GetAttrCount returns 0 in the TCollection 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.

This method is provided for compatibility with Delphi only and is not used in Free Pascal.

This method is provided for compatibility with Delphi only and is not used in Free Pascal.

This method is provided for compatibility with Delphi only and is not used in Free Pascal.

GetNamePath returns the name path for this collection. If the following conditions are satisfied:

1. There is an owner object.
2. The owner object returns a non-empty name path.
3. The property is not empty

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.

Update is called in the following cases:

1. An item is added to or removed from the collection.
2. An item is moved in the list, i.e. its property changes.
3. An item's property changes.

Descendent classes can override this method to perform additional actions when the collection changes. The Item parameter indicates the item that was changed. This can be Nil

Destroy first clears the collection, and then frees all memory allocated to this instance.

Don't call Destroy directly, call Free instead.

Assign 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 Source collection; it assigns to each created element the contents of it's counterpart in the Source element.

Two collections cannot be assigned to each other if instances of the ItemClass classes cannot be assigned to each other.

BeginUpdate is called at the beginning of a batch update. It raises the update count with 1.

Call BeginUpdate at the beginning of a series of operations that will change the state of the collection. This will avoid the call to for each operation. At the end of the operations, a corresponding call to EndUpdate must be made. It is best to do this in the context of a Try ... finally block:

This insures that the number of calls to BeginUpdate always matches the number of calls to , even in case of an exception.

FindItemID searches through the collection for the item that has a value of ID for its property, and returns the found item. If no such item is found in the collection, Nil is returned.

The routine performs a linear search, so this can be slow on very large collections.

Count contains the number of items in the collection.

Items provides indexed access to the items in the collection. Since the array is zero-based, Index should be an integer between 0 and Count-1.

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 property.

Adding an element to the array can be done with the method. The array can be cleared with the method. Removing an element of the array should be done by freeing that element.

TStrings 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.

It also introduces methods to manage a series of name=value settings, as found in many configuration files.

An instance of TStrings is never created directly, instead a descendent class such as should be created. This is because TStrings is an abstract class which does not implement all methods; TStrings also doesn't store any strings, this is the functionality introduced in descendents such as .

TStrings implements the interface: when the stringlist is changed, a ooChanged notification is sent to all observers.

Error raises an exception. It passes Msg as a format with Data as the only argument.

This method can be used by descendent objects to raise an error.

Get is the abstract read handler for the property. This is an abstract method, hence it is not implemented in TStrings.

Descendent classes, such as must override this method and implement a routine that retrieves the Index-th string in the list. Index should have a value between 0 and Count-1, in all other cases an error should be raised using .

GetCapacity is the read handler for the property. The implementation in TStrings will return 0.

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.

GetCount is the abstract read handler for the property. This is an abstract method, hence it is not implemented in TStrings.

Descendent classes must override this method. It should return the current number of strings in the list. (empty strings included).

GetObject is the read handler for the property. The TStrings implementation of this method ignores the Index argument and simply returns Nil.

Descendent classes that should support object storage should override this method and return the object associated to the Index-th string in the list. Index should have a value between 0 and Count-1. If Index is outside the allowed range, an error should be raised using .

GetTextStr is the read handler for the property. It simply concatenates all strings in the list with a linefeed between them, and returns the resulting string.

Descendent classes may override this method to implement an efficienter algorithm which is more suitable to their storage method.

Put is the write handler for the property. It does this by saving the object associated to the Index-th string, deleting the Index-th string, and inserting S and the saved object at position Index with

Descendent classes may wish to override Put to implement a more efficient method.

PutObject is the write handler for the property. The TStrings implementation of PutObject does nothing.

Descendent objects that should support Object storage must override this method to store the AObject so that it is associated with the Index-th string in the list. Index should have a value between 0 and Count-1. If the value of Index is out of range, an error should be raised using .

SetCapacity is the write handler for the property. The TStrings implementation of SetCapacity does nothing.

Descendent classes can override this method to set the current capacity of the stringlist to NewCapacity. The capacity is the number of strings the list can hold before it tries to expand its storage space. NewCapacity should be no less than Count.

SetTextStr is the write method for the property. It does nothing other than calling .

Descendent classes may override this method to implement a more efficient algoritm that fits their storage method better.

SetUpdateState sets the update state to Updating. The TStrings implementation of SetUpdateState does nothing.

Descendent objects may override this method to implement optimizations. If Updating is True then the list of strings is about to be updated (possibly many times). If it is False no more updates will take place till the next SetUpdateState call.

AddObject adds S to the list of strings, and associates AObject with it. It returns the index of S.

BeginUpdate increases the update count by one. It is advisable to call BeginUpdate before lengthy operations on the stringlist. At the end of these operation, 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.

All TStrings methods that modify the string list call BeginUpdate before the actual operation, and call endUpdate when the operation is finished. Descendent classes should also call these methods when modifying the string list.

Clear will remove all strings and their associated objects from the list. After a call to clear, is zero.

Since it is an abstract method, TStrings itself does not implement Clear. Descendent classes such as implement this method.

Delete deletes the string at position Index from the list. The associated object is also removed from the list, but not destroyed. Index is zero-based, and should be in the range 0 to Count-1.

Since it is an abstract method, TStrings itself does not implement Delete. Descendent classes such as implement this method.

EndUpdate should be called at the end of a lengthy operation on the stringlist, but only if there was a call to BeginUpdate before the operation was started. It is best to put the call to EndUpdate in the context of a Finally block, so it will be called even if an exception occurs.

For more information, see .

TStrings implements the interface: when EndUpdate is called, a ooChanged notification is sent to all observers.

Equals compares the contents of the stringlist with the contents of TheStrings. If the contents match, i.e. the stringlist contain an equal amount of strings, and all strings match, then True is returned. If the number of strings in the lists is is unequal, or they contain one or more different strings, False is returned.

Exchange exchanges the strings at positions Index1 and Index2. The associated objects are also exchanged.

Both indexes must be in the range of valid indexes, i.e. must have a value between 0 and Count-1.

GetText 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.

IndexOf searches the list for S. The search is case-insensitive. If a matching entry is found, its position is returned. if no matching string is found, -1 is returned.

IndexOfName searches in the list of strings for a name-value pair with name part Name. 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 -1. The search is done case-insensitive.

IndexOfObject searchs through the list of strings till it find a string associated with AObject, and returns the index of this string. If no such string is found, -1 is returned.

Insert inserts the string S at position Index in the list. Index is a zero-based position, and can have values from 0 to Count. If Index equals Count then the string is appended to the list.

InsertObject inserts the string S and its associated objectAObject at position Index in the list. Index is a zero-based position, and can have values from 0 to Count. If Index equals Count then the string is appended to the list.

LoadFromFile 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.

LoadFromFile simply creates a file stream with the given filename, and then executes ; after that the file stream object is destroyed again.

Move moves the string at position CurIndex so it has position NewIndex after the move operation. The object associated to the string is also moved. CurIndex and NewIndex should be in the range of 0 to Count-1.

SaveToFile saves the contents of the stringlist to the file with name FileName. 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.

SaveToFile creates a file stream with name FileName, calls and then destroys the file stream object.

SaveToStream saves the contents of the stringlist to Stream. 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.

Capacity is the number of strings that the list can hold before it tries to allocate more memory.

TStrings returns when read. Trying to set the capacity has no effect. Descendent classes such as can override this property such that it actually sets the new capacity.

DelimitedText returns all strings, properly quoted with QuoteChar and separated by the Delimiter character.

Strings are quoted if they contain a space or any character with ASCII value less than 32.

The CommaText property is a special case of delimited text where the delimiter character is a comma and the quote character is a double quote.

If StrictDelimiter is set to True, then no quoting is done (The QuoteChar property is disregarded completely): the returned text will contain the items in the stringlist, separated by the Delimiter character. When writing the DelimitedText property, the text will be split at all occurrences of the Delimiter character; however, when reading, the QuoteChar property will be taken into account.

NameValueSeparator is the character used to separate name,value pair. By default, this is the equal sign (=), resulting in Name=Value pairs.

It can be set to a colon for Name : Value pairs.

CommaText 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:

Comma,string
Quote"string
Space string
NormalSttring

is converted to

Conversely, when setting the CommaText 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:

"Comma,string" , "Quote""String",Space string,, NormalString

Will be converted to

Comma,String
Quote"String
Space
String

NormalString

This is a special case of the property where the quote character is always the double quote, and the delimiter is always the colon.

Count is the current number of strings in the list. TStrings does not implement this property; descendent classes should override the property read handler to return the correct value.

Strings in the list are always uniquely identified by their Index; the index of a string is zero-based, i.e. it's supported range is 0 to Count-1. trying to access a string with an index larger than or equal to Count 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.

Names provides indexed access to the names of the name-value pairs in the list. It returns the name part of the Index-th string in the list.

Objects provides indexed access to the objects associated to the strings in the list. Index is a zero-based index and must be in the range of 0 to Count-1.

Setting the objects 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.

TStrings does not implement any storage for objects. Reading the Objects property will always return Nil, Setting the property will have no effect. It is the responsability of the descendent classes to provide storage for the associated objects.

Values represents the value parts of the name-value pairs in the list.

When reading this property, if there is a name-value pair in the list of strings that has name part Name, then the corresponding value is returned. If there is no such pair, an empty string is returned.

When writing this value, first it is checked whether there exists a name-value pair in the list with name Name. 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 Name and value.

Strings is the default property of TStrings. It provides indexed read-write access to the list of strings. Reading it will return the string at position Index in the list. Writing it will set the string at position Index.

Index is the position of the string in the list. It is zero-based, i.e. valued values range from 0 (the first string in the list) till Count-1 (the last string in the list). When browsing through the strings in the list, this fact must be taken into account.

To access the objects associated with the strings in the list, use the property. The name parts of name-value pairs can be accessed with the property, and the values can be set or read through the property.

Searching through the list can be done using the method.

Text 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.

TStringList is a descendent class of that implements all of the abstract methods introduced there. It also introduces some additional methods:

• Sort the list, or keep the list sorted at all times
• Special handling of duplicates in sorted lists
• Notification of changes in the list

Destroy clears the stringlist, release all memory allocated for the storage of the strings, and then calls the inherited destroy method.

Add will add S to the list. If the list is sorted and the string S is already present in the list and is dupError then an exception is raised. If Duplicates is set to dupIgnore then the return value is underfined.

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.

Exchange will exchange two items in the list as described in .

Find returns True if the string S is present in the list. Upon exit, the Index parameter will contain the position of the string in the list. If the string is not found, the function will return False and Index will contain the position where the string will be inserted if it is added to the list.

Duplicates describes what to do in case a duplicate value is added to the list:

If the stringlist is not sorted, the Duplicates setting is ignored.

Sorted can be set to True 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 False has no immediate effect, but will allow strings to be inserted at any position.

OnChange 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.

The Onchange event is triggered after the modification took place. When the modification is about to happen, an event occurs.

OnChanging 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.

The Onchanging event is triggered before the modification will take place. When the modification has happened, an event occurs.

TStream is the base class for all streaming classes. It defines methods for reading, writing from and to streams, as well as functions to determine the size of the stream as well as the current position of the stream.

Descendent classes such as or then override these methods to write streams to memory or file.

Read attempts to read Count from the stream to Buffer and returns the number of bytes actually read.

This method should be used when the number of bytes is not determined. If a specific number of bytes is expected, use instead.

As implemented in TStream, Read does nothing but raises an exception to indicate that reading is not supported. Descendent classes that allow reading must override this method to do the actual reading.

Write attempts to write Count bytes from Buffer to the stream. It returns the actual number of bytes written to the stream.

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 instead.

As implemented in TStream, Write does nothing but raises exception to indicate that writing is not supported. Descendent classes that allow writing must override this method to do the actual writing.

Seek sets the position of the stream to Offset bytes from Origin. There is a 32-bit variant of this function and a 64-bit variant. The difference can be made by choosing the correct Offset parameter: the integer-typed parameter selects the 32-bit variant, the parameter of type selects the 64-bit variant of the function.

The Origin parameter for the 32-bit version can have one of the following values:

These values are defined in the unit.

The Origin parameter for the 64-bit version has one of the following values:

Offset should be negative when the origin is SoFromEnd (soEnd). It should be positive for soFromBeginning and can have both signs for soFromCurrent

This is an abstract method, which must be overridden by descendent classes. They may choose not to implement this method for all values of Origin and Offset.

ReadBuffer reads Count bytes of the stream into Buffer. If the stream does not contain Count bytes, then an exception is raised.

ReadBuffer 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 instead. ReadBuffer uses Read internally to do the actual reading.

WriteBuffer writes Count bytes to the stream from Buffer. If the stream does not allow Count bytes to be written, then an exception is raised.

WriteBuffer should be used to write a fixed number of bytes, such as when writing structures or the content of variables. If the number of bytes is not determined, use instead. WriteBuffer uses Write internally to do the actual writing.

CopyFrom reads Count bytes from Source 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. If Count is zero, then the whole contents of the Source stream is copied. It is positioned on the first byte of data, and Size bytes are copied. Note that this cannot be used with streams that do not allow seeking or do not allow determining the size of the stream.

This can be used to quickly copy data from one stream to another or to copy the whole contents of the stream.

ReadComponent reads a component state from the stream and transfers this state to Instance. If Instance is nil, then it is created first based on the type stored in the stream. ReadComponent returns the component as it is read from the stream.

ReadComponent simply creates a object and calls its ReadRootComponent method.

ReadComponentRes reads a resource header from the stream, and then calls ReadComponent to read the component state from the stream into Instance.

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.

WriteComponent writes the published properties of Instance to the stream, so they can later be read with . This method is intended to be used by an IDE, to preserve the state of a form or datamodule as designed in the IDE.

WriteComponent simply calls WriteDescendent with Nil ancestor.

WriteComponentRes writes a ResName resource header to the stream and then calls WriteComponent to write the published properties of Instance to the stream.

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.

WriteDescendent writes the state of Instance to the stream where it differs from Ancestor, i.e. only the changed properties are written to the stream.

WriteDescendent creates a object and calls its WriteDescendent object. The writer is passed a binary driver object by default.

WriteDescendentRes writes a ResName resource header, and then calls WriteDescendent to write the state of Instance to the stream where it differs from Ancestor, i.e. only the changed properties are written to the stream.

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.

WriteResourceHeader writes a resource-file header for a resource called ResName. It returns in FixupInfo the argument that should be passed on to .

WriteResourceHeader should not be used directly. It is called by the and methods.

FixupResourceHeader 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 FixupInfo. After that the current position is restored.

FixupResourceHeader should never be called directly; it is handled by the streaming system.

ReadResourceHeader reads a reasource file header from the stream. It positions the stream just beyond the header.

ReadResourceHeader should not be called directly, it is called by the streaming system when needed.

Position 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.

Size can be read to determine the stream size or to set the stream size.

THandleStream is an abstract descendent of the 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 Read and Write methods of TStream.

Read overrides the Read method of TStream. It uses the Handle property to read the Count bytes into Buffer

If no error occurs while reading, the number of bytes actually read will be returned.

Write overrides the Write method of TStream. It uses the Handle property to write the Count bytes from Buffer.

If no error occurs while writing, the number of bytes actually written will be returned.

TFileStream is a descdendent that stores or reads it's data from a named file in the filesystem of the operating system.

To this end, it overrides some of the methods in TStream and implements them for the case of files on disk, and it adds the FileName property to the list of public properties.

SetSize sets the size of the file at NewSize bytes. Errors returned by the operating system call will be silently ignored.

This is the protected write method of the public property.

Create creates a new instance of a TFileStream class. It opens the file AFileName with mode Mode, which can have one of the following values:

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.

Destroy closes the file (causing possible buffered data to be written to disk) and then calls the inherited destructor.

Do not call destroy directly, instead call the Free method. Destroy does not check whether Self is nil, while Free does.

Seek attempts to set the position of the stream at Offset bytes from Origin. Offset 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 Origin. Origin can have one of the following values:

Seek returns the new position in the file, or -1 on error.

TCustomMemoryStream 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 Memory property which points to the memory area where the stream data is kept.

The only thing which TCustomMemoryStream 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 . The reason for this approach is that this way it is possible to create e.g. read-only descendents of TCustomMemoryStream that point to a fixed part in memory which can be read from, but not written to.

SetPointer updates the internal memory pointer and the size of the memory area pointed to.

Descendent memory streams should call this method whenever they set or reset the memory the stream should read from or write to.

Read reads Count bytes from the stream into the memory pointed to by buffer. It returns the number of bytes actually read.

This method overrides the method of . It will read as much bytes as are still available in the memory area pointer to by Memory. After the bytes are read, the internal stream position is updated.

SaveToStream writes the contents of the memory stream to Stream. The content of Stream is not cleared first. The current position of the memory stream is not changed by this action.

SaveToFile writes the contents of the stream to a file with name FileName. It simply creates a filestream and writes the contents of the memorystream to this file stream using .

Memory points to the memory area where stream keeps it's data. The property is read-only, so the pointer cannot be set this way.

TMemoryStream is a descendent that stores it's data in memory. It descends directly from and implements the necessary to allocate and de-allocate memory directly from the heap. It implements the Write method which is missing in TCustomMemoryStream.

TMemoryStream also introduces methods to load the contents of another stream or a file into the memory stream.

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.

SetCapacity 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 NewCapacity 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.

Memory is allocated in blocks of 4 Kb; this can be changed by overriding the method.

Capacity 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 sets the capacity to the needed value.

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.

LoadFromStream loads the contents of Stream into the memorybuffer of the stream. Any previous contents of the memory stream are overwritten. Memory is allocated as needed.

LoadFromFile loads the contents of the file with name FileName into the memory stream. The current contents of the memory stream is replaced by the contents of the file. Memory is allocated as needed.

The LoadFromFile method simply creates a filestream and then calls the method.

Write writes Count bytes from Buffer 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 Count).

This method overrides the method.

TStringStream stores its data in an ansistring. The contents of this string is available as the DataString property. It also introduces some methods to read or write parts of the stringstream's data as a string.

The main purpose of a TStringSTream is to be able to treat a string as a stream from which can be read.

ReadString reads Count bytes from the stream and returns the read bytes as a string. If less than Count bytes were available, the string has as many characters as bytes could be read.

The ReadString method is a wrapper around the Read method. It does not do the same stringas the method, which first reads a length integer to determine the length of the string to be read.

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 TAbstractObjectReader 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.

Different streaming mechanisms can be implemented by making a descendent from TAbstractObjectReader. The class is such a descendent class, which streams data in binary (Delphi compatible) format.

All methods described in this class, mustbe implemented by descendent classes.

This function should return the type of the next value in the stream, but should not read the actual value, i.e. the stream position should not be altered by this method. This is used to 'peek' in the stream what value is next.

This method is called when the streaming process wants to start reading a new component.

Descendent classes should override this method to read the start of a component new component definition and return the needed arguments. Flags should be filled with any flags that were found at the component definition, as well as AChildPos. The CompClassName should be filled with the class name of the streamed component, and the CompName argument should be filled with the name of the component.

AChildPos is used to change the ordering in which components appear below their parent component when streaming descendent forms.

ReadIdent is called by the streaming system if it expects to read an identifier of type ValueType from the stream after a call to ReadValue returned vaIdent. The identifier should be returned as a string. Note that in some cases the identifier does not actually have to be in the stream. The following table indicates which identifiers must actually be read:

This method is called by the streaming system if it expects to read a set from the stream (i.e. after ReadValue returned a valuetype of vaSet). The return value is the contents of the set, encoded in a bitmask the following way:

For each (enumerated) value in the set, the bit corresponding to the ordinal value of the enumerated value should be set. i.e. as 1 shl ord(value).

The TBinaryObjectReader class reads component data stored in binary form in a file. For this, it overrides or implements all abstract methods from . No new functionality is added by this class, it is a driver class for the streaming system.

It should never be necessary to create an instance of this class directly. Instead, the call should be used.

The TReader 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 to do the actual reading of data. The interface of the TReader class should be identical to the interface in Delphi.

Note that the TReader design is such that it can read a single component from a stream. It will read all children of this component, but it is not designed to read multiple components in succession from one stream.

It should never be necessary to create an instance of this class directly. Instead, the call should be used.

Error returns False if no handler is installed. If one is installed, then it will be called, passing the reader instance, message, and function return value as parameters.

If the function result False, i.e. when there is no handler installed or the handler restured False, then the calling code will raise an exception.

FindMethod will search for the method in ARoot. If it isn't found there, then it will call a OnFindMethod handler, if one is installed, passing it the method name AMethodName, the result pointer and a variable which says whether an exception should be raised if no method with name AMethodName is found.

If the method cannot be found and the OnFindMethod returns True, then an exception will be raised.

The TWriter class is a writer class that implements generic component streaming capabilities, independent of the format of the data in the stream. It uses a driver class to do the actual reading of data. The interface of the TWriter class should be identical to the interface in Delphi.

Note that the TWriter design is such that it will write a single component to a stream. It will write all children of this component, but it is not designed to write multiple components in succession to one stream.

It should never be necessary to create an instance of this class directly. Instead, the call should be used.

This class breaks a stream of text data in tokens. Its primary use is to help reading the contents of a form file (usually a file with dfm, xfm or lfm extension), and for this reason it isn't suitable to be used as a general parser.

The parser is always positioned on a certain token, whose type is stored in the Token property. Various methods are provided to obtain the token value in the desired format.

To advance to the next token, invoke NextToken method.

Create creates a new TParser instance, using Stream as the stream to read data from, and reads the first token from the stream.

CheckTokenSymbol performs a case-insensitive comparison of current token value with S.

Current token must be of type , otherwise an exception is raised.

HexToBinary reads a sequence of hexadecimal characters from the input stream and converts them to a sequence of bytes which is written to Stream. Each byte is represented by two contiguous hexadecimal characters.

Whitespace is allowed between hexadecimal characters if it doesn't appear between two characters that form the same byte.

HexToBinary stops when the first non-hexadecimal and non-whitespace character is found, or the end of the input stream is reached.

NextToken parses the next token in the stream and returns its type. The type of the token can also be retrieved later reading Token property.

If the end of the stream is reached, is returned.

For details about token types, see

If current token is , TokenComponentIdent tries to find subcomponent names separated by a dot (.). The returned string is the longest subcomponent path found. If there are no subcomponents, current symbol is returned.

Example

If source stream contains a.b.c and TParser is positioned on the first token (a), this method returns a.b.c.

If current token type is , this method returns the token value as a float.

To specify a negative number, no space must exist between unary minus and number.

Floating point numbers can be postfixed with a character that specifies the floating point type. See FloatType for further information.

If current token type is , this method returns the token value as an integer.

In the input stream an integer can be an hexadecimal (prefixed by '$' character) or decimal number. Decimal numbers can be prefixed by an unary minus: if this is the case, no space must exist between minus and number.

If current token type is or , this method returns the contents of the string. That is, enclosing quotes are removed, embedded quotes are unescaped and control strings are converted to the appropriate sequence of characters.

If current token type isn't a string, a string containing the token representation in the input stream is returned, without any conversion: hexadecimal integers are returned with the leading $, and floating point suffixes like s, c or d are kept. For tokens whose type isn't a special type, return value of TokenString equals Token.

If current token type is , this method returns the contents of the string. That is, enclosing quotes are removed, embedded quotes are unescaped and control strings are converted to the appropriate sequence of characters.

If current token isn't a widestring, TokenWideString behaviour is the same as TokenString.

TokenSymbolIs performs a case-insensitive comparison of current token value with S.

If current token isn't of type , or comparison fails, False is returned.

Floating point numbers can be postfixed with a character specifying the type of floating point value. When specified, this property holds the character postfixed to the number.

It can be one of the following values:

If Token isn't or one of the above characters wasn't specified, FloatType is the null character (zero).

This property holds the type of the current token. When Token isn't one of the special token types (whose value can be retrieved with specific methods) it is the character representing the current token.

Special token types:

To advance to the next token, use NextToken method.

TComponent 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 TComponent, as it includes all support for streaming all its published properties.

Components can 'own' other components. TComponent 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 TComponent

TComponent introduces a form of automatic memory management: When a component is destroyed, all its child components will be destroyed first.

ChangeName is called by the SetName procedure when the component name is set and the name has been verified. It actually sets the name of the component to NewName, and can be used to bypass the name checks which are done when the Name property is set.

Application programmers should never use SetName directly.

GetChildren 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 TComponent implementation is empty.

TComponent descendents should override this method. For each child that needs to be streamed, Proc should be called with as an argument the child component that must be streamed. The Root argument contains the root component relative to which all streaming is done.

GetChildOwner returns the owner of the children that are read from the stream. If the method returns Nil (the default) this means that streamed child components are owned by the root component of the streaming process (usually a Form or Datamodule)

Application programmers should not call GetChildOwner directly, it is called by the streaming system when needed.

GetChildParent 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 Nil is returned, then the root component of the streaming operation is assumed. The TComponent implementation of this method returns Self.

Application programmers should not call this method, it is called automatically by the streaming mechanism.

GetNamePath returns the name of the component as it will be shown in the object inspector.

TComponent overrides GetNamePath so it returns the Name property of the component.

Loaded 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 TComponent should override this method to do some additional processing of properties after all published properties have been set from values obtained from the stream.

Application programmers should never call Loaded directly, this is done automatically by the streaming system.

Notification 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 FreeNotification) will also call Notification when they are freed.

The AComponent parameter specifies which component sends the notification, and Operation specifies whether the component is being inserted into or removed from the child component list, or whether it is being destroyed.

Descendents of TComponent can use FreeNotification to request notification of the destruction of another object. By overriding the Notification method, they can do special processing (typically, set a reference to this component to Nil) when this component is destroyed. The Notification method is called quite often in the streaming process, so speed should be a consideration when overriding this method.

ReadState reads the component's state from a stream through the reader object reader. Values for all published properties of the component can be read from the stream. Normally there is no need to call ReadState directly. The streaming system calls ReadState itself.

The implementation of ReadState simply calls Descendent classes can, however, override ReadStateto provide additional processing of stream data.

SetAncestor includes or excludes the csAncestor flag in the ComponentState set property, depending on the boolean Value. The flag is set recursively for all owned components as well.

This is normally only done during the streaming system, and should not be called directly by an application programmer.

SetDesigning includes or excludes the csDesigning flag in the ComponentState set property, depending on the boolean Value. The flag is set recursively for all owned components as well.

This is normally only done during the streaming system, and should not be called directly by an application programmer.

Updating includes csUpdating in the ComponentState property of the component.

Normally, an application programmer should not call this method directly, it is called automatically by the streaming system.

Updated excludes csUpdating from the ComponentState property of the component.

Normally, an application programmer should not call this method directly, it is called automatically by the streaming system.

ValidateInsert should be implemented by descendent components to see whether the AComponent component may be inserted in the list of owned components.

This procedure does nothing in the TComponent implementation, it should be overridden by descendant components.

WriteState writes the component's current state to a stream through the writer object writer. Values for all published properties of the component can be written to the stream. Normally there is no need to call WriteState directly. The streaming system calls WriteState itself.

The implementation of WriteState simply calls . Descendent classes can, however, override WriteStateto provide additional processing of stream data.

DestroyComponents calls the destructor of all owned components, till no more components are left in the Components array.

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.

Destroying sets the csDestroying flag in the component's state property, and does the same for all owned components.

It is not necessary to call Destroying directly, the destructor Destroy does this automatically.

ComponentState 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:

The component state is set by various actions such as reading it from stream, destroying it etc.

Name is the name of the component. This name should be a valid identifier, i.e. must start with a letter or underscore, 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.

By "letters", 7-bit letters are meant.

TBasicAction 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.

Do not create instances of TBasicAction. Instead, create a descendent class and create an instance of this class instead.

Change calls the OnChange handler if one is assigned.

Application programmers should not call Change directly. It is called automatically if a property of an action component changes.

Descendent classes of TBasicAction should call explicitly call Change if one of their properties that affect client controls changes its value.

OnChange 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.

Application programmers should never use the OnChange event directly.

Create calls the inherited constructor, and then initializes the list of clients controls (or action lists).

Under normal circumstances it should not be necessary to create a TBasicAction descendent manually, actions are created in an IDE.

Destroy cleans up the list of client controls and then calls the inherited destructor.

An application programmer should not call Destroy directly; Instead Free should be called, if it needs to be called at all. Normally the controlling class (e.g. a TActionList) will destroy the action.

HandlesTarget returns True if Target 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 HandlesTarget directly, it will be called by the action itself when needed.

In TBasicAction this method is empty; descendent classes should override this method to implement appropriate checks.

UpdateTarget should update the client control specified by Target when the action updates itself. In TBasicAction, the implementation of UpdateTarget is empty. Descendent classes should override and implement UpdateTarget to actually update the Target object.

An application programmer should never need to call HandlesTarget directly, it will be called by the action itself when needed.

ExecuteTarget performs the action on the Target object. In TBasicAction 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 Post method of the dataset.

An application programmer should never call ExecuteTarget directly.

Update triggers the OnUpdate event, if one is assigned. It returns True if the event was triggered, or False if no event was assigned.

Application programmers should never run Update directly. The Update method is called automatically by the action mechanism; Normally this is in the Idle time of an application. An application programmer should assign the OnUpdate event, and perform any checks in that handler.

OnExecute 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 OnExecute event handler to execute whatever code is necessary when the button is pressed or the menu item is chosen.

Note that assigning an OnExecute handler will result in the Execute method returning a True value. Predefined actions (such as dataset actions) will check the result of Execute and will not perform their normal task if the OnExecute handler was called.

TBasicActionLink links an Action to its clients. With each client for an action, a TBasicActionLink 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.

An application programmer should never use a TBasicActionLink instance directly; They are created automatically when an action is associated with a component. Component programmers should create specialized descendents of TBasicActionLink which communicate changes in the action to the component.

Change is executed whenever the action changes. It executes the OnChange handler, if one is assigned.

Component programmers may decide to override the Change procedure in descendent classes to perform aditional actions when the properties of the action changes.

Create creates a new instance of a TBasicActionLink and assigns AClient as the client of the link.

Application programmers should never instantiate TBasicActionLink classes directly. An instance is created automatically when an action is assigned to a control (client).

Component programmers can override the create constructor to initialize further properties.

Destroy unregisters the TBasicActionLink with the action, and then calls the inherited destructor.

Application programmers should never call Destroy directly. If a link should be destroyed at all, the Free method should be called instead.

Execute sets the ActionComponent property of the associated Action to AComponent and then calls the Action's execute method. After the action has executed, the ActionComponent property is cleared again.

The return value of the function is the return value of the Action's execute method.

Application programmers should never call Execute directly. This method will be called automatically when the associated control is activated. (e.g. a button is clicked on)

Component programmers should call Execute whenever the action should be activated.

Update calls the associated Action's Update methoda.

Component programmers can override the Update method to provide additional processing when the Update method occurs.

OnChange is the event triggered when the action's properties change.

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.

Rect returns a record with the given top-left (ALeft,ATop) and bottom-right (ABottom,ARight) corners filled in.

No checking is done to see whether the coordinates are valid.

FindClass searches for the class named ClassName 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.

The function does not raise an exception when it does not find the class, but returns a Nil pointer instead.

GetClass searches for the class named ClassName in the list of registered classes and returns a class pointer to the definition. If no class with the given name could be found, Nil is returned.

The function will raise an exception if the does not find the class.

RegisterComponents 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.

Registercomponents inserts the component class in the correct component page. If the RegisterComponentsProc 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.

TIdentToInt is a callback used to look up identifiers (Ident) and return an integer value corresponding to this identifier (Int). The callback should return True if a value corresponding to integer Ident was found, False if not.

A callback of type TIdentToInt should be specified when an integer is registered using the call.

TIdentToInt is a callback used to look up integers (Ident) and return an identifier (Ident) that can be used to represent this integer value in an IDE. The callback should return True if a value corresponding to integer Ident was found, False if not.

A callback of type TIntToIdent should be specified when an integer is registered using the call.

TFindGlobalComponent 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 Name, or Nil if none is found.

The variable is a callback of type TFindGlobalComponent. 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.

FindGlobalComponent is a callback of type . 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.

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 Name, or Nil if none is found.

RegisterIntegerConsts registers a pair of callbacks to be used when an integer of type IntegerType must be mapped to an identifier (using IntToIdentFn) or when an identifier must be mapper to an integer (using IdentToIntFn).

Component programmers can use RegisterIntegerConsts 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 type integer syntax. If a type of integer is defined in this way, an IDE can show symbolic names for the values of these properties.

The IntegerType should be a pointer to the type information of the integer type. The IntToIdentFn and IdentToIntFn are two callbacks that will be used when converting between the identifier and integer value and vice versa. The functions and can be used to implement these callback functions.

InitInheritedComponent should be called from a constructor to read properties of the component Instance from the streaming system. The RootAncestor class is the root class from which Instance is a descendent. This must be one of TDatamodule, TCustomForm or TFrame.

The function returns True if the properties were successfully read from a stream or False if some error occurred.

RedirectFixupReferences examines the list of unresolved references and replaces references to a root object named OldRootName with references to root object NewRootName.

An application programmer should never need to call RedirectFixupReferences. This function can be used by an IDE to support redirection of broken component links.

RemoveFixupReferences examines the list of unresolved references and removes references to a root object pointing at Root or a root component named RootName.

An application programmer should never need to call RemoveFixupReferences. This function can be used by an IDE to support removal of broken component links.

ObjectTextToResource reads an object stream in text format from Input and writes a resource stream to Output.

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)

TRecall is a helper class used to copy published properties of a class (the reference object) in another class (the storage object). The reference object and storage object must be assignable to each other.

The TRecall can be used to store the state of a persistent class, and restore it at a later time.

When a TRecall object is created, it gets passed a reference instance and a storage instance. It immediatly stores the properties of the reference object in the storage object.

The Store method can be called throughout the lifetime of the reference object to update the stored properties.

When the TRecall instance is destroyed then the properties are copied from the storage object to the reference object. The storage object is freed automatically.

If the properties should not be copied back from the storage to the reference object, the Forget can be called.

Store assigns the reference instance to the storage instance. This will only work if the two classes can be assigned to each other.

This method can be used to refresh the storage.

Forget sets the Reference property to Nil. When the TRecall instance is destroyed, the reference instance will not be restored.

Note that after a call to Forget, a call to Store has no effect.

Insert creates a new item instance and inserts it in the collection at position Index, and returns the new instance.

In contrast, adds a new item at the end.

Source is the source stream. It should be used by descendent streams to access the source stream to read from or write to.

Do not free the Source reference directly if SourceOwner is True. In that case the owner stream instance will free the source stream itself.

NextValue returns the type of the next value in a binary stream, but does not read the value.

This method is simply the implementation for a binary stream of the abstract method introduced in

NextValue reads the next value in a binary stream and returns the type of the read value.

This method is simply the implementation for a binary stream of the abstract method introduced in

BeginRootComponent starts reading the root component in a binary stream.

This method is simply the implementation for a binary stream of the abstract method introduced in

This method is simply the implementation for a binary stream of the abstract method introduced in

This method is simply the implementation for a binary stream of the abstract method introduced in

ReadBinary reads a binary valye from a binary stream.

This method is simply the implementation for a binary stream of the abstract method introduced in

ReadFloat reads a float value from a binary stream.

This method is simply the implementation for a binary stream of the abstract method introduced in

ReadSingle reads a single-sized float value from a binary stream.

This method is simply the implementation for a binary stream of the abstract method introduced in

ReadDate reads a date value from a binary stream.

This method is simply the implementation for a binary stream of the abstract method introduced in

ReadIdent reads an identifier from a binary stream.

This method is simply the implementation for a binary stream of the abstract method introduced in

Read8Int reads an 8-bits signed integer from a binary stream.

This method is simply the implementation for a binary stream of the abstract method introduced in

Read16Int reads a 16-bits signed integer from a binary stream.

This method is simply the implementation for a binary stream of the abstract method introduced in

Read32Int reads a 32-bits signed integer from a binary stream.

This method is simply the implementation for a binary stream of the abstract method introduced in

Read64Int reads a 64-bits signed integer from a binary stream.

This method is simply the implementation for a binary stream of the abstract method introduced in

ReadSet reads a set from a binary stream.

This method is simply the implementation for a binary stream of the abstract method introduced in

ReadStr reads a short string from a binary stream.

This method is simply the implementation for a binary stream of the abstract method introduced in

ReadStr reads a string of type StringType from a binary stream.

This method is simply the implementation for a binary stream of the abstract method introduced in

SkipComponent skips the data of a component in a binary stream.

This method is simply the implementation for a binary stream of the abstract method introduced in .

SkipComponent skips the data of the next value in a binary stream.

This method is simply the implementation for a binary stream of the abstract method introduced in

OnPropertyNotFound can be used to take appropriate action when a property is read from a stream and no such property is found in the RTTI information of the Instance that is being read from the stream. It can be set at runtime, or at designtime by an IDE.

For more information about the meaning of the various arguments to the event handler, see .

TDataModule is a container for non-visual objects which can be used in an IDE to group non-visual objects which can be used by various other containers (forms) in a project. Notably, data access components are typically stored on a datamodule. Web components and services can also be implemented as descendents of datamodules.

TDataModule introduces some events which make it easier to program, and provides the needed streaming capabilities for persistent storage.

An IDE will typically allow to create a descendent of TDataModule which contains non-visual components in it's published property list.

Destroy destroys the TDataModule instance. If the OldCreateOrder property is True the OnDestroy event handler is called prior to destroying the data module.

Before calling the inherited destroy, the handler is called if it is set, and Self is passed as a parameter.

OldCreateOrder determines when exactly the OnCreate and OnDestroy event handlers are called.

If set to True, then the OnCreate event handler is called after the data module was streamed. If it is set to False, then the handler is called prior to the streaming process.

If set to True, then the OnDestroy event handler is called before the data module is removed from the streaming system. If it is set to False, then the handler is called after the data module was removed from the streaming process.

CheckSynchronize should be called regularly by the main application thread to handle any calls that may be waiting for execution by the main thread. If any such calls are waiting for execution by the main thread, they are executed at once, in the order that they were scheduled.

The function returns True if any Synchronize method was executed.

TimeOut is the maximum amount of time (in milliseconds) that the CheckSynchronize routine will wait for synchronisation requests to appear in the queue.

Calling this routine more often will ensure that synchronize requests are handled faster.

This routine may not be called from any thread other than the main thread, as it will execute the waiting requests.

Threads may call the to signal the main thread that the synchronisation queue contains items, and thus speed up the execution of the synchronize calls.

WakeMainThread is a handler, which, when set, is called by the routine to signal the main thread that a synchronization routine is waiting in the queue.

This handler is by default empty. An actual implementation depends on the main program logic (usually an event loop) and must be provided by the event loop logic: the event loop will normally call at regular intervals. The WakeMainThread can make sure this happens as soon as possible.

While this handle should alert the main program thread that a thread is waiting for synchronization, the call is executed by the thread, and should therefore NOT synchronize the thread, but should somehow signal the main thread that a thread is waiting for synchronization. For example, by sending a message.

StartClassGroup starts a new class group and adds AClass to it.

The class registration and streaming mechanism allows to organize the classes in groups. This allows an IDE to form groups of classes, which can be enabled or disabled. It is not needed at Run-Time.

GroupDescendentsWith adds AClass to the group that AClassGroup belongs to. If AClassGroup belongs to more than 1 group, then it is added to the group which contains the nearest ancestor.

The class registration and streaming mechanism allows to organize the classes in groups. This allows an IDE to form groups of classes, which can be enabled or disabled. It is not needed at Run-Time.

ActivateClassGroup activates the group of classes to which AClass belongs. The function returns the class that was last used to activate the class group.

The class registration and streaming mechanism allows to organize the classes in groups. This allows an IDE to form groups of classes, which can be enabled or disabled. It is not needed at Run-Time.

BinToHex converts the byte values in BinValue to a string consisting of 2-charachter hexadecimal strings in HexValue. BufSize specifies the length of BinValue, which means that HexValue must have size 2*BufSize.

For example a buffer containing the byte values 255 and 0 will be converted to FF00.

IInterfaceList is an interface for maintaining a list of interfaces, strongly resembling the standard class. It offers the same list of public methods as TList, with the exception that it uses interfaces instead of pointers.

All interfaces in the list should descend from IUnknown.

More detailed descriptions of how the various methods behave can be found in the TList reference.

TInterfaceList is a standard implementation of the interface. It uses a instance to store the list of interfaces.

Destroy first calls Clear and then frees the TInterfaceList instance from memory.

Note that the Clear method decreases the reference count of all interfaces.