Introduction to Collections

Definition

A collection primarily follows the same definition as a list: it is made of items that use the same characteristics. That is, each item can be described using the same features. Most of the time, a collection is used for composite items in which case each item is made of parts. For example, in a collection of cars, each car could identified by a name, a color, the number of seats, the type of transmission, etc.

 In the VCL, various classes or many objects use collections. Each may have its own way of creating and managing its collection of items, but there is a foundation that most, if not all, collections share. In many classes, the collection of an object is created from a class named TCollection.

The TCollection class is defined in the Classes.hpp header file and that class derived from TPersistent.

Most of the time, you will not directly use the TCollection class to create a collection. As mentioned already, the class that uses a collection will have a property that uses a class derived directly or indirectly from TCollection (the name of the collection property varies; in some classes it is called Items but it may have another name in another class).

In the TCollection class, the collection of items is represented by a property named Items. The Items property is a collection of objects that each is of type TCollectionItem:

__property Classes::TCollectionItem * Items = {read=GetItem,write=SetItem};

The TCollectionItem class is derived from TPersistent.

To let you get a reference to the collection to which an item belongs, the TCollectionItem class provides the Collection property that is of type TCollection:

__property Classes::TCollection * Collection = {read=FCollection,write=SetCollection};

This property gives access to the collection that owns the current item.

In the next section, we will see how to create items. Once a collection contains items, you can access one using its position. To let you do this, the  TCollectionItem class contains a property named ID:

__property int ID = {read=FID};

If an item has already been created, to get its reference based in its ID value, you can call the FindItemID() method. Its syntax is:

Classes::TCollectionItem * __fastcall FindItemID(int ID);

ID is a read-only property. It only gives you access to an item but doesn't allow you to specify or change the position of an item. If you want to perform such an operation, you can use the Index property, which is read-write:

__property int Index = {read=GetIndex,write=SetIndex};

In both cases, the items of a collection use a zero-based index. That is, the first item uses an index of 0. The second uses an index of 1, and so on.

As you will in most cases, the items of a collection are visually created and managed using window. In that window, each item displays, or is represented by, a name. To identify this name, the TCollectionItem is equipped with a property named DisplayName that is of type UnicodeString:

__property System::UnicodeString DisplayName =
{
    read=GetDisplayName,
    write=SetDisplayName
};

A collection is meant to hold one or more items. There are many ways you can create an item.

To let you add a new item to a collection, the TCollection class provides a method named Add. Its syntax is:

Classes::TCollectionItem * __fastcall Add(void);

When this method is called, it adds a new item to the collection:

• If the collection is empty, the new item becomes the first and only one
• In the collection already contains at least one item, the new item is added at the end of the existing list

In the same way, you can add as many items as necessary. If you add the items one at a time, the operation may be short. If you have many items to add and each item takes time, the application may have to stop its other activities to take care of the adding operation. To assist you with this, the TCollection class is equipped with a method named BeginUpdate. Its syntax is:

virtual void __fastcall BeginUpdate(void);

Call this method to suspend the activities of an application while adding a series of items. Then call the Add() method repeatedly to create the new items. After adding the items, call the EndUpdate() method. Its syntax is:

virtual void __fastcall EndUpdate(void);

As mentioned already, once the items have been created, you can access each by its index.

Instead of add an item, you can insert an item using an index. This is done through the Insert() method:

Classes::TCollectionItem * __fastcall Insert(int Index);

The number of items in a collection is represented by the read-only Count property:

__property int Count = {read=GetCount};

The capacity of a collection is the number of items that the collection should have. This information is set, or provided by, the Capacity property:

__property int Capacity = {read=GetCapacity,write=SetCapacity};

You can access the Capacity property before the list is created and assign an integral value to it to indicate the primary amount of memory you want the compiler to set aside for the collection.

To let you remove an item, the TCollection class provides the Delete() method. Its syntax;

void __fastcall Delete(int Index);

This method takes one argument as the index of the item to be deleted.

To remove all items from the collection, you can call the Clear() method. Its syntax is:

void __fastcall Clear(void);

Of course, you course perform this operation by removing one item at a time from beginning to end until the list is empty.