/*
* Copyright (c) 2002-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:  Uses notification framework to show a global list query.
*
*/

#ifndef __AKNGLOBALLISTQUERY_H__
#define __AKNGLOBALLISTQUERY_H__

#include <AknNotify.h>
#include <AknNotifyStd.h>
#include <bamdesca.h>

class CAknSDData;

// Default index for list query
const TInt KGlobalListQueryDefaultIndex = 0;

_LIT( KGlobalListQueryItemSeparator, "\n");

/**
* CAknGlobalListQuery
*   Uses notification framework to show a global list query.
*   Usage:
*       Create an active object, start it and pass its TRequestStatus as a
*       parameter to ShowListQueryL. After the user selects one item from
*       the list query, the request status will hold the number of the
*       selected item. If the user selected Cancel, the request status will
*       hold -1.
*
*   Example 1. Show the global list query:
*        CDesCArray* textArray = iCoeEnv->ReadDesCArrayResourceL( R_GLOBAL_LIST_ARRAY );
*        CleanupStack::PushL(textArray);
*        TInt result = -555;
*        if ( iListObserver )
*            {
*            iListObserver->Cancel();
*            delete iListObserver;
*            }
*        iListObserver = new(ELeave) CGlobalListObserver(iEikonEnv);
*        iListObserver->Start();
*        iGlobalListQuery->ShowListQueryL(textArray, iListObserver->iStatus, 4);
*        CleanupStack::PopAndDestroy(); // textArray
*
*   Example 2. Get and handle the result in active object.
*        void CMyActiveObject::RunL() 
*            {
*            TBuf<120> msg = _L("Received: ");
*            msg.AppendNum( iStatus.Int() );
*            iEnv->InfoMsg(msg);
*            Cancel();
*            }
*/
NONSHARABLE_CLASS(CAknGlobalListQuery) : public CBase
    {
    public:
        /**
        * Two-phased constructor.
        */
        IMPORT_C static CAknGlobalListQuery* NewL();

        /**
        * Two-phased constructor. Leaves the instance to cleanupstack
        */
        IMPORT_C static CAknGlobalListQuery* NewLC();

        /**
        * Destructor
        */
        IMPORT_C ~CAknGlobalListQuery();

        /**
        * Shows global list query synchronously.
        *
        * @param    aItems  Strings for items
        * @param    aStatus TRequestStatus which will be completed when user
        *                   selects one item from the list query.
        * @param    aIndex  Index which item in the list will be highlighted 
        */
        IMPORT_C void ShowListQueryL( 
            const MDesCArray* aItems,
            TRequestStatus& aStatus,
            const TInt aIndex = KGlobalListQueryDefaultIndex);

        /**
        * Move selection up.
        */
        IMPORT_C void MoveSelectionUp();

        /**
        * Move selection down.
        */
        IMPORT_C void MoveSelectionDown();

        /**
        * Select currently selected item in the list.
        */
        IMPORT_C void SelectItem();

        /**
        * Cancel the list query.
        */
        IMPORT_C void CancelListQuery();

        /**
        * Sets the heading for the query. In order to have effect, the heading must be set before 
        * calling ShowListQueryL.
        *
        * @param    aHeading  Heading string.
        * @since 2.1
        */
        IMPORT_C void SetHeadingL(const TDesC& aHeading);

        /**
        * Sets additional information to be sent to secondary display. Takes ownership of object.
        * Must be called before sending data to notifier to have effect.
        *
        * @param aData Data to be sent to cover UI.
        * @internal to S60
        * @since S60 3.1
        */
        IMPORT_C void SetSecondaryDisplayData(CAknSDData* aData);
        
    private:
        /**
        * Updates list query.
        */
        IMPORT_C void UpdateListQuery();

    private:
        /**
        * Default constructor.
        */
        CAknGlobalListQuery();

        /**
        * EPOC constructor.
        */
        void ConstructL(); 

    private:
        // Command id.
        TAknGlobalQueryCmd iCmd;
        // Notifier handle.
        RNotifier iNotify;
        // Index to set which item will be selected.
        TInt iIndex;
        // Buffer to hold the variables passed to server.
        CBufFlat *iBuffer;
        // Pointer to buffer.
        TPtrC8 iBufferPtr;
        HBufC* iHeading;
        CAknSDData* iAknSDData;
        TBuf8<1> iResultBuf; // Not really used, but needed to prevent buffer handling errors.
    };

#endif // __AKNGLOBALLISTQUERY_H__