General idea of Content Listing Framework API usage is described here. An application developer can use Content Listing Framework API according to these steps. More detailed real world programming examples of the API can be found from the sample application – CLF Example – source code.
CMyOperationObserver) is derived from the MCLFOperationObserver:CMyOperationObserver* observer = CMyOperationObserver::NewLC();
MCLFContentListingEngine* engine =
ContentListingFactory::NewContentListingEngineLC();
MCLFItemListModel* model = engine->CreateListModelLC( *observer );
RArrayarray;<TCLFMediaType> CleanupClosePushL( array ); array.AppendL( ECLFMediaTypeMusic ); model->SetWantedMediaTypesL( array.Array() ); CleanupStack::PopAndDestroy( &array )
model->RefreshL();
TInt count( model->ItemCount() );
for( Tint i( 0 ); i < count; ++i )
{
const MCLFItem& myItem = model->Item( i );
TPtrC songName;
TInt errorSong( myItem.GetField( ECLFFieldIdSongName,
songName ) );
TPtrC songArtist;
TInt errorArtist( myItem.GetField( ECLFFieldIdArtist,
songArtist ) );
// Do something with song and artist names
}
When using Content Listing Framework, first step is to create a Content
Listing Engine by using ContentListingFactory::NewContentListingEngineLC.
At least one List Model must be created to list media content. The creation
is done by CreateListModelLC method of Content Listing Engine.
For example, if an application lists music files and images it would be a
good idea to create separate list models for music files and images. Media
types that will be requested to the List Model are defined by wanted media
types array and/or wanted mime types array.
Below is an example of initialization process that must be done before using CLF. After these steps, content listing operations can be used.
// CMyOperationObserver is derived from MCLFOperationObserver
CMyOperationObserver* observer = CMyOperationObserver::NewLC();
MCLFContentListingEngine* engine =
ContentListingFactory::NewContentListingEngineLC();
MCLFItemListModel* model = engine->CreateListModelLC( *observer );
Sorting styles provide basic sorting functionality for the List Model.
Sorting style can be created by using the Content Listing Factory. Parameters
for sorting are added to the created sorting style with MCLFSortingStyle::AddFieldL method.
For example, if you add two fields for sorting, first added field will be
used to sort the item. If the item does not contain information for this first
field, second field will be used to sort the item. After adding sorting parameter
fields, SetSortingDataType method is used to define format
of the sorting parameters.
Sort ordering and undefined items position is set similarly by using corresponding
methods of the sorting style object. Finally, this primary sorting style is
set to the List Model by using SetSortingStyle method of
the List Model object.
MCLFSortingStyle* sortingStyle = ContentListingFactory::NewSortingStyleLC(); sortingStyle->AddFieldL( ECLFFieldIdArtist ); sortingStyle->AddFieldL( ECLFFieldIdAlbum ); sortingStyle->SetSortingDataType( ECLFItemDataTypeDesC ); sortingStyle->SetOrdering( ECLFOrderingAscending ); sortingStyle->SetUndefinedItemPosition( ECLFSortingStyleUndefinedEnd ); model->SetSortingStyle( sortingStyle );
Secondary sorting style is used to sort items that could not be sorted
by the primary sorting style. In other words, items that do not have the field
defined by primary or any previous secondary sorting style, the items are
sorted using the next secondary sorting style. When a secondary sorting style
is appended, it becomes the least significant sorting style until a new one
is added after it. Items with undefined fields are placed before or after
items with defined fields, depending on the undefined field position setting
in MCLFSortingStyle.
Secondary sorting styles are created similarly as the primary sorting style.
After creating a secondary sorting style, it is set to the List Model by using AppendSecondarySortingStyleL method
of the List Model object and the model needs to be refreshed.
MCLFSortingStyle* secSortingStyle =
ContentListingFactory::NewSortingStyleLC();
secSortingStyle->AddFieldL( ECLFFieldIdFileName );
model->AppendSecondarySortingStyleL( *secSortingStyle );
// The RefreshL-method is synchronous when used with a parameter.
// In this case only the model’s sorting is refreshed
model->RefreshL( ECLFRefreshSorting );
It is also possible to create custom sorters. A custom sorter is a class
derived from MCLFCustomSorter. The custom sorter class contains SortItemsL method
(derived from the base class) that receives RPointerArray of MCLFItems as
a parameter. The array contains all items in the List Model. Now it is possible
for the developer to create sorting functionality to sort the array. For example,
the array can be randomized or it can be sorted by item IDs etc. Note that
ownership of sorting styles is not transferred to Content Listing Framework.
Post filter is a tool for filtering List Model. Post filter can, for example,
remove all other items except music files of some specific artist. Post filter
is created by deriving a class from the MCLFPostFilter. Post
filter class contains FilterItemsL method (derived from the
base class) that receives a TArray of MCLFItem pointers
and an RPointerArray of MCLFItems.
The TArray is so called source list of items that contains
all items in the List Model. Now the TArray can be checked
item by item and all wanted ones are added to the RPointerArray.
The RPointerArray is so called destination array. After the
filtering process, the List Model contains only items that were added to the RPointerArray.
Grouping functionality allows List Model to be grouped by some parameter.
For example, a List Model of music files can be grouped by album name and
the model will contain name of each album after the grouping. Grouping is
activated by calling SetGroupingStyle method of the List
Model. Grouping parameter – like grouping by albums – is given as a parameter.
Custom groupers are grouping tools created by a developer. They can group
items by any criteria. Custom grouper class is derived from MCLFCustomGrouper.
The class contains GroupItemsL method (derived from the base
class) that will be called when the grouping process is executed. The method
receives a TArray of MCLFItem pointers as
a source array and an RPointerArray of MCLFItems as
a grouped array.
Custom grouping is done as follows. The source array is checked item by
item. When new group is found, new MCLFModifiableItem is
created and its AddFieldL method is used to give the group
a name. For example, if the custom grouping is done for music files by artist
name, AddFieldL method is given ECLFFieldIdArtist and
name of the artist as parameters. Note that ownership of these modifiable
items is not transferred to the Content Listing Framework!
After creating a custom grouper, it is added to the List Model by using SetCustomGrouper -method
of the List Model object.
Refreshing of the List Model is needed when modification tools have been activated to the model or some items have changed. The refresh operation will execute these modifications and update the model.
MCLFItemListModel::RefreshL without parameters is the
only non-blocking method in the Content Listing Framework API. RefreshL method
should only be used without parameters when it is absolutely necessary. Situation
to use this so called heavy refresh would be, for example, an application
startup. At that time, the List Model is refreshed for the first time and
all items must be retrieved from the server. Completion of this non-blocking
refresh can be monitored with the Operation Observer; the observer will receive
an operation event when the refresh operation is finished.
It is recommended to use the RefreshL method with parameters
(blocking method) when it is not required to refresh the whole List Model
from the server. Parameters of RefreshL method can also be
combined. For example, function call RefreshL( ECLFRefreshSorting
| ECLFRefreshPostFilter ) will refresh the model by using sorter
and post filter that are assigned to the List Model. Now the items are not
retrieved from the server, the model is only re-arranged. Blocking version
of RefreshL method does not generate operation events for
Operation Observer.
Observers in Content Listing Framework are used to observer operation completions and item changes.
Operation Observer is used to monitor the completion of non-blocking RefreshL function
call. An Operation Observer class is derived from the MCLFOperationObserver.
The class will contain HandleOperationEventL method (derived
from the base class) and it is called by Content Listing Framework when the
operation has completed. Type of the operation event is delivered as parameters.
The Operation Observer object is set to List Model when the List Model object
is constructed.
Changed Item Observer monitors items in the file system and reports if
old items are changed or new items are added. A Changed Item Observer is similar
to the Operation Observer. A Changed Item Observer class is derived from the MCLFChangedItemObserver and
it contains HandleItemChangeL method (derived from the base
class) and it is called by Content Listing Framework when there are changed
or new items. After you have renamed or deleted items, ContentListingEngine::UpdateItemsL method
should be called to update the item listing. Note that unnecessary UpdateItemsL calls
should be avoided because it causes load for the system.
Process Observer can be used to monitor starting and stopping of CLF server
update processes. A Process Observer is derived from the MCLFProcessObserver and
it contains HandleCLFProcessEventL method (derived from the
base class) and it is called by the framework when update process starts and
when it stops. Process Observer is activated to Content Listing Engine by
calling MCLFContentListingEngine::AddCLFProcessObserverL and
removed by calling RemoveCLFProcessObserver method.
Content Listing Framework API uses standard Symbian error reporting mechanism. If an unrecoverable error occurs, panics are used. Leaves and system wide error codes as function return values are used if the error is recoverable. A client application can handle these errors similarly as a normal Symbian platform application.
There are some common mistakes that developer can do when using the Content Listing Framework.
Modification tools of List Model
One mistake is to delete modification tool – like sorting style, post filter,
custom grouper etc. – before setting it to NULL to the List Model. For example,
a sorting style is activated, used and deleted. If the model is now refreshed
for some reason, null pointer panic will be raised if MCLFItemListModel::SetSortingStyle(NULL) was
not called when the sorting style object was deleted.
Custom grouper
Another common mistake is to leave memory leaks to a custom grouper. When
creating custom grouper, MCLFModifiableItem pointer must
be created for each group. Despite the modifiable item is added to the grouped
items array, ownership of the pointer is not transferred, so you must take
care of the object deletion. You can not delete the modifiable item right
after adding it to the grouped items array. So, a good way to do the trick
is to create a member RPointerArray containing these same
modifiable items. Now, these items can be deleted with RPointerArray::ResetAndDestroy() in
destructor of the custom grouper class when the items are no longer needed.
Secondary sorting style
Use of secondary sorting style can also leave a memory leak to the client
application. Sorting style is created and added to the model as secondary
sorting style by calling AppendSecondarySortingStyleL method
of the List Model object. However, ownership of secondary sorting style objects
is not transferred to the framework. The secondary sorting style is also in
an active state until the primary sorting style is set to NULL by calling SetSortingStyle(NULL) of
the List Model object. In other words, to avoid null pointer panics, secondary
sorting style objects should be deleted only after calling SetSortingStyle(NULL).
Memory consumption of Content Listing Framework is directly proportional to the number of items that are in the List Model.
The basic functionality for List Model modifications can be extended by
customized tools. It is possible to create customized tools for sorting and
grouping the item list in the model. Customized sorters can be implemented
by creating a class and deriving it from the MCLFCustomSorter.
Custom sorter can be activated by calling SetCustomSorter method
of the List Model. Custom grouper is created similarly. A custom grouper class
is derived from the MCLFCustomGrouper class and it is activated
with SetCustomGrouper method of the List Model.