/*

 * Copyright (c) 2002-2009 Nokia Corporation and/or its subsidiary(-ies). 

 * All rights reserved.

 * This component and the accompanying materials are made available

 * under the terms of "Eclipse Public License v1.0"

 * which accompanies this distribution, and is available

 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

 *

 * Initial Contributors:

 * Nokia Corporation - initial contribution.

 *

 * Contributors:

 *

 * Description: 

 *

 */

 #ifndef MCLFSORTINGSTYLE_H

 #define MCLFSORTINGSTYLE_H

 //  INCLUDES

 #include <CLFContentListing.hrh>

 #include <CLFContentListing.h>

 #include <e32std.h>

 // FORWARD DECLARATIONS

 class MCLFSortingStyleExt;

 // CLASS DECLARATION

 /**

 *  Sorting style for Content Listing Framework.

 *  This class can be used to define primary and secondary sorting styles for

 *  Content Listing Framework list model. Sorting styles are used to sort the

 *  list model.<br><br>

 *  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.

 *  <br><br>

 *  Usage:

 *  @code

 *  // Create a sorting style instance

 *  MCLFSortingStyle* sortingStyle = ContentListingFactory::NewSortingStyleLC();

 *

 *  // Set sort ordering

 *  sortingStyle->SetOrdering( ECLFOrderingDescending );

 *

 *  // Set undefied item position. Undefined items are items that doesn't

 *  // have field that is defined in sorting style fields

 *  sortingStyle->SetUndefinedItemPosition( ECLFSortingStyleUndefinedEnd );

 *

 *  // All sorting style parameter fields are string type

 *  sortingStyle->SetSortingDataType( ECLFItemDataTypeDesC );

 *

 *  // Set default sorting parameter

 *  sortingStyle->AddFieldL( ECLFFieldIdSongName );

 *

 *  // Set secondary sorting parameter

 *  sortingStyle->AddFieldL( ECLFFieldIdFileName );

 *

 *  // If item doesn't have ECLFFieldIdSongName field then

 *  // ECLFFieldIdFileName field is used to sort item.

 *  @endcode

 *

 *  @lib ContentListingFramework.lib

 *  @since S60 3.1

 */

 class MCLFSortingStyle

     {

     public:  // Destructor

         /**

         * Destructor.

         */

         virtual ~MCLFSortingStyle() {}

     public: // New functions

         /**

         * Reset settings of the sorting style to default.

         * @since S60 3.1

         */

         virtual void ResetL() = 0;

         /**

         * Set sort ordering. Ordering can be ascending or descending. See

         * TCLFSortingStyleOrdering

         * @since S60 3.1

         * @param aOrdering Sort ordering to be set

         */

         virtual void SetOrdering( TCLFSortingStyleOrdering aOrdering ) = 0;

         /**

         * Get current sort ordering of the sorting style.

         * @since S60 3.1

         * @return Current sort ordering

         */

         virtual TCLFSortingStyleOrdering Ordering() const = 0;

         /**

         * Set data type of sorting parameter fields. Data type can be text,

         * time or number. See TCLFItemDataType

         * @since S60 3.1

         * @param aDataType Data type to be set

         */

         virtual void SetSortingDataType( TCLFItemDataType aDataType ) = 0;

         /**

         * Get current sorting data type of fields.

         * @since S60 3.1

         * @return Current data type sorting of sorting fields

         */

         virtual TCLFItemDataType SortingDataType() const = 0;

         /**

         * Set undefined item position. Items not having information for defined

         * sorting parameter fields are placed to top or bottom of the model. See

         * TCLFUndefinedItemPosition

         * @since S60 3.1

         * @param aUndefinedItemPosition Position for undefiened items

         */

         virtual void SetUndefinedItemPosition(

                     TCLFUndefinedItemPosition aUndefinedItemPosition ) = 0;

         /**

         * Get current position of undefined items.

         * @since S60 3.1

         * @return Current position for undefined items

         */

         virtual TCLFUndefinedItemPosition UndefinedItemPosition() const = 0;

         /**

         * Add new field to the sorting style. First added field will be the

         * default field. Remember to set type of field(s) with

         * SetSortingDataType. Fields that are some other type will be ignored.

         * See TCLFDefaultFieldId in CLFContentListing.hrh

         * @since S60 3.1

         * @param aFieldId Id of the sorting parameter field

         */

         virtual void AddFieldL( TCLFFieldId aFieldId ) = 0;

         /**

         * Get IDs of fields that have been set to the sorting style.

         * @since S60 3.1

         * @param aArray Array of field IDs

         */

         virtual void GetFieldsL( RArray<TCLFFieldId>& aArray ) const = 0;

     private: // Extension interface

         virtual MCLFSortingStyleExt* Extension() { return NULL; }

     };

 #endif      // MCLFSORTINGSTYLE_H

 // End of File