/*
* 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 "Eclipse Public License v1.0"
* which accompanies this distribution, and is available
* at the URL "http://www.eclipse.org/legal/epl-v10.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