Microsoft DirectX 8.0

CGenericList Class

CGenericList class hierarchy

Class template that implements a type-specific list. For more information, see CBaseList.

Declaration: Wxlist.h

To use this template, declare a variable of type CGenericList, with a template argument that defines the type of object in the list. For example, the following statement declares a list of CBaseFilter objects:

CGenericList<CBaseFilter> myFilterList("Filters"); 

For convenience, the following list types are defined:

typedef CGenericList<CBaseObject> CBaseObjectList;
typedef CGenericList<IUnknown> CBaseInterfaceList;
Public Methods
CGenericListConstructor method.
~CGenericListDestructor method.
GetHeadPositionRetrieves the position of the first item in the list.
GetTailPositionRetrieves the position of the last item of the list.
GetCountRetrieves the number of items in the list.
GetNextRetrieves the item at the specified position, and advances the position.
GetRetrieves the item at the specified position.
GetHeadRetrieves the item at the head of the list.
RemoveHeadRemoves the first item in the list.
RemoveTailRemoves the last item in the list.
RemoveRemoves the item at the specified position.
AddBeforeInserts an item or list before the specified position.
AddAfterInserts an item or list after the specified position.
AddHeadAdds an item or list to the front of the list.
AddTailAppends an item or list to the end of the list.
FindRetrieves the first position that holds the specified item.

CGenericList::AddAfter

CGenericList Class

Inserts an item or list after the specified position.

Syntax

POSITION AddAfter(
    POSITION p,
    OBJECT *pObj
);

Parameters

p
Position after which to add the item. If p is NULL, the method adds the item to the head of the list.
pObj
Pointer to an object of type OBJECT (the template type).

Return Value

Returns the position indicator of the inserted item.

Syntax

BOOL AddAfter(
    POSITION pos,
    CGenericList<OBJECT> *pList
);

Parameters

pos
Position after which to insert the list.
pList
Pointer to the list to insert.

Return Value

Returns TRUE if successful, or FALSE otherwise.

CGenericList::AddBefore

CGenericList Class

Inserts an item or list before the specified position.

Syntax

POSITION AddBefore(
    POSITION p,
    OBJECT *pObj
);

Parameters

p
Position before which to insert the list. If p is NULL, this method adds the item to the tail of the list.
pObj
Pointer to an object of type OBJECT (the template type).

Return Value

Returns the position indicator for the inserted item.

Syntax

BOOL AddBefore(
    POSITION pos,
    CGenericList<OBJECT> *pList
);

Parameters

pos
Position before which to insert the list.
pList
Pointer to the list to insert.

Return Value

Returns TRUE if successful. Otherwise, returns FALSE.

CGenericList::AddHead

CGenericList Class

Adds an item or list to the front of the list.

Syntax

POSITION AddHead(
    OBJECT *pObj
);

Parameters

pObj
Pointer to an object of type OBJECT (the template type).

Return Value

Returns a POSITION value indicating the new head position. If the method fails, the return value is NULL.

Syntax

BOOL AddHead(
    CGenericList<OBJECT> *pList
);

Parameters

pList
Pointer to the list of items to add.

Return Value

Returns TRUE if successful, or FALSE otherwise.

CGenericList::AddTail

CGenericList Class

Appends an item or list to the end of the list.

Syntax

POSITION AddTail(
    OBJECT *pObj
);

Parameters

pObj
Pointer to an object of type OBJECT (the template type).

Return Value

Returns a POSITION value for the new tail position. If the method fails, it returns NULL.

Syntax

BOOL AddTail(
    CGenericList<OBJECT> *pList
);

Parameters

pList
Pointer to the list to append.

Return Value

Returns TRUE if successful, or FALSE otherwise.

CGenericList::CGenericList

CGenericList Class

Constructor method.

Syntax

CGenericList(
    TCHAR *pName,
    INT iItems,
    BOOL bLock,
    BOOL bAlert
);

CGenericList(
    TCHAR *pName
);

Parameters

pName
Pointer to the name of the list.
iItems
Size of the node cache.
bLock
Not used.
bAlert
Not used.

Remarks

For efficiency, the CGenericList class maintains a cache of list nodes. If you know approximately how many items the list will hold, use the first version of the constructor. The second version uses a default cache size.

CGenericList::~CGenericList

CGenericList Class

Destructor method.

Syntax

CGenericList(void);

CGenericList::Find

CGenericList Class

Retrieves the first position that holds the specified item.

Syntax

POSITION Find(
    OBJECT *pObj
);

Parameters

pObj
Pointer to an object of type OBJECT (the template type).

Return Value

Returns a POSITION value, or NULL if the item is not in the list.

CGenericList::Get

CGenericList Class

Retrieves the item at the specified position.

Syntax

OBJECT *Get(
    POSITION pos
);

Parameters

pos
Position indicator for the item to retrieve.

Return Value

Returns a pointer to an object of type OBJECT (the template type).

Remarks

If pos is NULL, the method returns NULL.

CGenericList::GetCount

CGenericList Class

Retrieves the number of items in the list.

Syntax

int GetCount(void);

Return Value

Returns the number of items in the list.

CGenericList::GetHead

CGenericList Class

Retrieves the item at the head of the list.

Syntax

OBJECT GetHead(void);

Return Value

Returns a pointer to an object of type OBJECT (the template type).

CGenericList::GetHeadPosition

CGenericList Class

Retrieves the position of the first item in the list.

Syntax

POSITION GetHeadPosition(void);

Return Value

Returns a POSITION value, or NULL if the list is empty.

CGenericList::GetNext

CGenericList Class

Retrieves the item at the specified position, and advances the position.

Syntax

OBJECT *GetNext(
    POSITION& rp
);

Parameters

rp
Reference to a POSITION value.

Return Value

Returns a pointer to an object of type OBJECT (the template type).

Remarks

This method advances the position indicator to the next position. If the position indicator moves past the end of the list, the method sets it to NULL.

If rp is NULL, the method returns NULL.

CGenericList::GetTailPosition

CGenericList Class

Retrieves the position of the last item of the list.

Syntax

POSITION GetTailPosition(void);

Return Value

Returns a POSITION value, or NULL if the list is empty.

CGenericList::Remove

CGenericList Class

Removes the item at the specified position.

Syntax

OBJECT *Remove(
    POSITION pos
    );

Parameters

pos
POSITION value indicating the item to remove.

Return Value

Returns a pointer to an object of type OBJECT (the template type).

Remarks

This method deletes the node from the list, but does not delete the item contained in that node.

If pos is NULL, the method returns NULL.

CGenericList::RemoveHead

CGenericList Class

Removes the first item in the list.

Syntax

OBJECT *RemoveHead(void);

Return Value

Returns a pointer to an object of type OBJECT (the template type), or NULL if the list is empty.

Remarks

This method deletes the list node, but not the item that the node contains.

CGenericList::RemoveTail

CGenericList Class

Removes the last item in the list.

Syntax

OBJECT *RemoveTail(void);

Return Value

Returns a pointer to an object of type OBJECT (the template type), or NULL if the list is empty.

Remarks

This method deletes the list node, but not the item that is contained in the node.