--- a/epoc32/include/mw/akngloballistmsgquery.h Tue Nov 24 13:55:44 2009 +0000
+++ b/epoc32/include/mw/akngloballistmsgquery.h Tue Mar 16 16:12:26 2010 +0000
@@ -1,1 +1,228 @@
-akngloballistmsgquery.h
+/*
+* 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__