Indy 9 | Content | Index | Reference

TIdObjectList
Hierarchy, Properties, Methods, See Also, Unit: IdContainers
Implements a list of object instances.

    TIdObjectList = class(TList)

Unit
IdContainers
Description
TIdObjectList is a TList descendant that implements a list of object instances. TObjectList provides properties and methods to add, delete, rearrange, locate, access, and sort objects. If the OwnsObjects property is set to True (the default), TObjectList controls the memory of its objects, freeing an object when its index is reassigned; when it is removed from the list with the Delete, Remove, or Clear method; or when the TObjectList instance is itself destroyed.

TIdObjectList.Items
TIdObjectList
Provides indexed access to the contents of the object list.

    property Items [AIndex: Integer]: TObject;

Parameters
AIndex
Position in the list to be accessed.
Return Value
TObject - Object at the position on the list.
Description
Items is an indexed TObject property that provides access to the contents of the object list using the Integer position specified in AIndex. The index positions in Items are zero-based.

If OwnsObjects is True, reassigning an Items index frees the object that previously occupied that position in the list.

Items can contain nil references. To remove nil references and reduce the size of the array, call the Pack method.

TIdObjectList.OwnsObjects
TIdObjectList
Indicates if objects are freed when deleted from the list.

    property OwnsObjects: Boolean;

Description
OwnsObjects is a Boolean property that indicates if objects are freed when deleted from the list, or the list or destroyed. OwnsObjects allows TObjectList to control the memory of its objects. If OwnsObjects is True (the default), calling Delete or Remove frees the deleted object in addition to removing it from the list. calling Clear frees all the objects in the list in addition to emptying the list. calling the destructor frees all the objects in the list in addition to destroying the TObjectList itself. assigning a new value to an index in Items frees the object that previously occupied that position in the list.

Even if OwnsObjects is True, the Extract method can be used to remove objects from the list without freeing them.

TIdObjectList.Add
TIdObjectList
Inserts an object at the end of the list.

    function Add(AObject: TObject): Integer;

Parameters
AObject: TObject
Object to add to the object list.
Return Value
Integer - Index position of the inserted object.
Description
Add is an Integer function used to insert an object at the end of the list. Add places the object after the last item, even if the array contains nil references, and returns the index of the inserted object. (The first object in the list has an index of 0.)

Add increments Count and, if necessary, allocates memory by increasing the value of Capacity.

TIdObjectList.Create
TIdObjectList
Creates and initializes the Object list.

    constructor Create; overload;

Parameters
AOwnsObjects
Indicates if the list owns it's object instances.
Description
Create is an overoaded Constructior in TIdObjectList that creates and initializes the Object list. If no parameter is specified, or if the constructor is called with the True parameter, the new TObjectList is initialized with OwnsObjects set to True.

TIdObjectList.Create
TIdObjectList
Creates and initializes the Object list.

    constructor Create(AOwnsObjects: Boolean); overload;

Parameters
AOwnsObjects: Boolean
Indicates if the list owns it's object instances.
Description
Create is an overoaded Constructior in TIdObjectList that creates and initializes the Object list. If no parameter is specified, or if the constructor is called with the True parameter, the new TObjectList is initialized with OwnsObjects set to True.

TIdObjectList.FindInstanceOf
TIdObjectList
Finds the first instance of a specified class in the list.

    function FindInstanceOf(AClassRef: TClass; AMatchExact: Boolean = True; AStartPos: Integer = 0): Integer;

Parameters
AClass
CLass instance to be located in the list.
AExact
Indicates if descendants classes are a match. Default value is True.
AStartAt
Initial position to start the search. Default value is 0.
Return Value
Integer - Index position of the class instance.
Description
FindInstanceOf is an Integer function that returns the index of the first instance of AClass appearing after the AStartAt index position in the Items array. If AExact is True, FindInstanceOf returns instances only of AClass itself, ignoring instances descendant classes. If no instance of the specified class is found, FindInstanceOf returns –1.

TIdObjectList.IndexOf
TIdObjectList
Returns the index of the first object in the list with a specified value.

    function IndexOf(AObject: TObject): Integer;

Parameters
AObject: TObject
Object instance to be located.
Return Value
Integer - Index position of the located object instance.
Description
Call IndexOf to get the index for a specified object in the list, where the first object has index 0, the second object has index 1, and so on. If an object is not in the list, IndexOf returns -1. If an object appears more than once, IndexOf returns the index of the first appearance.

TIdObjectList.Insert
TIdObjectList
Adds an object to the list at a specified position.

    procedure Insert(AIndex: Integer; AObject: TObject);

Parameters
AObject: TObject
Object instance to be stored in the list.
Index
- Position in the list for the new object instance.
Description
Insert is a procedure used to add an object at a specified position in the list, shifting the item that previously occupied that position (and all subsequent items) up. Insert increments Count and, if necessary, allocates memory by increasing the value of Capacity.

The Index parameter is zero-based, so the first position in the list has an index of 0.

To replace a nil reference with a new object without growing the array, set the Items property directly.

TIdObjectList.Remove
TIdObjectList
Removes (and optionally frees) an object from the list.

    function Remove(AObject: TObject): Integer;

Parameters
AObject: TObject
Onject instance to be removed.
Return Value
Integer - Index position of the object removed from the list.
Description
Remove is an Integer function that can be used to delete a specific object from the list when its index is unknown. The value returned is the index of the object in the Items array before it was removed. If the specified object is not found on the list, Remove returns –1. If OwnsObjects is True, Remove frees the object in addition to removing it from the list.

After an object is deleted, all the objects that follow it are moved up in index position and Count is decremented. If an object appears more than once on the list, Remove deletes only the first appearance. Hence, if OwnsObjects is True, removing an object that appears more than once results in empty object references later in the list.

To use an index position (rather than an object reference) to specify the object to be removed, call Delete.

To remove an object from the list without freeing it, call Extract.

Created with Doc-O-Matic 2 donated to Project JEDI. Commercial license available from the Doc-O-Matic site.