/*

* 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 settings array class.

*

*/

#ifndef IPSSETUIARRAY_H

#define IPSSETUIARRAY_H

#include <barsread.h>       // TResourceReader

#include <bamdesca.h>                // MDesCArray

#include <eikenv.h>

#include "ipssetuifinderinterface.h"

/**

 * Stack states.

 */

enum TIpsSetUiStackResult

    {

    EIpsSetUiStackResultOk,

    EIpsSetUiStackResultSubMenuOpen,

    EIpsSetUiStackResultInvalid

    };

typedef RArray<TInt> RResourceStack;

class CIpsSetUiItem;

class CIpsSetUiFinder;

class CIpsSetUiItemLink;

class CIpsSetUiItemLinkExt;

/**

 * Defines settings array behavior.

 *

 * @lib IpsSosSettings.lib

 * @since FS v1.0

 */

class CIpsSetUiBaseArray :

    public CBase,

    public MDesCArray,

    public MIpsSetUiFinder

    {

public: // Constructors and destructor

    /**

     * Destructor.

     */

    virtual ~CIpsSetUiBaseArray();

public: // New functions

    /**

     * Forces the redraw

     */

    void Refresh();

    /**

     * Sets the setting text inside the item.

     *

     * @param aBaseItem Item for modification.

     * @param aText Text to be stored.

     * @param Force update of the view.

     */

    void SetItemText(

        CIpsSetUiItem& aBaseItem,

        const TDesC& aText,

        const TBool aUpdate = EFalse );

    /**

     * Retrieves the setting text inside the item.

     *

     * @param aBaseItem Item which contains the text.

     */

    const TDesC& ItemText(

        CIpsSetUiItem& aBaseItem );

    /**

     * Goes forward in resoruce stack.

     *

     * @param aBase Item which has been opened.

     * @return Status of the operation.

     */

    TIpsSetUiStackResult HandleStackForwardL( const CIpsSetUiItem& aBase );

    /**

     * Goes backward in resource stack.

     *

     * @param aCount Number of submenus to be moved.

     * @return Status of the operation.

     */

    TIpsSetUiStackResult HandleStackBackwardL( TInt aCount = 1 );

    /**

     * Event invoked by stack change.

     *

     * @param aForward Submenu item has opened.

     * @param aResourceId Resource ID of the item that caused the action.

     * @return Status of the operation.

     */

    TIpsSetUiStackResult HandleStackChangeL(

        const TInt aForward,

        const TInt aResourceId = KErrNotFound );

    /**

     * Checks if item is hidden

     *

     * @param aIndex index of the item

     * @return KErrNone, if item is visible

     * @return KErrNotFound, if item is hidden

     * @return KErrNotSupported, if item is permanently hidden

     */

    TInt IsHidden( const TInt aIndex ) const;

    /**

     * Checks if item is hidden

     *

     * @param aId id of the item

     * @return KErrNone, if item is visible

     * @return KErrNotFound, if item is hidden

     * @return KErrNotSupported, if item is permanently hidden

     */

    TInt IsHidden( const TUid& iId ) const;

    /**

     * Checks if item is hidden

     *

     * @param aItem the item

     * @return KErrNone, if item is visible

     * @return KErrNotFound, if item is hidden

     * @return KErrNotSupported, if item is permanently hidden

     */

    virtual TInt IsHidden( const CIpsSetUiItem& aItem ) const;

    /**

     * Hides the provided item.

     *

     * @param aHide Hide/Unhide.

     * @param aId Id of the item to be modified.

     * @param aUpdate Refresh the UI.

     */

    void SetHideItem(

        const TBool aHide,

        const TUid& aId,

        const TBool aUpdate = EFalse );

    /**

     * Hides the provided item.

     *

     * @param aHide Hide/Unhide.

     * @param aItem Item to be modified.

     * @param aUpdate Refresh the UI.

     */

    void SetHideItem(

        const TBool aHide,

        CIpsSetUiItem& aItem,

        const TBool aUpdate = EFalse );

    /**

     * Find the item from the tree structure.

     *

     * @param aId Unique ID of the item.

     * @param aExcludeHidden Skip all hidden item.

     */

    CIpsSetUiItem* GetItem(

        const TUid& aId,

        const TBool aExcludeHidden = ETrue ) const;

    /**

     * Find the item from the tree structure.

     *

     * @param Index of the item in resource.

     * @param aExcludeHidden Skip all hidden item.

     */

    CIpsSetUiItem* GetItem(

        const TInt aIndex,

        const TBool aExcludeHidden = ETrue ) const;

protected:  // Constructors

    /**

     *  Constructor.

     */

    CIpsSetUiBaseArray();

    /**

     * 2nd phase of construction.

     */

    void BaseConstructL();

    /**

     * 2nd phase of construction.

     *

     * @param aResourceId Tree root resource.

     */

    void BaseConstructL( const TInt aResourceId );

protected:  // Data

    /**

     * Events invoked by array changes.

     */

    enum TIpsSetUiArrayEvent

        {

        EIpsSetUiArrayAdded = 0,

        EIpsSetUiArrayRemoved,

        EIpsSetUiArrayChanged,

        EIpsSetUiArrayStackForward,

        EIpsSetUiArrayStackBackward

        };

// New virtual functions

    /**

     * Initializes the data in the item.

     *

     * @param aBaseItem Item to be initialized.

     */

    virtual void InitUserData( CIpsSetUiItem& aBaseItem ) = 0;

    /**

     * Handler for array change events.

     *

     * @param aEvent The invoked event.

     * @return KErrNone, when ok.

     */

    virtual TInt EventArrayChangedL(

        const TIpsSetUiArrayEvent aEvent ) = 0;

    /**

     * Custom drawing operation for items.

     *

     * @param aId Unique Id of the item to be drawn.

     * @param aString String to be constructed.

     * @return ETrue, when handled.

     */

    virtual TBool EventCustomMdcaPoint(

        const TUid& aId,

        TPtr& aString ) const = 0;

    /**

     * Creates array of items.

     *

     * @param aId Unique Id of the item to be drawn.

     * @return Created item with client ownership.

     */

    virtual CIpsSetUiItem* CreateCustomItemToArrayLC(

        const TUid& aId );

    /**

     * Fills the label text to item.

     *

     * @param aBaseItem Item which contains the label.

     * @param aText Return parameter for the label.

     */

    virtual void ListboxItemFillMultiLineLabel(

        const CIpsSetUiItem& aBaseItem,

        TIpsSetUtilsTextPlain& aText ) const;

    /**

     * Fills the label text to item.

     *

     * @param aBaseItem Item which contains the label.

     * @param aText Return parameter for the label.

     */

    virtual void ListboxItemFillEditTextLabel(

        const CIpsSetUiItem& aBaseItem,

        TIpsSetUtilsTextPlain& aText ) const;

    /**

     * Fills the label text to item.

     *

     * @param aBaseItem Item which contains the label.

     * @param aText Return parameter for the label.

     */

    virtual void ListboxItemFillEditValueLabel(

        const CIpsSetUiItem& aBaseItem,

        TIpsSetUtilsTextPlain& aText ) const;

    /**

     * Fills the label text to item.

     *

     * @param aBaseItem Item which contains the label.

     * @param aText Return parameter for the label.

     */

    virtual void ListboxItemFillEditTimeLabel(

        const CIpsSetUiItem& aBaseItem,

        TIpsSetUtilsTextPlain& aText ) const;

    /**

     * Fills the label text to item.

     *

     * @param aBaseItem Item which contains the label.

     * @param aText Return parameter for the label.

     */

    virtual void ListboxUndefinedFillLabel(

        const CIpsSetUiItem& aBaseItem,

        TIpsSetUtilsTextPlain& aText ) const;

    /**

     * Fills the label text to item.

     *

     * @param aBaseItem Item which contains the label.

     * @param aText Return parameter for the label.

     */

    virtual void ListboxRadioButtonFillArrayLabel(

        const CIpsSetUiItem& aBaseItem,

        TIpsSetUtilsTextPlain& aText ) const;

    /**

     * Fills the label text to item.

     *

     * @param aBaseItem Item which contains the label.

     * @param aText Return parameter for the label.

     */

    virtual void ListboxCheckboxFillArrayLabel(

        const CIpsSetUiItem& aBaseItem,

        TIpsSetUtilsTextPlain& aText ) const;

// New functions

    /**

     * Locates the item behind the provided item.

     *

     * @param aBaseItem Item which contains the array of items.

     * @param aId Unique Id to be searched.

     * @param aExcludeHidden Skip hidden items.

     * @return Located item.

     */

    CIpsSetUiItem* GetSubItem(

        const CIpsSetUiItem& aBaseItem,

        const TUid& aId,

        const TBool aExcludeHidden = ETrue ) const;

    /**

     * Locates the item behind the provided item.

     *

     * @param aBaseItem Item which contains the array of items.

     * @param aIndex Index of the item in array.

     * @param aExcludeHidden Skip hidden items.

     * @return Located item.

     */

    CIpsSetUiItem* GetSubItem(

        const CIpsSetUiItem& aBaseItem,

        const TInt aIndex,

        const TBool aExcludeHidden = ETrue ) const;

    /**

     * Locates item of specific subtype from array.

     *

     * @param aBaseItem Item which contains the array of items.

     * @param aType Type of the item to be searched.

     * @return Located item.

     */

    CIpsSetUiItem* GetSubItemByType(

        const CIpsSetUiItem& aBaseItem,

        const TInt aType ) const;

    /**

     * Gets the index of the item in the array.

     *

     * @param aLinkItem Item which contains the array.

     * @param aId Unique Id to be searched.

     * @param aExcludeHidden Skip hidden items.

     * @return Index of the item.

     */

    TInt GetSubItemIndex(

        const CIpsSetUiItemLink& aLinkItem,

        const TUid& aId,

        const TBool aExcludeHidden = ETrue ) const;

    /**

     * Gets the index of the item in the array.

     *

     * @param aLinkItem Item which contains the array.

     * @param aIndex Index of the item in array.

     * @param aActualIndex

     *    ETrue  : aIndex is from visible list and index

     *             from the actual resource is required

     *    EFalse : aIndex is from resource and visible

     *             index is required

     */

    TInt GetSubItemIndex(

        const CIpsSetUiItemLink& aLinkItem,

        const TInt aIndex,

        const TBool aActualIndex ) const;

    /**

     * Gets all item, which belongs to certain resource.

     *

     * @param aResourceId The certain resource.

     * @param aExcludeHidden Skip hidden items.

     * @return Array of items in certain resource with ownership.

     */

    CIpsSetUiFinderArray* GetResourceL(

        const TInt aResourceId,

        const TBool aExcludeHidden = ETrue ) const;

    /**

     * Gets all item, which belongs to certain resource.

     *

     * @param aResourceId The certain resource.

     * @param aExcludeHidden Skip hidden items.

     * @return Array of items in certain resource with ownership.

     */

    CIpsSetUiFinderArray* GetResourceLC(

        const TInt aResourceId,

        const TInt aExcludeHidden = ETrue ) const;

    /**

     * Index of the item in array.

     *

     * @param aId Unique Id to be searched.

     * @param aExcludeHidden Skip hidden items.

     * @return Index of the item.

     */

    TInt ItemIndex(

        const TUid& aId,

        const TBool aExcludeHidden = ETrue ) const;

    /**

     * Check whether the provided value is between the limits.

     *

     * @param aValue Value to be modified between the limits.

     * @param aMin Minimun value.

     * @param aMax Maximum value.

     */

    void SetBetweenValues(

        TInt& aValue,

        TInt aMin,

        TInt aMax ) const;

    /**

     * Checks if the item contains array of items.

     *

     * @param aBaseItem Item to be check.

     * @return ETrue, when item has submenu.

     */

    TBool ItemSubArrayCheck(

        const CIpsSetUiItem& aBaseItem ) const;

    /**

     * Checks if the item contains array of items.

     *

     * @param aBaseItem Item to be check.

     * @return ETrue, when item has submenu.

     */

    TBool ItemSubItemCheck(

        const CIpsSetUiItem& aBaseItem ) const;

    /**

     * @return Currently active resource.

     */

    TInt StackActiveResource() const;

    /**

     * Check if the item is visible or not.

     *

     * @param aBaseItem Item to be inspected.

     * @param aExcludeHidden To make the check useless.

     * @return ETrue, when item is visible.

     */

    TBool IsVisibleCheck(

        const CIpsSetUiItem& aBaseItem,

        const TBool aExcludeHidden ) const;

// Functions from base classes

    /**

     * @return Number of items in array

     */

    TInt MdcaCount() const;

// From MIpsSetUiFinder

    /**

     * Handle error in search.

     *

     * @return ETrue, Search can continue.

     */

    virtual TBool SearchDoError();

    /**

     * Check if the search criterias have been filled.

     *

     * @param aItem Item to be checked.

     * @param aIndex Index of the item.

     * @return ETrue, when search should continue.

     */

    virtual TBool SearchDoContinuationCheck(

        const CIpsSetUiItem& aItem,

        const TInt aIndex );

    /**

     * Checks if the item is the one we are searching for.

     *

     * @param aItem to be checked.

     * @return ETrue, Our precious.

     */

    virtual TBool SearchDoItemCheck(

        CIpsSetUiItem& aItem );

    TInt GetLastResourceId( );

private:  // New functions

    /**

     * Clear array of items.

     */

    void CleanArrayItems();

    /**

     * Load array of items from the specific resource.

     *

     * @param aResourceId specific resource.