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