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