1 /*

     2 * Copyright (c) 2002-2007 Nokia Corporation and/or its subsidiary(-ies).

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:  Uses notification framework to show a global message query.

    15 *

    16 */

    17 

    18 #ifndef __AKNGLOBALMSGQUERY_H__

    19 #define __AKNGLOBALMSGQUERY_H__

    20 

    21 #include <AknNotify.h>

    22 #include <AknNotifyStd.h>

    23 #include <AknQueryDialog.h>

    24 #include <AknsItemID.h>

    25 

    26 class CAknSDData;

    27 

    28 /**

    29 * CAknGlobalMsgQuery

    30 *   Uses notification framework to show a global message query.

    31 *   Usage:

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

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

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

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

    36 *

    37 *   Example 1. Show the global message query:

    38 *        if ( iListObserver )

    39 *            {

    40 *            iListObserver->Cancel();

    41 *            delete iListObserver;

    42 *            }

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

    44 *        iMsgObserver->Start();

    45 *        iGlobalMsgQuery->ShowMsgQueryL(

    46 *            iMsgObserver->iStatus, iMsgText, 

    47 *            R_AVKON_SOFTKEYS_OK_CANCEL, iMsgHeader,

    48 *            iHeaderImageFile, EImageId, EMaskId );

    49 *

    50 *   Example 2. Get and handle the result in active object.

    51 *        void CMyActiveObject::RunL() 

    52 *            {

    53 *            TBuf<120> msg = _L("Received: ");

    54 *            msg.AppendNum( iStatus.Int() );

    55 *            iEnv->InfoMsg(msg);

    56 *            Cancel();

    57 *            }

    58 *

    59 *   Example 3. Update the query (softkeys)

    60 *       iGlobalMsgQuery->UpdateMsgQuery( R_AVKON_SOFTKEYS_BACK );

    61 *

    62 *   Example 4. Cancel the query

    63 *       iGlobalMsgQuery->CancelMsgQuery();

    64 *

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

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

    67 *           they need to exist when server gets the message.

    68 */

    69 

    70 NONSHARABLE_CLASS(CAknGlobalMsgQuery) : public CBase

    71     {

    72     public:

    73         IMPORT_C static CAknGlobalMsgQuery* NewL();

    74         IMPORT_C static CAknGlobalMsgQuery* NewLC();

    75         IMPORT_C ~CAknGlobalMsgQuery();

    76 

    77         /**

    78         * Shows global message query synchronously.

    79         *

    80         * @param    aMsgText        Message text.

    81         * @param    aHeaderText     Header text.

    82         * @param    aSoftkeys       Softkey resource.

    83         * @param    aStatus         TRequestStatus which will be completed when user

    84         *                           selects one item from the list query.

    85         */

    86         IMPORT_C void ShowMsgQueryL( 

    87             TRequestStatus& aStatus,

    88             const TDesC& aMsgText,

    89             TInt aSoftkeys,

    90             const TDesC& aHeaderText,

    91             const TDesC& aHeaderImageFile,

    92             TInt aImageId = 0,

    93             TInt aImageMaskId = -1,

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

    95 

    96         /**

    97         * Update the softkeys of the message query.

    98         *

    99         * @param    aSoftkeys  New resource for softkeys.

   100         */

   101         IMPORT_C void UpdateMsgQuery( TInt aSoftkeys );

   102 

   103         /**

   104         * Cancel the message query.

   105         */

   106         IMPORT_C void CancelMsgQuery();

   107 

   108         /**

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

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

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

   112         * 

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

   114         * @since  S60 2.1

   115         */

   116         IMPORT_C void SetExitDelay(TInt aDelay);

   117 

   118         /**

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

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

   121         *

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

   123         *               definitions used in ShowMsgQueryL used instead.

   124         * @since S60 2.6

   125         */      

   126         IMPORT_C void SetImageSkinId( TAknsItemID& aId );

   127 

   128         /**

   129         * Sets additional information to be sent to secondary display. Takes ownership of object.

   130         * Must be called before sending data to notifier to have effect.

   131         *

   132         * @param aData Data to be sent to cover UI.

   133         * @internal to S60

   134         * @since S60 3.1

   135         */

   136         IMPORT_C void SetSecondaryDisplayData(CAknSDData* aData);

   137     

   138     private:

   139         CAknGlobalMsgQuery();

   140         void ConstructL(); 

   141 

   142     private:

   143         TAknGlobalQueryCmd iCmd;

   144         TInt iSoftkeys;

   145         TInt iImageId;

   146         TInt iImageMaskId;

   147         CAknQueryDialog::TTone iTone;

   148         RNotifier iNotify;

   149         CBufFlat *iBuffer;

   150         TPtrC8 iBufferPtr;

   151         TInt iDelay;

   152         TInt   iSkinsMajorId;

   153         TInt   iSkinsMinorId;

   154         CAknSDData* iAknSDData;

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

   156     };

   157 

   158 #endif // __AKNGLOBALMSGQUERY_H__