/*

 * 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__