1
<?xml version="1.0" encoding="ISO8859-1"?>
5
$Id: objects.xml,v 1.5 2005/05/05 13:11:50 peter Exp $
6
This file is part of the FPC documentation.
7
Copyright (C) 1997, by Michael Van Canneyt
9
The FPC documentation is free text; you can redistribute it and/or
10
modify it under the terms of the GNU Library General Public License as
11
published by the Free Software Foundation; either version 2 of the
12
License, or (at your option) any later version.
14
The FPC Documentation is distributed in the hope that it will be useful,
15
but WITHOUT ANY WARRANTY; without even the implied warranty of
16
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
17
Library General Public License for more details.
19
You should have received a copy of the GNU Library General Public
20
License along with the FPC documentation; see the file COPYING.LIB. If not,
21
write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
22
Boston, MA 02111-1307, USA.
25
<module name="objects">
26
<short>TP-Compatible basic Objects.</short>
27
<!-- \FPCexampledir{objectex} -->
30
This document documents the <file>objects</file> unit. The unit was implemented by
31
many people, and was mainly taken from the FreeVision sources. It has been
32
ported to all supported platforms.
35
The methods and fields that are in a <var>Private</var> part of an object
36
declaration have been left out of this documentation.
41
<short>Stream error codes: No error</short>
44
<element name="stError">
45
<short>Stream error codes: Access error</short>
48
<element name="stInitError">
49
<short>Stream error codes: Initialize error</short>
52
<element name="stReadError">
53
<short>Stream error codes: Stream read error</short>
56
<element name="stWriteError">
57
<short>Stream error codes: Stream write error</short>
60
<element name="stGetError">
61
<short>Stream error codes: Get object error</short>
64
<element name="stPutError">
65
<short>Stream error codes: Put object error</short>
68
<element name="stSeekError">
69
<short>Stream error codes: Seek error in stream</short>
72
<element name="stOpenError">
73
<short>Stream error codes: Error opening stream</short>
76
<element name="stCreate">
77
<short>Stream initialization mode: Create new file</short>
80
<element name="stOpenRead">
81
<short>Stream initialization mode: Read access only</short>
84
<element name="stOpenWrite">
85
<short>Stream initialization mode: Write access only</short>
88
<element name="stOpen">
89
<short>Stream initialization mode: Read/write access</short>
92
<element name="coIndexError">
93
<short>Collection list error: Index out of range</short>
96
<element name="coOverflow">
97
<short>Collection list error: Overflow</short>
100
<element name="MaxBytes">
101
<short>Maximum data size (in bytes)</short>
104
<element name="MaxWords">
105
<short>Maximum data size (in words)</short>
108
<element name="MaxPtrs">
109
<short>Maximum data size (in pointers)</short>
112
<element name="MaxReadBytes">
113
<short>Maximum data that can be read from a stream (not used)</short>
116
<element name="MaxCollectionSize">
117
<short>Maximum collection size (in items)</short>
120
<element name="DefaulTPCompatible">
121
<short>Is the default stream content TP compatible</short>
123
This variable determines whether the default stream is filled or read in a
124
TP compatible way. The <var>TPCompatible</var> field can be set on a
125
per-stream basis, and is initialized with the <var>DefaulTPCompatible</var>
130
<element name="RCollection">
131
<short>Default stream record for the <link id="TCollection"/> object.</short>
134
<element name="RStrCollection">
135
<short>Default stream record for the <link id="TStrCollection"/> object.</short>
138
<element name="RStringCollection">
139
<short>Default stream record for the <link id="TStringCollection"/> object.</short>
142
<element name="RStringList">
143
<short>Default stream record for the <link id="TStringList"/> object.</short>
146
<element name="RStrListMaker">
147
<short>Default stream record for the <link id="TStrListMaker"/> object.</short>
150
<element name="StreamError">
151
<short>Pointer to default stream error handler.</short>
154
<element name="vmtHeaderSize">
155
<short>Size of the VMT header in an object (not used).</short>
159
<element name="MaxTPCompatibleCollectionSize">
160
<short>Maximum collection size (in items, same value as in TP)</short>
164
<element name="TCharSet">
165
<short>Generic set of characters type.</short>
168
<element name="PCharSet">
169
<short>Pointer to <link id="TCharSet"/>.</short>
172
<element name="TByteArray">
173
<short>Array with maxmimum allowed number of bytes.</short>
176
<element name="PByteArray">
177
<short>Pointer to <link id="TByteArray"/></short>
180
<element name="TWordArray">
181
<short>Array with maxmimum allowed number of words.</short>
184
<element name="PWordArray">
185
<short>Pointer to <link id="TWordArray"/></short>
188
<element name="TPointerArray">
189
<short>Array with maxmimum allowed number of pointers</short>
192
<element name="PPointerArray">
193
<short>Pointer to <link id="TPointerArray"/></short>
196
<element name="PString">
197
<short>Pointer to a shortstring.</short>
200
<element name="AsciiZ">
201
<short>Filename - null terminated array of characters.</short>
204
<element name="FNameStr">
205
<short>Filename - shortstring version.</short>
208
<element name="Sw_Word">
209
<short>Alias for Cardinal</short>
212
<element name="Sw_Integer">
213
<short>Alias for longint</short>
216
<element name="WordRec">
217
<short>Record describing a Word (in bytes)</short>
220
<element name="WordRec.Hi">
221
<short>High byte of a word</short>
224
<element name="WordRec.Lo">
225
<short>Low byte of a word</short>
228
<element name="LongRec">
229
<short>Record describing a longint (in Words)</short>
232
<element name="LongRec.Lo">
233
<short>Lower word of longint</short>
236
<element name="LongRec.Hi">
237
<short>High word of longint</short>
240
<element name="PtrRec">
241
<short>Record describing a pointer to a memory location.</short>
244
<element name="PtrRec.Ofs">
245
<short>Pointer offset</short>
248
<element name="PtrRec.Seg">
249
<short>Pointer segment</short>
252
<element name="PStreamRec">
253
<short>Pointer to <link id="TStreamRec"/></short>
256
<element name="TStreamRec">
257
<short>Record used in streaming mechanism. </short>
259
<var>TSreamRec</var> is used by the <file>Objects</file> unit streaming
260
mechanism: when an object is registered, a <var>TStreamRec</var> record is
261
added to a list of records. This list is used when objects need to be
262
streamed from/streamed to a stream. It contains all the information needed
263
to stream the object.
267
<element name="TStreamRec.ObjType">
268
<short>Unique identifier for this object type.</short>
271
<element name="TStreamRec.VmtLink">
272
<short>Pointer to object VMT</short>
275
<element name="TStreamRec.Load">
276
<short>Procedure to call when object must be loaded from a stream</short>
279
<element name="TStreamRec.Store">
280
<short>Procedure to call when object must be stored in a stream.</short>
283
<element name="TStreamRec.Next">
284
<short>Next item in list</short>
287
<element name="PPoint">
288
<short>Pointer to <link id="TPoint"/> record.</short>
291
<element name="TPoint">
292
<short>Record describing a point in a 2 dimensional plane.</short>
295
<element name="TPoint.X">
296
<short>X coordinate</short>
299
<element name="TPoint.Y">
300
<short>Y coordinate</short>
303
<element name="TItemList">
304
<short>Pointer array type used in a <link id="TCollection"/></short>
307
<element name="TStrIndex">
308
<short>Pointer array type used in a <link id="TStringList"/></short>
311
<element name="TStrIndexRec">
312
<short>Record type used in a <link id="TStringList"/> to store the strings</short>
315
<element name="TStrIndexRec.Key">
316
<short>String key value</short>
319
<element name="TStrIndexRec.Count">
320
<short>String character count</short>
323
<element name="TStrIndexRec.Offset">
324
<short>String offset in stream</short>
327
<element name="NewStr">
328
<short>Allocate a copy of a shortstring on the heap.</short>
331
<var>NewStr</var> makes a copy of the string <var>S</var> on the heap,
332
and returns a pointer to this copy. If the string is empty then
333
<var>Nil</var> is returned.
336
The allocated memory is not based on the declared size of the string passed
337
to <var>NewStr</var>, but is baed on the actual length of the string.
341
If not enough memory is available, an 'out of memory' error will occur.
344
<link id="DisposeStr"/>
347
<example file="objectex/ex40"/>
350
<element name="SetStr">
351
<short>Allocate a copy of a shortstring on the heap.</short>
354
<var>SetStr</var> makes a copy of the string <var>S</var> on the heap and
355
returns the pointer to this copy in <var>P</var>. If <var>P</var> pointed to
356
another string (i.e. was not <var>Nil</var>, the memory is released first.
357
Contrary to <link id="NewStr"/>, if the string is empty then a pointer to
358
an empty string is returned.
361
The allocated memory is not based on the declared size of the string passed
362
to <var>NewStr</var>, but is based on the actual length of the string.
366
If not enough memory is available, an 'out of memory' error will occur.
369
<link id="DisposeStr"/>
376
<element name="DisposeStr">
377
<short>Dispose of a shortstring which was allocated on the heap.</short>
380
<var>DisposeStr</var> removes a dynamically allocated string from the heap.
383
For an example, see <link id="NewStr"/>.
396
<element name="Abstract">
397
<short>Abstract error handler.</short>
400
When implementing abstract methods, do not declare them as <var>abstract</var>.
401
Instead, define them simply as <var>virtual</var>. In the implementation of such
402
abstract methods, call the <var>Abstract</var> procedure. This allows explicit
403
control of what happens when an abstract method is called.
406
The current implementation of <var>Abstract</var> terminates the program with
407
a run-time error 211.
415
<element name="RegisterObjects">
416
<short>Register standard objects.</short>
419
<var>RegisterObjects</var> registers the following objects for streaming:
422
<li> <var>TCollection</var>, see <link id="TCollection"/>.</li>
423
<li> <var>TStringCollection</var>, see <link id="TStringCollection"/>.</li>
424
<li> <var>TStrCollection</var>, see <link id="TStrCollection"/>.</li>
431
<link id="RegisterType"/>
435
<element name="RegisterType">
436
<short>Register new object for streaming.</short>
439
<var>RegisterType</var> registers a new type for streaming. An object cannot
440
be streamed unless it has been registered first.
441
The stream record <var>S</var> needs to have the following fields set:
444
<dt>ObjType: Sw_Word</dt>
445
<dd> This should be a unique identifier. Each possible
446
type should have it's own identifier.
448
<dt>VmtLink: pointer</dt>
449
<dd>This should contain a pointer to the VMT (Virtual
450
Method Table) of the object you try to register.
452
<dt>Load : Pointer</dt>
453
<dd> is a pointer to a method that initializes an instance
454
of that object, and reads the initial values from a stream. This method
455
should accept as it's sole argument a <var>PStream</var> type variable.
457
<dt>Store: Pointer</dt>
458
<dd>is a pointer to a method that stores an instance of the
459
object to a stream. This method should accept as it's sole argument
460
a <var>PStream</var> type variable.
464
The VMT of the object can be retrieved with the
465
following expression:
468
VmtLink: Ofs(TypeOf(MyType)^);
472
In case of error (if a object with the same <var>ObjType</var>) is already
473
registered), run-time error 212 occurs.
475
<example file="objectex/myobject"/>
479
<element name="LongMul">
480
<short>Overflow safe multiply.</short>
482
<var>LongMul</var> multiplies <var>X</var> with <var>Y</var>. The result is of
483
type <var>Longint</var>. This avoids possible overflow errors you would normally
484
get when multiplying <var>X</var> and <var>Y</var> that are too big.
494
<element name="LongDiv">
495
<short>Overflow safe divide</short>
497
<var>LongDiv</var> divides <var>X</var> by <var>Y</var>. The result is of
498
type <var>Integer</var> instead of type <var>Longint</var>, as you would get
502
If Y is zero, a run-time error will be generated.
509
<element name="TRect">
510
<short>Describes a rectangular region in a plane.</short>
513
<element name="TRect.A">
514
<short>Top left corner of rectangle</short>
517
<element name="TRect.B">
518
<short>Bottom right corner of rectangle</short>
521
<element name="TRect.Empty">
522
<short>Is the surface of the rectangle zero</short>
524
<var>Empty</var> returns <var>True</var> if the rectangle defined by the corner points
525
<var>A</var>, <var>B</var> has zero or negative surface.
531
<link id="TRect.Equals"/>
532
<link id="TRect.Contains"/>
534
<example file="objectex/ex1"/>
538
<element name="TRect.Equals">
539
<short>Do the corners of the rectangles match</short>
542
<var>Equals</var> returns <var>True</var> if the rectangle has the
543
same corner points <var>A,B</var> as the rectangle R, and <var>False</var>
547
For an example, see <link id="TRect.Empty"/>
554
<link id="TRect.Empty"/>
555
<link id="TRect.Contains"/>
560
<element name="TRect.Contains">
561
<short>Determine if a point is inside the rectangle</short>
563
<var>Contains</var> returns <var>True</var> if the point <var>P</var> is contained
564
in the rectangle (including borders), <var>False</var> otherwise.
570
<link id="TRect.Intersect"/>
571
<link id="TRect.Equals"/>
575
<element name="TRect.Copy">
576
<short>Copy cornerpoints from another rectangle.</short>
578
Assigns the rectangle R to the object. After the call to <var>Copy</var>, the
579
rectangle R has been copied to the object that invoked <var>Copy</var>.
585
<link id="TRect.Assign"/>
587
<example file="objectex/ex2"/>
591
<element name="TRect.Union">
592
<short>Enlarges rectangle to encompas another rectangle.</short>
594
<var>Union</var> enlarges the current rectangle so that it becomes the union
595
of the current rectangle with the rectangle <var>R</var>.
601
<link id="TRect.Intersect"/>
603
<example file="objectex/ex3"/>
607
<element name="TRect.Intersect">
608
<short>Reduce rectangle to intersection with another rectangle</short>
610
<var>Intersect</var> makes the intersection of the current rectangle with
611
<var>R</var>. If the intersection is empty, then the rectangle is set to the empty
612
rectangle at coordinate (0,0).
618
<link id="TRect.Union"/>
620
<example file="objectex/ex4"/>
623
<element name="TRect.Move">
624
<short>Move rectangle along a vector.</short>
626
<var>Move</var> moves the current rectangle along a vector with components
627
<var>(ADX,ADY)</var>. It adds <var>ADX</var> to the X-coordinate of both corner
628
points, and <var>ADY</var> to both end points.
634
<link id="TRect.Grow"/>
636
<example file="objectex/ex5"/>
640
<element name="TRect.Grow">
641
<short>Expand rectangle with certain size.</short>
644
<var>Grow</var> expands the rectangle with an amount <var>ADX</var> in the <var>X</var>
645
direction (both on the left and right side of the rectangle, thus adding a
646
length 2*ADX to the width of the rectangle), and an amount <var>ADY</var> in
647
the <var>Y</var> direction (both on the top and the bottom side of the rectangle,
648
adding a length 2*ADY to the height of the rectangle.
651
<var>ADX</var> and <var>ADY</var> can be negative. If the resulting rectangle is empty, it is set
652
to the empty rectangle at <var>(0,0)</var>.
659
<link id="TRect.Move"/>
661
<example file="objectex/ex6"/>
664
<element name="TRect.Assign">
665
<short>Set rectangle corners.</short>
668
<var>Assign</var> sets the corner points of the rectangle to <var>(XA,YA)</var> and
672
For an example, see <link id="TRect.Copy"/>.
679
<link id="TRect.Copy"/>
683
<element name="TObject">
684
<short>Basis of all objects</short>
686
This type serves as the basic object for all other objects in the
687
<file>Objects</file> unit.
691
<element name="TObject.Init">
692
<short>Construct (initialize) a new object</short>
695
Instantiates a new object of type <var>TObject</var>. It fills the instance up
699
For an example, see <link id="TObject.Free">Free</link>
706
<link id="TObject.Free"/>
707
<link id="TObject.Done"/>
712
<element name="TObject.Free">
713
<short>Destroy an object and release all memory.</short>
715
<var>Free</var> calls the destructor of the object, and releases the memory
716
occupied by the instance of the object.
719
No checking is performed to see whether <var>self</var> is <var>nil</var> and whether
720
the object is indeed allocated on the heap.
723
<link id="TObject.Init"/>
724
<link id="TObject.Done"/>
726
<example file="objectex/ex7"/>
730
<element name="TObject.Done">
731
<short>Destroy an object.</short>
734
<var>Done</var>, the destructor of <var>TObject</var> does nothing. It is mainly
735
intended to be used in the <link id="TObject.Free"/> method.
738
The destructore Done does not free the memory occupied by the object.
745
<link id="TObject.Free"/>
746
<link id="TObject.Init"/>
748
<example file="objectex/ex8"/>
751
<element name="TObject.Is_Object">
752
<short>Check whether a pointer points to an object.</short>
754
<var>Is_Object</var> returns <var>True</var> if the pointer <var>P</var>
755
points to an instance of a <var>TObject</var> descendent, it returns
756
<var>false</var> otherwise.
761
<element name="TStream">
762
<short>Base stream class</short>
765
The <var>TStream</var> object is the ancestor for all streaming objects, i.e.
766
objects that have the capability to store and retrieve data.
769
It defines a number of methods that are common to all objects that implement
770
streaming, many of them are virtual, and are only implemented in the
774
Programs should not instantiate objects of type TStream directly, but
775
instead instantiate a descendant type, such as <var>TDosStream</var>,
776
<var>TMemoryStream</var>.
781
<link id="TDosStream"/>
782
<link id="TMemoryStream"/>
786
<element name="PStream">
787
<short>Pointer type to <link id="TStream"/></short>
790
<element name="TStream.Init">
791
<short>Constructor for TStream instance</short>
793
<var>Init</var> initializes a TStream instance. Descendent streams should
794
always call the inherited <var>Init</var>.
798
<element name="TStream.Status">
799
<short>Current stream status</short>
802
<element name="TStream.ErrorInfo">
803
<short>Additional error info when there is an error.</short>
806
<element name="TStream.StreamSize">
807
<short>Current size of the stream</short>
810
<element name="TStream.Position">
811
<short>Current Stream position</short>
814
<element name="TStream.TPCompatible">
815
<short>If set to <var>True</var> streamed data is written in a TP compatible format.</short>
818
<element name="TStream.Get">
819
<short>Read an object definition from the stream.</short>
821
<var>Get</var> reads an object definition from a stream, and returns
822
a pointer to an instance of this object.
825
On error, <link id="TStream.Status"/> is set, and <var>NIL</var> is returned.
828
<link id="TStream.Put"/>
830
<example file="objectex/ex9"/>
834
<element name="TStream.StrRead">
835
<short>Read a null-terminated string from the stream.</short>
837
<var>StrRead</var> reads a string from the stream, allocates memory
838
for it, and returns a pointer to a null-terminated copy of the string
842
On error, <var>Nil</var> is returned.
845
<link id="TStream.StrWrite"/>
846
<link id="TStream.ReadStr"/>
848
<example file="objectex/ex10"/>
853
<element name="TStream.GetPos">
854
<short>Return current position in the stream</short>
856
If the stream's status is <var>stOk</var>, <var>GetPos</var> returns the current
857
position in the stream. Otherwise it returns <var>-1</var>
860
<var>-1</var> is returned if the status is an error condition.
863
<link id="TStream.Seek"/>
864
<link id="TStream.GetSize"/>
866
<example file="objectex/ex11"/>
871
<element name="TStream.GetSize">
872
<short>Return the size of the stream.</short>
874
If the stream's status is <var>stOk</var> then <var>GetSize</var> returns
875
the size of the stream, otherwise it returns <var>-1</var>.
878
<var>-1</var> is returned if the status is an error condition.
881
<link id="TStream.Seek"/>
882
<link id="TStream.GetPos"/>
884
<example file="objectex/ex12"/>
887
<element name="TStream.ReadStr">
888
<short>Read a shortstring from the stream.</short>
890
<var>ReadStr</var> reads a string from the stream, copies it to the heap
891
and returns a pointer to this copy. The string is saved as a pascal
892
string, and hence is NOT null terminated.
895
On error (e.g. not enough memory), <var>Nil</var> is returned.
898
<link id="TStream.StrRead"/>
900
<example file="objectex/ex13"/>
903
<element name="TStream.Open">
904
<short>Open the stream</short>
907
<var>Open</var> is an abstract method, that should be overridden by descendent
908
objects. Since opening a stream depends on the stream's type this is not
912
For an example, see <link id="TDosStream.Open"/>.
919
<link id="TStream.Close"/>
920
<link id="TStream.Reset"/>
925
<element name="TStream.Close">
926
<short>Close the stream</short>
929
<var>Close</var> is an abstract method, that should be overridden by descendent
930
objects. Since Closing a stream depends on the stream's type this is not
934
for an example, see <link id="TDosStream.Open"/>.
941
<link id="TStream.Open"/>
942
<link id="TStream.Reset"/>
946
<element name="TStream.Reset">
947
<short>Reset the stream</short>
949
<var>Reset</var> sets the stream's status to <var>0</var>, as well as the ErrorInfo
955
<link id="TStream.Open"/>
956
<link id="TStream.Close"/>
960
<element name="TStream.Flush">
961
<short>Flush the stream data from the buffer, if any.</short>
964
<var>Flush</var> is an abstract method that should be overridden by descendent
965
objects. It serves to enable the programmer to tell streams that implement
966
a buffer to clear the buffer.
969
for an example, see <link id="TBufStream.Flush"/>.
976
<link id="TStream.Truncate"/>
981
<element name="TStream.Truncate">
982
<short>Truncate the stream size on current position.</short>
985
<var>Truncate</var> is an abstract procedure that should be overridden by
986
descendent objects. It serves to enable the programmer to truncate the
987
size of the stream to the current file position.
990
For an example, see <link id="TDosStream.Truncate"/>.
997
<link id="TStream.Seek"/>
1002
<element name="TStream.Put">
1003
<short>Write an object to the stream.</short>
1006
<var>Put</var> writes the object pointed to by <var>P</var>. <var>P</var> should be
1007
non-nil. The object type must have been registered with <link id="RegisterType"/>.
1010
After the object has been written, it can be read again with <link id="TStream.Get">Get</link>.
1013
For an example, see <link id="TStream.Get"/>;
1017
No check is done whether P is <var>Nil</var> or not. Passing <var>Nil</var> will cause
1018
a run-time error 216 to be generated. If the object has not been registered,
1019
the status of the stream will be set to <var>stPutError</var>.
1022
<link id="TStream.Get"/>
1027
<element name="TStream.StrWrite">
1028
<short>Write a null-terminated string to the stream.</short>
1031
<var>StrWrite</var> writes the null-terminated string <var>P</var> to the stream.
1032
<var>P</var> can only be 65355 bytes long.
1035
For an example, see <link id="TStream.StrRead"/>.
1042
<link id="TStream.WriteStr"/>
1043
<link id="TStream.StrRead"/>
1044
<link id="TStream.ReadStr"/>
1049
<element name="TStream.WriteStr">
1050
<short>Write a pascal string to the stream.</short>
1053
<var>StrWrite</var> writes the pascal string pointed to by <var>P</var> to the stream.
1056
For an example, see <link id="TStream.ReadStr"/>.
1063
<link id="TStream.StrWrite"/>
1064
<link id="TStream.StrRead"/>
1065
<link id="TStream.ReadStr"/>
1069
<element name="TStream.Seek">
1070
<short>Set stream position.</short>
1073
Seek sets the position to <var>Pos</var>. This position is counted
1074
from the beginning, and is zero based. (i.e. seeek(0) sets the position
1075
pointer on the first byte of the stream)
1078
For an example, see <link id="TDosStream.Seek"/>.
1082
If <var>Pos</var> is larger than the stream size, <var>Status</var> is set to
1083
<var>StSeekError</var>.
1086
<link id="TStream.GetPos"/>
1087
<link id="TStream.GetSize"/>
1093
<element name="TStream.Error">
1094
<short>Set stream status</short>
1097
<var>Error</var> sets the stream's status to <var>Code</var> and <var>ErrorInfo</var>
1098
to <var>Info</var>. If the <var>StreamError</var> procedural variable is set,
1099
<var>Error</var> executes it, passing <var>Self</var> as an argument.
1102
This method should not be called directly from a program. It is intended to
1103
be used in descendent objects.
1111
<element name="TStream.Read">
1112
<short>Read data from stream to buffer.</short>
1115
<var>Read</var> is an abstract method that should be overridden by descendent
1119
<var>Read</var> reads <var>Count</var> bytes from the stream into <var>Buf</var>.
1120
It updates the position pointer, increasing it's value with <var>Count</var>.
1121
<var>Buf</var> must be large enough to contain <var>Count</var> bytes.
1125
No checking is done to see if <var>Buf</var> is large enough to contain
1126
<var>Count</var> bytes.
1129
<link id="TStream.Write"/>
1130
<link id="TStream.ReadStr"/>
1131
<link id="TStream.StrRead"/>
1133
<example file="objectex/ex18"/>
1138
<element name="TStream.Write">
1139
<short>Write a number of bytes to the stream.</short>
1142
<var>Write</var> is an abstract method that should be overridden by descendent
1146
<var>Write</var> writes <var>Count</var> bytes to the stream from <var>Buf</var>.
1147
It updates the position pointer, increasing it's value with <var>Count</var>.
1150
For an example, see <link id="TStream.Read"/>.
1154
No checking is done to see if <var>Buf</var> actually contains <var>Count</var> bytes.
1157
<link id="TStream.Read"/>
1158
<link id="TStream.WriteStr"/>
1159
<link id="TStream.StrWrite"/>
1164
<element name="TStream.CopyFrom">
1165
<short>Copy data from another stream. </short>
1167
<var>CopyFrom</var> reads Count bytes from stream <var>S</var> and stores them
1168
in the current stream. It uses the <link id="TStream.Read">Read</link> method
1169
to read the data, and the <link id="TStream.Write">Write</link> method to
1170
write in the current stream.
1176
<link id="TStream.Read">Read</link>
1177
<link id="TStream.Write">Write</link>
1179
<example file="objectex/ex19"/>
1184
<element name="TDosStream">
1185
<short>DOS file stream</short>
1188
<var>TDosStream</var> is a stream that stores it's contents in a file.
1189
it overrides a couple of methods of <link id="TStream"/> for this.
1192
In addition to the fields inherited from <var>TStream</var> (see <link id="TStream"/>),
1193
there are some extra fields, that describe the file. (mainly the name and
1197
No buffering in memory is done when using <var>TDosStream</var>.
1198
All data are written directly to the file. For a stream that buffers
1199
in memory, see <link id="TBufStream"/>.
1204
<element name="TDosStream.Handle">
1205
<short>OS file handle for stream</short>
1208
<element name="TDosStream.FName">
1209
<short>File name</short>
1212
<element name="TDosStream.Init">
1213
<short>Instantiate a new instance of TDosStream.</short>
1216
<var>Init</var> instantiates an instance of <var>TDosStream</var>. The name of the
1217
file that contains (or will contain) the data of the stream is given in
1218
<var>FileName</var>. The <var>Mode</var> parameter determines whether a new file
1219
should be created and what access rights you have on the file.
1220
It can be one of the following constants:
1223
<dt>stCreate</dt><dd> Creates a new file.</dd>
1224
<dt>stOpenRead</dt><dd> Read access only.</dd>
1225
<dt>stOpenWrite</dt><dd> Write access only.</dd>
1226
<dt>stOpen</dt><dd> Read and write access.</dd>
1229
For an example, see <link id="TDosStream.Truncate"/>.
1233
On error, <link id="TStream.Status">Status</link> is set to <var>stInitError</var>, and <var>ErrorInfo</var>
1234
is set to the dos error code.
1237
<link id="TDosStream.Done"/>
1242
<element name="TDosStream.Done">
1243
<short>Closes the file and cleans up the instance.</short>
1246
<var>Done</var> closes the file if it was open and cleans up the
1247
instance of <var>TDosStream</var>.
1250
for an example, see e.g. <link id="TDosStream.Truncate"/>.
1257
<link id="TDosStream.Init"/>
1258
<link id="TDosStream.Close"/>
1263
<element name="TDosStream.Close">
1264
<short>Close the file.</short>
1267
<var>Close</var> closes the file if it was open, and sets <var>Handle</var> to -1.
1268
Contrary to <link id="TDosStream.Done">Done</link> it does not clean up the instance
1269
of <var>TDosStream</var>
1272
For an example, see <link id="TDosStream.Open"/>.
1279
<link id="TStream.Close"/>
1280
<link id="TDosStream.Init"/>
1281
<link id="TDosStream.Done"/>
1286
<element name="TDosStream.Truncate">
1287
<short>Truncate the file on the current position.</short>
1289
If the status of the stream is <var>stOK</var>, then <var>Truncate</var> tries to
1290
truncate the stream size to the current file position.
1293
If an error occurs, the stream's status is set to <var>stError</var> and
1294
<var>ErrorInfo</var> is set to the OS error code.
1297
<link id="TStream.Truncate"/>
1298
<link id="TStream.GetSize"/>
1300
<example file="objectex/ex16"/>
1305
<element name="TDosStream.Seek">
1306
<short>Set file position.</short>
1308
If the stream's status is <var>stOK</var>, then <var>Seek</var> sets the
1309
file position to <var>Pos</var>. <var>Pos</var> is a zero-based offset, counted from
1310
the beginning of the file.
1313
In case an error occurs, the stream's status is set to <var>stSeekError</var>,
1314
and the OS error code is stored in <var>ErrorInfo</var>.
1317
<link id="TStream.Seek"/>
1318
<link id="TStream.GetPos"/>
1320
<example file="objectex/ex17"/>
1325
<element name="TDosStream.Open">
1326
<short>Open the file stream</short>
1328
If the stream's status is <var>stOK</var>, and the stream is closed then
1329
<var>Open</var> re-opens the file stream with mode <var>OpenMode</var>.
1330
This call can be used after a <link id="TDosStream.Close">Close</link> call.
1333
If an error occurs when re-opening the file, then <var>Status</var> is set
1334
to <var>stOpenError</var>, and the OS error code is stored in <var>ErrorInfo</var>
1337
<link id="TStream.Open"/>
1338
<link id="TDosStream.Close"/>
1340
<example file="objectex/ex14"/>
1343
<element name="TDosStream.Read">
1344
<short>Read data from the stream to a buffer.</short>
1347
If the Stream is open and the stream status is <var>stOK</var> then
1348
<var>Read</var> will read <var>Count</var> bytes from the stream and place them
1352
For an example, see <link id="TStream.Read"/>.
1356
In case of an error, <var>Status</var> is set to <var>StReadError</var>, and
1357
<var>ErrorInfo</var> gets the OS specific error, or 0 when an attempt was
1358
made to read beyond the end of the stream.
1361
<link id="TStream.Read"/>
1362
<link id="TDosStream.Write"/>
1366
<element name="TDosStream.Write">
1367
<short>Write data from a buffer to the stream.</short>
1370
If the Stream is open and the stream status is <var>stOK</var> then
1371
<var>Write</var> will write <var>Count</var> bytes from <var>Buf</var> and place them
1375
For an example, see <link id="TStream.Read"/>.
1379
In case of an error, <var>Status</var> is set to <var>StWriteError</var>, and
1380
<var>ErrorInfo</var> gets the OS specific error.
1383
<link id="TStream.Write"/>
1384
<link id="TDosStream.Read"/>
1389
<element name="PBufStream">
1390
<short>Pointer to <link id="TBufStream"/> object.</short>
1393
<element name="PDosStream">
1394
<short>Pointer to <link id="TDosStream"/> object.</short>
1397
<element name="PMemoryStream">
1398
<short>Pointer to <link id="TMemoryStream"/> object.</short>
1402
<element name="PCollection">
1403
<short>Pointer to <link id="TCollection"/> object.</short>
1407
<element name="PItemList">
1408
<short>Pointer to <link id="TItemList"/> object.</short>
1412
<element name="PObject">
1413
<short>Pointer to <link id="TObject"/> object.</short>
1416
<element name="PRect">
1417
<short>Pointer to <link id="TRect"/> object.</short>
1420
<element name="PResourceCollection">
1421
<short>Pointer to <link id="TResourceCollection"/> object.</short>
1424
<element name="PSortedCollection">
1425
<short>Pointer to <link id="TSortedCollection"/> object.</short>
1428
<element name="PSTrCollection">
1429
<short>Pointer to <link id="TStrCollection"/> object.</short>
1432
<element name="PSTrListMaker">
1433
<short>Pointer to <link id="TStrListMaker"/> object.</short>
1436
<element name="PStringCollection">
1437
<short>Pointer to <link id="TStringCollection"/> object.</short>
1440
<element name="PStringList">
1441
<short>Pointer to <link id="TStringList"/> object.</short>
1444
<element name="PUnsortedStrCollection">
1445
<short>Pointer to <link id="TUnsortedStrCollection"/> object.</short>
1449
<element name="PResourceFile">
1450
<short>Pointer to <link id="TResourceFile"/> object.</short>
1454
<element name="PStrIndex">
1455
<short>Pointer to <link id="TStrIndex"/> array.</short>
1460
<element name="PObject">
1461
<short>Pointer to <link id="TObject"/> object.</short>
1465
<element name="TBufStream">
1466
<short>Buffered file stream</short>
1469
<var>Bufstream</var> implements a buffered file stream. That is, all data written
1470
to the stream is written to memory first. Only when the buffer is full, or
1471
on explicit request, the data is written to disk.
1474
Also, when reading from the stream, first the buffer is checked if there is
1475
any unread data in it. If so, this is read first. If not the buffer is
1476
filled again, and then the data is read from the buffer.
1479
The size of the buffer is fixed and is set when constructing the file.
1482
This is useful if you need heavy throughput for your stream, because it
1483
speeds up operations.
1491
<element name="TBufStream.LastMode">
1492
<short>Last file open mode</short>
1495
<element name="TBufStream.BufSize">
1496
<short>Size of buffer</short>
1499
<element name="TBufStream.BufPtr">
1500
<short>Pointer to current position in buffer</short>
1503
<element name="TBufStream.Bufend">
1504
<short>End of data in buffer.</short>
1507
<element name="TBufStream.Buffer">
1508
<short>Actual buffer</short>
1511
<element name="TBufStream.Init">
1512
<short>Initialize an instance of <var>TBufStream</var> and open the file.</short>
1515
<var>Init</var> instantiates an instance of <var>TBufStream</var>. The name of the
1516
file that contains (or will contain) the data of the stream is given in
1517
<var>FileName</var>. The <var>Mode</var> parameter determines whether a new file
1518
should be created and what access rights you have on the file.
1519
It can be one of the following constants:
1522
<dt>stCreate</dt><dd> Creates a new file.</dd>
1523
<dt>stOpenRead</dt><dd> Read access only.</dd>
1524
<dt>stOpenWrite</dt><dd> Write access only.</dd>
1525
<dt>stOpen</dt><dd> Read and write access.</dd>
1528
The <var>Size</var> parameter determines the size of the buffer that will be
1529
created. It should be different from zero.
1532
For an example see <link id="TBufStream.Flush"/>.
1536
On error, <var>Status</var> is set to <var>stInitError</var>, and <var>ErrorInfo</var>
1537
is set to the dos error code.
1540
<link id="TDosStream.Init"/>
1541
<link id="TBufStream.Done"/>
1546
<element name="TBufStream.Done">
1547
<short>Close the file and cleans up the instance.</short>
1550
<var>Done</var> flushes and closes the file if it was open and cleans up the
1551
instance of <var>TBufStream</var>.
1554
For an example see <link id="TBufStream.Flush"/>.
1561
<link id="TDosStream.Done"/>
1562
<link id="TBufStream.Init"/>
1563
<link id="TBufStream.Close"/>
1568
<element name="TBufStream.Close">
1569
<short>Flush data and Close the file.</short>
1572
<var>Close</var> flushes and closes the file if it was open, and sets <var>Handle</var> to -1.
1573
Contrary to <link id="TBufStream.Done">Done</link> it does not clean up the instance
1574
of <var>TBufStream</var>
1577
For an example see <link id="TBufStream.Flush"/>.
1584
<link id="TStream.Close"/>
1585
<link id="TBufStream.Init"/>
1586
<link id="TBufStream.Done"/>
1591
<element name="TBufStream.Flush">
1592
<short>FLush data from buffer, and write it to stream.</short>
1594
When the stream is in write mode, the contents of the buffer are written to
1595
disk, and the buffer position is set to zero.
1597
When the stream is in read mode, the buffer position is set to zero.
1600
Write errors may occur if the file was in write mode.
1601
see <link id="TBufStream.Write">Write</link> for more info on the errors.
1604
<link id="TStream.Close"/>
1605
<link id="TBufStream.Init"/>
1606
<link id="TBufStream.Done"/>
1608
<example file="objectex/ex15"/>
1613
<element name="TBufStream.Truncate">
1614
<short>Flush buffer, and truncate the file at current position.</short>
1617
If the status of the stream is <var>stOK</var>, then <var>Truncate</var> tries to
1618
flush the buffer, and then truncates the stream size to the current
1622
For an example, see <link id="TDosStream.Truncate"/>.
1626
Errors can be those of <link id="TBufStream.Flush">Flush</link> or
1627
<link id="TDosStream.Truncate"/>.
1630
<link id="TStream.Truncate"/>
1631
<link id="TDosStream.Truncate"/>
1632
<link id="TStream.GetSize"/>
1637
<element name="TBufStream.Seek">
1638
<short>Set current position in file.</short>
1641
If the stream's status is <var>stOK</var>, then <var>Seek</var> sets the
1642
file position to <var>Pos</var>. <var>Pos</var> is a zero-based offset, counted from
1643
the beginning of the file.
1646
For an example, see <link id="TStream.Seek"/>;
1650
In case an error occurs, the stream's status is set to <var>stSeekError</var>,
1651
and the OS error code is stored in <var>ErrorInfo</var>.
1654
<link id="TStream.Seek"/>
1655
<link id="TStream.GetPos"/>
1660
<element name="TBufStream.Open">
1661
<short>Open the file if it is closed.</short>
1664
If the stream's status is <var>stOK</var>, and the stream is closed then
1665
<var>Open</var> re-opens the file stream with mode <var>OpenMode</var>.
1666
This call can be used after a <link id="TBufStream.Close">Close</link> call.
1669
For an example, see <link id="TDosStream.Open"/>.
1673
If an error occurs when re-opening the file, then <var>Status</var> is set
1674
to <var>stOpenError</var>, and the OS error code is stored in <var>ErrorInfo</var>
1677
<link id="TStream.Open"/>
1678
<link id="TBufStream.Close"/>
1683
<element name="TBufStream.Read">
1684
<short>Read data from the file to a buffer in memory.</short>
1687
If the Stream is open and the stream status is <var>stOK</var> then
1688
<var>Read</var> will read <var>Count</var> bytes from the stream and place them
1692
<var>Read</var> will first try to read the data from the stream's internal
1693
buffer. If insufficient data is available, the buffer will be filled before
1694
contiunuing to read. This process is repeated until all needed data
1698
For an example, see <link id="TStream.Read"/>.
1702
In case of an error, <var>Status</var> is set to <var>StReadError</var>, and
1703
<var>ErrorInfo</var> gets the OS specific error, or 0 when an attempt was
1704
made to read beyond the end of the stream.
1707
<link id="TStream.Read"/>
1708
<link id="TBufStream.Write"/>
1713
<element name="TBufStream.Write">
1714
<short>Write data to the file from a buffer in memory.</short>
1717
If the Stream is open and the stream status is <var>stOK</var> then
1718
<var>Write</var> will write <var>Count</var> bytes from <var>Buf</var> and place them
1722
<var>Write</var> will first try to write the data to the stream's internal
1723
buffer. When the internal buffer is full, then the contents will be written
1724
to disk. This process is repeated until all data has been written.
1727
For an example, see <link id="TStream.Read"/>.
1731
In case of an error, <var>Status</var> is set to <var>StWriteError</var>, and
1732
<var>ErrorInfo</var> gets the OS specific error.
1735
<link id="TStream.Write"/>
1736
<link id="TBufStream.Read"/>
1741
<element name="TMemoryStream">
1742
<short>Stream which keeps data in memory.</short>
1745
The <var>TMemoryStream</var> object implements a stream that stores it's data
1746
in memory. The data is stored on the heap, with the possibility to specify
1747
the maximum amout of data, and the the size of the memory blocks being used.
1751
<link id="TStream"/>
1755
<element name="TMemoryStream.BlkCount">
1756
<short>Number of allocated memory blocks</short>
1759
<element name="TMemoryStream.BlkSize">
1760
<short>Size of one memory block</short>
1763
<element name="TMemoryStream.MemSize">
1764
<short>Total memory size</short>
1767
<element name="TMemoryStream.BlkList">
1768
<short>Pointer to list of allocated blocks.</short>
1771
<element name="TMemoryStream.Init">
1772
<short>Initialize memory stream, reserves memory for stream data.</short>
1775
<var>Init</var> instantiates a new <var>TMemoryStream</var> object. The
1776
memorystreamobject will initially allocate at least <var>ALimit</var> bytes memory,
1777
divided into memory blocks of size <var>ABlockSize</var>.
1778
The number of blocks needed to get to <var>ALimit</var> bytes is rounded up.
1781
By default, the number of blocks is 1, and the size of a block is 8192. This
1782
is selected if you specify 0 as the blocksize.
1785
For an example, see e.g <link id="TStream.CopyFrom"/>.
1789
If the stream cannot allocate the initial memory needed for the memory blocks, then
1790
the stream's status is set to <var>stInitError</var>.
1793
<link id="TMemoryStream.Done"/>
1798
<element name="TMemoryStream.Done">
1799
<short>Clean up memory and destroy the object instance.</short>
1802
<var>Done</var> releases the memory blocks used by the stream, and then cleans up
1803
the memory used by the stream object itself.
1806
For an example, see e.g <link id="TStream.CopyFrom"/>.
1813
<link id="TMemoryStream.Init"/>
1818
<element name="TMemoryStream.Truncate">
1819
<short>Set the stream size to the current position.</short>
1821
<var>Truncate</var> sets the size of the memory stream equal to the current
1822
position. It de-allocates any memory-blocks that are no longer needed, so
1823
that the new size of the stream is the current position in the stream,
1824
rounded up to the first multiple of the stream blocksize.
1827
If an error occurs during memory de-allocation, the stream's status is set
1828
to <var>stError</var>
1831
<link id="TStream.Truncate"/>
1833
<example file="objectex/ex20"/>
1838
<element name="TMemoryStream.Read">
1839
<short>Read data from the stream to a location in memory.</short>
1842
<var>Read</var> reads <var>Count</var> bytes from the stream to <var>Buf</var>. It updates
1843
the position of the stream.
1846
For an example, see <link id="TStream.Read"/>.
1850
If there is not enough data available, no data is read, and the stream's
1851
status is set to <var>stReadError</var>.
1854
<link id="TStream.Read"/>
1855
<link id="TMemoryStream.Write"/>
1860
<element name="TMemoryStream.Write">
1861
<short>Write data to the stream.</short>
1864
<var>Write</var> copies <var>Count</var> bytes from <var>Buf</var> to the stream. It
1865
updates the position of the stream.
1868
If not enough memory is available to hold the extra <var>Count</var> bytes,
1869
then the stream will try to expand, by allocating as much blocks with
1870
size <var>BlkSize</var> (as specified in the constuctor call
1871
<link id="TMemoryStream.Init">Init</link>) as needed.
1874
For an example, see <link id="TStream.Read"/>.
1878
If the stream cannot allocate more memory, then the status is set to
1879
<var>stWriteError</var>
1882
<link id="TStream.Write"/>
1883
<link id="TMemoryStream.Read"/>
1888
<element name="TCollection">
1889
<short>Manage a collection of pointers of objects</short>
1892
The <var>TCollection</var> object manages a collection of pointers or objects.
1893
It also provides a series of methods to manipulate these pointers or
1897
Whether or not objects are used depends on the kind of calls you use.
1898
All kinds come in 2 flavors, one for objects, one for pointers.
1903
<element name="TCollection.Items">
1904
<short>Pointer to list of items.</short>
1907
<element name="TCollection.Count">
1908
<short>Current count of items</short>
1911
<element name="TCollection.Limit">
1912
<short>Max number of items</short>
1915
<element name="TCollection.Delta">
1916
<short>Number of pointers to allocate when adding items.</short>
1919
<element name="TCollection.Init">
1920
<short>Instantiate a new collection.</short>
1923
<var>Init</var> initializes a new instance of a collection. It sets the (initial) maximum number
1924
of items in the collection to <var>ALimit</var>. <var>ADelta</var> is the increase
1925
size : The number of memory places that will be allocatiod in case <var>ALimit</var> is reached,
1926
and another element is added to the collection.
1929
For an example, see <link id="TCollection.ForEach"/>.
1936
<link id="TCollection.Load"/>
1937
<link id="TCollection.Done"/>
1942
<element name="TCollection.Load">
1943
<short>Initialize a new collection and load collection from a stream.</short>
1945
<var>Load</var> initializes a new instance of a collection. It reads from stream
1946
<var>S</var> the item count, the item limit count, and the increase size. After
1947
that, it reads the specified number of items from the stream.
1948
<!-- Do not call this method if you intend to use only pointers in your collection. -->
1951
Errors returned can be those of <link id="TCollection.GetItem">GetItem</link>.
1954
<link id="TCollection.Init"/>
1955
<link id="TCollection.GetItem"/>
1956
<link id="TCollection.Done"/>
1958
<example file="objectex/ex22"/>
1963
<element name="TCollection.Done">
1964
<short>Clean up collection, release all memory.</short>
1967
<var>Done</var> frees all objects in the collection, and then releases all memory
1968
occupied by the instance.
1971
For an example, see <link id="TCollection.ForEach"/>.
1973
<!-- Do not call this method if you intend to use only pointers in your collection. -->
1979
<link id="TCollection.Init"/>
1980
<link id="TCollection.FreeAll"/>
1985
<element name="TCollection.At">
1986
<short>Return the item at a certain index.</short>
1988
<var>At</var> returns the item at position <var>Index</var>.
1991
If <var>Index</var> is less than zero or larger than the number of items
1992
in the collection, seepl{Error}{TCollection.Error} is called with
1993
<var>coIndexError</var> and <var>Index</var> as arguments, resulting in a run-time
1997
<link id="TCollection.Insert"/>
1999
<example file="objectex/ex23"/>
2004
<element name="TCollection.IndexOf">
2005
<short>Find the position of a certain item.</short>
2007
<var>IndexOf</var> returns the index of <var>Item</var> in the collection.
2008
If <var>Item</var> isn't present in the collection, -1 is returned.
2011
If the item is not present, -1 is returned.
2014
<link id="TCollection.At"/>
2015
<link id="TCollection.GetItem"/>
2016
<link id="TCollection.Insert"/>
2018
<example file="objectex/ex24"/>
2023
<element name="TCollection.GetItem">
2024
<short>Read one item off the stream.</short>
2026
<var>GetItem</var> reads a single item off the stream <var>S</var>, and
2027
returns a pointer to this item. This method is used internally by the Load
2028
method, and should not be used directly.
2031
Possible errors are the ones from <link id="TStream.Get"/>.
2034
<link id="TStream.Get"/>,
2035
<link id="TCollection.Store"/>
2039
<element name="TCollection.LastThat">
2040
<short>Return last item which matches a test.</short>
2042
This function returns the last item in the collection for which <var>Test</var>
2043
returns a non-nil result. <var>Test</var> is a function that accepts 1 argument:
2044
a pointer to an object, and that returns a pointer as a result.
2050
<link id="TCollection.FirstThat"/>
2052
<example file="objectex/ex25"/>
2057
<element name="TCollection.FirstThat">
2058
<short>Return first item which matches a test.</short>
2060
This function returns the first item in the collection for which <var>Test</var>
2061
returns a non-nil result. <var>Test</var> is a function that accepts 1 argument:
2062
a pointer to an object, and that returns a pointer as a result.
2068
<link id="TCollection.LastThat"/>
2070
<example file="objectex/ex26"/>
2075
<element name="TCollection.Pack">
2076
<short>Remove all <var>>Nil</var> pointers from the collection.</short>
2078
<var>Pack</var> removes all <var>Nil</var> pointers from the collection, and adjusts
2079
<var>Count</var> to reflect this change. No memory is freed as a result of this
2080
call. In order to free any memory, you can call <var>SetLimit</var> with an
2081
argument of <var>Count</var> after a call to <var>Pack</var>.
2087
<link id="TCollection.SetLimit"/>
2089
<example file="objectex/ex26"/>
2094
<element name="TCollection.FreeAll">
2095
<short>Release all objects from the collection.</short>
2097
<var>FreeAll</var> calls the destructor of each object in the collection.
2098
It doesn't release any memory occumpied by the collection itself, but it
2099
does set <var>Count</var> to zero.
2104
<link id="TCollection.DeleteAll"/>
2105
<link id="TCollection.FreeItem"/>
2107
<example file="objectex/ex28"/>
2110
<element name="TCollection.DeleteAll">
2111
<short>Delete all elements from the collection. Objects are not destroyed.</short>
2113
<var>DeleteAll</var> deletes all elements from the collection. It just sets
2114
the <var>Count</var> variable to zero. Contrary to
2115
<link id="TCollection.FreeAll">FreeAll</link>, <var>DeletAll</var> doesn't call the
2116
destructor of the objects.
2122
<link id="TCollection.FreeAll"/>
2123
<link id="TCollection.Delete"/>
2125
<example file="objectex/ex29"/>
2130
<element name="TCollection.Free">
2131
<short>Free item from collection, calling it's destructor.</short>
2133
<var>Free</var> Deletes <var>Item</var> from the collection, and calls the destructor
2134
<var>Done</var> of the object.
2137
If the <var>Item</var> is not in the collection, <var>Error</var> will be called with
2138
<var>coIndexError</var>.
2141
<link id="TCollection.FreeItem"/>
2143
<example file="objectex/ex30"/>
2148
<element name="TCollection.Insert">
2149
<short>Insert a new item in the collection at the end.</short>
2151
<var>Insert</var> inserts <var>Item</var> in the collection. <var>TCollection</var>
2152
inserts this item at the end, but descendent objects may insert it at
2159
<link id="TCollection.AtInsert"/>
2160
<link id="TCollection.AtPut"/>
2165
<element name="TCollection.Delete">
2166
<short>Delete an item from the collection, but does not destroy it.</short>
2168
<var>Delete</var> deletes <var>Item</var> from the collection. It doesn't call the
2169
item's destructor, though. For this the <link id="TCollection.Free">Free</link>
2173
If the <var>Item</var> is not in the collection, <var>Error</var> will be called with
2174
<var>coIndexError</var>.
2177
<link id="TCollection.AtDelete"/>
2178
<link id="TCollection.Free"/>
2180
<example file="objectex/ex31"/>
2185
<element name="TCollection.AtFree">
2186
<short>Free an item at the indicates position, calling it's destructor.</short>
2188
<var>AtFree</var> deletes the item at position <var>Index</var> in the collection,
2189
and calls the item's destructor if it is not <var>Nil</var>.
2192
If <var>Index</var> isn't valid then <link id="TCollection.Error">Error</link> is called
2193
with <var>CoIndexError</var>.
2196
<link id="TCollection.Free"/>
2197
<link id="TCollection.AtDelete"/>
2199
<example file="objectex/ex32"/>
2203
<element name="TCollection.FreeItem">
2204
<short>Destroy a non-nil item.</short>
2207
<var>FreeItem</var> calls the destructor of <var>Item</var> if it is not
2211
This function is used internally by the TCollection object, and should not be
2219
<link id="TCollection.Free"/>
2220
<link id="TCollection.AtFree"/>
2225
<element name="TCollection.AtDelete">
2226
<short>Delete item at certain position.</short>
2228
<var>AtDelete</var> deletes the pointer at position <var>Index</var> in the
2229
collection. It doesn't call the object's destructor.
2232
If <var>Index</var> isn't valid then <link id="TCollection.Error">Error</link> is called
2233
with <var>CoIndexError</var>.
2236
<link id="TCollection.Delete"/>
2238
<example file="objectex/ex33"/>
2242
<element name="TCollection.ForEach">
2243
<short>Execute procedure for each item in the list.</short>
2246
<var>ForEach</var> calls <var>Action</var> for each element in the collection,
2247
and passes the element as an argument to <var>Action</var>.
2250
<var>Action</var> is a procedural type variable that accepts a pointer as an
2258
<link id="TCollection.FirstThat"/>
2259
<link id="TCollection.LastThat"/>
2261
<example file="objectex/ex21"/>
2266
<element name="TCollection.SetLimit">
2267
<short>Set maximum number of elements in the collection.</short>
2270
<var>SetLimit</var> sets the maximum number of elements in the collection.
2271
<var>ALimit</var> must not be less than <var>Count</var>, and should not be larger
2272
than <var>MaxCollectionSize</var>
2275
For an example, see <link id="TCollection.Pack">Pack</link>.
2282
<link id="TCollection.Init"/>
2287
<element name="TCollection.Error">
2288
<short>Set error code.</short>
2291
<var>Error</var> is called by the various <var>TCollection</var> methods
2292
in case of an error condition. The default behaviour is to make
2293
a call to <var>RunError</var> with an error of <var>212-Code</var>.
2296
This method can be overridden by descendent objects to implement
2297
a different error-handling.
2303
<link id="Abstract"/>
2307
<element name="TCollection.AtPut">
2308
<short>Set collection item, overwriting an existing value.</short>
2311
<var>AtPut</var> sets the element at position <var>Index</var> in the collection
2312
to <var>Item</var>. Any previous value is overwritten.
2315
For an example, see <link id="TCollection.Pack">Pack</link>.
2319
If <var>Index</var> isn't valid then <link id="TCollection.Error">Error</link> is called
2320
with <var>CoIndexError</var>.
2327
<element name="TCollection.AtInsert">
2328
<short>Insert an element at a certain position in the collection.</short>
2330
<var>AtInsert</var> inserts <var>Item</var> in the collection at position <var>Index</var>,
2331
shifting all elements by one position. In case the current limit is reached,
2332
the collection will try to expand with a call to <var>SetLimit</var>
2335
If <var>Index</var> isn't valid then <link id="TCollection.Error">Error</link> is called
2336
with <var>CoIndexError</var>. If the collection fails to expand, then
2337
<var>coOverFlow</var> is passd to <var>Error</var>.
2340
<link id="TCollection.Insert"/>
2342
<example file="objectex/ex34"/>
2347
<element name="TCollection.Store">
2348
<short>Write collection to a stream.</short>
2351
<var>Store</var> writes the collection to the stream <var>S</var>. It does
2352
this by writeing the current <var>Count</var>, <var>Limit</var> and <var>Delta</var>
2353
to the stream, and then writing each item to the stream.
2356
The contents of the stream are then suitable for instantiating another
2357
collection with <link id="TCollection.Load">Load</link>.
2360
For an example, see <link id="TCollection.Load"/>.
2364
Errors returned are those by <link id="TStream.Put"/>.
2367
<link id="TCollection.Load"/>
2368
<link id="TCollection.PutItem"/>
2373
<element name="TCollection.PutItem">
2374
<short>Put one item on the stream</short>
2376
<var>PutItem</var> writes <var>Item</var> to stream <var>S</var>. This method is used
2377
internaly by the <var>TCollection</var> object, and should not be called
2381
Errors are those returned by <link id="TStream.Put"/>.
2384
<link id="TCollection.Store">Store</link>
2385
<link id="TCollection.GetItem">GetItem</link>
2389
<element name="TSortedCollection">
2390
<short>Abstract sorted collection.</short>
2393
<var>TSortedCollection</var> is an abstract class, implementing a sorted
2394
collection. You should never use an instance of <var>TSortedCollection</var>
2395
directly, instead you should declare a descendent type, and override the
2396
<link id="TSortedCollection.Compare">Compare</link> method.
2399
Because the collection is ordered, <var>TSortedCollection</var> overrides some
2400
<var>TCollection</var> methods, to provide faster routines for lookup.
2403
The <link id="TSortedCollection.Compare">Compare</link> method decides how elements
2404
in the collection should be ordered. Since <var>TCollection</var> has no way
2405
of knowing how to order pointers, you must override the compare method.
2408
Additionally, <var>TCollection</var> provides a means to filter out duplicates.
2409
if you set <var>Duplicates</var> to <var>False</var> (the default) then duplicates
2410
will not be allowed.
2413
The example below defines a descendent of <var>TSortedCollection</var> which
2414
is used in the examples.
2417
<example file="objectex/mysortc"/>
2420
<element name="TSortedCollection.Duplicates">
2421
<short>If <var>True</var> duplicate strings are allowed in the collection.</short>
2424
<element name="TSortedCollection.Init">
2425
<short>Instantiates a new instance of a <var>TSortedCollection</var></short>
2428
<var>Init</var> calls the inherited constuctor (see <link id="TCollection.Init"/>) and
2429
sets the <var>Duplicates</var> flag to false.
2432
You should not call this method directly, since <var>TSortedCollection</var> is a
2433
abstract class. Instead, the descendent classes should call it via the
2434
<var>inherited</var> keyword.
2441
<link id="TSortedCollection.Load"/>
2442
<link id="TCollection.Done"/>
2446
<element name="TSortedCollection.Load">
2447
<short>Instantiates a new instance of a <var>TSortedCollection</var> and
2448
loads it from stream.</short>
2451
<var>Load</var> calls the inherited constuctor (see <link id="TCollection.Load"/>) and
2452
reads the <var>Duplicates</var> flag from the stream..
2455
You should not call this method directly, since <var>TSortedCollection</var> is a
2456
abstract class. Instead, the descendent classes should call it via the
2457
<var>inherited</var> keyword.
2460
For an example, see <link id="TCollection.Load"/>.
2467
<link id="TSortedCollection.Init"/>
2468
<link id="TCollection.Done"/>
2473
<element name="TSortedCollection.KeyOf">
2474
<short>Return the key of an item</short>
2477
<var>KeyOf</var> returns the key associated with <var>Item</var>.
2478
<var>TSortedCollection</var> returns the item itself as the key, descendent
2479
objects can override this method to calculate a (unique) key based on the
2480
item passed (such as hash values).
2483
<var>Keys</var> are used to sort the objects, they are used to search and sort
2484
the items in the collection. If descendent types override this method then
2485
it allows possibly for faster search/sort methods based on keys rather than
2486
on the objects themselves.
2493
<link id="TSortedCollection.IndexOf"/>
2494
<link id="TSortedCollection.Compare"/>
2498
<element name="TSortedCollection.IndexOf">
2499
<short>Return index of an item in the collection.</short>
2502
<var>IndexOf</var> returns the index of <var>Item</var> in the collection. It searches
2503
for the object based on it's key. If duplicates are allowed, then it returns
2504
the index of last object that matches <var>Item</var>.
2507
In case <var>Item</var> is not found in the collection, -1 is returned.
2510
For an example, see <link id="TCollection.IndexOf"/>
2517
<link id="TSortedCollection.Search"/>
2518
<link id="TSortedCollection.Compare"/>
2523
<element name="TSortedCollection.Compare">
2524
<short>Compare two items in the collection.</short>
2527
<var>Compare</var> is an abstract method that should be overridden by descendent
2528
objects in order to compare two items in the collection. This method is used
2529
in the <link id="TSortedCollection.Search">Search</link> method and in the
2530
<link id="TSortedCollection.Insert">Insert</link> method to determine the ordering of
2534
The function should compare the two keys of items and return the following
2538
<dt>Result < 0</dt><dd>If <var>Key1</var> is logically before <var>Key2</var> (<var>Key1<Key2</var>)</dd>
2539
<dt>Result = 0</dt><dd> If <var>Key1</var> and <var>Key2</var> are equal. (<var>Key1=Key2</var>)</dd>
2540
<dt>Result > 0</dt><dd> If <var>Key1</var> is logically after <var>Key2</var> (<var>Key1>Key2</var>)</dd>
2544
An 'abstract run-time error' will be generated if you call
2545
<var>TSortedCollection.Compare</var> directly.
2548
<link id="TSortedCollection.IndexOf"/>
2549
<link id="TSortedCollection.Search"/>
2551
<example file="objectex/mysortc"/>
2555
<element name="TSortedCollection.Search">
2556
<short>Search for item with given key.</short>
2559
<var>Search</var> looks for the item with key <var>Key</var> and returns the position
2560
of the item (if present) in the collection in <var>Index</var>.
2563
Instead of a linear search as <var>TCollection</var> does, <var>TSortedCollection</var>
2564
uses a binary search based on the keys of the objects. It uses the
2565
<link id="TSortedCollection.Compare">Compare</link> function to implement this
2569
If the item is found, <var>Search</var> returns <var>True</var>, otherwise <var>False</var>
2577
<link id="TCollection.IndexOf"/>
2579
<example file="objectex/ex36"/>
2583
<element name="TSortedCollection.Insert">
2584
<short>Insert new item in collection.</short>
2587
<var>Insert</var> inserts an item in the collection at the correct position, such
2588
that the collection is ordered at all times. You should never use
2589
<link id="TCollection.AtInsert">Atinsert</link>, since then the collection ordering
2593
If <var>Item</var> is already present in the collection, and <var>Duplicates</var> is
2594
<var>False</var>, the item will not be inserted.
2601
<link id="TCollection.AtInsert"/>
2603
<example file="objectex/ex35"/>
2608
<element name="TSortedCollection.Store">
2609
<short>Write the collection to the stream.</short>
2612
<var>Store</var> writes the collection to the stream <var>S</var>. It does this by
2613
calling the inherited <link id="TCollection.Store"/>, and then writing the
2614
<var>Duplicates</var> flag to the stream.
2617
After a <var>Store</var>, the collection can be loaded from the stream with the
2618
constructor <link id="TSortedCollection.Load">Load</link>
2621
For an example, see <link id="TCollection.Load"/>.
2625
Errors can be those of <link id="TStream.Put"/>.
2628
<link id="TSortedCollection.Load"/>
2633
<element name="TStringCollection">
2634
<short>Collection of pascal strings.</short>
2637
The <var>TStringCollection</var> object manages a sorted collection of pascal
2639
To this end, it overrides the <link id="TSortedCollection.Compare">Compare</link>
2640
method of <var>TSortedCollection</var>, and it introduces methods to read/write
2641
strings from a stream.
2646
<element name="TStringCollection.GetItem">
2647
<short>Get string from the stream.</short>
2650
<var>GetItem</var> reads a string from the stream <var>S</var> and returns a pointer
2651
to it. It doesn't insert the string in the collection.
2654
This method is primarily introduced to be able to load and store the
2655
collection from and to a stream.
2659
The errors returned are those of <link id="TStream.ReadStr"/>.
2662
<link id="TStringCollection.PutItem"/>
2666
<element name="TStringCollection.Compare">
2667
<short>Compare two strings in the collection.</short>
2670
<var>TStringCollection</var> overrides the <var>Compare</var> function so it compares
2671
the two keys as if they were pointers to strings. The compare is done case
2672
sensitive. It returns the following results:
2675
<dt>-1</dt><dd> if the first string is alphabetically earlier than the second string.</dd>
2676
<dt>0</dt><dd> if the two strings are equal.</dd>
2677
<dt>1</dt><dd> if the first string is alphabetically later than the second string.</dd>
2684
<link id="TSortedCollection.Compare"/>
2686
<example file="objectex/ex37"/>
2691
<element name="TStringCollection.FreeItem">
2692
<short>Dispose a string in the collection from memory.</short>
2694
<var>TStringCollection</var> overrides <var>FreeItem</var> so that the string pointed
2695
to by <var>Item</var> is disposed from memory.
2701
<link id="TCollection.FreeItem"/>
2705
<element name="TStringCollection.PutItem">
2706
<short>Write a string to the stream.</short>
2709
<var>PutItem</var> writes the string pointed to by <var>Item</var> to the stream
2713
This method is primarily used in the <var>Load</var> and <var>Store</var> methods,
2714
and should not be used directly.
2718
Errors are those of <link id="TStream.WriteStr"/>.
2721
<link id="TStringCollection.GetItem"/>
2726
<element name="TStrCollection">
2727
<short>Collection of null-terminated strings</short>
2730
The <var>TStrCollection</var> object manages a sorted collection
2731
of null-terminated strings (pchar strings).
2732
To this end, it overrides the <link id="TSortedCollection.Compare">Compare</link>
2733
method of <var>TSortedCollection</var>, and it introduces methods to read/write
2734
strings from a stream.
2739
<element name="TStrCollection.GetItem">
2740
<short>Read a null-terminated string from the stream.</short>
2743
<var>GetItem</var> reads a null-terminated string from the stream <var>S</var>
2744
and returns a pointer to it. It doesn't insert the string in the
2748
This method is primarily introduced to be able to load and store the
2749
collection from and to a stream.
2753
The errors returned are those of <link id="TStream.StrRead"/>.
2756
<link id="TStrCollection.PutItem"/>
2760
<element name="TStrCollection.Compare">
2761
<short>Compare two strings in the collection.</short>
2764
<var>TStrCollection</var> overrides the <var>Compare</var> function so it compares
2765
the two keys as if they were pointers to strings. The compare is done case
2766
sensitive. It returns
2769
<dt>-1</dt><dd> if the first string is alphabetically earlier than the second string. </dd>
2770
<dt>0</dt><dd> if the two strings are equal. </dd>
2771
<dt>1</dt><dd> if the first string is alphabetically later than the second string.</dd>
2778
<link id="TSortedCollection.Compare"/>
2780
<example file="objectex/ex38"/>
2783
<element name="TStrCollection.FreeItem">
2784
<short>Free null-terminated string from the collection.</short>
2786
<var>TStrCollection</var> overrides <var>FreeItem</var> so that the string pointed
2787
to by <var>Item</var> is disposed from memory.
2793
<link id="TCollection.FreeItem"/>
2797
<element name="TStrCollection.PutItem">
2798
<short>Write a null-terminated string to the stream.</short>
2801
<var>PutItem</var> writes the string pointed to by <var>Item</var> to the stream
2805
This method is primarily used in the <var>Load</var> and <var>Store</var> methods,
2806
and should not be used directly.
2810
Errors are those of <link id="TStream.StrWrite"/>.
2813
<link id="TStrCollection.GetItem"/>
2817
<element name="TUnSortedStrCollection">
2818
<short>Unsorted string collection</short>
2821
The <var>TUnSortedStrCollection</var> object manages an unsorted list of strings.
2822
To this end, it overrides the <link id="TStringCollection.Insert"/> method to add
2823
strings at the end of the collection, rather than in the alphabetically
2827
Take care, the <link id="TSortedCollection.Search">Search</link> and
2828
<link id="TCollection.IndexOf">IndexOf</link> methods will not work on an unsorted
2834
<element name="TUnSortedStrCollection.Insert">
2835
<short>Insert a new string in the collection.</short>
2837
<var>Insert</var> inserts a string at the end of the collection, instead
2838
of on it's alphabetical place, resulting in an unsorted collection of
2845
<link id="TCollection.Insert"/>
2847
<example file="objectex/ex39"/>
2852
<element name="TResourceCollection">
2853
<short>Collection of resource names</short>
2856
A <var>TResourceCollection</var> manages a collection of resource names.
2857
It stores the position and the size of a resource, as well as the name of
2858
the resource. It stores these items in records that look like this:
2862
TResourceItem = packed RECORD
2867
PResourceItem = ^TResourceItem;
2870
It overrides some methods of <var>TStringCollection</var> in order to accomplish
2874
Remark that the <var>TResourceCollection</var> manages the names of the
2875
resources and their assiciated positions and sizes, it doesn't manage
2876
the resources themselves.
2881
<element name="TResourceCollection.KeyOf">
2882
<short>Return the key of an item in the collection.</short>
2884
<var>KeyOf</var> returns the key of an item in the collection. For resources, the
2885
key is a pointer to the string with the resource name.
2891
<link id="TStringCollection.Compare"/>
2895
<element name="TResourceCollection.GetItem">
2896
<short>Read an item from the stream.</short>
2899
<var>GetItem</var> reads a resource item from the stream <var>S</var>. It reads the
2900
position, size and name from the stream, in that order. It DOES NOT read the
2901
resource itself from the stream.
2904
The resulting item is not inserted in the collection. This call is manly for
2905
internal use by the <link id="TCollection.Load"/> method.
2909
Errors returned are those by <link id="TStream.Read"/>
2912
<link id="TCollection.Load"/>
2913
<link id="TStream.Read"/>
2917
<element name="TResourceCollection.FreeItem">
2918
<short>Release memory occupied by item.</short>
2921
<var>FreeItem</var> releases the memory occupied by <var>Item</var>. It de-allocates
2922
the name, and then the resourceitem record.
2925
It does NOT remove the item from the collection.
2932
<link id="TCollection.FreeItem"/>
2936
<element name="TResourceCollection.PutItem">
2937
<short>Write an item to the stream.</short>
2940
<var>PutItem</var> writes <var>Item</var> to the stream <var>S</var>. It does this by
2941
writing the position and size and name of the resource item to the stream.
2944
This method is used primarily by the <link id="TCollection.Store">Store</link>
2949
Errors returned are those by <link id="TStream.Write"/>.
2952
<link id="TCollection.Store"/>
2957
<element name="TResourceFile">
2958
<short>Resource file</short>
2960
<link id="TResourceFile"/> represents the resources in a binary file image.
2964
<element name="TResourceFile.Stream">
2965
<short>Actual file stream</short>
2967
contains the (file) stream that has the executable image and
2968
the resources. It can be initialized by the <link id="TResourceFile.Init">Init</link>
2973
<element name="TResourceFile.Modified">
2974
<short>Have resources changed ?</short>
2976
<var>Modified</var> is set to <var>True</var> if one of the resources has been changed.
2977
It is set by the <link id="TResourceFile.Init">SwitchTo</link>,
2978
<link id="TResourceFile.Delete">Delete</link> and <link id="TResourceFile.Put">Put</link>
2979
methods. Calling <link id="TResourceFile.Flush">Flush</link> will clear the
2980
<var>Modified</var> flag.
2984
<element name="TResourceFile.Init">
2985
<short>Instantiate a new instance.</short>
2988
<var>Init</var> instantiates a new instance of a <var>TResourceFile</var> object.
2989
If <var>AStream</var> is not nil then it is considered as a stream describing an
2990
executable image on disk.
2993
<var>Init</var> will try to position the stream on the start of the resources section,
2994
and read all resources from the stream.
3001
<link id="TResourceFile.Done"/>
3005
<element name="TResourceFile.Done">
3006
<short>Destroy the instance and remove it from memory.</short>
3008
<var>Done</var> cleans up the instance of the <var>TResourceFile</var> Object.
3009
If <var>Stream</var> was specified at initialization, then <var>Stream</var> is
3016
<link id="TResourceFile.Init"/>
3020
<element name="TResourceFile.Count">
3021
<short>Number of resources in the file</short>
3023
<var>Count</var> returns the number of resources. If no resources were
3024
read, zero is returned.
3030
<link id="TResourceFile.Init"/>
3034
<element name="TResourceFile.KeyAt">
3035
<short>Return the key of the item at a certain position.</short>
3037
<var>KeyAt</var> returns the key (the name) of the <var>I</var>-th resource.
3040
In case <var>I</var> is invalid, <var>TCollection.Error</var> will be executed.
3043
<link id="TResourceFile.Get"/>
3047
<element name="TResourceFile.Get">
3048
<short>Return a resource by key name.</short>
3050
<var>Get</var> returns a pointer to a instance of a resource identified by
3051
<var>Key</var>. If <var>Key</var> cannot be found in the list of resources, then
3052
<var>Nil</var> is returned.
3055
Errors returned may be those by <var>TStream.Get</var>
3061
<element name="TResourceFile.SwitchTo">
3062
<short>Write resources to a new stream.</short>
3065
<var>SwitchTo</var> switches to a new stream to hold the resources in.
3066
<var>AStream</var> will be the new stream after the call to <var>SwitchTo</var>.
3069
If <var>Pack</var> is true, then all the known resources will be copied from
3070
the current stream to the new stream (<var>AStream</var>). If <var>Pack</var> is
3071
<var>False</var>, then only the current resource is copied.
3074
The return value is the value of the original stream: <var>Stream</var>.
3077
The <var>Modified</var> flag is set as a consequence of this call.
3081
Errors returned can be those of <link id="TStream.Read"/> and
3082
<link id="TStream.Write"/>.
3085
<link id="TResourceFile.Flush"/>
3089
<element name="TResourceFile.Flush">
3090
<short>Writes the resources to the stream.</short>
3092
If the <var>Modified</var> flag is set to <var>True</var>, then <var>Flush</var>
3093
writes the resources to the stream <var>Stream</var>. It sets the <var>Modified</var>
3094
flag to true after that.
3097
Errors can be those by <link id="TStream.Seek"/> and <link id="TStream.Write"/>.
3100
<link id="TResourceFile.SwitchTo"/>
3104
<element name="TResourceFile.Delete">
3105
<short>Delete a resource from the file</short>
3107
<var>Delete</var> deletes the resource identified by <var>Key</var> from the
3108
collection. It sets the <var>Modified</var> flag to true.
3114
<link id="TResourceFile.Flush"/>
3118
<element name="TResourceFile.Put">
3119
<short>Set a resource by key name.</short>
3121
<var>Put</var> sets the resource identified by <var>Key</var> to <var>Item</var>.
3122
If no such resource exists, a new one is created. The item is written
3126
Errors returned may be those by <link id="TStream.Put"/> and <var>TStream.Seek</var>
3129
<link id="TResourceFile.Get">Get</link>
3133
<element name="TStringList">
3134
<short>Collection of strings</short>
3137
A <var>TStringList</var> object can be used to read a collection of strings
3138
stored in a stream. If you register this object with the <link id="RegisterType"/>
3139
function, you cannot register the <var>TStrListMaker</var> object.
3144
<element name="TStringList.Load">
3145
<short>Load stringlist from stream.</short>
3147
The <var>Load</var> constructor reads the <var>TStringList</var> object from the
3148
stream <var>S</var>. It also reads the descriptions of the strings from the
3149
stream. The string descriptions are stored as an array of
3150
<var>TstrIndexrec</var> records, where each record describes a string on the
3151
stream. These records are kept in memory.
3154
If an error occurs, a stream error is triggered.
3157
<link id="TStringList.Done"/>
3161
<element name="TStringList.Done">
3162
<short>Clean up the instance</short>
3164
The <var>Done</var> destructor frees the memory occupied by the string
3165
descriptions, and destroys the object.
3171
<link id="TStringList.Load">Load</link>
3172
<link id="TObject.Done"/>
3176
<element name="TStringList.Get">
3177
<short>Return a string by key name</short>
3179
<var>Get</var> reads the string with key <var>Key</var> from the list of strings on the
3180
stream, and returns this string. If there is no string with such a key, an
3181
empty string is returned.
3184
If no string with key <var>Key</var> is found, an empty string is returned.
3185
A stream error may result if the stream doesn't contain the needed strings.
3188
<link id="TStrListMaker.Put"/>
3192
<element name="TStrListMaker">
3193
<short>Generate a stream with strings, readable by <link id="TStringList"/></short>
3196
The <var>TStrListMaker</var> object can be used to generate a stream with
3197
strings, which can be read with the <var>TStringList</var> object.
3198
If you register this object with the <link id="RegisterType"/>
3199
function, you cannot register the <var>TStringList</var> object.
3204
<element name="TStrListMaker.Init">
3205
<short>Instantiate a new instance of <var>TStrListMaker</var></short>
3208
The <var>Init</var> constructor creates a new instance of the <var>TstrListMaker</var>
3209
object. It allocates <var>AStrSize</var> bytes on the heap to hold all the
3210
strings you wish to store. It also allocates enough room for
3211
<var>AIndexSize</var> key description entries (of the type <var>TStrIndexrec</var>).
3214
<var>AStrSize</var> must be large enough to contain all the strings you wish to
3215
store. If not enough memory is allocated, other memory will be overwritten.
3216
The same is true for <var>AIndexSize</var> : maximally <var>AIndexSize</var> strings
3217
can be written to the stream.
3224
<link id="TObject.Init"/>
3225
<link id="TStrListMaker.Done"/>
3229
<element name="TStrListMaker.Done">
3230
<short>Clean up the instance and free all related memory.</short>
3232
The <var>Done</var> destructor de-allocates the memory for the index description
3233
records and the string data, and then destroys the object.
3239
<link id="TObject.Done"/>
3240
<link id="TStrListMaker.Init"/>
3244
<element name="TStrListMaker.Put">
3245
<short>Add a new string to the list with associated key.</short>
3247
<var>Put</var> adds they string <var>S</var> with key <var>Key</var> to the collection of
3248
strings. This action doesn't write the string to a stream. To write the
3249
strings to the stream, see the <link id="TStrListMaker.Store">Store</link> method.
3255
<link id="TStrListMaker.Store"/>
3259
<element name="TStrListMaker.Store">
3260
<short>Write the strings to the stream.</short>
3262
<var>Store</var> writes the collection of strings to the stream <var>S</var>.
3263
The collection can then be read with the <var>TStringList</var> object.
3266
A stream error may occur when writing the strings to the stream.
3269
<link id="TStringList.Load"/>
3270
<link id="TStrListMaker.Put"/>
3274
<element name="InvalidHandle">
3275
<short>Value for invalid handle. Initial value for file stream handles or when the stream is closed.</short>
3278
<!-- function Visibility: default -->
3279
<element name="CallVoidConstructor">
3280
<short>Call a constructor with no arguments</short>
3283
<var>CallVoidConstructor</var> calls the constructor of an object.
3284
<var>Ctor</var> is the address of the constructor, <var>Obj</var> is a
3285
pointer to the instance. If it is <var>Nil</var>, then a new instance is
3286
allocated. <var>VMT</var> is a pointer to the object's VMT. The return value
3287
is a pointer to the instance.
3290
Note that this can only be used on constructors that require no arguments.
3294
If the constructor expects arguments, the stack may be corrupted.
3297
<link id="CallPointerConstructor"/>
3298
<link id="CallPointerMethod"/>
3299
<link id="CallVoidLocal"/>
3300
<link id="CallPointerLocal"/>
3301
<link id="CallVoidMethodLocal"/>
3302
<link id="CallPointerMethodLocal"/>
3306
<!-- function Visibility: default -->
3307
<element name="CallPointerConstructor">
3308
<short>Call a constructor with a pointer argument.</short>
3311
<var>CallVoidConstructor</var> calls the constructor of an object.
3312
<var>Ctor</var> is the address of the constructor, <var>Obj</var> is a
3313
pointer to the instance. If it is <var>Nil</var>, then a new instance is
3314
allocated. <var>VMT</var> is a pointer to the object's VMT.
3315
<var>Param1</var> is passed to the constructor. The return value
3316
is a pointer to the instance.
3319
Note that this can only be used on constructors that require a pointer as
3320
the sole argument. It can also be used to call a constructor with a single
3321
argument by reference.
3325
If the constructor expects other arguments than a pointer, the stack may be corrupted.
3328
<link id="CallVoidConstructor"/>
3329
<link id="CallPointerMethod"/>
3330
<link id="CallVoidLocal"/>
3331
<link id="CallPointerLocal"/>
3332
<link id="CallVoidMethodLocal"/>
3333
<link id="CallPointerMethodLocal"/>
3337
<!-- function Visibility: default -->
3338
<element name="CallVoidMethod">
3339
<short>Call an object method</short>
3341
<var>CallVoidMethod</var> calls the method with address <var>Method</var>
3342
for instance <var>Obj</var>. It returns a pointer to the instance.
3345
If the method expects parameters, the stack may become corrupted.
3348
<link id="CallPointerMethod"/>
3349
<link id="CallVoidLocal"/>
3350
<link id="CallPointerLocal"/>
3351
<link id="CallVoidMethodLocal"/>
3352
<link id="CallPointerMethodLocal"/>
3353
<link id="CallVoidConstructor"/>
3354
<link id="CallPointerConstructor"/>
3358
<!-- function Visibility: default -->
3359
<element name="CallPointerMethod">
3360
<short>Call a method with a single pointer argument</short>
3362
<var>CallPointerMethod</var> calls the method with address <var>Method</var>
3363
for instance <var>Obj</var>. It passes <var>Param1</var> to the method as
3364
the single argument. It returns a pointer to the instance.
3367
If the method expects other parameters than a single pointer, the stack may become corrupted.
3370
<link id="CallVoidMethod"/>
3371
<link id="CallVoidLocal"/>
3372
<link id="CallPointerLocal"/>
3373
<link id="CallVoidMethodLocal"/>
3374
<link id="CallPointerMethodLocal"/>
3375
<link id="CallVoidConstructor"/>
3376
<link id="CallPointerConstructor"/>
3380
<!-- function Visibility: default -->
3381
<element name="CallVoidLocal">
3382
<short>Call a local nested procedure.</short>
3384
<var>CallVoidLocal</var> calls the local procedure with address
3385
<var>Func</var>, where <var>Frame</var> is the frame of the wrapping
3389
If the local function expects parameters, the stack may become corrupted.
3392
<link id="CallPointerMethod"/>
3393
<link id="CallVoidMethod"/>
3394
<link id="CallPointerLocal"/>
3395
<link id="CallVoidMethodLocal"/>
3396
<link id="CallPointerMethodLocal"/>
3397
<link id="CallVoidConstructor"/>
3398
<link id="CallPointerConstructor"/>
3402
<!-- function Visibility: default -->
3403
<element name="CallPointerLocal">
3404
<short>Call a local nested function with a pointer argument</short>
3406
<var>CallPointerLocal</var> calls the local procedure with address
3407
<var>Func</var>, where <var>Frame</var> is the frame of the wrapping
3408
function. It passes <var>Param1</var> to the local function.
3411
If the local function expects other parameters than a pointer, the stack may become corrupted.
3414
<link id="CallPointerMethod"/>
3415
<link id="CallVoidMethod"/>
3416
<link id="CallVoidLocal"/>
3417
<link id="CallVoidMethodLocal"/>
3418
<link id="CallPointerMethodLocal"/>
3419
<link id="CallVoidConstructor"/>
3420
<link id="CallPointerConstructor"/>
3424
<!-- function Visibility: default -->
3425
<element name="CallVoidMethodLocal">
3426
<short>Call a local procedure of a method</short>
3428
<var>CallVoidMethodLocal</var> calls the local procedure with address
3429
<var>Func</var>, where <var>Frame</var> is the frame of the wrapping
3433
If the local function expects parameters, the stack may become corrupted.
3436
<link id="CallPointerMethod"/>
3437
<link id="CallVoidMethod"/>
3438
<link id="CallPointerLocal"/>
3439
<link id="CallVoidLocal"/>
3440
<link id="CallPointerMethodLocal"/>
3441
<link id="CallVoidConstructor"/>
3442
<link id="CallPointerConstructor"/>
3446
<!-- function Visibility: default -->
3447
<element name="CallPointerMethodLocal">
3448
<short>Call a local procedure of a method with a pointer argument</short>
3450
<var>CallPointerMethodLocal</var> calls the local procedure with address
3451
<var>Func</var>, where <var>Frame</var> is the frame of the wrapping
3452
method. It passes <var>Param1</var> to the local function.
3455
If the local function expects other parameters than a pointer, the stack may become corrupted.
3458
<link id="CallPointerMethod"/>
3459
<link id="CallVoidMethod"/>
3460
<link id="CallPointerLocal"/>
3461
<link id="CallVoidLocal"/>
3462
<link id="CallVoidMethodLocal"/>
3463
<link id="CallVoidConstructor"/>
3464
<link id="CallPointerConstructor"/>
3468
<!-- constant Visibility: default -->
3469
<element name="DefaultTPCompatible">
3470
<short>Default value for <link id="#rtl.objects.tstream.tpcompatible">tstream.tpcompatible</link></short>
3472
<var>DefaultTPCompatible</var> is used to initialize <link
3473
id="tstream.tpcompatible">tstream.tpcompatible</link>.
3479
</fpdoc-descriptions>
b'\\ No newline at end of file'
added
removed
docs/objects.xml
