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