/*
* 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 the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members
* which accompanies this distribution, and is available
* at the URL "http://www.symbianfoundation.org/legal/licencesv10.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