/*

* 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 message query.

*

*/

#ifndef __AKNGLOBALMSGQUERY_H__

#define __AKNGLOBALMSGQUERY_H__

#include <AknNotify.h>

#include <AknNotifyStd.h>

#include <AknQueryDialog.h>

#include <AknsItemID.h>

class CAknSDData;

/**

* CAknGlobalMsgQuery

*   Uses notification framework to show a global message query.

*   Usage:

*       Create an active object, start it and pass its TRequestStatus as a

*       parameter to ShowMsgQueryL. After the user presses a softkey,

*       the request status will hold the id of the pressed softkey. E.g. 

*       If the user selected Cancel, the request status will hold -1.

*

*   Example 1. Show the global message query:

*        if ( iListObserver )

*            {

*            iListObserver->Cancel();

*            delete iListObserver;

*            }

*        iMsgObserver = new(ELeave) CGlobalMsgObserver(iEikonEnv);

*        iMsgObserver->Start();

*        iGlobalMsgQuery->ShowMsgQueryL(

*            iMsgObserver->iStatus, iMsgText, 

*            R_AVKON_SOFTKEYS_OK_CANCEL, iMsgHeader,

*            iHeaderImageFile, EImageId, EMaskId );

*

*   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();

*            }

*

*   Example 3. Update the query (softkeys)

*       iGlobalMsgQuery->UpdateMsgQuery( R_AVKON_SOFTKEYS_BACK );

*

*   Example 4. Cancel the query

*       iGlobalMsgQuery->CancelMsgQuery();

*

* NOTE !!! All descriptors passed as parameters need to be class members, i.e.

*           they cannot be local variables of a method. That is because

*           they need to exist when server gets the message.

*/

NONSHARABLE_CLASS(CAknGlobalMsgQuery) : public CBase

    {

    public:

        IMPORT_C static CAknGlobalMsgQuery* NewL();

        IMPORT_C static CAknGlobalMsgQuery* NewLC();

        IMPORT_C ~CAknGlobalMsgQuery();

        /**

        * Shows global message query synchronously.

        *

        * @param    aMsgText        Message text.

        * @param    aHeaderText     Header text.

        * @param    aSoftkeys       Softkey resource.

        * @param    aStatus         TRequestStatus which will be completed when user

        *                           selects one item from the list query.

        */

        IMPORT_C void ShowMsgQueryL( 

            TRequestStatus& aStatus,

            const TDesC& aMsgText,

            TInt aSoftkeys,

            const TDesC& aHeaderText,

            const TDesC& aHeaderImageFile,

            TInt aImageId = 0,

            TInt aImageMaskId = -1,

            CAknQueryDialog::TTone aTone = CAknQueryDialog::ENoTone);

        /**

        * Update the softkeys of the message query.

        *

        * @param    aSoftkeys  New resource for softkeys.

        */

        IMPORT_C void UpdateMsgQuery( TInt aSoftkeys );

        /**

        * Cancel the message query.

        */

        IMPORT_C void CancelMsgQuery();

        /**

        * Set delay after which query will be removed from screen after message is completed.

        * Can be used to get around problems with global query exit and CrossCheckForeground probs.

        * Must be called before ShowMsgQueryL in order to be effective.

        * 

        * @param aDelay   Time in microsecond, after which query will be removed from display.

        * @since  S60 2.1

        */

        IMPORT_C void SetExitDelay(TInt aDelay);

        /**

        * Set Skin id for query header image. Must be called before ShowMsgQueryL in order to have 

        * effect. No need to use this method if image from avkon.mbm is used.

        *

        * @aparam aId   SkinId for image in query. If image not found from active skin, image 

        *               definitions used in ShowMsgQueryL used instead.

        * @since S60 2.6

        */      

        IMPORT_C void SetImageSkinId( TAknsItemID& aId );

        /**

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

        CAknGlobalMsgQuery();

        void ConstructL(); 

    private:

        TAknGlobalQueryCmd iCmd;

        TInt iSoftkeys;

        TInt iImageId;

        TInt iImageMaskId;

        CAknQueryDialog::TTone iTone;

        RNotifier iNotify;

        CBufFlat *iBuffer;

        TPtrC8 iBufferPtr;

        TInt iDelay;

        TInt   iSkinsMajorId;

        TInt   iSkinsMinorId;

        CAknSDData* iAknSDData;

        TBuf8<1> iResultBuf; // Not really used, but needed to prevent buffer handling errors.

    };

#endif // __AKNGLOBALMSGQUERY_H__