williamr@4: /*
williamr@4: * Copyright (c) 2005-2007 Nokia Corporation and/or its subsidiary(-ies).
williamr@4: * All rights reserved.
williamr@4: * This component and the accompanying materials are made available
williamr@4: * under the terms of "Eclipse Public License v1.0"
williamr@4: * which accompanies this distribution, and is available
williamr@4: * at the URL "http://www.eclipse.org/legal/epl-v10.html".
williamr@4: *
williamr@4: * Initial Contributors:
williamr@4: * Nokia Corporation - initial contribution.
williamr@4: *
williamr@4: * Contributors:
williamr@4: *
williamr@4: * Description:  Phonebook 2 view state.
williamr@4: *
williamr@4: */
williamr@4: 
williamr@4: 
williamr@4: 
williamr@4: /**
williamr@4:  *  VIEW STATE BINARY STREAM FORMAT
williamr@4:  *
williamr@4:  *  - View parameter UID is 0x102072a0
williamr@4:  *
williamr@4:  *  - Format of the stream in (slightly freeform) EBNF:
williamr@4:  *
williamr@4:  *  stream  ::= version , { command } ;
williamr@4:  *  version ::= Int8(1) ;
williamr@4:  *  command ::= Int8(EFocusedContact) , contactlink ;
williamr@4:  *  command ::= Int8(ETopContact) , contactlink ;
williamr@4:  *  command ::= Int8(EMarkedContacts) , Uint16(length) , MVPbkContactLinkArray(links) ;
williamr@4:  *  command ::= Int8(EFocusedFieldIndex) , Int32(index) ;
williamr@4:  *  command ::= Int8(ETopFieldIndex) , Int32(index) ;
williamr@4:  *  command ::= Int8(EParentContact) , contactlink ;
williamr@4:  *  command ::= Int8(EFocusedPropertiesIndex) , Int32(index) ;
williamr@4:  *  command ::= Int8(ETopPropertiesIndex) , Int32(index) ;
williamr@4:  *  command ::= Int8(EFlags) , Int32(flags) ;
williamr@4:  *  command ::= EEnd ; // no further commands are read after EEnd,
williamr@4:  *                     // EEnd is not mandatory in a stream
williamr@4:  *  contactlink ::= Uint16(length) , MVPbkContactLink(link) ;
williamr@4:  *
williamr@4:  *  Constants:
williamr@4:  *      EEnd                    = 0,
williamr@4:  *      EFocusedContact         = 1,
williamr@4:  *      ETopContact             = 2,
williamr@4:  *      EMarkedContacts         = 3,
williamr@4:  *      EFocusedFieldIndex      = 4,
williamr@4:  *      ETopFieldIndex          = 5,
williamr@4:  *      EParentContact          = 6
williamr@4:  *      EFlags                  = 7
williamr@4:  *      EFocusedPropertiesIndex = 8,
williamr@4:  *      ETopPropertiesIndex     = 9,
williamr@4:  *
williamr@4:  *  - Example:
williamr@4:  *  Activate Phonebook2's contact info view to show a contact
williamr@4:  *  with field at index 3 focused. This example assumes there
williamr@4:  *  is a contactLink variable of type MVPbkContactLink.
williamr@4:  *
williamr@4:  *  // Write parameters in a buffer
williamr@4:  *  TBuf8<256> param;
williamr@4:  *  RDesWriteStream stream( param );
williamr@4:  *  stream.PushL();
williamr@4:  *  stream.WriteInt8L(1);                   // version number
williamr@4:  *  stream.WriteInt8L( 1 );                 // opcode EFocusedContact
williamr@4:  *  HBufC8* buf = contactLink->PackLC();   // pack the contact link
williamr@4:  *  stream.WriteUint16L( buf->Length() );   // write link length
williamr@4:  *  stream.WriteL( *buf );                  // write the actual link buffer
williamr@4:  *  CleanupStack::PopAndDestroy();         // cleanup buf
williamr@4:  *  stream.WriteInt8L( 4 );                 // opcode EFocusedFieldIndex
williamr@4:  *  stream.WriteInt32L( 3 );                // field index 3
williamr@4:  *  stream.CommitL();
williamr@4:  *  CleanupStack::PopAndDestroy();         // cleanup stream
williamr@4:  *
williamr@4:  *  // Make view id with Phonebook2's app UID3 and Contact Info View's id
williamr@4:  *  // (view ids are defined in Pbk2ViewId.hrh)
williamr@4:  *  const TVwsViewId viewId( TUid::Uid(0x101f4cce), 4 );
williamr@4:  *
williamr@4:  *  // Activate the view
williamr@4:  *  AppUi()->ActivateViewL( viewId, TUid::Uid( 0x102072a0 ), param );
williamr@4:  *
williamr@4:  *
williamr@4:  *  - Same example as above, now using CPbk2ViewState:
williamr@4:  *
williamr@4:  *  #include <Pbk2UID.h>           // Phonebook 2 UIDs
williamr@4:  *  #include <CPbk2ViewState.h>    // need also to add Pbk2CommonUI.lib
williamr@4:  *                                 // into projects .mmp
williamr@4:  *
williamr@4:  *  CPbk2ViewState* pbk2ViewParam = CPbk2ViewState::NewLC();
williamr@4:  *  pbk2ViewParam->SetFocusedContact( contactLink );
williamr@4:  *  pbk2ViewParam->SetFocusedFieldIndex( 3 );
williamr@4:  *  HBufC8* paramBuf = pbk2ViewParam->PackLC();
williamr@4:  *
williamr@4:  *  // Make view id with Phonebook2's app UID3 and Contact Info View's id
williamr@4:  *  const TVwsViewId viewId( TUid::Uid(0x101f4cce), EPbk2ContactInfoViewId );
williamr@4:  *
williamr@4:  *  // Activate the view
williamr@4:  *  AppUi()->ActivateViewL( viewId, CPbk2ViewState::Uid(), *paramBuf );
williamr@4:  *
williamr@4:  *  // Cleanup
williamr@4:  *  CleanupStack::PopAndDestroy( 2 ); // paramBuf, pbk2ViewParam
williamr@4:  *
williamr@4:  *  - The latter example is cleaner, but using CPbk2ViewState from your
williamr@4:  *  application means that your application will have a dependency to
williamr@4:  *  CPbk2ViewState.h and Pbk2CommonUI.lib at compile time and to
williamr@4:  *  Pbk2CommonUI.dll at run time.
williamr@4:  */
williamr@4: 
williamr@4: #ifndef CPBK2VIEWSTATE_H
williamr@4: #define CPBK2VIEWSTATE_H
williamr@4: 
williamr@4: //  INCLUDES
williamr@4: #include <e32base.h>
williamr@4: 
williamr@4: // FORWARD DECLARATIONS
williamr@4: class RReadStream;
williamr@4: class RWriteStream;
williamr@4: class MVPbkContactLink;
williamr@4: class MVPbkContactLinkArray;
williamr@4: 
williamr@4: // CLASS DECLARATION
williamr@4: 
williamr@4: /**
williamr@4:  * Phonebook 2 view state.
williamr@4:  *
williamr@4:  * Responsible for storing the state of a Phonebook 2 view.
williamr@4:  * The state includes, for example, focused contact, focused
williamr@4:  * contact field and other information for restoring the state later.
williamr@4:  * This state object can be externalized to a buffer and
williamr@4:  * initialized from a buffer.
williamr@4:  */
williamr@4: class CPbk2ViewState : public CBase
williamr@4:     {
williamr@4:     public: // Types
williamr@4: 
williamr@4:         /// View state data types
williamr@4:         enum TDataType
williamr@4:             {
williamr@4:             EEnd = 0,
williamr@4:             /// Focused contact
williamr@4:             EFocusedContact,
williamr@4:             // Top most contact of the view
williamr@4:             ETopContact,
williamr@4:             /// Array of marked contacts
williamr@4:             EMarkedContacts,
williamr@4:             /// Index of the focused field
williamr@4:             EFocusedFieldIndex,
williamr@4:             /// Index of the topmost field of the view
williamr@4:             ETopFieldIndex,
williamr@4:             /// Parent contact
williamr@4:             EParentContact,
williamr@4:             /// View state flags
williamr@4:             EFlags,
williamr@4:             /// Index of the focused properties item
williamr@4:             EFocusedPropertiesIndex,
williamr@4:             /// Index of the topmost properties item of the view
williamr@4:             ETopPropertiesIndex
williamr@4:             };
williamr@4: 
williamr@4:         /// View state flags
williamr@4:         enum TFlags
williamr@4:             {
williamr@4:             /// Reset flags
williamr@4:             ENullFlags = 0,
williamr@4:             /// Focus the first item in list views
williamr@4:             EFocusFirst  = 0x0001,
williamr@4:             /// Focus the last item in list views
williamr@4:             EFocusLast   = 0x0002,
williamr@4:             /// Reset state to the view's initial state
williamr@4:             EInitialized = 0x0004,
williamr@4:             /// Send application to background
williamr@4:             ESendToBackground = 0x0008
williamr@4:             };
williamr@4: 
williamr@4:     public: // Constructors and destructor
williamr@4: 
williamr@4:         /**
williamr@4:          * Creates a new instace of this class.
williamr@4:          *
williamr@4:          * @return  A new instance of this class.
williamr@4:          */
williamr@4:         IMPORT_C static CPbk2ViewState* NewL();
williamr@4: 
williamr@4:         /**
williamr@4:          * Creates a new instace of this class.
williamr@4:          *
williamr@4:          * @return  A new instance of this class.
williamr@4:          */
williamr@4:         IMPORT_C static CPbk2ViewState* NewLC();
williamr@4: 
williamr@4:         /**
williamr@4:          * Creates a new instace of this class initialized from a buffer.
williamr@4:          * @see CPbk2ViewState::PackL and CPbk2ViewState::PackLC for
williamr@4:          * constructing the buffer.
williamr@4:          *
williamr@4:          * @param aBuf  Buffer to initialize this instance from.
williamr@4:          * @return  A new instance of this class.
williamr@4:          */
williamr@4:         IMPORT_C static CPbk2ViewState* NewL(
williamr@4:                 const TDesC8& aBuf );
williamr@4: 
williamr@4:         /**
williamr@4:          * Creates a new instace of this class initialized from a buffer.
williamr@4:          * @see CPbk2ViewState::PackL and CPbk2ViewState::PackLC for
williamr@4:          * constructing the buffer.
williamr@4:          *
williamr@4:          * @param aBuf  Buffer to initialize this instance from.
williamr@4:          * @return  A new instance of this class.
williamr@4:          */
williamr@4:         IMPORT_C static CPbk2ViewState* NewLC(
williamr@4:                 const TDesC8& aBuf );
williamr@4: 
williamr@4:         /**
williamr@4:          * Destructor.
williamr@4:          */
williamr@4:         ~CPbk2ViewState();
williamr@4: 
williamr@4:     public: // Getters
williamr@4: 
williamr@4:         /**
williamr@4:          * Returns the message uid for use with view server messages.
williamr@4:          *
williamr@4:          * @return  Message uid.
williamr@4:          */
williamr@4:         IMPORT_C static TUid Uid();
williamr@4: 
williamr@4:         /**
williamr@4:          * Returns a link to the focused contact.
williamr@4:          * Null if not set.
williamr@4:          *
williamr@4:          * @return  Link to the focused contact.
williamr@4:          */
williamr@4:         IMPORT_C const MVPbkContactLink* FocusedContact() const;
williamr@4: 
williamr@4:         /**
williamr@4:          * Returns a link to the focused contact.
williamr@4:          * Null if not set. Ownership is transferred to the caller.
williamr@4:          *
williamr@4:          * @return  Link to the focused contact.
williamr@4:          */
williamr@4:         IMPORT_C MVPbkContactLink* TakeFocusedContact();
williamr@4: 
williamr@4:         /**
williamr@4:          * Returns a link to the the topmost contact.
williamr@4:          * Null if not set.
williamr@4:          *
williamr@4:          * @return  Link to the topmost contact.
williamr@4:          */
williamr@4:         IMPORT_C const MVPbkContactLink* TopContact() const;
williamr@4: 
williamr@4:         /**
williamr@4:          * Returns a link to the topmost contact.
williamr@4:          * Null if not set. Ownership is transferred to caller.
williamr@4:          *
williamr@4:          * @return  Link to the topmost contact.
williamr@4:          */
williamr@4:         IMPORT_C MVPbkContactLink* TakeTopContact();
williamr@4: 
williamr@4:         /**
williamr@4:          * Returns a link to the parent contact.
williamr@4:          *
williamr@4:          * @return  Link to the parent contact.
williamr@4:          */
williamr@4:         IMPORT_C const MVPbkContactLink* ParentContact() const;
williamr@4: 
williamr@4:         /**
williamr@4:          * Returns a link to the parent contact.
williamr@4:          * Null if not set. Ownership is transferred to caller.
williamr@4:          *
williamr@4:          * @return  Link to the parent contact.
williamr@4:          */
williamr@4:         IMPORT_C MVPbkContactLink* TakeParentContact();
williamr@4: 
williamr@4:         /**
williamr@4:          * Returns const array of marked contacts.
williamr@4:          * NULL if not set.
williamr@4:          *
williamr@4:          * @return  Marked contacts in a link array.
williamr@4:          */
williamr@4:         IMPORT_C const MVPbkContactLinkArray* MarkedContacts() const;
williamr@4: 
williamr@4:         /**
williamr@4:          * Returns const array of marked contacts.
williamr@4:          * NULL if not set. Ownership is transferred to caller.
williamr@4:          *
williamr@4:          * @return  Marked contacts in a link array.
williamr@4:          */
williamr@4:         IMPORT_C MVPbkContactLinkArray* TakeMarkedContacts();
williamr@4: 
williamr@4:         /**
williamr@4:          * Returns the index of the focused field.
williamr@4:          * KErrNotFound indicates there is no
williamr@4:          * focused field information available.
williamr@4:          *
williamr@4:          * @return  Field index.
williamr@4:          */
williamr@4:         IMPORT_C TInt FocusedFieldIndex() const;
williamr@4: 
williamr@4:         /**
williamr@4:          * Returns the index of the top field.
williamr@4:          * KErrNotFound indicates there is no
williamr@4:          * focused field information available.
williamr@4:          *
williamr@4:          * @return  Field index.
williamr@4:          */
williamr@4:         IMPORT_C TInt TopFieldIndex() const;
williamr@4:         
williamr@4:         /**
williamr@4:          * Returns the index of the focused properties item.
williamr@4:          * KErrNotFound indicates there is no
williamr@4:          * focused properties item information available.
williamr@4:          *
williamr@4:          * @return  Properties item index.
williamr@4:          */
williamr@4:         IMPORT_C TInt FocusedPropertiesIndex() const;
williamr@4: 
williamr@4:         /**
williamr@4:          * Returns the index of the top properties item.
williamr@4:          * KErrNotFound indicates there is no
williamr@4:          * focused properties item information available.
williamr@4:          *
williamr@4:          * @return  Properties item index.
williamr@4:          */
williamr@4:         IMPORT_C TInt TopPropertiesIndex() const;
williamr@4: 
williamr@4:         /**
williamr@4:          * Returns the view state flags.
williamr@4:          *
williamr@4:          * @return  View state flags.
williamr@4:          */
williamr@4:         IMPORT_C TUint Flags() const;
williamr@4: 
williamr@4:     public: // Setters
williamr@4: 
williamr@4:         /**
williamr@4:          * Sets focused contact to given contact.
williamr@4:          *
williamr@4:          * @param aContact  The contact to set.
williamr@4:          */
williamr@4:         IMPORT_C void SetFocusedContact(
williamr@4:                 MVPbkContactLink* aContact );
williamr@4: 
williamr@4:         /**
williamr@4:          * Sets top contact to given contact.
williamr@4:          *
williamr@4:          * @param aTopContact  The contact to set.
williamr@4:          */
williamr@4:         IMPORT_C void SetTopContact(
williamr@4:                 MVPbkContactLink* aTopContact );
williamr@4: 
williamr@4:         /**
williamr@4:          * Sets parent contact to given contact.
williamr@4:          *
williamr@4:          * @param aParentContact  The contact to set.
williamr@4:          */
williamr@4:         IMPORT_C void SetParentContact(
williamr@4:                 MVPbkContactLink* aParentContact );
williamr@4: 
williamr@4:         /**
williamr@4:          * Sets marked contacts according to given array of contact links.
williamr@4:          *
williamr@4:          * @param aArray  The contacts to set marked.
williamr@4:          */
williamr@4:         IMPORT_C void SetMarkedContacts(
williamr@4:                 MVPbkContactLinkArray* aArray );
williamr@4: 
williamr@4:         /**
williamr@4:          * Sets the index of the focused field to the given index.
williamr@4:          * KErrNotFound indicates there is no focused field
williamr@4:          * information available.
williamr@4:          *
williamr@4:          * @param aIndex    The index to set.
williamr@4:          */
williamr@4:         IMPORT_C void SetFocusedFieldIndex(
williamr@4:                 TInt aIndex );
williamr@4: 
williamr@4:         /**
williamr@4:          * Sets the index of the topmost field to the given index.
williamr@4:          * KErrNotFound indicates there is no topmost field
williamr@4:          * information available.
williamr@4:          *
williamr@4:          * @param aIndex    The index to set.
williamr@4:          */
williamr@4:         IMPORT_C void SetTopFieldIndex(
williamr@4:                 TInt aIndex );
williamr@4:         
williamr@4:         /**
williamr@4:          * Sets the index of the focused properties item to the given index.
williamr@4:          * KErrNotFound indicates there is no focused properties item
williamr@4:          * information available.
williamr@4:          *
williamr@4:          * @param aIndex    The index to set.
williamr@4:          */
williamr@4:         IMPORT_C void SetFocusedPropertiesIndex(
williamr@4:                 TInt aIndex );
williamr@4: 
williamr@4:         /**
williamr@4:          * Sets the index of the topmost properties item to the given index.
williamr@4:          * KErrNotFound indicates there is no topmost properties item
williamr@4:          * information available.
williamr@4:          *
williamr@4:          * @param aIndex    The index to set.
williamr@4:          */
williamr@4:         IMPORT_C void SetTopPropertiesIndex(
williamr@4:                 TInt aIndex );
williamr@4: 
williamr@4:         /**
williamr@4:          * Reset this view state to an empty state.
williamr@4:          */
williamr@4:         IMPORT_C void Reset();
williamr@4: 
williamr@4:         /**
williamr@4:          * Sets the view state flags.
williamr@4:          *
williamr@4:          * @param aFlags    The flags to set.
williamr@4:          */
williamr@4:         IMPORT_C void SetFlags(
williamr@4:                 TUint aFlags );
williamr@4: 
williamr@4:     public: // Client-server support
williamr@4: 
williamr@4:         /**
williamr@4:          * Packages and returns this object in a buffer.
williamr@4:          * Caller is responsible for deleting the buffer.
williamr@4:          *
williamr@4:          * @return  This view state instance packaged into a buffer.
williamr@4:          */
williamr@4:         IMPORT_C HBufC8* PackL() const;
williamr@4: 
williamr@4:         /**
williamr@4:          * Packages and returns this object in a buffer.
williamr@4:          * Caller is responsible for deleting the buffer.
williamr@4:          *
williamr@4:          * @return  This view state instance packaged into a buffer.
williamr@4:          */
williamr@4:         IMPORT_C HBufC8* PackLC() const;
williamr@4: 
williamr@4:         /**
williamr@4:          * Sets this view state from given packaged buffer.
williamr@4:          *
williamr@4:          * @param aPack     Packaged view state buffer.
williamr@4:          */
williamr@4:         IMPORT_C void UnpackL(
williamr@4:                 const TDesC8& aPack );
williamr@4: 
williamr@4: 
williamr@4:     public: // Support functions
williamr@4: 
williamr@4:         /**
williamr@4:          * Comparison operator.
williamr@4:          *
williamr@4:          * @param aRhs  View state instance to compare to this instance.
williamr@4:          * @return  ETrue if view states are equal, EFalse otherwise.
williamr@4:          */
williamr@4:         IMPORT_C TBool operator==(
williamr@4:                 const CPbk2ViewState& aRhs ) const;
williamr@4: 
williamr@4:     private: // Implementation
williamr@4:         CPbk2ViewState();
williamr@4:         void ConstructL(
williamr@4:                 const TDesC8& aBuf );
williamr@4:         void ExternalizeL(
williamr@4:                 RWriteStream& aStream ) const;
williamr@4:         void InternalizeL(
williamr@4:                 RReadStream& aStream );
williamr@4: 
williamr@4:     private: // Data
williamr@4:         /// Own: Link to the focused contact.
williamr@4:         MVPbkContactLink* iFocusedContact;
williamr@4:         /// Own: Link to the topmost contact.
williamr@4:         MVPbkContactLink* iTopContact;
williamr@4:         /// Own: Link to the parent contact.
williamr@4:         MVPbkContactLink* iParentContact;
williamr@4:         /// Own: Array of marked contacts.
williamr@4:         MVPbkContactLinkArray* iArray;
williamr@4:         /// Own: Index of the focused field
williamr@4:         TInt iFocusedFieldIndex;
williamr@4:         /// Own: Index of the top field
williamr@4:         TInt iTopFieldIndex;
williamr@4:         /// Own: Index of the properties item
williamr@4:         TInt iFocusedPropertiesIndex;
williamr@4:         /// Own: Index of the top properties item
williamr@4:         TInt iTopPropertiesIndex;
williamr@4:         /// Own: Flags
williamr@4:         TUint iFlags;
williamr@4: 
williamr@4:     private: // Const static data
williamr@4:         static const TUid KUid;
williamr@4:     };
williamr@4: 
williamr@4: #endif // CPBK2VIEWSTATE_H
williamr@4: 
williamr@4: // End of File