diff --git a/docs/classes.xml b/docs/classes.xml new file mode 100644 index 0000000000..1669c75e72 --- /dev/null +++ b/docs/classes.xml @@ -0,0 +1,9101 @@ + + + + +Basic classes for FCL + +

This documentation describes the FPC classes unit. +The Classes unit contains basic classes for the Free Component +Library (FCL): +

+
    +
  • a class for maintaining lists of pointers,
    • +
  • for lists of strings,
    • +
  • to manage collections of objects
    • +
  • classes to support streaming.
    • +
+

+Furthermore it introduces methods for object persistence, and classes +that understand an owner-owned relationship, with automatic memory +management. +

+ + + +A class for managing multiple threads +This class is not yet implemented. + + + +Type to manage resources +This type is provided for Delphi compatibilty, it is used for resource +streams. + + + + +Type to manage streams. +This type is used as the handle for THandleStream stream descendents + + + +Special type for component names. +Names of components are of type TComponentName. By +specifying a different type, the Object inspector can handle this property +differently than a standard string property. + + + + +IUnknown Interface +IUknown is not yet implemented since interfaces are not yet supported +by FPC. + + + + +Special type for GUID's. +FPC doesn't support GUID yet. + + + + +Special type for handling modules. + +FPC doesn't support modules yet, so this is a dummy type. + + + + +Special type to handle a fake +position + +

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

+ + + + +Type to describe point in a small plane. +Same as , only the X and Y ranges are limited to +2-byte integers instead of 4-byte integers. + + + + +Descibes a rectangle + +TRect describes a rectangle in space with its upper-left (in +(Top,Left>)) and lower-right (in (Bottom +,Right)) corners. + + + + + +Maximum number of elemens in list. + + +This constant sets the maximum number of elements in a . + + + + + +Indicates Shift key in a keyboard shortcut. + + + + + +indicates CTRL key in a keyboard shortcut. + + + + + +Indicates ALT key in a keyboard shortcut. + + + + + +Indicates no special key is presed in a keyboard shortcut. + + + + + +Seek starts relative to the stream origin. + + + + + +Seek starts relative to the current position in +the stream. + + + + + +Seek starts relative to the stream end. + + + + + + creates a new file if needed. + + + + + + opens a file with read-only access. + + + + + + opens a file with write-only access. + + + + + + opens a file with read-write access. + + + + + +Token returned by , meaning the end of the input stream was reached. + + + + + +Value returned by when the end of the input stream was reached. + + + + + +Value returned by when a symbol was found in the input stream. + + + + + +Value returned by when a string was found in the +input stream. + + + + + +Value returned by when an integer was found in the +input stream. + + + + + +Value returned by when a floating point value was found in the +input stream. + + + + + +Constant that is found at the start of a binary stream containing a +streamed component. + + + + +Type to specify text alignment in controls that display text. + +

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

+ + + + + + +
TALignment values and their meanings.
ValueMeaning
taLeftJustifyText is displayed aligned to the left.
taRightJustifyText is displayed aligned to the right.
taCenterText is displayed centered.
+ + + + + +Indicates what special keys were pressed in combination with a normal key + + +

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

+ + + + + + + + + + + + + + + + +
Set elementKey pressed
ssShiftEither left or right shift key
ssAltEither left or right ALT key
ssCTRLEither left or right CTRL key
ssLeftEither left or right shift key
ssRight
ssMiddle
ssDouble
ssMetaThe META key
ssSuper
ssHyper
ssAltGrThe AltGr (right Alt) key
ssCapsThe CapsLock key
ssNumThe NumLock key
ssScrollThe ScrollLock key
+ + + + + +Standard event handler type. + + +Most event handlers are implemented as a property of type +TNotifyEvent. When this is set to a certain method of a class, +when the event occurs, the method will be called, and the class that generated +the event will pass itself along as the Sender argument. + + + + + + + + + +Special event for display of online help. + + +This event is used for display of online help. + + + + + + + + + +Event for retrieving string values. + + +This event is used as a callback to retrieve string values. It is used, +among other things, to pass along string properties in property editors. + + + + + + + + + +Exception raised when an error occurs during read or write operations on a +stream. + + +

+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. +
  2. Trying to seek beyond the beginning or end of the stream.
    3. +
  3. Trying to set the capacity of a memory stream and no memory is +available.
    4. +
  4. Trying to write to a resource stream.
    5. +
+ + + + + + + + + +Exception raised when an error occurred during creation of a +stream. + + +When the operating system reports an error during creation of a new file in +the Filestream Constructor, a +EFCreateError is raised. + + + + + + + + + +Exception raised when an error occurred during creation of a + + +When the operating system reports an error during the opening of a file in +the Filestream Constructor, a +EFOpenError is raised. + + + + + + + + + + +Exception raised by the component streaming system if an error occurs. + + +This class serves as an ancestor class for exceptions that are raised +when an error occurs during component streaming. + +A EFilerError exception is raised when a class is registered +twice. + + + + + + + + + + +Exception raised if an error occurs while reading from a 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. +
  2. The stream containing a component's data contains invalid data. +this will occurr only when reading a component from a stream.
    3. +
+ + + + + + + + + +Exception raised when an error occurs during writing to 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. +
  2. An error occurred when writing a property to a stream.
    3. +
+ + + + + + + + + +Exception raised when an unknown class is referenced in a streamed +component. + + +When the streaming system needs to create a component, it looks for the +class pointer (VMT) in the list of registered classes by its name. If this +name is not found, then an EClassNotFound is raised. + + + + + + + + + +This exception is no longer used. + + +This exception is no longer used in the streaming system. This error is +replaced by a . + + + + + + + + + + +Exception raised when the resource header needed for streaming of a +component is invalid. + + +This exception is not used by Free Pascal but is provided for Delphi +compatibility. + + + + + + +Exception raised when a resource, needed to initialize a component, is not found. + + +This exception is not used by Free Pascal but is provided for Delphi +compatibility. + + + + + + +Exception raised when an error occurs in lists handling. + + +

+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. +
  2. The list tried to grow beyond its maximal capacity.
    3. +
  3. An attempt was made to reduce the capacity of the list below the +current element count.
    4. +
  4. An attempt was made to set the list count to a negative value.
    5. +
  5. A non-existent element of the list was referenced. (i.e. the list index +was out of bounds)
    6. +
  6. An attempt was made to move an item to a position outside the list's +bounds.
    7. +
+ + +, + + + + + + + +Exception raised when an error occurs in a method of . + + +When an index of a bit in a is out of the valid range +(0 to Count-1) then a EBitsError exception +is raised. + + + + + + +Exception raised when an error occurs in a method of . + + +

+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. +
  2. The list tried to grow beyond its maximal capacity.
    3. +
  3. A non-existent element of the list was referenced. (i.e. the list index +was out of bounds)
    4. +
  4. An attempt was made to add a duplicate entry to a when is +False.
    5. +
+ + + + + + + + + + +Exception raised when an error occurs in the component registration +routines. + + +

+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. +
  2. A component with the same name and owner already exists.
    3. +
  3. The component registration system isn't set up properly.
    4. +
+ + + + + + + + + + +Exception raised when an error occurs during the parsing of streams. + + +When an error occurs during the parsing of a stream, an EParserError +is raised. Usually this indicates that an invalid token was found on the +input stream, or the token read from the stream wasn't the expected token. + + + + + + + + + +Exception raised when the system is out of resources. + + +This exception is not used in Free Pascal, it is defined for Delphi +compatibiliy purposes only. + + + + + + +Exception raised when an invalid operation is performed. Obsolete. + + +This exception is not used in Free Pascal, it is defined for Delphi +compatibiliy purposes only. + + + + + + +Class to manage collections of pointers. + +

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

+ + + + + + + + + + + +Destroys the list and releases the memory used to store the list elements. + + +Destroy destroys the list and releases the memory used to store +the list elements. The elements themselves are in no way touched, i.e. any +meomory they point to must be explicitly released before calling the +destructor. + + + + + + +Adds a new pointer to the list. + + +

+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 +Grow +Insert + + + + + + + +Clears the pointer list. + + +Clear removes all pointers from the list, and sets the capacity to +0, thus freeing any memory allocated to maintain the list. + + +Destroy + + + + + + + +Removes a pointer from the list. + + +

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

+ + + + + + +Raises an exception. + + +Error raises an exception, with a message +formatted with Msg and Data. + + + + + + + +Exchanges two pointers in the list. + + +Exchange exchanges the pointers at positions Index1 +and Index2. Both pointers must be withing the current range of +the list, or an exception will be raised. + + + + + + +Increases the capacity of the list if needed. + + +

+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. +
  2. If the capacity is larger than 3 and less than 8, the capacity is increased with 8.
    3. +
  3. If the capacity is larger than 8, the capacity is increased with 16.
    4. +
+

+The return value is Self. +

+ + +Capacity + + + + + + + +Returns the first non-nil pointer in the list. + + +

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

+ + +Last + + + + + + + +Returns the index of a given pointer. + + +

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

+ + + + + + +Inserts a new pointer in the list at a given position. + + +

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

+ + +Add +Delete + + + + + Pointer to be inserted. + + + + Position where to insert + + + + + +Returns the last non-nil pointer in the list. + + +

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

+ + +First + + + + + + +Moves a pointer from one position in the list to another. + + +

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

+ + +Exchange + + + + + + +Removes a value from the list. + + +Remove searches Item in the list, and, if it finds it, +deletes the item from the list. Only the first occurrence of Item +is removed. + + +Delete +IndexOf +Insert + + + + + + +Removes Nil pointers from the list and frees unused memory. + + +Pack removes all nil pointers from the list. +The capacity of the list is then set to the number of pointers in the list. + +This method can be used to free unused memory if the list has grown to +very large sizes and has a lot of unneeded nil pointers in it. + + + + + + + + + + +Sorts the pointers in the list. + + +

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

+ + + + + + +Current capacity (i.e. number of pointers that can be stored) of the list. + + +

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

+ + +SetCapacity +Count + + + + + + +Current number of pointers in the list. + + +Count is the current number of (possibly Nil) pointers +in the list. Since the list is zero-based, the index of the largest pointer +is Count-1. + +Capacity + + + + + +Probides access to the pointers in 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. +

+ + + + + + + +Memory array where pointers are stored. + + +List points to the memory space where the pointers are stored. +This can be used to quickly copy the list of pinters to another location. + + + + + + +List object containing all threads. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Used to calculate the size of a bits array + + + + + + + +Bitmask with all bits on. + + + + + + +Maximum number of bit records in TBits. + + + + + + +Maximum number of bits in TBits collection. + + + + + + +Array to store bits. + + + + + + + + + +Class to store collections of bits (binary values that can be 0 or 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. +

+ + + + +Creates a new bits collection. + +

+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 bit collection + +

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

+ + +None. + + +Create + + + + +Returns the number of records used to store the bits. + +GetFSize returns the number of records used to store the current +number of bits. + + +None. + + +Size + + + + +Turn a particular bit on. + +SetOn turns on the bit at position bit, i.e. sets it +to 1. +If bit is at a position bigger than the current size, the collection +is expanded to the required size using Grow. + + +If bit is larger than the maximum allowed bits array size or +is negative, an exception is raised. + + +Bits +Clear + + + + +Clears a particular bit. + +Clear clears the bit at position bit. If the array +If bit is at a position bigger than the current size, the collection +is expanded to the required size using Grow. + + +If bit is larger than the maximum allowed bits array size or +is negative, an exception is raised. + + +Bits +seton + + + + +Clears all bits in the array. + +ClearAll clears all bits in the array, i.e. sets them to zero. +ClearAll works faster than clearing all individual bits, since it +uses the packed nature of the bits. + + +None. + + +Bits +clear + + + + +Performs an and operation on the bits. + +andbits performs an and 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 cleared. + + +None. + + +ClearAll +OrBits +XOrBits +NotBits + + + + +Performs an or operation on the bits. + +

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

+ + +None. + + +ClearAll +andBits +XOrBits +NotBits + + + + +Performs a xor operation on the bits. + +

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

+ + +None. + + +ClearAll +andBits +OrBits +NotBits + + + + +Performs a not operation on the bits. + +

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

+ + +None. + + +ClearAll +andBits +OrBits +XOrBits + + + + +Retrieve the value of a particular bit + +Get returns True if the bit at position bit +is set, or False if it is not set. + + +If bit is not a valid bit index then an +exception is raised. + + +Bits +FindFirstBit +seton + + + + +Expands the bits array to the requested size. + +Grow expands the bit array so it can at least contain +nbit bits. If nbit is less than the current size, +nothing happens. + + +If there is not enough memory to complete the operation, then an +is raised. + + +Size + + + + +Determines whether the bits of 2 arrays are equal. + +

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

+ + +None. + + +ClearAll +andBits +OrBits +XOrBits + + + + +Sets the start position for FindNextBit and FindPrevBit + +

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

+ + +None. + + +FindNextBit +FindPrevBit +FindFirstBit +OpenBit + + + + +Find first bit with a particular value + +

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

+ + +None. + + +FindNextBit +FindPrevBit +OpenBit +SetIndex + + + + +Searches the next bit with a particular value. + +

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

+ + +None. + + +FindFirstBit +FindPrevBit +OpenBit +SetIndex + + + + +Searches the previous bit with a particular value. + +

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

+ + +None. + + +FindFirstBit +FindNextBit +OpenBit +SetIndex + + + + +Returns the position of the first bit that is set to False. + +OpenBit returns the position of the first bit whose value is +0 (False), or -1 if no open bit was found. +This call is equivalent to +FindFirstBit(False), except that it doesn't set the position for +the next searches. + + +None. + + +FindNextBit +FindPrevBit +FindFirstBit +SetIndex + + + + +Access to all bits in the array. + +Bits allows indexed access to all of the bits in the array. It +gives True if the bit is 1, False +otherwise; Assigning to this property will set, respectively clear the bit. + + +If an index is specified which is out of the allowed range then an exception is raised. + + +Size + + + + +Current size of the array of bits. + +Size is the current size of the bit array. Setting this property +will adjust the size; this is equivalent to calling Grow(Value-1) + + +If an invalid size (negative or too large) is specified, a exception is raised. + + +Bits + + + + + + +Base class for streaming system and persistent properties. + +

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

+ + + + + + + +Raises an EConvertError when an error occurs during +assignment. + +AssignError raises an EConvertError exception with +the classnames of the Source and destination classes. It is used +when two incompatible classes are assigned to each other. + + +Assign +AssignTo + + + + +Generic assignment function. + +

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

+ + Dest.AssignTo(Self); + +

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

+ + +Assign + + + + +Declare non-published properties that need to be streamed. + +

+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. +
  2. DefineProperty, to define a +property which contains binary data.
    3. +
+

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

+ + + + + + + + +Returns the owner of the component. + +GetOwner returns the owning component of the classes instane. +The TPersistent implementation of GetOwner returns +Nil. overrides this method. + + + + + + + +Destroys the TPersistent instance. + +Destroy disposes of the persistent object. This method should +never be called directly. Instead the Free method should be used. + + + + +Assign the contents of one class to another. + +

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

+ +

+In general, a statement of the form +

+ + Destination:=Source; + +

+(where Destination and Source are classes) does not +achieve the same as a statement of the form +

+ + Destination.Assign(Source); + +

After the former statement, both Source and +Destination will point to the same object. The latter statemtent +will copy the contents of the Source class to the +Destination class. +

+ + + +AssignTo + + + + +Returns a string that can be used to identify the class instance. + +

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

+ + + + + + + +Class reference type for . + +TPersistentClass is the class reference type for the class. + + + + + + + + + +Basic object that is managed by a class. + +

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

+ + + + + + + +Method to notify the managing collection that the name or index of +this item has changed. + + +This method is called when the is +set or when the is changed. + + + + + + + + + +Returns the namepath of this collection item. + +GetNamePath overrides the +method to return the name of the managing collection and appends its property. + + + + + + + + + +Returns the managing collection. + +TCollectionItem overrides to +and returns the that manages it. + + + + + + + + +Returns the of the +collectionitem + +

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

+ + + + + + + +Write method for the property. + +SetIndex implements the write handler for the property. It requests the managing collection to +move this item to the desired index value. + + + + + + + +Write method for the property + +

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

+ + + + + + + +Creates a new instance of this collection item. + +Create instantiates a new item in a . It +is called by the function and should under +normal circumstances never be called directly. +called + + + + + + + +Destroyes this collection item. + +

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

+

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

+ + + + + + + +Pointer to the collection managing this item. + +Collection points to the collection managing this item. This +property can be set to point to a new collection. If this is done, the old +collection will be notified that the item should no longer be managed, and +the new collection is notified that it should manage this item as well. + + + + + + + +Initial index of this item. + +

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 of the item in its managing collection property. + +

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

+ + + + + + + + +Name of the item, displayed in the object inspector. + +

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

+ + + + + + + + + + +Class reference for . + +TCollectionItemClass is used by the + property of to +identify the descendent class of which should +be created and managed. + + + + + + + + + + +Base class to manage collections of named objects. + +

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

+ + + + + + + +Returns the count of attributes associated with each item. + +

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

+ + + + + + + + +Returns an attribute of the collection. + +

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

+ + + + + + + + +Returns the attributes of an item. + +

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

+ + + + + + + + +Overrides to return a proper +pathname. + +

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

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

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

+ + + + + + + + +Procedure called if an item is added to or removed from the collection. + +Changed is called if a change takes place in the collection +managed by the class. If the update count ghas reached zero, it +calls with a nil argument. + + + + + + + + + +Read handler for the property. + +GetItem is the read handler for the property. It returns the Index-th +element from the list of objects. + + +If Index is outside the allowed range, then an exception is raised. + + + + + + + + + +Write handler for the property. + +SetItem implements the write handler for the property. It assignes Value to the +Index-th element in the array. For this to work properly, the + method of the Item must work +correctly. + + +If Index is outside the allowed range, then an exception is raised. + + + + + + + + + +Virtual method to set the name of the specified item + + + + + + + +Write handler for the property + +SetPropName must be overridden by descendent objects to set the + property to a suitable value. By default, +SetPropName sets the PropName property to empty. + + + + + + + +Hander called when an item in the collection has changed. + +

Update is called in the following cases: +

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

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

+ + + + + + + +Name of the property that this collection represents. + +PropName indicates the name of the property that this collection +is supposed to represent. By default, this is the empty string. Descendents +can override this property to return the name of the property that is +represented by this collection. + + + + + + + + +Creates a new collection. + +Create instantiates a new instance of the TCollection +class which will manage objects of class AItemClass. +It creates the list used to hold all objects, and stores the +AItemClass for the adding of new objects to the collection. + + + + + + + + +Destroys the collection and frees all the objects it manages. + +

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

+

+Don't call Destroy directly, call Free instead. +

+ + + + + + + +Creates and adds a new item to the collection. + +Add instantiates a new item of class and adds it to the list. The newly created +object is returned. + + + + + + + + +Assigns one collection to another. + +

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

+ + +If the objects in the collections cannot be assigned to one another, then +an EConvertError is raised. + + + + + + + + +Start an update batch. + +

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

+ + With MyCollection Do + try + BeginUpdate; + // Some Lengthy operations + finally + EndUpdate; + end; + +

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

+ + + + + + + + + +Removes all items from the collection. + +Clear will clear the collection, i.e. each item in the collection +is destroyed and removed from memory. +After a call to Clear, Count is zero. + + + + + + + + + +Ends an update batch. + +EndUpdate signals the end of a series of operations that change +the state of the collection, possibly triggering an update event. +It does this by decreasing the update count with 1 and calling it should always be used in conjunction with +, preferably in the Finally +section of a Try ... Finally block. + + + + + + + + + +Searches for an Item in the collection, based on its + property. + +

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

+ + + + + + + + +Number of items in the collection. + +

+Count contains the number of items in the collection. +

+ +The items in the collection are identified by their property, which is a zero-based index, meaning +that it can take values between 0 and Count. + + + + + + + + + +Class pointer for each item in the collection. + +ItemClass is the class pointer with which each new item in the +collection is created. It is the value that was passed to the collection's +constructor when it was created, and does not change during the lifetime of +the collection. + + + + + + + + +Indexed array 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. +

+ + + + + + + + + + + + + + + + + + + + + + +Class to manage arrays or collections of strings + +

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

+ + + + + + + +Method to stream the contents of the string collection + +DefineProperties allows the contents of the string collection +to be streamed. As such, it overrides + + + + + + + +Raises an exception. + +

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

+ + + + + + + +Abstract read handler for the property. + +

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

+ + + + + + + + + +Abstract Read handler for the property. + +

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

+ + + + + + + + +Abstract read handler for the property. + +

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

+ + + + + + + +Abstract read handler for the property. + +

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

+ + + + + + + + + +Read handler for the property. + +

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

+ + + + + + + + +Write handler for the property. + +

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

+ + + + + + + + + +Write handler for the property. + +

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

+ + + + + + + + + +Write handler for the property. + +

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

+ + + + + + + + +Write handler for the property. + +

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

+ + + + + + + + +Sets the update state. + +

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

+ + + + + + + + +Frees all strings and objects, and removes the list from memory. + +Destroy is the destructor of TStrings it does nothing +except calling the inherited destructor. + + + + + + +Add a string to the list + +Add adds S at the end of the list and returns the +index of S in the list (which should equal + + + +" + + + + + + + + +Add a string and associated object to the list. + +

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

+ +An object added to the list is not automatically destroyed by the list of +the list is destroyed or the string it is associated with is deleted. It is +the responsibility of the application to destroy any objects associated with +strings. + + + + + + + + + + + +Add a string to the list. + +Append does the same as , only it does +not return the index of the inserted string. + + + + + + + +Add contents of another stringlist to this list. + +AddStrings adds the contents of TheStrings to the +stringlist. Any associated objects are added as well. + + + + + + + + +Assign the contents of another stringlist to this one. + +Assign replaces the contents of the stringlist with the contents +of Source if Source is also of type +TStrings. Any associated objects are copied as well. + + + + + + + + + +Mark the beginning of an update batch. + +

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

+ +

+Always put the corresponding call to in the +context of a Finally block, to ensure that the update count is +always descreased at the end of the operation, even if an exception +occurred: +

+ + With MyStrings do + try + BeginUpdate; + // Some lengthy operation. + Finally + EndUpdate + end; + + + + + + + + + +Removes all strings and associated objects from the 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 a string from the list. + +

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

+ + +If Index is not in the allowed range, an is raised. + + + + + + + + + +Mark the end of an update batch. + +

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

+ + + + + + + +Compares the contents of two stringlists. + +

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

+ +
    +
  1. The strings are compared case-insensitively.
    2. +
  2. The associated objects are not compared
    3. +
+ + + + + + + + + + +Exchanges two strings in the list. + +

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

+ + +If either Index1 or Index2 is not in the range of valid +indexes, an exception is raised. + + + + + + + + + +Returns the contents as a PChar + +

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

+ +The caller is responsible for freeing the returned memory buffer. + + + + + + + +Find a string in the list and return its position. + +

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

+ +
    +
  1. Only the first occurrence of the string is returned.
    2. +
  2. The returned position is zero-based, i.e. 0 indicates the first string +in the list.
    3. +
+ + + + + + + + + + +Finds the index of a name in the name-value pairs. + +

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

+ +
    +
  1. Only the first occurrence of a matching name-value pair is returned.
    2. +
  2. The returned position is zero-based, i.e. 0 indicates the first string +in the list.
    3. +
+ + + + + + + + + + +Finds an object in the list and returns its index. + +

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

+ +
    +
  1. Only the first occurrence of a string with associated object +AObject is returned; if more strings in the list can be +associated with AObject, they will not be found by this routine.
    2. +
  2. The returned position is zero-based, i.e. 0 indicates the first string +in the list.
    3. +
+ + + + + + + +Insert a string in the list. + +

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

+ +
    +
  1. All methods that add strings to the list use Insert to add +a string to the list.
    2. +
  2. If the string has an associated object, use instead.
    3. +
+ + + +If Index is less than zero or larger than Count then +an exception is raised. + + + + + + + + + + + +Insert a string and associated object in 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. +

+ + +If Index is less than zero or larger than Count then +an exception is raised. + + + + + + + + + + +Load the contents of a file as a series of strings. + +

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

+ + + + + + + + + +Load the contents of a stream as a series of strings. + +LoadFromStream loads the contents of Stream + into the stringlist. +Each line in the stream (as marked by the end-of-line marker of the +particular OS the application runs on) becomes one string in the stringlist. +This action replaces +the contents of the stringlist, it does not append the strings to the +current content. + + + + + + + + + +Move a string from one place in the list to another. + +

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

+ +

+NewIndex is not the position in the stringlist before +the move operation starts. The move operation +

+
    +
  1. removes the string from position CurIndex
    2. +
  2. inserts the string at position NewIndex
    3. +
+

+This may not lead to the desired result if NewIndex is bigger +than CurIndex. Consider the following example: +

+ + With MyStrings do + begin + Clear; + Add('String 0'); + Add('String 1'); + Add('String 2'); + Add('String 3'); + Add('String 4'); + Move(1,3); + end; + +

+After the Move operation has completed, 'String 1' will be between 'String 3' +and 'String 4'. +

+ + + +If either CurIndex or NewIndex is outside the allowed +range, an is raised. + + + + + + + +Save the contents of the list to a file. + +

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

+ + +An exception can be raised if the file FileName cannot be opened, +or if it cannot be written to. + + + + + + + + + +Save the contents of the string to a stream. + +

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

+ + +An exception can be raised if the stream cannot be written to. + + + + + + + + + +Set the contents of the list from a PChar. + +SetText parses the contents of TheText and fills the +stringlist based on the contents. It regards TheText as a series +of strings, separated by end-of-line markers. Each of these strings is added +to the stringlist. + + + + + + + +Capacity of the list, i.e. number of strings that the list can +currently hold before it tries to expand. + +

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

+ + + + + + + + +Contents of the list as a comma-separated string. + +

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

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

+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
+
+ + + + + + + + +Number of strings in the list. + +

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

+ + + + + + + + + +Name parts of the name-value pairs in the list. + +

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

+ +The index is not an index based on the number of name-value pairs in the +list. It is the name part of the name-value pair a string Index +in the list. If the string at position Index is not a name-value +pair (i.e. does not contain the equal sign (=)), then an empty name is +returned. + + + + + + + + + +Indexed access to the objects associated with the strings 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. +

+ + +If an Index outside the valid range is specified, an exception will be raised. + + + + + + + + + + +Value parts of the name-value pairs in the list. + +

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

+ +
    +
  1. Names are compared case-insensitively.
    2. +
  2. Any character, including whitespace, up till the first equal (=) sign +in a string is considered part of the name.
    3. +
+ + + + + + + + + + +Indexed access to teh strings in the list. + +

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

+ + +If Index is outside the allowed range, an exception is raised. + + + + + + + + + + + +Contents of the list as one big string. + +

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

+ +If any of the strings in the list contains an end-of-line marker, then the +resulting string will appear to contain more strings than actually present +in the list. To avoid this ambiguity, use the +property instead. + + + + + + + + + + +Not implemented in Free Pascal. + + + + + + + +Type to describe what to do with duplicate values in a . + + + + + + + +Duplicate values will not be be added to the list, but no error will +be triggered. + + + + + +Duplicate values can be added to the list. + + + + + + + +If an attempt is made to add a duplicate value to the list, an + exception is raised. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Standard implementation of the class. + +

+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
    • +
+ + + + + + + + + +Called when the list of strings was modified. + + + + + + + +Called when the list is changing. + + + + + + + +Overrides the standard read handler for the property. + + + + + + + +Overrides the standard read handler for the property. + + + + + + + +Overrides the standard read handler for the property. + + + + + + + +Overrides the standard read handler for the property. + + + + + + + +Overrides the standard write handler for the property. + + + + + + + +Overrides the standard write handler for the property. + + + + + + + +Overrides the standard write handler for the property. + + + + + + + +Overrides the standard +call. + + + + + + + +Destroys the stringlist. + +

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

+ +Any objects associated to strings in the list will not be +destroyed; it is the responsability of the caller to destroy all objects +associated with strings in the list. + + + + + +Implements the function. + +

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

+ + +If the list is sorted and the string S is already present in the list and + is dupError then an exception is raised. + + + + + + + + +Implements the function. + + + + + + + +Implements the function. + + + + + + + +Implements the function. + +

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

+ +Exchange will not check whether the list os sorted or not; +if Exchange is called on a sorted list and the strings are not +identical, the sort order of the list will be destroyed. + + + + + + + + + +Locates the index for a given string in sorted lists. + +

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

+ +
    +
  1. Use this method only on sorted lists. For unsorted lists, use instead.
    2. +
  2. Find uses a binary search method to locate the string
    3. +
+ + + + + + + +Overrides the property. + +IndexOf overrides the ancestor method . It tries to optimize the +search by executing a binary search if the list is sorted. The function +returns the position of S if it is found in the list, or -1 if +the string is not found in the list. + + + + + + + + +Overrides the method. + +Insert will insert the string S at position +Index in the list. If the list is sorted, an exception will be raised instead. Index +is a zero-based position. + + +If Index contains an invalid value (less than zero or larger than +Count, or the list is sorted, an +exception will be raised. + + + + + + + + + +Sorts the strings in the list. + +Sort will sort the strings in the list using the quicksort +algorithm. If the list has its property set +to True then nothing will be done. + + + + + + + +Describes the behaviour of a sorted list with respect to duplicate +strings. + +

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

+ + + + +
dupIgnore
dupError
dupAccept
+

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

+ + + + + + +Determines whether the list is sorted or not. + +

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

+ +
    +
  1. +When Sorted is True, +cannot be used. For sorted lists, should be +used instead.
    2. +
  2. If Sorted is True, the setting has effect. This setting is ignored +when Sorted is False.
    3. +
+ + + + + + + + + + + +Event triggered after the list was modified. + +

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

+ + + + + + + +Event triggered when the list is about to be modified. + +

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

+ + + + + + + + + +Base class for streams. + +

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

+ + + + + + + + + +Sets the size of the stream + +SetSize is the write handler for the +property. The TStream implementation of SetSize does +nothing, but descendent classes may override this methods to allow +programmers to set the size of the stream. + + + + + + + + +Reads data from the stream to a buffer and returns the number of +bytes read. + +

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

+ + +Descendent classes that do not allow reading from the stream may raise an +exception when the Read is used. + + + + + + + + +Writes data from the stream to the buffer and returns the number of +bytes written. + +

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

+ + +Descendent classes that do not allow writing to the stream may raise an +exception when Write is used. + + + + + + + + +Sets the current position in the stream + +

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

+ + + + + +
ConstantMeaning
soFromBeginningSet the position relative to the start of +the stream.
soFromCurrentSet the position relative to the beginning of +the stream.
soFromEndSet the position relative to the end of the +stream.
+

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

+ + +An exception may be raised if this method is called with an invalid pair of +Offset,Origin values. e.g. a negative +offset for soFromBeginning. + + + + + + + +Reads data from the stream to a buffer + +

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

+ + +If the stream does not allow to read Count bytes, then an +exception is raised. + + + + + + + + +Writes data from the stream to the buffer + +

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

+ + +If the stream does not allow to write Count bytes, then an +exception is raised. + + + + + + + + +Copy data from one stream to another + +

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

+ + + + + + + + +Reads component data from a 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. +

+ + +If an error occurs during the reading of the component, an exception is raised. + + + + + + + + + +Reads component data and resource header from a stream + +

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

+ + +If an error occurs during the reading of the component, an exception is raised. + + + + + + + + +Write component data to the stream + +

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

+ + + + + + + + +Write resource header and component data to a stream + +

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

+ + + + + + + + +Write component data to a stream, relative to an ancestor + +

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

+ + + + + + +Write resource header and component data to a stream, relative to an ancestor + +

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

+ + + + + + +Write resource header to the 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. +

+ + + + + + + + + +Not implemented in FPC + +

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

+ + + + + + + + + + +Read a resource header from the stream. + +

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

+ + +If the resource header is invalid an exception is +raised. + + + + + + + + +Read a byte from the stream and return its value. + +ReadByte reads one byte from the stream and returns its value. + + +If the byte cannot be read, a exception will be +raised. This is a utility function which symply calls the +Read function. + + + + + + + + + + + + +Read a word from the stream and return its value. + +ReadWord reads one Word (i.e. 2 bytes) from the stream +and returns its value. This is a utility function which symply calls the +Read function. + + +If the word cannot be read, a exception will be +raised. + + + + + + + + + + + +Read a DWord from the stream and return its value. + +ReadDWord reads one DWord (i.e. 4 bytes) from the stream +and returns its value. This is a utility function which simply calls the +Read function. + + +If the DWord cannot be read, a exception will be +raised. + + + + + + + + + + + +Read an ansistring from the stream and return its value. + +ReadAnsiString reads an ansistring from the stream +and returns its value. This is a utility function which simply calls the +read function several times. + +The Ansistring should be stored as 4 bytes (a DWord) representing the length +of the string, and then the string value itself. +The WriteAnsiString function +writes an ansistring in such a format. + + +If the AnsiString cannot be read, a exception will be +raised. + + + + + + + + + + + +Write a byte to the stream. + +WriteByte writes the byte B to the stream. This is a +utility function which simply calls the Write function. + +The byte can be read from the stream using the ReadByte function. + + +If an error occurs when attempting to write, an exception will be raised. + + + + + + + + + + + +Write a word to the stream. + +WriteWord writes the word W (i.e. 2 bytes) to the stream. This is a +utility function which simply calls the Write function. + +The word can be read from the stream using the ReadWord function. + + +If an error occurs when attempting to write, an exception will be raised. + + + + + + + + + + + +Write a DWord to the stream. + +WriteDWord writes the DWord D (i.e. 4 bytes) to the stream. This is a +utility function which simply calls the Write function. + +The DWord can be read from the stream using the ReadDWord function. + + +If an error occurs when attempting to write, an exception will be raised. + + + + + + + + + + + +Write an ansistring to the stream. + +WriteAnsiString writes the AnsiString S (i.e. 4 bytes) to the stream. This is a +utility function which simply calls the Write function. + +The ansistring is written as a 4 byte length specifier, followed by the +ansistring's content. + +The ansistring can be read from the stream using the ReadAnsiString function. + + +If an error occurs when attempting to write, an exception will be raised. + + + + + + + + + + + +The current position in the stream. + +

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

+ +Not all TStream descendants support setting the position in the +stream, so this should be used with care. + + + +Some descendents may raise an exception if they +do not support setting the stream position. + + + + + + + + +The current size of the stream. + +

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

+ +Not all descendents of TStream support getting or setting the +stream size; they may raise an exception if the Size property +is read or set. + + + + + + + + + + + +Base clas for streams that are identified by an OS handle. + +

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

+ +
    +
  • +ThandleStream does not obtain a handle from the OS by itself, +it just handles reading and writing to such a handle by wrapping the system +calls for reading and writing; +Descendent classes should obtain a handle from the OS by themselves and pass it on in the inherited +constructor.
    • +
  • +Contrary to Delphi, no seek is implemented for THandleStream, +since pipes and sockets do not support this. The seek is implemented in +descendent methods that support it. +
    • +
+ + + + + + + + + +Create a handlestream from an OS Handle. + +Create creates a new instance of a THandleStream +class. It stores AHandle in an internal variable and +then calls the inherited constructor. + + + + + + + +Overrides standard read method. + +

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

+ + +If the operating system reports an error while reading from the handle, -1 +is returned. + + + + + + + + + +Overrides standard write method. + +

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

+ + +If the operating system reports an error while writing to handle, -1 +is returned. + + + + + + + + + +The OS handle of the stream. + +Handle represents the Operating system handle to which reading +and writing is done. The handle can be read only, i.e. it cannot be set +after the THandlestream instance was created. It should be +passed to the constructor + + + + + + + + + + +Stream that stores its data in a named file on disk. + +

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

+ + + + + + + + +Sets the size of the file stream. + +

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

+ + + + + + + +Creates a file stream. + +

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

+ + + + + + + + + + + + + +
fmCreate
fmOpenRead
fmOpenWrite
fmOpenReadWrite
+

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

+ + +If the file could not be opened in the requested mode, an exception is raised. + + + + + + + + + +Destroys the file stream. + +

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

+ + + + + + + +Overrides the standard method. + +

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

+ + + + + + + + + + +
soFromBeginning
soFromCurrent
soFromEnd
+

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

+ + +On error, -1 is returned, and the position is not changed. + + + + + + + + +The filename of the stream. + +FileName is the name of the file that the stream reads from or writes +to. It is the name as passed in the constructor of the stream; it cannot be +changed. To write to another file, the stream must be freed and created +again with the new filename. + + + + + + + + + +Abstract stream that stores its data in memory. + +

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

+ +Since TCustomMemoryStream is an abstract class, do not create +instances of TMemoryStream directly. Instead, +create instances of descendents such as . + + + + + + + + + +Sets the internal memory pointer and size of the memory block. + +

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

+ + + + + + + + +Reads Count bytes from the stream into buffer. + +

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

+ + + + + + + + +Sets a new position in the stream. + +Seek overrides the abstract method. +It simply updates the internal stream position, and returns the new +position. + + +No checking is done whether the new position is still a valid position, i.e. +whether the position is still within the range 0..Size. +Attempting a seek outside the valid memory range of the stream may result in +an exception at the next read or write operation. + + + + + + + + + +Writes the contents of the memory stream to another stream. + +

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

+ +

+This method will work much faster than the use of the + method: +

+ + Seek(0,soFromBeginning); + Stream.CopyFrom(Self,Size); + +

+because the CopyFrom method copies the contents in blocks, while +SaveToStream writes the contents of the memory as one big block. +

+ + + +If an error occurs when writing to Stream an exception will be raised. + + + + + + + + +Writes the contents of the stream to a file. + +

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

+ +

+This method will work much faster than the use of the method: +

+ + Stream:=TFileStream.Create(fmCreate,FileName); + Seek(0,soFromBeginning); + Stream.CopyFrom(Self,Size); + +

+because the CopyFrom method copies the contents in blocks, while +SaveToFile writes the contents of the memory as one big block. +

+ + + +If an error occurs when creating or writing to the file, an exception may occur. + + + + + + + + + +Pointer to the data kept in the memory stream. + +

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

+ +Do not write to the memory pointed to by Memory, since the memory +content may be read-only, and thus writing to it may cause errors. + + + + + + + + + + +Standard implementation of a stream that stores its data in memory + +

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

+ + + + + + + + +Sets the new capacity for the memory stream + +

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

+ + + + + + + +Current capacity of the stream. + +

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

+ + + + + + + +Frees any allocated memory and destroys the memory stream. + +Free clears the memory stream, thus in effect freeing any memory +allocated for it, and then frees the memory stream. + + + + +Zeroes the position, capacity and size of the stream. + +Clear sets the position and size to 0, and sets the capacity of +the stream to 0, thus freeing all memory allocated for the stream. + + + + + + + + + +Loads the contents of a stream into memory. + +

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

+ +

+The LoadFromStream uses the Size +property of Stream to determine how much memory must be +allocated. Some streams do not allow the stream size to be determined, so +care must be taken when using this method. +

+

+This method will work much faster than the use of the method: +

+ + Seek(0,soFromBeginning); + CopyFrom(Stream,Stream.Size); + +

+because the CopyFrom method copies the contents in blocks, while +LoadFromStream reads the contents of the stream as one big block. +

+ + + +If an error occurs when reading from the stream, an may occur. + + + + + + + + +Loads the contents of a file into memory. + +

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

+ +If an error occurs when creating or reading from the stream, an may occur. + + + + + + +Sets the size for the memory stream. + +SetSize sets the size of the memory stream to NewSize. +This will set the capacity of the stream to NewSize and correct +the current position in the stream when needed. + + + + + + + + +Writes data to the stream's memory. + +

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

+ + +If no more memory could be allocated, then an exception will be raised. + + + + + + + + + + +Stream that stores its data in a string. + +

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

+ + + + + + + + + + +Sets the size of the stream. + +SetSize sets the size of the stream to newsize. +It does this by setting the size of the ansisting in which the stream +is stored. NewSize can have any value greater than or equal to +zero. + + +In case there is not enough memory, an exception may be raised. + + + + + + + +Creates a new stringstream and sets its initial content. + +Create creates a new TStringStream instance and +sets its initial content to Astring. The position is still 0 but +the size of the stream will equal the length of the string. + + + + + + + +Reads from the stream. + +Read implements the abstract Read +from . It tries to read Count bytes into +Buffer. It returns the number of bytes actually read. The +position of the stream is advanced with the number of bytes actually read; +When the reading has reached the end of the DataString, then the reading stops, +i.e. it is not possible to read beyond the end of the datastring. + + + + + + + + + +Reads a string of length Count + +

+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. + + + + + + + + +Sets the position in the stream. + +Seek implements the abstract Seek +method. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Stream that reads its data from a resource object. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Class responsible for streaming of components. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Abstract driver class to read stored component data. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Driver class which reads component data stored in binary format. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Generic reader object which reads component data from any given source. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Abstract driver class for writing component data. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Driver class which stores component data in binary form. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Driver class which stores component data in text format. + + + + + + + + + + + + + + + + + +Object to write component data to an arbitrary format. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Class to parse the contents of a stream containing text data. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Thread error exception. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Basic thread class, which starts a new thread. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Base class for all components that need owner-owned functionality. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/fakehtml.sty b/docs/fakehtml.sty new file mode 100644 index 0000000000..3b0b4011f7 --- /dev/null +++ b/docs/fakehtml.sty @@ -0,0 +1,127 @@ +% +% $Id$ +% This file is part of the FPC documentation. +% Copyright (C) 1997, by Michael Van Canneyt +% +% The FPC documentation is free text; you can redistribute it and/or +% modify it under the terms of the GNU Library General Public License as +% published by the Free Software Foundation; either version 2 of the +% License, or (at your option) any later version. +% +% The FPC Documentation is distributed in the hope that it will be useful, +% but WITHOUT ANY WARRANTY; without even the implied warranty of +% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +% Library General Public License for more details. +% +% You should have received a copy of the GNU Library General Public +% License along with the FPC documentation; see the file COPYING.LIB. If not, +% write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, +% Boston, MA 02111-1307, USA. +% +\ProvidesPackage{fakehtml}[2001/07/01] +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% based upon Eijkhout's comment.sty v2.0 +% with modifications to avoid conflicts with later versions +% of this package, should a user be requiring it. +% Ross Moore, 10 March 1999 +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% Comment.sty version 2.0, 19 June 1992 +% selectively in/exclude pieces of text: the user can define new +% comment versions, and each is controlled separately. +% This style can be used with plain TeX or LaTeX, and probably +% most other packages too. +% +% Examples of use in LaTeX and TeX follow \endinput +% +% Author +% Victor Eijkhout +% Department of Computer Science +% University Tennessee at Knoxville +% 104 Ayres Hall +% Knoxville, TN 37996 +% USA +% +% eijkhout@cs.utk.edu +% +% Usage: all text included in between +% \comment ... \endcomment +% or \begin{comment} ... \end{comment} +% is discarded. The closing command should appear on a line +% of its own. No starting spaces, nothing after it. +% This environment should work with arbitrary amounts +% of comment. +% +% Other 'comment' environments are defined by +% and are selected/deselected with +% \includecomment{versiona} +% \excludecoment{versionb} +% +% These environments are used as +% \versiona ... \endversiona +% or \begin{versiona} ... \end{versiona} +% with the closing command again on a line of its own. +% +% Basic approach: +% to comment something out, scoop up every line in verbatim mode +% as macro argument, then throw it away. +% For inclusions, both the opening and closing comands +% are defined as noop +% +% Changed \next to \html@next to prevent clashes with other sty files +% (mike@emn.fr) +% Changed \html@next to \htmlnext so the \makeatletter and +% \makeatother commands could be removed (they were causing other +% style files - changebar.sty - to crash) (nikos@cbl.leeds.ac.uk) +% Changed \htmlnext back to \html@next... + +\def\makeinnocent#1{\catcode`#1=12 } +\def\csarg#1#2{\expandafter#1\csname#2\endcsname} + +\def\ThrowAwayComment#1{\begingroup + \def\CurrentComment{#1}% + \let\do\makeinnocent \dospecials + \makeinnocent\^^L% and whatever other special cases +%%RRM +%% use \xhtmlComment for \xComment +%% use \html@next for \next + \endlinechar`\^^M \catcode`\^^M=12 \xhtmlComment} +{\catcode`\^^M=12 \endlinechar=-1 % + \gdef\xhtmlComment#1^^M{\def\test{#1}\edef\test{\meaning\test} + \csarg\ifx{PlainEnd\CurrentComment Test}\test + \let\html@next\endgroup + \else \csarg\ifx{LaLaEnd\CurrentComment Test}\test + \edef\html@next{\endgroup\noexpand\end{\CurrentComment}} + \else \csarg\ifx{LaInnEnd\CurrentComment Test}\test + \edef\html@next{\endgroup\noexpand\end{\CurrentComment}} + \else \let\html@next\xhtmlComment + \fi \fi \fi \html@next} +} + +%%\def\includecomment %%RRM +\def\htmlincludecomment + #1{\expandafter\def\csname#1\endcsname{}% + \expandafter\def\csname end#1\endcsname{}} +%%\def\excludecomment %%RRM +\def\htmlexcludecomment + #1{\expandafter\def\csname#1\endcsname{\ThrowAwayComment{#1}}% + {\escapechar=-1\relax + \edef\tmp{\string\\end#1}% + \csarg\xdef{PlainEnd#1Test}{\meaning\tmp}% + \edef\tmp{\string\\end\string\{#1\string\}}% + \csarg\xdef{LaLaEnd#1Test}{\meaning\tmp}% + \edef\tmp{\string\\end \string\{#1\string\}}% + \csarg\xdef{LaInnEnd#1Test}{\meaning\tmp}% + }} + +%%\excludecomment{comment} %%RRM +\htmlexcludecomment{comment} +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% end Comment.sty +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\let\includecomment=\htmlincludecomment +\let\excludecomment=\htmlexcludecomment + +\newcommand{\latex}[1]{#1} +\newcommand{\html}[1]{} +\htmlexcludecomment{htmlonly} +\newenvironment{latexonly}[1]{}{}