1.1 --- a/epoc32/include/mw/akngloballistmsgquery.h Tue Nov 24 13:55:44 2009 +0000
1.2 +++ b/epoc32/include/mw/akngloballistmsgquery.h Tue Mar 16 16:12:26 2010 +0000
1.3 @@ -1,1 +1,228 @@
1.4 -akngloballistmsgquery.h
1.5 +/*
1.6 +* Copyright (c) 2008 Nokia Corporation and/or its subsidiary(-ies).
1.7 +* All rights reserved.
1.8 +* This component and the accompanying materials are made available
1.9 +* 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
1.10 +* which accompanies this distribution, and is available
1.11 +* at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
1.12 +*
1.13 +* Initial Contributors:
1.14 +* Nokia Corporation - initial contribution.
1.15 +*
1.16 +* Contributors:
1.17 +*
1.18 +* Description: Uses notification framework to show a global list query with
1.19 +* message field.
1.20 +*
1.21 +*/
1.22 +
1.23 +#ifndef __AKNGLOBALLISTMSGQUERY_H__
1.24 +#define __AKNGLOBALLISTMSGQUERY_H__
1.25 +
1.26 +#include <aknnotifystd.h>
1.27 +#include <aknquerydialog.h>
1.28 +
1.29 +class CAknSDData;
1.30 +
1.31 +/**
1.32 +* Uses notification framework to show a global list query with message field.
1.33 +*
1.34 +* Usage:
1.35 +* Create an active object, start it and pass its TRequestStatus as a
1.36 +* parameter to ShowListMsgQueryL(). After the user selects one item from
1.37 +* the query and accepts it, the request status will hold the number of the
1.38 +* selected item. If the user cancels the query with softkey, the request status will
1.39 +* hold -1. If method CancelListMsgQuery() is called, the request status will
1.40 +* hold -3 (KErrCancel).
1.41 +*
1.42 +* Example 1. Show the global list message query:
1.43 +* @code
1.44 +* #include <akngloballistmsgquery.h>
1.45 +* ...
1.46 +* _LIT(KQueryHeaderText, "Global list msg query");
1.47 +* _LIT(KQueryMsgText, "Query message.");
1.48 +* _LIT(KListMsgQueryItem1, "Item 1");
1.49 +* _LIT(KListMsgQueryItem2, "Item 2");
1.50 +*
1.51 +* CDesCArray* textArray = new (ELeave) CDesCArrayFlat(2);
1.52 +* CleanupStack::PushL(textArray);
1.53 +* textArray->AppendL(KListMsgQueryItem1);
1.54 +* textArray->AppendL(KListMsgQueryItem2);
1.55 +*
1.56 +* if (iListObserver)
1.57 +* {
1.58 +* iListObserver->Cancel();
1.59 +* delete iListObserver;
1.60 +* iListObserver = 0;
1.61 +* }
1.62 +*
1.63 +* if (iGlobalListMsgQuery)
1.64 +* {
1.65 +* delete iGlobalListMsgQuery;
1.66 +* iGlobalListMsgQuery = 0;
1.67 +* }
1.68 +*
1.69 +* iListObserver = CMyActiveObject::NewL();
1.70 +* iGlobalListMsgQuery = CAknGlobalListMsgQuery::NewL();
1.71 +*
1.72 +* iGlobalListMsgQuery->ShowListMsgQueryL(
1.73 +* textArray,
1.74 +* iListObserver->iStatus,
1.75 +* KQueryHeaderText,
1.76 +* KQueryMsgText);
1.77 +*
1.78 +* iListObserver->Start();
1.79 +*
1.80 +* CleanupStack::PopAndDestroy(textArray);
1.81 +* @endcode
1.82 +*
1.83 +* Example 2. Get and handle the result in active object. The result is simply displayed on
1.84 +* screen using info message:
1.85 +* @code
1.86 +* void CMyActiveObject::RunL()
1.87 +* {
1.88 +* _LIT(KReceivedMsg, "Received:");
1.89 +* TBuf<100> msg = KReceivedMsg();
1.90 +* msg.AppendNum(iStatus.Int());
1.91 +* CEikonEnv::Static()->InfoMsg(msg);
1.92 +* }
1.93 +* @endcode
1.94 +*
1.95 +* @lib AknNotify.lib
1.96 +* @since S60 3.2
1.97 +*/
1.98 +NONSHARABLE_CLASS(CAknGlobalListMsgQuery) : public CBase
1.99 + {
1.100 +public:
1.101 + /**
1.102 + * Two-phased constructor.
1.103 + *
1.104 + * @return A pointer to the new instance.
1.105 + */
1.106 + IMPORT_C static CAknGlobalListMsgQuery* NewL();
1.107 +
1.108 + /**
1.109 + * Two-phased constructor. Leaves the instance to cleanup stack.
1.110 + *
1.111 + * @return A pointer to the new instance.
1.112 + */
1.113 + IMPORT_C static CAknGlobalListMsgQuery* NewLC();
1.114 +
1.115 + /**
1.116 + * Destructor.
1.117 + */
1.118 + IMPORT_C ~CAknGlobalListMsgQuery();
1.119 +
1.120 + /**
1.121 + * Shows the global list message query.
1.122 + *
1.123 + * @param aItems Array of strings for list items. The items will be copied, so it is
1.124 + * safe to delete the array as soon as ShowListMsgQueryL() has been called.
1.125 + * @param aStatus TRequestStatus which will be completed when user dismisses the query.
1.126 + * Will contain KErrInUse if another global list query is already being shown.
1.127 + * Will contain KErrArgument if aSoftkeys does not point to a valid resource.
1.128 + * Will contain KErrArgument if aItems array is empty.
1.129 + * Will contain KErrArgument if aIndex is out of bounds.
1.130 + * Will contain KErrArgument if aAcceptKeyId is EAknSoftkeyCancel.
1.131 + * Will contain KErrArgument if aCancelKeyId is EAknSoftkeyOk.
1.132 + * @param aHeaderText Query header text.
1.133 + * @param aMsgText Query message text. Maximum is three lines.
1.134 + * @param aIndex Index of the item that will be highlighted by default.
1.135 + * @param aSoftkeys Softkey resource id from Avkon.rss. If used, give also
1.136 + * aAcceptKeyId and aCancelKeyId.
1.137 + * @param aAcceptKeyId Identifier of the softkey that is used to accept the query.
1.138 + * @param aCancelKeyId Identifier of the softkey that is used to cancel the query.
1.139 + * @param aHeaderImageFile A full path to image to be used in the header field.
1.140 + * @param aImageId Image id.
1.141 + * @param aImageId Image mask id.
1.142 + * @param aTone Tone id.
1.143 + */
1.144 + IMPORT_C void ShowListMsgQueryL(
1.145 + const MDesCArray* aItems,
1.146 + TRequestStatus& aStatus,
1.147 + const TDesC& aHeaderText,
1.148 + const TDesC& aMsgText,
1.149 + const TInt aIndex = 0,
1.150 + TInt aSoftkeys = 0,
1.151 + TInt aAcceptKeyId = 0,
1.152 + TInt aCancelKeyId = 0,
1.153 + const TDesC& aHeaderImageFile = KNullDesC,
1.154 + TInt aImageId = 0,
1.155 + TInt aImageMaskId = -1,
1.156 + CAknQueryDialog::TTone aTone = CAknQueryDialog::ENoTone);
1.157 +
1.158 + /**
1.159 + * Moves selection up.
1.160 + */
1.161 + IMPORT_C void MoveSelectionUp();
1.162 +
1.163 + /**
1.164 + * Moves selection down.
1.165 + */
1.166 + IMPORT_C void MoveSelectionDown();
1.167 +
1.168 + /**
1.169 + * Selects currently selected item in the list.
1.170 + */
1.171 + IMPORT_C void SelectItem();
1.172 +
1.173 + /**
1.174 + * Cancels the query.
1.175 + */
1.176 + IMPORT_C void CancelListMsgQuery();
1.177 +
1.178 + /**
1.179 + * Sets additional information to be sent to secondary display. Takes ownership of object.
1.180 + * Must be called before sending data to notifier to have effect.
1.181 + *
1.182 + * @param aData Data to be sent to cover UI.
1.183 + */
1.184 + IMPORT_C void SetSecondaryDisplayData(CAknSDData* aData);
1.185 +
1.186 + /**
1.187 + * Sets skin id for image. Must be called before ShowListMsgQueryL() is called.
1.188 + *
1.189 + * @param aId Image skin id.
1.190 + */
1.191 + IMPORT_C void SetImageSkinId(const TAknsItemID& aId);
1.192 +
1.193 +private:
1.194 + /**
1.195 + * Default constructor.
1.196 + */
1.197 + CAknGlobalListMsgQuery();
1.198 +
1.199 + /**
1.200 + * Symbian second-phase constructor.
1.201 + */
1.202 + void ConstructL();
1.203 +
1.204 + /**
1.205 + * Sets the heading for the query.
1.206 + */
1.207 + void SetHeadingL(const TDesC& aHeading);
1.208 +
1.209 + /**
1.210 + * Updates the query.
1.211 + */
1.212 + void UpdateListMsgQuery();
1.213 +
1.214 +private:
1.215 + // Command id.
1.216 + TAknGlobalQueryCmd iCmd;
1.217 + // Notifier handle.
1.218 + RNotifier iNotify;
1.219 + // Index to set which item will be selected.
1.220 + TInt iIndex;
1.221 + // Buffer to hold the variables passed to server.
1.222 + CBufFlat *iBuffer;
1.223 + // Pointer to buffer.
1.224 + TPtrC8 iBufferPtr;
1.225 + HBufC* iHeading;
1.226 + CAknSDData* iAknSDData;
1.227 + TBuf8<1> iResultBuf; // Not really used, but needed to prevent buffer handling errors.
1.228 + TInt iSkinsMajorId;
1.229 + TInt iSkinsMinorId;
1.230 + };
1.231 +
1.232 +#endif // __AKNGLOBALLISTMSGQUERY_H__