williamr@2: /*
williamr@2: * Copyright (c) 2008 Nokia Corporation and/or its subsidiary(-ies).
williamr@2: * All rights reserved.
williamr@2: * This component and the accompanying materials are made available
williamr@2: * under the terms of the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members
williamr@2: * which accompanies this distribution, and is available
williamr@2: * at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
williamr@2: *
williamr@2: * Initial Contributors:
williamr@2: * Nokia Corporation - initial contribution.
williamr@2: *
williamr@2: * Contributors:
williamr@2: *
williamr@2: * Description:  Uses notification framework to show a global list query with 
williamr@2: *                message field.
williamr@2: *
williamr@2: */
williamr@2: 
williamr@2: #ifndef __AKNGLOBALLISTMSGQUERY_H__
williamr@2: #define __AKNGLOBALLISTMSGQUERY_H__
williamr@2: 
williamr@2: #include <aknnotifystd.h>
williamr@2: #include <aknquerydialog.h>
williamr@2: 
williamr@2: class CAknSDData;
williamr@2: 
williamr@2: /**
williamr@2: * Uses notification framework to show a global list query with message field.
williamr@2: *   
williamr@2: * Usage:
williamr@2: *     Create an active object, start it and pass its TRequestStatus as a
williamr@2: *     parameter to ShowListMsgQueryL(). After the user selects one item from
williamr@2: *     the query and accepts it, the request status will hold the number of the
williamr@2: *     selected item. If the user cancels the query with softkey, the request status will
williamr@2: *     hold -1. If method CancelListMsgQuery() is called, the request status will  
williamr@2: *     hold -3 (KErrCancel).
williamr@2: *
williamr@2: * Example 1. Show the global list message query:
williamr@2: * @code
williamr@2: *     #include <akngloballistmsgquery.h>
williamr@2: *     ...
williamr@2: *     _LIT(KQueryHeaderText, "Global list msg query");
williamr@2: *     _LIT(KQueryMsgText, "Query message.");
williamr@2: *     _LIT(KListMsgQueryItem1, "Item 1");
williamr@2: *     _LIT(KListMsgQueryItem2, "Item 2");
williamr@2: *
williamr@2: *     CDesCArray* textArray = new (ELeave) CDesCArrayFlat(2);
williamr@2: *     CleanupStack::PushL(textArray);
williamr@2: *     textArray->AppendL(KListMsgQueryItem1);
williamr@2: *     textArray->AppendL(KListMsgQueryItem2);
williamr@2: *         
williamr@2: *     if (iListObserver)
williamr@2: *         {
williamr@2: *         iListObserver->Cancel();
williamr@2: *         delete iListObserver;
williamr@2: *         iListObserver = 0;
williamr@2: *         }
williamr@2: *
williamr@2: *     if (iGlobalListMsgQuery)
williamr@2: *         {
williamr@2: *         delete iGlobalListMsgQuery;
williamr@2: *         iGlobalListMsgQuery = 0;
williamr@2: *         }
williamr@2: *
williamr@2: *     iListObserver = CMyActiveObject::NewL();
williamr@2: *     iGlobalListMsgQuery = CAknGlobalListMsgQuery::NewL();
williamr@2: *
williamr@2: *     iGlobalListMsgQuery->ShowListMsgQueryL(
williamr@2: *         textArray, 
williamr@2: *         iListObserver->iStatus, 
williamr@2: *         KQueryHeaderText,
williamr@2: *         KQueryMsgText);
williamr@2: *
williamr@2: *     iListObserver->Start();
williamr@2: *
williamr@2: *     CleanupStack::PopAndDestroy(textArray);
williamr@2: * @endcode
williamr@2: *
williamr@2: * Example 2. Get and handle the result in active object. The result is simply displayed on 
williamr@2: *            screen using info message:
williamr@2: * @code
williamr@2: *     void CMyActiveObject::RunL() 
williamr@2: *         {
williamr@2: *         _LIT(KReceivedMsg, "Received:");
williamr@2: *         TBuf<100> msg = KReceivedMsg();
williamr@2: *         msg.AppendNum(iStatus.Int());
williamr@2: *         CEikonEnv::Static()->InfoMsg(msg);
williamr@2: *         }
williamr@2: * @endcode
williamr@2: *
williamr@2: * @lib AknNotify.lib
williamr@2: * @since S60 3.2
williamr@2: */
williamr@2: NONSHARABLE_CLASS(CAknGlobalListMsgQuery) : public CBase
williamr@2:     {
williamr@2: public:
williamr@2:     /**
williamr@2:     * Two-phased constructor.
williamr@2:     *
williamr@2:     * @return A pointer to the new instance.
williamr@2:     */
williamr@2:     IMPORT_C static CAknGlobalListMsgQuery* NewL();
williamr@2: 
williamr@2:     /**
williamr@2:     * Two-phased constructor. Leaves the instance to cleanup stack.
williamr@2:     *
williamr@2:     * @return A pointer to the new instance.
williamr@2:     */
williamr@2:     IMPORT_C static CAknGlobalListMsgQuery* NewLC();
williamr@2: 
williamr@2:     /**
williamr@2:     * Destructor.
williamr@2:     */
williamr@2:     IMPORT_C ~CAknGlobalListMsgQuery();
williamr@2: 
williamr@2:     /**
williamr@2:     * Shows the global list message query.
williamr@2:     *
williamr@2:     * @param  aItems           Array of strings for list items. The items will be copied, so it is
williamr@2:     *                          safe to delete the array as soon as ShowListMsgQueryL() has been called.
williamr@2:     * @param  aStatus          TRequestStatus which will be completed when user dismisses the query.
williamr@2:     *                          Will contain KErrInUse if another global list query is already being shown.
williamr@2:     *                          Will contain KErrArgument if aSoftkeys does not point to a valid resource.
williamr@2:     *                          Will contain KErrArgument if aItems array is empty.
williamr@2:     *                          Will contain KErrArgument if aIndex is out of bounds.
williamr@2:     *                          Will contain KErrArgument if aAcceptKeyId is EAknSoftkeyCancel.
williamr@2:     *                          Will contain KErrArgument if aCancelKeyId is EAknSoftkeyOk.
williamr@2:     * @param  aHeaderText      Query header text.
williamr@2:     * @param  aMsgText         Query message text. Maximum is three lines.
williamr@2:     * @param  aIndex           Index of the item that will be highlighted by default.    
williamr@2:     * @param  aSoftkeys        Softkey resource id from Avkon.rss. If used, give also 
williamr@2:     *                          aAcceptKeyId and aCancelKeyId.
williamr@2:     * @param  aAcceptKeyId     Identifier of the softkey that is used to accept the query.
williamr@2:     * @param  aCancelKeyId     Identifier of the softkey that is used to cancel the query.
williamr@2:     * @param  aHeaderImageFile A full path to image to be used in the header field.
williamr@2:     * @param  aImageId         Image id.
williamr@2:     * @param  aImageId         Image mask id.
williamr@2:     * @param  aTone            Tone id.
williamr@2:     */
williamr@2:     IMPORT_C void ShowListMsgQueryL(
williamr@2:         const MDesCArray* aItems,
williamr@2:         TRequestStatus& aStatus,
williamr@2:         const TDesC& aHeaderText,
williamr@2:         const TDesC& aMsgText,
williamr@2:         const TInt aIndex = 0,
williamr@2:         TInt aSoftkeys = 0,
williamr@2:         TInt aAcceptKeyId = 0,
williamr@2:         TInt aCancelKeyId = 0,
williamr@2:         const TDesC& aHeaderImageFile = KNullDesC,        
williamr@2:         TInt aImageId = 0,
williamr@2:         TInt aImageMaskId = -1,
williamr@2:         CAknQueryDialog::TTone aTone = CAknQueryDialog::ENoTone);
williamr@2: 
williamr@2:     /**
williamr@2:     * Moves selection up.
williamr@2:     */
williamr@2:     IMPORT_C void MoveSelectionUp();
williamr@2: 
williamr@2:     /**
williamr@2:     * Moves selection down.
williamr@2:     */
williamr@2:     IMPORT_C void MoveSelectionDown();
williamr@2: 
williamr@2:     /**
williamr@2:     * Selects currently selected item in the list.
williamr@2:     */
williamr@2:     IMPORT_C void SelectItem();
williamr@2: 
williamr@2:     /**
williamr@2:     * Cancels the query.
williamr@2:     */
williamr@2:     IMPORT_C void CancelListMsgQuery();
williamr@2: 
williamr@2:     /**
williamr@2:     * Sets additional information to be sent to secondary display. Takes ownership of object.
williamr@2:     * Must be called before sending data to notifier to have effect.
williamr@2:     *
williamr@2:     * @param aData Data to be sent to cover UI.
williamr@2:     */
williamr@2:     IMPORT_C void SetSecondaryDisplayData(CAknSDData* aData);
williamr@2:     
williamr@2:     /**
williamr@2:     * Sets skin id for image. Must be called before ShowListMsgQueryL() is called.
williamr@2:     * 
williamr@2:     * @param aId Image skin id.
williamr@2:     */
williamr@2:     IMPORT_C void SetImageSkinId(const TAknsItemID& aId);
williamr@2:     
williamr@2: private:
williamr@2:     /**
williamr@2:     * Default constructor.
williamr@2:     */
williamr@2:     CAknGlobalListMsgQuery();
williamr@2: 
williamr@2:     /**
williamr@2:     * Symbian second-phase constructor.
williamr@2:     */
williamr@2:     void ConstructL(); 
williamr@2:     
williamr@2:     /**
williamr@2:     * Sets the heading for the query.
williamr@2:     */
williamr@2:     void SetHeadingL(const TDesC& aHeading);
williamr@2:     
williamr@2:     /**
williamr@2:     * Updates the query.
williamr@2:     */
williamr@2:     void UpdateListMsgQuery();        
williamr@2: 
williamr@2: private:
williamr@2:     // Command id.
williamr@2:     TAknGlobalQueryCmd iCmd;
williamr@2:     // Notifier handle.
williamr@2:     RNotifier iNotify;
williamr@2:     // Index to set which item will be selected.
williamr@2:     TInt iIndex;
williamr@2:     // Buffer to hold the variables passed to server.
williamr@2:     CBufFlat *iBuffer;
williamr@2:     // Pointer to buffer.
williamr@2:     TPtrC8 iBufferPtr;
williamr@2:     HBufC* iHeading;
williamr@2:     CAknSDData* iAknSDData;
williamr@2:     TBuf8<1> iResultBuf; // Not really used, but needed to prevent buffer handling errors.
williamr@2:     TInt iSkinsMajorId;
williamr@2:     TInt iSkinsMinorId;
williamr@2:     };
williamr@2: 
williamr@2: #endif // __AKNGLOBALLISTMSGQUERY_H__