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

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

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

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

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 .

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.

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

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 teh 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 abstract 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 implement these abstract 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.

Read is an abstract method that is overridden by descendent classes 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.

Write is an abstract method that is overridden by descendent classes to do the actual writinging.

Seek sets the position of the stream to Offset bytes from Origin. Origin can have one of the following values:

Offset should be negative when the origin is SoFromEnd. 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 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 instead. WriteBuffer uses Write internally to do the actual reading.

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.

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 implements the abstract 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 implements the abstract 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 abstract 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 abstract 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 diretly 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 abstract 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 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.

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.

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;

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