学步园

Description

Each TCollection holds a group of TCollectionItem descendants. TCollection maintains an index of the collection items in its Items array. The Count property contains the number of items in the collection. Use the Add and Delete methods to add items to the collection and delete items from the collection.

Objects descended from TCollection can contain objects descended from TCollectionItem. Thus, for each TCollection descendant, there is a corresponding TCollectionItem descendant. The following table lists some typical descendants of TCollection with the corresponding TCollectionItem descendant and the component that uses each pair.

TCollection
descendant TCollectionItem
descendant Component
TAggregates TAggregate TClientDataSet
TCookieCollection TCookie TWebResponse
TCoolBands TCoolBand TCoolBar
TDBGridColumns TColumn TDBGrid
TDependencies TDependency TService
TDisplayDims TDisplayDim TDecisionGrid
TFieldDefs TFieldDef TDataSet
THeaderSections THeaderSection THeaderControl
TIndexDefs TIndexDef TTable
TListColumns TListColumn TListView
TParams TParam many datasets
TStatusPanels TStatusPanel TStatusBar
TWorkAreas TWorkArea TListView
The controls that use TCollection and TCollectionItem descendants have a published property that holds a collection. (For example, the Panels property of TStatusBar holds a TStatusPanels.) A standard property editor, referred to generically as the Collection editor, can be invoked from the Object Inspector to edit the items in the collection.

Note: When writing a TCollection descendant that is used by another control, be sure to override the protected GetOwner method of the collection so that it can appear in the Object Inspector.

1.  TCollectionItemClass = class of TCollectionItem;
2.   TCollectionNotification = (cnAdded, cnExtracting, cnDeleting);
4.   TCollection = class(TPersistent)
5.   private
6.     FItemClass: TCollectionItemClass;
7.     FItems: TList;
8.     FUpdateCount: Integer;
9.     FNextID: Integer;
10.     FPropName: string;
11.     function GetCount: Integer;
12.     function GetPropName: string;
13.     procedure InsertItem(Item: TCollectionItem);
14.     procedure RemoveItem(Item: TCollectionItem);
15.   protected
16.     procedure Added(var Item: TCollectionItem); virtual; deprecated;
17.     procedure Deleting(Item: TCollectionItem); virtual; deprecated;
18.     property NextID: Integer read FNextID;
19.     procedure Notify(Item: TCollectionItem; Action: TCollectionNotification); virtual;
20.     { Design-time editor support }
21.     function GetAttrCount: Integer; dynamic;
22.     function GetAttr(Index: Integer): string; dynamic;
23.     function GetItemAttr(Index, ItemIndex: Integer): string; dynamic;
24.     procedure Changed;
25.     function GetItem(Index: Integer): TCollectionItem;
26.     procedure SetItem(Index: Integer; Value: TCollectionItem);
27.     procedure SetItemName(Item: TCollectionItem); virtual;
28.     procedure Update(Item: TCollectionItem); virtual;
29.     property PropName: string read GetPropName write FPropName;
30.     property UpdateCount: Integer read FUpdateCount;
31.   public
32.     constructor Create(ItemClass: TCollectionItemClass);
33.     destructor Destroy; override;
34.     function Owner: TPersistent;
35.     function Add: TCollectionItem;
36.     procedure Assign(Source: TPersistent); override;
37.     procedure BeginUpdate; virtual;
38.     procedure Clear;
39.     procedure Delete(Index: Integer);
40.     procedure EndUpdate; virtual;
41.     function FindItemID(ID: Integer): TCollectionItem;
42.     function GetNamePath: string; override;
43.     function Insert(Index: Integer): TCollectionItem;
44.     property Count: Integer read GetCount;
45.     property ItemClass: TCollectionItemClass read FItemClass;
46.     property Items[Index: Integer]: TCollectionItem read GetItem write SetItem;
47.   end;
49. { Collection class that maintains an "Owner" in order to obtain property
50.   path information at design-time }
52. { TCollection }
54. constructor TCollection.Create(ItemClass: TCollectionItemClass);
55. begin
56.   FItemClass := ItemClass;
57.   FItems := TList.Create;
58.   NotifyDesigner(Self, Self, opInsert);
59. end;
61. destructor TCollection.Destroy;
62. begin
63.   FUpdateCount := 1;
64.   if FItems <> nil then
65.     Clear;
66.   NotifyDesigner(Self, Self, opRemove);
67.   FItems.Free;
68.   inherited Destroy;
69. end;
71. function TCollection.Add: TCollectionItem;
72. begin
73.   Result := FItemClass.Create(Self);
74.   Added(Result);
75. end;
77. procedure TCollection.Assign(Source: TPersistent);
78. var
79.   I: Integer;
80. begin
81.   if Source is TCollection then
82.   begin
83.     BeginUpdate;
84.     try
85.       Clear;
86.       for I := 0 to TCollection(Source).Count - 1 do
87.         Add.Assign(TCollection(Source).Items[I]);
88.     finally
89.       EndUpdate;
90.     end;
91.     Exit;
92.   end;
93.   inherited Assign(Source);
94. end;
96. procedure TCollection.BeginUpdate;
97. begin
98.   Inc(FUpdateCount);
99. end;
101. procedure TCollection.Changed;
102. begin
103.   if FUpdateCount = 0 then Update(nil);
104. end;
106. procedure TCollection.Clear;
107. begin
108.   if FItems.Count > 0 then
109.   begin
110.     BeginUpdate;
111.     try
112.       while FItems.Count > 0 do
113.         TCollectionItem(FItems.Last).Free;
114.     finally
115.       EndUpdate;
116.     end;
117.   end;
118. end;
120. procedure TCollection.EndUpdate;
121. begin
122.   Dec(FUpdateCount);
123.   Changed;
124. end;
126. function TCollection.FindItemID(ID: Integer): TCollectionItem;
127. var
128.   I: Integer;
129. begin
130.   for I := 0 to FItems.Count-1 do
131.   begin
132.     Result := TCollectionItem(FItems[I]);
133.     if Result.ID = ID then Exit;
134.   end;
135.   Result := nil;
136. end;
138. function TCollection.GetAttrCount: Integer;
139. begin
140.   Result := 0;
141. end;
143. function TCollection.GetAttr(Index: Integer): string;
144. begin
145.   Result := '';
146. end;
148. function TCollection.GetItemAttr(Index, ItemIndex: Integer): string;
149. begin
150.   Result := Items[ItemIndex].DisplayName;
151. end;
153. function TCollection.GetCount: Integer;
154. begin
155.   Result := FItems.Count;
156. end;
158. function TCollection.GetItem(Index: Integer): TCollectionItem;
159. begin
160.   Result := FItems[Index];
161. end;
163. function TCollection.GetNamePath: string;
164. var
165.   S, P: string;
166. begin
167.   Result := ClassName;
168.   if GetOwner = nil then Exit;
169.   S := GetOwner.GetNamePath;
170.   if S = '' then Exit;
171.   P := PropName;
172.   if P = '' then Exit;
173.   Result := S + '.' + P;
174. end;
176. function TCollection.GetPropName: string;
177. var
178.   I: Integer;
179.   Props: PPropList;
180.   TypeData: PTypeData;
181.   Owner: TPersistent;
182. begin
183.   Result := FPropName;
184.   Owner := GetOwner;
185.   if (Result <> '') or (Owner = nil) or (Owner.ClassInfo = nil) then Exit;
186.   TypeData := GetTypeData(Owner.ClassInfo);
187.   if (TypeData = nil) or (TypeData^.PropCount = 0) then Exit;
188.   GetMem(Props, TypeData^.PropCount * sizeof(Pointer));
189.   try
190.     GetPropInfos(Owner.ClassInfo, Props);
191.     for I := 0 to TypeData^.PropCount-1 do
192.     begin
193.       with Props^[I]^ do
194.         if (PropType^^.Kind = tkClass) and
195.           (GetOrdProp(Owner, Props^[I]) = Integer(Self)) then
196.           FPropName := Name;
197.     end;
198.   finally
199.     Freemem(Props);
200.   end;
201.   Result := FPropName;
202. end;
204. function TCollection.Insert(Index: Integer): TCollectionItem;
205. begin
206.   Result := Add;
207.   Result.Index := Index;
208. end;
210. procedure TCollection.InsertItem(Item: TCollectionItem);
211. begin
212.   if not (Item is FItemClass) then TList.Error(@SInvalidProperty, 0);
213.   FItems.Add(Item);
214.   Item.FCollection := Self;
215.   Item.FID := FNextID;
216.   Inc(FNextID);
217.   SetItemName(Item);
218.   Notify(Item, cnAdded);
219.   Changed;
220.   NotifyDesigner(Self, Item, opInsert);
221. end;
223. procedure TCollection.RemoveItem(Item: TCollectionItem);
224. begin
225.   Notify(Item, cnExtracting);
226.   if Item = FItems.Last then
227.     FItems.Delete(FItems.Count - 1)
228.   else
229.     FItems.Remove(Item);
230.   Item.FCollection := nil;
231.   NotifyDesigner(Self, Item, opRemove);
232.   Changed;
233. end;
235. procedure TCollection.SetItem(Index: Integer; Value: TCollectionItem);
236. begin
237.   TCollectionItem(FItems[Index]).Assign(Value);
238. end;
240. procedure TCollection.SetItemName(Item: TCollectionItem);
241. begin
242. end;
244. procedure TCollection.Update(Item: TCollectionItem);
245. begin
246. end;
248. procedure TCollection.Delete(Index: Integer);
249. begin
250.   Notify(TCollectionItem(FItems[Index]), cnDeleting);
251.   TCollectionItem(FItems[Index]).Free;
252. end;
254. function TCollection.Owner: TPersistent;
255. begin
256.   Result := GetOwner;
257. end;
259. procedure TCollection.Added(var Item: TCollectionItem);
260. begin
261. end;
263. procedure TCollection.Deleting(Item: TCollectionItem);
264. begin
265. end;
267. procedure TCollection.Notify(Item: TCollectionItem;
268.   Action: TCollectionNotification);
269. begin
270.   case Action of
271.     cnAdded: Added(Item);
272.     cnDeleting: Deleting(Item);
273.   end;
274. end;