/*
* Copyright (c) 2007 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:  Decleares class for tree structure searching.
*
*/


#ifndef IPSSETUIITEMFINDER_H
#define IPSSETUIITEMFINDER_H

#include <e32base.h>

#include "ipssetuiitembase.h"
#include "ipssetuifinderinterface.h"

class CIpsSetUiItem;


/**
 *  Class to find item(s) from the setting tree
 *
 *  @lib IpsSosSettings.lib
 *  @since FS v1.0
 */
class CIpsSetUiFinder : public CBase
    {
public:

// Constructors and destructor

    /**
     * Destructor
     */
    ~CIpsSetUiFinder();

    /**
     * @param aObserver Observer for search operation.
     * @return New finder object.
     */
    static CIpsSetUiFinder* NewL(
        MIpsSetUiFinder& aObserver );

    /**
     * @param aObserver Observer for search operation.
     * @return New finder object.
     */
    static CIpsSetUiFinder* NewLC(
        MIpsSetUiFinder& aObserver );

// New functions

    /**
     * Set method to member iSearchFlags
     * @param aSearchFlags, Sets value of iSearchFlags
     */
    void SetSearchFlags( const TUint64& aSearchFlags );

    /**
     * Get function for member iSearchFlags
     * @return value of iSearchFlags
     */
    TUint64 SearchFlags() const;

    /**
     *
     * @param aItemArray Array to be searched.
     */
    void StartSearchL(
        CIpsSetUiBaseItemArray& aItemArray,
        const TUid& aId );

    /**
     *
     * @param aItemArray Array to be searched.
     *
     */
    void StartSearchL(
        CIpsSetUiBaseItemArray& aItemArray,
        const TInt aItem );

    /**
     * Get function for member iFinderArray
     * @return value of iFinderArray
     */
    CIpsSetUiFinderArray* FinderArray() const;

    /**
     * Gets the copy of finder array and saves it to stack
     * @return value of iFinderArray
     */
    CIpsSetUiFinderArray* FinderArrayLC() const;

private:

// Constructors

    /**
     * Constructor
     *
     * @param aObserver Observer for search operation.
     */
    CIpsSetUiFinder(
        MIpsSetUiFinder& aObserver );

    /**
     * 2nd phase constructor
     */
    void ConstructL();

// New functions

    /**
     * Prepare for search.
     *
     * @param aNth Start from nth item in the array.
     */
    void InitializeSearchL( const TInt aNth );

    /**
     * Clear all internal data.
     */
    void FinalizeSearchL();

    /**
     * Check, if the search criterias have been met.
     *
     * @param aCurrentItem Index of the current item
     * @param aMaxItems Maximum number of items in the array.
     * @return ETrue, when the search should be continued.
     */
    TBool ContinueSearch(
        const TInt aCurrentItem,
        const TInt aMaxItems );

    /**
     * @return ETrue, when the item fills the search criterias.
     */
    TBool SearchingItem();

    /**
     * Adds new branch to search array.
     */
    void ItemToArrayL();

    /**
     * Item check for ID search algorithm.
     *
     * @param aId Id to be searched
     */
    void ItemCheckL( const TUid& aId );

    /**
     * Item check for index search algorithm.
     */
    void ItemCheckL();

    /**
     * @return ETrue, when item doesn't have container for other items.
     */
    TBool ItemSubArrayCheck();

    /**
     * @return ETrue, when search criterias are not met.
     */
    TBool ContinueSubSearch();

    /**
     * Intelligence to search the ID from the subarrays.
     *
     * @param aId Id to be searched
     */
    void DoIdSearchSubArraysL( const TUid& aId );

    /**
     * Intelligence to search index from the sub arrays.
     */
    void DoIndexSearchSubArraysL();

    /**
     * Stops the search opertion.
     */
    void DoEndSearch();

    /**
     * Main intelligence to search ID from the tree.
     *
     * @param aItemArray Array to be searched.
     * @param aId Id to be searched
     */
    void DoIdSearchL(
        CIpsSetUiBaseItemArray& aItemArray,
        const TUid& aId );

    /**
     * Main intelligence for index search.
     * @param aItemArray Array to be searched.
     */
    void DoIndexSearchL( CIpsSetUiBaseItemArray& aItemArray );

    /**
     * Searches for the item from the array based on the id.
     *
     * @param aItemArray Array, which may contain the item.
     * @param aId Id to be searched
     */
    void SearchIdFromTreeL(
        CIpsSetUiBaseItemArray& aItemArray,
        const TUid& aId );

    /**
     * Searches for the item's index from the given array.
     *
     * @param aItemArray Array to be searched.
     */
    void SearchIndexFromTreeL(
        CIpsSetUiBaseItemArray& aItemArray );

    /**
     * @return ETrue, when item is hidden. Otherwise EFalse.
     */
    TBool IsHidden();

    /**
     * Check wheter searching has met the conditions to finish itself.
     */
    void SearchShouldStop();

public:

// Data

    /** Flags to control finder's search routine. */
    enum TIpsSetUiFinderFlags
        {
        // Following flags are for set up the search

        // When enabled, user defined check is made
        EFinderCustomCheck          = 0x001,
        // Includes subfolders in search
        EFinderSearchSubFolders     = 0x002,
        // Overrides the item spesific tests for one round
        EFinderOverrideChecks       = 0x004,
        // Hidden items will not be included into the search
        EFinderDoHideCheck          = 0x008,
        // Searches for resources instead of item
        EFinderResourceSearch       = 0x010,
        // Goes through whole array regardless of hits
        EFinderSearchAll            = 0x020,
        // Keeps the last search result in memory
        EFinderKeepLastResult       = 0x040,
        // Searches items that doesn't match the set
        EFinderExlusiveSearch       = 0x080,
        // The result tree's ownership is moved to client
        EFinderMoveOwnership        = 0x100,

        // Following flags are mainly for internal use
        EFinderItemFound            = 0x200,
        EFinderItemFindError        = 0x400,
        EFinderExit                 = 0x800
        };

private:

// Data


    /**
     * Observer for search operation.
     */
    MIpsSetUiFinder&        iObserver;

    /**
     * Flags to control the finder
     */
    TUint64                 iSearchFlags;

    /**
     * Container for subarrays.
     * Owned.
     */
    CIpsSetUiBaseItemArray* iSubArrays;

    /**
     * Temporary item storage.
     * Not owned.
     */
    CIpsSetUiItem*          iTempItem;

    /**
     * Starting point as index for search.
     */
    TInt                    iSearchItem;

    /**
     * Current item index, used for passing forward
     */
    TInt                    iCurrentItem;

    /**
     * Container for search results.
     * Owned.
     */
    CIpsSetUiFinderArray*   iFinderArray;
    };

#endif      // IPSSETUIITEMFINDER_H

// End of File