1.1 --- a/epoc32/include/app/cpbkviewstate.h Tue Nov 24 13:55:44 2009 +0000
1.2 +++ b/epoc32/include/app/cpbkviewstate.h Tue Mar 16 16:12:26 2010 +0000
1.3 @@ -1,1 +1,400 @@
1.4 -cpbkviewstate.h
1.5 +/*
1.6 +* Copyright (c) 2002 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:
1.19 +* View states.
1.20 +*
1.21 +*/
1.22 +
1.23 +
1.24 +#ifndef __CPbkViewState_H__
1.25 +#define __CPbkViewState_H__
1.26 +
1.27 +// INCLUDES
1.28 +#include <e32base.h> // CBase
1.29 +#include <cntdef.h> // TContactItemId, CContactIdArray
1.30 +
1.31 +// FORWARD DECLARATIONS
1.32 +class RReadStream;
1.33 +class RWriteStream;
1.34 +class CPbkFieldDataArray;
1.35 +
1.36 +// CLASS DECLARATION
1.37 +
1.38 +/**
1.39 + * Generic Phonebook view state class. Class can be used to pass parameters
1.40 + * the Phonebook application when launching the application with the symbian
1.41 + * view launching mechanism.
1.42 + */
1.43 +class CPbkViewState : public CBase
1.44 + {
1.45 + public: // Types
1.46 + enum TDataType
1.47 + {
1.48 + EEnd = 0,
1.49 + EFocusedContactId,
1.50 + ETopContactId,
1.51 + EMarkedContactIds,
1.52 + EFocusedFieldIndex,
1.53 + ETopFieldIndex,
1.54 + EFieldDataArray,
1.55 + EParentContactId,
1.56 + EFlags
1.57 + };
1.58 +
1.59 + enum TFlags
1.60 + {
1.61 + /// Reset flags
1.62 + ENullFlags = 0,
1.63 + /// Focus the first item in list views
1.64 + EFocusFirst = 0x0001,
1.65 + /// Focus the last item in list views
1.66 + EFocusLast = 0x0002,
1.67 + /// Reset state to the view's initial state
1.68 + EInitialized = 0x0004,
1.69 + /// Send application to background
1.70 + ESendToBackground = 0x0008
1.71 + };
1.72 +
1.73 + public: // Constructors and destructor
1.74 + /**
1.75 + * Creates and returns a new instance of this class.
1.76 + */
1.77 + IMPORT_C static CPbkViewState* NewL();
1.78 +
1.79 + /**
1.80 + * Like NewL(), but leaves the object on the cleanup stack
1.81 + * @see NewL
1.82 + */
1.83 + IMPORT_C static CPbkViewState* NewLC();
1.84 +
1.85 + /**
1.86 + * Creates and returns a new instance of this class initialized
1.87 + * from aStream.
1.88 + * @param aStream A view state stream to internalize.
1.89 + */
1.90 + IMPORT_C static CPbkViewState* NewL(RReadStream& aStream);
1.91 +
1.92 + /**
1.93 + * Like NewL(RReadStream& aStream) but leaves the object on
1.94 + * the cleanup stack.
1.95 + * @see NewL(RReadStream& aStream)
1.96 + * @param aStream A view state stream to internalize.
1.97 + */
1.98 + IMPORT_C static CPbkViewState* NewLC(RReadStream& aStream);
1.99 +
1.100 + /**
1.101 + * Creates and returns a new instance of this class initialized
1.102 + * from aBuf.
1.103 + * @param aBuf A view state buffer to internalize.
1.104 + */
1.105 + IMPORT_C static CPbkViewState* NewL(const TDesC8& aBuf);
1.106 +
1.107 + /**
1.108 + * Like NewL(const TDesC8& aBuf) but leaves the object on
1.109 + * the cleanup stack.
1.110 + * @see NewL(const TDesC8& aBuf)
1.111 + * @param aBuf A view state buffer to internalize.
1.112 + */
1.113 + IMPORT_C static CPbkViewState* NewLC(const TDesC8& aBuf);
1.114 +
1.115 + /**
1.116 + * Destructor.
1.117 + */
1.118 + ~CPbkViewState();
1.119 +
1.120 + public: // Getters
1.121 + /**
1.122 + * Returns the message uid for use with view server messages.
1.123 + */
1.124 + IMPORT_C static TUid Uid();
1.125 +
1.126 + /**
1.127 + * Returns id of the focused contact.
1.128 + * @return Contact item id of the focused contact, KNullContactId if not set.
1.129 + */
1.130 + IMPORT_C TContactItemId FocusedContactId() const;
1.131 +
1.132 + /**
1.133 + * Returns id of the topmost contact.
1.134 + * @return Contact item id of the top contact, KNullContactId if not set.
1.135 + */
1.136 + IMPORT_C TContactItemId TopContactId() const;
1.137 +
1.138 + /**
1.139 + * Returns const array of marked contacts ids, NULL if not set.
1.140 + * @return Contact id array of the marked contacts, NULL if not set.
1.141 + */
1.142 + IMPORT_C const CContactIdArray* MarkedContactIds() const;
1.143 +
1.144 + /**
1.145 + * Returns array of marked contacts ids, NULL if not set. Owmership not
1.146 + * transferred.
1.147 + * @return Contact id array of the marked contacts, NULL if not set.
1.148 + */
1.149 + IMPORT_C CContactIdArray* MarkedContactIds();
1.150 +
1.151 + /**
1.152 + * Returns index of the focused field (field is from FocusedContactId()),
1.153 + * -1 when no field focused.
1.154 + * @return Index of the focused field, -1 if no field is focused.
1.155 + */
1.156 + IMPORT_C TInt FocusedFieldIndex() const;
1.157 +
1.158 + /**
1.159 + * Returns index of the topmost field (field is from FocusedContactId()),
1.160 + * -1 when no topmost field.
1.161 + * @return Index of the topmost field, -1 if no topmost field.
1.162 + */
1.163 + IMPORT_C TInt TopFieldIndex() const;
1.164 +
1.165 + /**
1.166 + * Returns field data array, NULL if not set.
1.167 + * @return Field data array object, NULL if not set.
1.168 + */
1.169 + IMPORT_C CPbkFieldDataArray* FieldDataArray() const;
1.170 +
1.171 + /**
1.172 + * Returns the focused contact id's parent, KNullContactId if not set.
1.173 + * @return Focused contact id's parent, KNullContactId if not set.
1.174 + */
1.175 + IMPORT_C TContactItemId ParentContactId() const;
1.176 +
1.177 + /**
1.178 + * Returns the view state flags. See CPbkViewState::TFlags.
1.179 + * @return View state object flags
1.180 + */
1.181 + IMPORT_C TUint Flags() const;
1.182 +
1.183 + public: // Setters
1.184 + /**
1.185 + * Sets id of the focused contact to aId.
1.186 + * @param aId Sets the focused contact id.
1.187 + */
1.188 + IMPORT_C void SetFocusedContactId(TContactItemId aId);
1.189 +
1.190 + /**
1.191 + * Sets id of the topmost contact to aId.
1.192 + * @param aId Sets the topmost contact id.
1.193 + */
1.194 + IMPORT_C void SetTopContactId(TContactItemId aId);
1.195 +
1.196 + /**
1.197 + * Sets the array of marked contact ids to aArray. Destroys previous
1.198 + * array and takes ownership of aArray.
1.199 + * @param aArray Sets the marked contact ids.
1.200 + */
1.201 + IMPORT_C void SetMarkedContactIds(CContactIdArray* aArray);
1.202 +
1.203 + /**
1.204 + * Sets index of the focused field to aIndex (field from
1.205 + * FocusedContactId()), -1 when no field focused.
1.206 + * @param aIndex Sets focused field index.
1.207 + */
1.208 + IMPORT_C void SetFocusedFieldIndex(TInt aIndex);
1.209 +
1.210 + /**
1.211 + * Sets index of the topmost field to aIndex (field from
1.212 + * FocusedContactId()), -1 when no topmost field.
1.213 + * @param aIndex Sets the topmost field index.
1.214 + */
1.215 + IMPORT_C void SetTopFieldIndex(TInt aIndex);
1.216 +
1.217 + /**
1.218 + * Sets field data array to aArray. Destroys previous array
1.219 + * and takes ownership of aArray.
1.220 + * @param aFieldDataArray Sets the field data array.
1.221 + */
1.222 + IMPORT_C void SetFieldDataArray(CPbkFieldDataArray* aFieldDataArray);
1.223 +
1.224 + /**
1.225 + * Reset this state to empty.
1.226 + */
1.227 + IMPORT_C void Reset();
1.228 +
1.229 + /**
1.230 + * Sets the focused contact ids parent contact id.
1.231 + * @param aParentContactId Sets the contact ids parent id.
1.232 + */
1.233 + IMPORT_C void SetParentContactId(TContactItemId aParentContactId);
1.234 +
1.235 + /**
1.236 + * Sets the view state flags.
1.237 + * @param aFlags Sets the view state parameters. See CPbkViewState::TFlags.
1.238 + */
1.239 + IMPORT_C void SetFlags(TUint aFlags);
1.240 +
1.241 + /**
1.242 + * Merges another view state to this view state by setting values from the
1.243 + * parameter and overriding any previous values in this state.
1.244 + *
1.245 + * @param aOtherState The state to merge to this state. The
1.246 + * properties which have a value in aOtherState
1.247 + * override properties in this object. The aOtherState
1.248 + * object may be modified by this function.
1.249 + */
1.250 + /*IMPORT_C*/ void MergeViewState(CPbkViewState& aOtherState);
1.251 +
1.252 + public: // Stream support
1.253 + /**
1.254 + * Packages and returns this object in a buffer. Caller is responsible
1.255 + * of deleting the buffer.
1.256 + * @return Packaged state in a buffer.
1.257 + */
1.258 + IMPORT_C HBufC8* PackL() const;
1.259 +
1.260 + /**
1.261 + * Like PackL, but leaves the buffer on the cleanup stack.
1.262 + * @see PackL
1.263 + * @return Packaged state in a buffer.
1.264 + */
1.265 + IMPORT_C HBufC8* PackLC() const;
1.266 +
1.267 + /**
1.268 + * Sets this state from aPack previously created with PackL.
1.269 + * @see PackL
1.270 + * @see PackLC
1.271 + * @param aPack Previously packaged state.
1.272 + */
1.273 + IMPORT_C void UnpackL(const TDesC8& aPack);
1.274 +
1.275 + /**
1.276 + * Externalizes this object to aStream.
1.277 + * @see InternalizeL
1.278 + * @param aSteam Stream where to externalize this objects state.
1.279 + */
1.280 + IMPORT_C void ExternalizeL(RWriteStream& aStream) const;
1.281 +
1.282 + /**
1.283 + * Internalizes this object from aStream.
1.284 + * @see ExternalizeL
1.285 + * @param aStream A stream from where this objects state can be internalized from.
1.286 + */
1.287 + IMPORT_C void InternalizeL(RReadStream& aStream);
1.288 +
1.289 + public: // Support functions
1.290 + IMPORT_C TBool operator==(const CPbkViewState& aRhs) const;
1.291 +
1.292 + private: // Implementation
1.293 + CPbkViewState();
1.294 +
1.295 + private: // data
1.296 + /// Own: Id of the focused contact
1.297 + TContactItemId iFocusedContactId;
1.298 + /// Own: Id of the topmost contact
1.299 + TContactItemId iTopContactId;
1.300 + /// Own: Index of the focused field
1.301 + TInt iFocusedFieldIndex;
1.302 + /// Own: Index of the top field
1.303 + TInt iTopFieldIndex;
1.304 + /// Own: Array of marked contacts
1.305 + CContactIdArray* iMarkedContactIds;
1.306 + /// Own: Field data array
1.307 + CPbkFieldDataArray* iFieldDataArray;
1.308 + /// Own: Id of the focused contacts parent
1.309 + TContactItemId iParentContactId;
1.310 + /// Own: Flags
1.311 + TUint iFlags;
1.312 +
1.313 + private: // const static data
1.314 + static const TUid KUid;
1.315 + };
1.316 +
1.317 +
1.318 +/*
1.319 + ** View state binary stream format **
1.320 +
1.321 + - View parameter UID is 0x101f4ccf
1.322 +
1.323 + - Format of the stream in (slightly freeform) BNF:
1.324 +
1.325 + <stream> ::= <command>+
1.326 + <command> ::= Int8(opcode) parameters
1.327 + <opcode> ::= EEnd | EFocusedContactId | ETopContactId | EMarkedContactIds |
1.328 + EFocusedFieldIndex | ETopFieldIndex | EFieldDataArray
1.329 + <command> ::= EEnd // no further commands are read after EEnd. EEnd is not mandatory in a stream.
1.330 + <command> ::= EFocusedContactId Int32(TContactItemId)
1.331 + <command> ::= ETopContactId Int32(TContactItemId)
1.332 + <command> ::= EMarkedContactIds (Int32(count) { Int32(TContactItemId) }) // count is count TContactItemIds
1.333 + <command> ::= EFocusedFieldIndex Int32(index)
1.334 + <command> ::= ETopFieldIndex Int32(index)
1.335 + <command> ::= EFieldDataArray <contactdata>
1.336 + <command> ::= EParentContactId Int32(TContactItemId)
1.337 +
1.338 + <contactdata> ::= Int32(count) { fielddata } // count is count of fieldatas
1.339 + <fielddata> ::= <fieldtype> data
1.340 + <fieldtype> ::= ETypeText | ETypeTime
1.341 + <fielddata> ::= ETypeText (Int32(length) text) // length is length of text in chars, text is unicode
1.342 + <fielddata> ::= ETypeTime (Int32(high) Int32(low)) // high and low words of a TTime's internal Int64
1.343 +
1.344 + Constants:
1.345 + EEnd = 0,
1.346 + EFocusedContactId = 1,
1.347 + ETopContactId = 2,
1.348 + EMarkedContactIds = 3,
1.349 + EFocusedFieldIndex = 4,
1.350 + ETopFieldIndex = 5,
1.351 + EFieldDataArray = 6,
1.352 + EParentContactId = 7
1.353 +
1.354 + - Example:
1.355 + Activate Phonebook's contact info view to show contact with id 5 and field
1.356 + at index 3 focused:
1.357 +
1.358 + // Write parameters in a buffer
1.359 + TBuf8<16> param;
1.360 + RDesWriteStream stream(param);
1.361 + stream.PushL();
1.362 + param.WriteInt8L(1); // opcode EFocusedContactId
1.363 + param.WriteInt32L(5); // Contact id 5
1.364 + param.WriteInt8L(4); // opcode EFocusedFieldIndex
1.365 + param.WriteInt32L(3); // field index 3
1.366 + stream.CommitL();
1.367 + CleanupStack::PopAndDestroy(); // stream
1.368 +
1.369 + // Make view id with Phonebook's app UID3 and Contact Info View's id
1.370 + const TVwsViewId viewId(0x101f4cce, 4);
1.371 +
1.372 + // Activate the view
1.373 + AppUi()->ActivateViewL(viewId, TUid::Uid(0x101f4ccf), param);
1.374 +
1.375 +
1.376 + - Same example as above, now using CPbkViewState:
1.377 +
1.378 + #include <CPbkViewState.h> // need also to add PbkView.lib into projects .mmp
1.379 + #include <PbkUID.h> // Phonebook UIDs
1.380 +
1.381 + CPbkViewState* pbkViewParam = CPbkViewState::NewLC();
1.382 + pbkViewParam->SetFocusedContactId(5);
1.383 + pbkViewParam->SetFocusedFieldIndex(3);
1.384 + HBufC8* paramBuf = pbkViewParam->PackLC();
1.385 +
1.386 + // Make view id with Phonebook's app UID3 and Contact Info View's id
1.387 + const TVwsViewId viewId(KPbkUID3, 4);
1.388 +
1.389 + // Activate the view
1.390 + AppUi()->ActivateViewL(viewId, CPbkViewState::Uid(), *paramBuf);
1.391 +
1.392 + // Cleanup
1.393 + CleanupStack::PopAndDestroy(2); // paramBuf, pbkViewParam
1.394 +
1.395 + - The latter example is cleaner, but using CPbkViewState from your
1.396 + application means that your application will have a dependency to
1.397 + CPbkViewState.h and PbkView.lib at compile time and to PbkView.dll at
1.398 + run time.
1.399 +
1.400 +*/
1.401 +
1.402 +#endif // __CPbkViewState_H__
1.403 +
1.404 +// End of File