/*

* Copyright (c) 2006 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:  Iterator class for traversing the tree structure.

*

*/

#ifndef T_AKNTREEITERATOR_H

#define T_AKNTREEITERATOR_H

#include <e32def.h>

class CAknTreeItem;

class CAknTreeNode;

/**  Flag indicating that the content of collapsed nodes is not to be

     included in the iteration sequence. */

const TUint KAknSkipCollapsedNodeContents = 0x01;

/**

 *  Iterator class for traversing a tree structure.

 *

 *  The @c CAknTree class is responsible for constructing the iterators for

 *  tree instances. The @c CAknTree::Iterator() method can be used in

 *  retrieving an iterator for the expanded tree structure, or 

 *  @c CAknTree::Iterator( CAknTreeNode*, TUint ) method can be used in

 *  retrieving iterator with specified properties for some specified node.

 *

 *  Each iterator instance stores the root node which is being iterated,

 *  item denoting the current position in the iteration sequence, and flags

 *  affecting the iteration.

 *

 *  @lib aknhlist.lib

 *  @since S60 v3.2

 */

NONSHARABLE_CLASS( TAknTreeIterator )

    {

    friend class CAknTree;

public:

    /**

     * Copy constructor.

     *

     * @param aIterator Copied iterator.

     */

    TAknTreeIterator( const TAknTreeIterator& aIterator );

    /**

     * Returns whether the iterator has next tree item.

     *

     * @return @c ETrue, if there is a next item.

     */

    TBool HasNext() const;

    /**

     * Returns a pointer to the next tree item. The returned value is @c NULL,

     * when there is no more items. This changes also the iterator to point

     * to the returned item.

     *

     * @return Pointer to the next tree item.

     */

    CAknTreeItem* Next();

    /**

     * Returns whether the iterator has previous tree item.

     *

     * @return @c ETrue, if there is a previous item.

     */

    TBool HasPrevious() const;

    /**

     * Returns a pointer to the previous tree item. The returned value is

     * @c NULL, if there is no previous tree item. This changes also the

     * iterator to point to the returned item. 

     *

     * @return Pointer to the previous tree item.

     */

    CAknTreeItem* Previous();

    /**

     * Return pointer to the first item in the sequence.

     *

     * @return First item.

     */

    CAknTreeItem* First() const;

    /**

     * Returns pointer to the las item in the sequence.

     *

     * @return Last item.

     */ 

    CAknTreeItem* Last() const;

    /**

     * Changes the position of the iterator.

     *

     * Note: This method does not check that the specified position is

     * included in the iterated subtree.

     *

     * @param aCurrent Pointer to the new position of the iterator.

     */

    void SetCurrent( CAknTreeItem* aCurrent );

private:

    /**

     * Default C++ constructor.

     *

     * @param aRoot Root node for the iterated tree (or subtree).

     */

    TAknTreeIterator( CAknTreeNode* aRoot, TUint aFlags );

    /**

     * Assignment operator.

     *

     * @param aIterator Iterator.

     */

    TAknTreeIterator& operator=( const TAknTreeIterator& aIterator );

    /**

     * Returns pointer to the next tree item.

     *

     * @return Pointer to the next tree item. @c NULL, if the next item is not

     *      found.

     */

    CAknTreeItem* FindNext() const;

    /**

     * Returns pointer ot the previous tree item.

     *

     * @return Pointer to the previous tree item. @c NULL, if previous item is

     *      not found.

     */

    CAknTreeItem* FindPrevious() const;

private: // data

    /**

     * Current item.

     */

    CAknTreeItem* iCurrent;

    /**

     * Root of the tree (or subtree).

     */

    CAknTreeNode* iRoot;

    /**

     * Next item. Contains a pointer to the cached next item.

     */

    mutable CAknTreeItem* iNext;

    /**

     * Previous item. Contains a pointer to the cached previous item.

     */

    mutable CAknTreeItem* iPrevious;

    /**

     * Flags for the iterator.

     */

    mutable TUint iFlags;

    };

#endif // T_AKNTREEITERATOR_H