![[Index]](../../../../_stock/btn_index_wt.gif){kind=small}
![[Spacer]](../../../../_stock/btn_spacer.gif){kind=small}
![[Previous]](../../../../_stock/btn_prev_wt.gif){kind=small}
![[Next]](../../../../_stock/btn_next_wt.gif){kind=small}
|
|
| ||
|
|
|||
Location:
MQikListBoxModel.h
Link against: qiklbx.lib
class MQikListBoxModel;
Base class for listbox data model classes.
The inherited class is responsible for calling ReportModelEventL to notify the observer (i.e. CQikListBox when items are inserted, removed, swapped, updated, etc). There can only be at most one observer per model.
Make sure that you always report EQikListBoxModelBeginUpdate before any data is updated and EQikListBoxModelEndUpdate after the data has been updated. It is ok to make several updates in a row and then send the EQikListBoxModelEndUpdate message. If you don't have access to the inside of a model, one can always call ModelBeginUpdateLC() and ModelEndUpdateL() instead. It simply sends the message.
All MQikListBoxData that is returned from the model should be Open() before it is returned, and when the data is no longer used it needs to be Close() and then the pointer discarded. The data is reference counted. The model needs to keep all of its data objects opened since it has pointers to them. In case of a caching model, it needs to send a data updated message if it removes an item from the cache, so any item left in the listbox is set to dirty and requests fresh data if it is used again. Otherwise you will end up with one data object for the item (which you can not access) and another data object in your model.
Simple example use of the model (Remove etc are similar):
void CExample::PopulateListboxL()
{
MQikListBoxModel& model = iListBox->Model();
model.ModelBeginUpdateLC();
TRAPD(error, AddAllFooL(model));
if(error == KErrNone)
{
// Tell the model we are done. Do not do anything not related to the
// model between the Begin and End call, as the listbox is considered to be in a
// volatile state between ModelBeginUpdateLC and the ModelEndUpdateL call.
model.ModelEndUpdateL();
}
else
{
// We failed, need to do some form of cleaning / error handling.
model.ModelEndUpdateL();
model.RemoveAllDataL();
}
}
void CExample::AddAllFooL(MQikListBoxModel& aModel)
{
const TInt count = iExampleList.Count();
for(TInt i=0; i<count; i++)
{
AddFooL(aModel, iExampleList[i]);
}
}
void CExample::AddFooL(MQikListBoxModel& aModel, const CYourSpecialData* aData)
{
// Get a new data item (Open() and owned by the model), it is Open() again
// before returned, so your MQikListBoxData pointer is Open() and needs to
// be Close(). Only Open() pointers should be operated upon. Discard after
// Close().
MQikListBoxData* data = aModel.NewDataL(MQikListBoxModel::EDataNormal);
// Must make sure the data is closed if AddTextL leaves.
CleanupClosePushL(*data);
// Add some text to this data item.
data->AddTextL(aData->YourText(), EYourSlot);
data->AddTextL(aData->AnotherText(), EAnotherSlot);
// We are done with the data, close it.
CleanupStack::PopAndDestroy(data);
}
Remember that RetrieveDataL does an Open() on the data before returning it, so one has to make a Close(). Also remember to push the data object on the stack properly with CleanupClosePushL and ending it with a CleanupStack::PopAndDestroy.
Remember to report EQikListBoxDataUpdated with the index of the updated data after you have updated an existing data item. This can also be done by calling DataUpdatedL, which simply sends the message.
Defined in MQikListBoxModel:
Count(), DataUpdatedL(), EDataNormal, EDataSeparator, EDataUnselectable, FindMatchIndexL(), ItemIdIndex(), MQikListBoxModel(), MQikListBoxModelDataType, ModelBeginUpdateLC(), ModelEndUpdateL(), NewDataL(), NewDataL(), NewDataLC(), NewDataLC(), ReleaseModel(), RemoveAllDataL(), RemoveDataL(), ReportModelEventL(), RetrieveDataL(), SetModelObserver(), Sort()
|
virtual void ReleaseModel()=0;
Called when the listbox does not need the model any longer. The listbox considers the model dead after this, and the model is responsible for cleaning itself up.
virtual IMPORT_C void DataUpdatedL(TInt aIndex);
Call when you have updated the data of the model from outside a model.
Use ReportModelEventL when updating data from within a model.
|
virtual IMPORT_C void ModelBeginUpdateLC();
Call before updating the model, for example inserting, removing, sorting, or updating data (<see-also>DataUpdated()</see-also>).
ModelBeginUpdateLC calls can not be nestled, each call must be ended with a call to ModelEndUpdateL . These calls must be balanced. A EQikListBoxPanicModelUpdatedNotCalledAfterChangingData panic typically indicates a second call to ModelBeginUpdateLC has been made when a ModelEndUpdateL call was expected.
Use ReportModelEventL when updating data from within a model.
virtual IMPORT_C void ModelEndUpdateL();
Call after updating the model, for example inserting, removing, sorting, or updating data (<see-also>DataUpdated()</see-also>).
Use ReportModelEventL when updating data from within a model.
IMPORT_C void SetModelObserver(MQikListBoxModelObserver *aObserver);
Sets the model observer. This is exclusively used by CQikListBox .
|
virtual TInt Count() const=0;
Returns the number of elements in the data model. It is recomended that the count is cached if getting the real data storage count is time consuming, since this method is frequently called from within CQikListBox .
|
virtual MQikListBoxData *NewDataL(MQikListBoxModelDataType aDataType)=0;
Creates a new data object.
OBS. The data returned is Open(). When done using the data you must call Close() and after that you can not continue to use that data object.
|
|
virtual MQikListBoxData *NewDataL(MQikListBoxModelDataType aDataType, TInt aItemIndex)=0;
Creates a new data object at an index.
OBS. The data returned is Open(). When done using the data you must call Close() and after that you can not continue to use that data object.
|
|
virtual MQikListBoxData *NewDataLC(MQikListBoxModelDataType aDataType)=0;
Creates a new data object.
OBS. The data returned is Open() and put on the stack. When done using the data it must be Close() and it's done by calling CleanupStack::PopAndDestroy().
|
|
virtual MQikListBoxData *NewDataLC(MQikListBoxModelDataType aDataType, TInt aItemIndex)=0;
Creates a new data object at an index.
OBS. The data returned is Open() and put on the stack. When done using the data it must be Close() and it's done by calling CleanupStack::PopAndDestroy().
|
|
virtual MQikListBoxData *RetrieveDataL(TInt aItemIndex)=0;
Called when the listbox needs more data for the view. The model always owns the data, but can supply the data in two ways: 1) All data are instantiated by the model at construction time and occupies memoryspace. The returned data object is simply a pointer into that memory space. Small lists are most suited for this kind of data handling. Use MQikListBoxData::Open() on the data object before it is returned. 2) Only a small fraction of the data is kept in memory at the same time (i.e. using a cache) and new data needs to be loaded/constructed and old data deleted. It is the responsibility of the model to keep track of the data items and make sure they are cleared from the cache when neccesary. To see if an object is currently in use outside the model, use the reference counting functionality of the MQikListBoxData class. Use MQikListBoxData::Open() on the data object before it is returned and use MQikListBoxData::ReferenceCount() on the data objects in the cache to see if they can be removed.
|
|
virtual void RemoveDataL(TInt aItemIndex)=0;
Removes an item from the model and deletes the item data. The model is responsible for notifying the observer about items that are being removed. The base class implementation is empty and needs to be overridden by a subclass if support for data removal is wanted.
|
virtual void RemoveAllDataL()=0;
Removes all items from the model and deletes the item's data. The model is responsible for notifying the observer about items that are being removed.
The remove all call needs to report a EQikListBoxModelBeginUpdate, a EQikListBoxAllDataRemoved, and a EQikListBoxModelEndUpdate event.
virtual void Sort(TLinearOrder< MQikListBoxData > aOrder)=0;
Sorts the items in the model. The model is responsible for notifying the observer about items that are being swapped.
|
virtual TInt FindMatchIndexL(const TDesC &aMatchBuffer, TInt aStartIndex, TInt aIncrementalMatchSlot) const=0;
Called by listbox view when incremental matching is enabled and needs to match a string in the list. The base class implementation is empty and needs to be overridden by a subclass if support for incremental matching is wanted.
The function shall start searching for a match starting on, and including, aStartIndex (i.e. if aStartIndex itself matches then aStartIndex should be returned). The routine shall search from aStartIndex to the end of the list, then wrap to search from the very first item down to aStartIndex.
|
|
virtual TInt ItemIdIndex(TInt aItemId) const=0;
Returns the index of the data with a certain item id.
|
|
protected: IMPORT_C void ReportModelEventL(MQikListBoxModelObserver::TModelEvent aEvent, TInt aItemIndex, TInt aItemSecond);
Method for reporting model events to the observer.
|
|
MQikListBoxModelDataType
Used to give the item representing a data object certain characteristics.
|
|
© Copyright Symbian Software Ltd 2006. All rights reserved. UIQ 3 SDK 9 May 2006 |
|
![[Top]](../../../../_stock/arrow_up_2.gif){kind=icon}
![[Previous]](../../../../_stock/btn_prev.gif){kind=small}
![[Top]](../../../../_stock/btn_top.gif)
![[Next]](../../../../_stock/btn_next.gif){kind=small}