williamr@4: /*
williamr@4: * Copyright (c) 2002-2007 Nokia Corporation and/or its subsidiary(-ies).
williamr@4: * All rights reserved.
williamr@4: * This component and the accompanying materials are made available
williamr@4: * under the terms of "Eclipse Public License v1.0"
williamr@4: * which accompanies this distribution, and is available
williamr@4: * at the URL "http://www.eclipse.org/legal/epl-v10.html".
williamr@4: *
williamr@4: * Initial Contributors:
williamr@4: * Nokia Corporation - initial contribution.
williamr@4: *
williamr@4: * Contributors:
williamr@4: *
williamr@4: * Description:  Uses notification framework to show a global list query.
williamr@4: *
williamr@4: */
williamr@4: 
williamr@4: #ifndef __AKNGLOBALLISTQUERY_H__
williamr@4: #define __AKNGLOBALLISTQUERY_H__
williamr@4: 
williamr@4: #include <AknNotify.h>
williamr@4: #include <AknNotifyStd.h>
williamr@4: #include <bamdesca.h>
williamr@4: 
williamr@4: class CAknSDData;
williamr@4: 
williamr@4: // Default index for list query
williamr@4: const TInt KGlobalListQueryDefaultIndex = 0;
williamr@4: 
williamr@4: _LIT( KGlobalListQueryItemSeparator, "\n");
williamr@4: 
williamr@4: /**
williamr@4: * CAknGlobalListQuery
williamr@4: *   Uses notification framework to show a global list query.
williamr@4: *   Usage:
williamr@4: *       Create an active object, start it and pass its TRequestStatus as a
williamr@4: *       parameter to ShowListQueryL. After the user selects one item from
williamr@4: *       the list query, the request status will hold the number of the
williamr@4: *       selected item. If the user selected Cancel, the request status will
williamr@4: *       hold -1.
williamr@4: *
williamr@4: *   Example 1. Show the global list query:
williamr@4: *        CDesCArray* textArray = iCoeEnv->ReadDesCArrayResourceL( R_GLOBAL_LIST_ARRAY );
williamr@4: *        CleanupStack::PushL(textArray);
williamr@4: *        TInt result = -555;
williamr@4: *        if ( iListObserver )
williamr@4: *            {
williamr@4: *            iListObserver->Cancel();
williamr@4: *            delete iListObserver;
williamr@4: *            }
williamr@4: *        iListObserver = new(ELeave) CGlobalListObserver(iEikonEnv);
williamr@4: *        iListObserver->Start();
williamr@4: *        iGlobalListQuery->ShowListQueryL(textArray, iListObserver->iStatus, 4);
williamr@4: *        CleanupStack::PopAndDestroy(); // textArray
williamr@4: *
williamr@4: *   Example 2. Get and handle the result in active object.
williamr@4: *        void CMyActiveObject::RunL() 
williamr@4: *            {
williamr@4: *            TBuf<120> msg = _L("Received: ");
williamr@4: *            msg.AppendNum( iStatus.Int() );
williamr@4: *            iEnv->InfoMsg(msg);
williamr@4: *            Cancel();
williamr@4: *            }
williamr@4: */
williamr@4: NONSHARABLE_CLASS(CAknGlobalListQuery) : public CBase
williamr@4:     {
williamr@4:     public:
williamr@4:         /**
williamr@4:         * Two-phased constructor.
williamr@4:         */
williamr@4:         IMPORT_C static CAknGlobalListQuery* NewL();
williamr@4: 
williamr@4:         /**
williamr@4:         * Two-phased constructor. Leaves the instance to cleanupstack
williamr@4:         */
williamr@4:         IMPORT_C static CAknGlobalListQuery* NewLC();
williamr@4: 
williamr@4:         /**
williamr@4:         * Destructor
williamr@4:         */
williamr@4:         IMPORT_C ~CAknGlobalListQuery();
williamr@4: 
williamr@4:         /**
williamr@4:         * Shows global list query synchronously.
williamr@4:         *
williamr@4:         * @param    aItems  Strings for items
williamr@4:         * @param    aStatus TRequestStatus which will be completed when user
williamr@4:         *                   selects one item from the list query.
williamr@4:         * @param    aIndex  Index which item in the list will be highlighted 
williamr@4:         */
williamr@4:         IMPORT_C void ShowListQueryL( 
williamr@4:             const MDesCArray* aItems,
williamr@4:             TRequestStatus& aStatus,
williamr@4:             const TInt aIndex = KGlobalListQueryDefaultIndex);
williamr@4: 
williamr@4:         /**
williamr@4:         * Move selection up.
williamr@4:         */
williamr@4:         IMPORT_C void MoveSelectionUp();
williamr@4: 
williamr@4:         /**
williamr@4:         * Move selection down.
williamr@4:         */
williamr@4:         IMPORT_C void MoveSelectionDown();
williamr@4: 
williamr@4:         /**
williamr@4:         * Select currently selected item in the list.
williamr@4:         */
williamr@4:         IMPORT_C void SelectItem();
williamr@4: 
williamr@4:         /**
williamr@4:         * Cancel the list query.
williamr@4:         */
williamr@4:         IMPORT_C void CancelListQuery();
williamr@4: 
williamr@4:         /**
williamr@4:         * Sets the heading for the query. In order to have effect, the heading must be set before 
williamr@4:         * calling ShowListQueryL.
williamr@4:         *
williamr@4:         * @param    aHeading  Heading string.
williamr@4:         * @since 2.1
williamr@4:         */
williamr@4:         IMPORT_C void SetHeadingL(const TDesC& aHeading);
williamr@4: 
williamr@4:         /**
williamr@4:         * Sets additional information to be sent to secondary display. Takes ownership of object.
williamr@4:         * Must be called before sending data to notifier to have effect.
williamr@4:         *
williamr@4:         * @param aData Data to be sent to cover UI.
williamr@4:         * @internal to S60
williamr@4:         * @since S60 3.1
williamr@4:         */
williamr@4:         IMPORT_C void SetSecondaryDisplayData(CAknSDData* aData);
williamr@4:         
williamr@4:     private:
williamr@4:         /**
williamr@4:         * Updates list query.
williamr@4:         */
williamr@4:         IMPORT_C void UpdateListQuery();
williamr@4: 
williamr@4:     private:
williamr@4:         /**
williamr@4:         * Default constructor.
williamr@4:         */
williamr@4:         CAknGlobalListQuery();
williamr@4: 
williamr@4:         /**
williamr@4:         * EPOC constructor.
williamr@4:         */
williamr@4:         void ConstructL(); 
williamr@4: 
williamr@4:     private:
williamr@4:         // Command id.
williamr@4:         TAknGlobalQueryCmd iCmd;
williamr@4:         // Notifier handle.
williamr@4:         RNotifier iNotify;
williamr@4:         // Index to set which item will be selected.
williamr@4:         TInt iIndex;
williamr@4:         // Buffer to hold the variables passed to server.
williamr@4:         CBufFlat *iBuffer;
williamr@4:         // Pointer to buffer.
williamr@4:         TPtrC8 iBufferPtr;
williamr@4:         HBufC* iHeading;
williamr@4:         CAknSDData* iAknSDData;
williamr@4:         TBuf8<1> iResultBuf; // Not really used, but needed to prevent buffer handling errors.
williamr@4:     };
williamr@4: 
williamr@4: #endif // __AKNGLOBALLISTQUERY_H__