Developer

API Reference

IVectorModel_InsertAt()

Brew Release
Brew MP 1.0.2
See Also
Model Events ListModelEvent IVectorModel Interface IVectorModel_EnsureCapacity()
Description
This function inserts a new item to a vector model, adding the new item before the item specified in the function call. The item being added to the model is referenced by a pointer to the item's contents, with the pointer (rather that the contents) actually being stored in the vector model.
Parameters
  • po
    []:
    Pointer to the IVectorModel interface object.
  • nIndex
    []:
    Indicates the zero-based index of the item before which the new item will be added. The first item in the model is indexed by 0, the second is indexed by 1, and so on. So, if IVectorModel_InsertAt() is called with nIndex equal to 2, the new item will be inserted at index 2, with items 2, 3, 4, etc all shifting one position higher. If IVectorModel_InsertAt is called with VECTOR_LAST (-1) the new item is isserted at the end of the vector
  • pvItem
    []:
    Pointer to the contents of the item being added to the vector model.
Interface
Prototype
   int IVectorModel_InsertAt(IVectorModel *po, uint32 nIndex, void *pvItem);
Return
   AEE_SUCCESS    - The item was successfully added to the vector model.
   ENOMEMORY  - The vector model was unable to allocate enough memory to accommodate the new item.
Side Effect
Inserting an item in a vector model by calling IVectorModel_InsertAt() will cause BREW to send an EVT_MDL_LIST_CHANGE ListModelEvent to any object that has registered as a listener with the model.
The fields of the ListModelEvent will contain the following information:
       pos:      The index of the item before which the new item was inserted.
       oldSize:  The number of items in the vector model before calling IVectorModel_InsertAt().
       newSize:  The number of items in the vector model after calling IVectorModel_InsertAt().

Comment
The vector model inserts items by first growing the array of item pointers stored in the model by one item, moving the existing items from 'nIndex' to the end of the list in order to make room for the new item, then placing the new pointer ('pvItem') at 'nIndex' in the array.
IVectorModel_InsertAt() will check to see if there is sufficient allocated space already available in the vector model and use that space to store the new item. If space is not available, IVectorModel_InsertAt() will attempt to allocate storage for the new item, and any additional items as previously declared in a call to IVectorModel_EnsureCapacity().
Passing -1 (MAXINT) for 'nIndex' will add the new item to the end of the vector model.
  • Follow