--- a/epoc32/include/app/cpbkviewstate.h Tue Nov 24 13:55:44 2009 +0000
+++ b/epoc32/include/app/cpbkviewstate.h Tue Mar 16 16:12:26 2010 +0000
@@ -1,1 +1,400 @@
-cpbkviewstate.h
+/*
+* Copyright (c) 2002 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:
+* View states.
+*
+*/
+
+
+#ifndef __CPbkViewState_H__
+#define __CPbkViewState_H__
+
+// INCLUDES
+#include <e32base.h> // CBase
+#include <cntdef.h> // TContactItemId, CContactIdArray
+
+// FORWARD DECLARATIONS
+class RReadStream;
+class RWriteStream;
+class CPbkFieldDataArray;
+
+// CLASS DECLARATION
+
+/**
+ * Generic Phonebook view state class. Class can be used to pass parameters
+ * the Phonebook application when launching the application with the symbian
+ * view launching mechanism.
+ */
+class CPbkViewState : public CBase
+ {
+ public: // Types
+ enum TDataType
+ {
+ EEnd = 0,
+ EFocusedContactId,
+ ETopContactId,
+ EMarkedContactIds,
+ EFocusedFieldIndex,
+ ETopFieldIndex,
+ EFieldDataArray,
+ EParentContactId,
+ EFlags
+ };
+
+ enum TFlags
+ {
+ /// Reset flags
+ ENullFlags = 0,
+ /// Focus the first item in list views
+ EFocusFirst = 0x0001,
+ /// Focus the last item in list views
+ EFocusLast = 0x0002,
+ /// Reset state to the view's initial state
+ EInitialized = 0x0004,
+ /// Send application to background
+ ESendToBackground = 0x0008
+ };
+
+ public: // Constructors and destructor
+ /**
+ * Creates and returns a new instance of this class.
+ */
+ IMPORT_C static CPbkViewState* NewL();
+
+ /**
+ * Like NewL(), but leaves the object on the cleanup stack
+ * @see NewL
+ */
+ IMPORT_C static CPbkViewState* NewLC();
+
+ /**
+ * Creates and returns a new instance of this class initialized
+ * from aStream.
+ * @param aStream A view state stream to internalize.
+ */
+ IMPORT_C static CPbkViewState* NewL(RReadStream& aStream);
+
+ /**
+ * Like NewL(RReadStream& aStream) but leaves the object on
+ * the cleanup stack.
+ * @see NewL(RReadStream& aStream)
+ * @param aStream A view state stream to internalize.
+ */
+ IMPORT_C static CPbkViewState* NewLC(RReadStream& aStream);
+
+ /**
+ * Creates and returns a new instance of this class initialized
+ * from aBuf.
+ * @param aBuf A view state buffer to internalize.
+ */
+ IMPORT_C static CPbkViewState* NewL(const TDesC8& aBuf);
+
+ /**
+ * Like NewL(const TDesC8& aBuf) but leaves the object on
+ * the cleanup stack.
+ * @see NewL(const TDesC8& aBuf)
+ * @param aBuf A view state buffer to internalize.
+ */
+ IMPORT_C static CPbkViewState* NewLC(const TDesC8& aBuf);
+
+ /**
+ * Destructor.
+ */
+ ~CPbkViewState();
+
+ public: // Getters
+ /**
+ * Returns the message uid for use with view server messages.
+ */
+ IMPORT_C static TUid Uid();
+
+ /**
+ * Returns id of the focused contact.
+ * @return Contact item id of the focused contact, KNullContactId if not set.
+ */
+ IMPORT_C TContactItemId FocusedContactId() const;
+
+ /**
+ * Returns id of the topmost contact.
+ * @return Contact item id of the top contact, KNullContactId if not set.
+ */
+ IMPORT_C TContactItemId TopContactId() const;
+
+ /**
+ * Returns const array of marked contacts ids, NULL if not set.
+ * @return Contact id array of the marked contacts, NULL if not set.
+ */
+ IMPORT_C const CContactIdArray* MarkedContactIds() const;
+
+ /**
+ * Returns array of marked contacts ids, NULL if not set. Owmership not
+ * transferred.
+ * @return Contact id array of the marked contacts, NULL if not set.
+ */
+ IMPORT_C CContactIdArray* MarkedContactIds();
+
+ /**
+ * Returns index of the focused field (field is from FocusedContactId()),
+ * -1 when no field focused.
+ * @return Index of the focused field, -1 if no field is focused.
+ */
+ IMPORT_C TInt FocusedFieldIndex() const;
+
+ /**
+ * Returns index of the topmost field (field is from FocusedContactId()),
+ * -1 when no topmost field.
+ * @return Index of the topmost field, -1 if no topmost field.
+ */
+ IMPORT_C TInt TopFieldIndex() const;
+
+ /**
+ * Returns field data array, NULL if not set.
+ * @return Field data array object, NULL if not set.
+ */
+ IMPORT_C CPbkFieldDataArray* FieldDataArray() const;
+
+ /**
+ * Returns the focused contact id's parent, KNullContactId if not set.
+ * @return Focused contact id's parent, KNullContactId if not set.
+ */
+ IMPORT_C TContactItemId ParentContactId() const;
+
+ /**
+ * Returns the view state flags. See CPbkViewState::TFlags.
+ * @return View state object flags
+ */
+ IMPORT_C TUint Flags() const;
+
+ public: // Setters
+ /**
+ * Sets id of the focused contact to aId.
+ * @param aId Sets the focused contact id.
+ */
+ IMPORT_C void SetFocusedContactId(TContactItemId aId);
+
+ /**
+ * Sets id of the topmost contact to aId.
+ * @param aId Sets the topmost contact id.
+ */
+ IMPORT_C void SetTopContactId(TContactItemId aId);
+
+ /**
+ * Sets the array of marked contact ids to aArray. Destroys previous
+ * array and takes ownership of aArray.
+ * @param aArray Sets the marked contact ids.
+ */
+ IMPORT_C void SetMarkedContactIds(CContactIdArray* aArray);
+
+ /**
+ * Sets index of the focused field to aIndex (field from
+ * FocusedContactId()), -1 when no field focused.
+ * @param aIndex Sets focused field index.
+ */
+ IMPORT_C void SetFocusedFieldIndex(TInt aIndex);
+
+ /**
+ * Sets index of the topmost field to aIndex (field from
+ * FocusedContactId()), -1 when no topmost field.
+ * @param aIndex Sets the topmost field index.
+ */
+ IMPORT_C void SetTopFieldIndex(TInt aIndex);
+
+ /**
+ * Sets field data array to aArray. Destroys previous array
+ * and takes ownership of aArray.
+ * @param aFieldDataArray Sets the field data array.
+ */
+ IMPORT_C void SetFieldDataArray(CPbkFieldDataArray* aFieldDataArray);
+
+ /**
+ * Reset this state to empty.
+ */
+ IMPORT_C void Reset();
+
+ /**
+ * Sets the focused contact ids parent contact id.
+ * @param aParentContactId Sets the contact ids parent id.
+ */
+ IMPORT_C void SetParentContactId(TContactItemId aParentContactId);
+
+ /**
+ * Sets the view state flags.
+ * @param aFlags Sets the view state parameters. See CPbkViewState::TFlags.
+ */
+ IMPORT_C void SetFlags(TUint aFlags);
+
+ /**
+ * Merges another view state to this view state by setting values from the
+ * parameter and overriding any previous values in this state.
+ *
+ * @param aOtherState The state to merge to this state. The
+ * properties which have a value in aOtherState
+ * override properties in this object. The aOtherState
+ * object may be modified by this function.
+ */
+ /*IMPORT_C*/ void MergeViewState(CPbkViewState& aOtherState);
+
+ public: // Stream support
+ /**
+ * Packages and returns this object in a buffer. Caller is responsible
+ * of deleting the buffer.
+ * @return Packaged state in a buffer.
+ */
+ IMPORT_C HBufC8* PackL() const;
+
+ /**
+ * Like PackL, but leaves the buffer on the cleanup stack.
+ * @see PackL
+ * @return Packaged state in a buffer.
+ */
+ IMPORT_C HBufC8* PackLC() const;
+
+ /**
+ * Sets this state from aPack previously created with PackL.
+ * @see PackL
+ * @see PackLC
+ * @param aPack Previously packaged state.
+ */
+ IMPORT_C void UnpackL(const TDesC8& aPack);
+
+ /**
+ * Externalizes this object to aStream.
+ * @see InternalizeL
+ * @param aSteam Stream where to externalize this objects state.
+ */
+ IMPORT_C void ExternalizeL(RWriteStream& aStream) const;
+
+ /**
+ * Internalizes this object from aStream.
+ * @see ExternalizeL
+ * @param aStream A stream from where this objects state can be internalized from.
+ */
+ IMPORT_C void InternalizeL(RReadStream& aStream);
+
+ public: // Support functions
+ IMPORT_C TBool operator==(const CPbkViewState& aRhs) const;
+
+ private: // Implementation
+ CPbkViewState();
+
+ private: // data
+ /// Own: Id of the focused contact
+ TContactItemId iFocusedContactId;
+ /// Own: Id of the topmost contact
+ TContactItemId iTopContactId;
+ /// Own: Index of the focused field
+ TInt iFocusedFieldIndex;
+ /// Own: Index of the top field
+ TInt iTopFieldIndex;
+ /// Own: Array of marked contacts
+ CContactIdArray* iMarkedContactIds;
+ /// Own: Field data array
+ CPbkFieldDataArray* iFieldDataArray;
+ /// Own: Id of the focused contacts parent
+ TContactItemId iParentContactId;
+ /// Own: Flags
+ TUint iFlags;
+
+ private: // const static data
+ static const TUid KUid;
+ };
+
+
+/*
+ ** View state binary stream format **
+
+ - View parameter UID is 0x101f4ccf
+
+ - Format of the stream in (slightly freeform) BNF:
+
+ <stream> ::= <command>+
+ <command> ::= Int8(opcode) parameters
+ <opcode> ::= EEnd | EFocusedContactId | ETopContactId | EMarkedContactIds |
+ EFocusedFieldIndex | ETopFieldIndex | EFieldDataArray
+ <command> ::= EEnd // no further commands are read after EEnd. EEnd is not mandatory in a stream.
+ <command> ::= EFocusedContactId Int32(TContactItemId)
+ <command> ::= ETopContactId Int32(TContactItemId)
+ <command> ::= EMarkedContactIds (Int32(count) { Int32(TContactItemId) }) // count is count TContactItemIds
+ <command> ::= EFocusedFieldIndex Int32(index)
+ <command> ::= ETopFieldIndex Int32(index)
+ <command> ::= EFieldDataArray <contactdata>
+ <command> ::= EParentContactId Int32(TContactItemId)
+
+ <contactdata> ::= Int32(count) { fielddata } // count is count of fieldatas
+ <fielddata> ::= <fieldtype> data
+ <fieldtype> ::= ETypeText | ETypeTime
+ <fielddata> ::= ETypeText (Int32(length) text) // length is length of text in chars, text is unicode
+ <fielddata> ::= ETypeTime (Int32(high) Int32(low)) // high and low words of a TTime's internal Int64
+
+ Constants:
+ EEnd = 0,
+ EFocusedContactId = 1,
+ ETopContactId = 2,
+ EMarkedContactIds = 3,
+ EFocusedFieldIndex = 4,
+ ETopFieldIndex = 5,
+ EFieldDataArray = 6,
+ EParentContactId = 7
+
+ - Example:
+ Activate Phonebook's contact info view to show contact with id 5 and field
+ at index 3 focused:
+
+ // Write parameters in a buffer
+ TBuf8<16> param;
+ RDesWriteStream stream(param);
+ stream.PushL();
+ param.WriteInt8L(1); // opcode EFocusedContactId
+ param.WriteInt32L(5); // Contact id 5
+ param.WriteInt8L(4); // opcode EFocusedFieldIndex
+ param.WriteInt32L(3); // field index 3
+ stream.CommitL();
+ CleanupStack::PopAndDestroy(); // stream
+
+ // Make view id with Phonebook's app UID3 and Contact Info View's id
+ const TVwsViewId viewId(0x101f4cce, 4);
+
+ // Activate the view
+ AppUi()->ActivateViewL(viewId, TUid::Uid(0x101f4ccf), param);
+
+
+ - Same example as above, now using CPbkViewState:
+
+ #include <CPbkViewState.h> // need also to add PbkView.lib into projects .mmp
+ #include <PbkUID.h> // Phonebook UIDs
+
+ CPbkViewState* pbkViewParam = CPbkViewState::NewLC();
+ pbkViewParam->SetFocusedContactId(5);
+ pbkViewParam->SetFocusedFieldIndex(3);
+ HBufC8* paramBuf = pbkViewParam->PackLC();
+
+ // Make view id with Phonebook's app UID3 and Contact Info View's id
+ const TVwsViewId viewId(KPbkUID3, 4);
+
+ // Activate the view
+ AppUi()->ActivateViewL(viewId, CPbkViewState::Uid(), *paramBuf);
+
+ // Cleanup
+ CleanupStack::PopAndDestroy(2); // paramBuf, pbkViewParam
+
+ - The latter example is cleaner, but using CPbkViewState from your
+ application means that your application will have a dependency to
+ CPbkViewState.h and PbkView.lib at compile time and to PbkView.dll at
+ run time.
+
+*/
+
+#endif // __CPbkViewState_H__
+
+// End of File