1 cpbkviewstate.h

     1 /*

     2 * Copyright (c) 2002 Nokia Corporation and/or its subsidiary(-ies).

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * 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

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description: 

    15 *     View states.

    16 *

    17 */

    18 

    19 

    20 #ifndef __CPbkViewState_H__

    21 #define __CPbkViewState_H__

    22 

    23 //  INCLUDES

    24 #include <e32base.h>    // CBase

    25 #include <cntdef.h>     // TContactItemId, CContactIdArray

    26 

    27 // FORWARD DECLARATIONS

    28 class RReadStream;

    29 class RWriteStream;

    30 class CPbkFieldDataArray;

    31 

    32 // CLASS DECLARATION

    33 

    34 /**

    35  * Generic Phonebook view state class. Class can be used to pass parameters

    36  * the Phonebook application when launching the application with the symbian

    37  * view launching mechanism.

    38  */

    39 class CPbkViewState : public CBase

    40     {

    41     public:  // Types

    42         enum TDataType

    43             {

    44             EEnd = 0,

    45             EFocusedContactId,

    46             ETopContactId,

    47             EMarkedContactIds,

    48             EFocusedFieldIndex,

    49             ETopFieldIndex,

    50             EFieldDataArray,

    51             EParentContactId,

    52             EFlags

    53             };

    54 

    55         enum TFlags

    56             {

    57             /// Reset flags

    58             ENullFlags = 0,

    59             /// Focus the first item in list views

    60             EFocusFirst  = 0x0001,

    61             /// Focus the last item in list views

    62             EFocusLast   = 0x0002,

    63             /// Reset state to the view's initial state

    64             EInitialized = 0x0004,

    65             /// Send application to background

    66             ESendToBackground = 0x0008

    67             };

    68 

    69     public:  // Constructors and destructor

    70         /**

    71          * Creates and returns a new instance of this class.

    72          */

    73         IMPORT_C static CPbkViewState* NewL();

    74 

    75         /**

    76          * Like NewL(), but leaves the object on the cleanup stack

    77          * @see NewL

    78          */

    79         IMPORT_C static CPbkViewState* NewLC();

    80         

    81         /**

    82          * Creates and returns a new instance of this class initialized

    83          * from aStream.

    84          * @param aStream   A view state stream to internalize.

    85          */

    86         IMPORT_C static CPbkViewState* NewL(RReadStream& aStream);

    87         

    88         /**

    89          * Like NewL(RReadStream& aStream) but leaves the object on

    90          * the cleanup stack.

    91          * @see NewL(RReadStream& aStream)

    92          * @param aStream   A view state stream to internalize.

    93          */

    94         IMPORT_C static CPbkViewState* NewLC(RReadStream& aStream);

    95         

    96         /**

    97          * Creates and returns a new instance of this class initialized

    98          * from aBuf.

    99          * @param aBuf   A view state buffer to internalize.

   100          */

   101         IMPORT_C static CPbkViewState* NewL(const TDesC8& aBuf);

   102         

   103         /**

   104          * Like NewL(const TDesC8& aBuf) but leaves the object on

   105          * the cleanup stack.

   106          * @see NewL(const TDesC8& aBuf)

   107          * @param aBuf   A view state buffer to internalize.

   108          */

   109         IMPORT_C static CPbkViewState* NewLC(const TDesC8& aBuf);

   110 

   111         /**

   112          * Destructor.

   113          */

   114         ~CPbkViewState();

   115 

   116     public:  // Getters

   117         /**

   118          * Returns the message uid for use with view server messages.

   119          */

   120         IMPORT_C static TUid Uid();

   121 

   122         /**

   123          * Returns id of the focused contact.

   124          * @return  Contact item id of the focused contact, KNullContactId if not set.

   125          */

   126         IMPORT_C TContactItemId FocusedContactId() const;

   127 

   128         /**

   129          * Returns id of the topmost contact.

   130          * @return  Contact item id of the top contact, KNullContactId if not set.

   131          */

   132         IMPORT_C TContactItemId TopContactId() const;

   133 

   134         /**

   135          * Returns const array of marked contacts ids, NULL if not set. 

   136          * @return  Contact id array of the marked contacts, NULL if not set.

   137          */

   138         IMPORT_C const CContactIdArray* MarkedContactIds() const;

   139 

   140         /**

   141          * Returns array of marked contacts ids, NULL if not set. Owmership not

   142          * transferred.

   143          * @return  Contact id array of the marked contacts, NULL if not set.

   144          */

   145         IMPORT_C CContactIdArray* MarkedContactIds();

   146 

   147         /**

   148          * Returns index of the focused field (field is from FocusedContactId()), 

   149          * -1 when no field focused.

   150          * @return  Index of the focused field, -1 if no field is focused.

   151          */

   152         IMPORT_C TInt FocusedFieldIndex() const;

   153 

   154         /**

   155          * Returns index of the topmost field (field is from FocusedContactId()), 

   156          * -1 when no topmost field.

   157          * @return  Index of the topmost field, -1 if no topmost field.

   158          */

   159         IMPORT_C TInt TopFieldIndex() const;

   160 

   161         /**

   162          * Returns field data array, NULL if not set.

   163          * @return Field data array object, NULL if not set.

   164          */

   165         IMPORT_C CPbkFieldDataArray* FieldDataArray() const;

   166 

   167         /**

   168          * Returns the focused contact id's parent, KNullContactId if not set.

   169          * @return Focused contact id's parent, KNullContactId if not set.

   170          */

   171         IMPORT_C TContactItemId ParentContactId() const; 

   172 

   173         /**

   174          * Returns the view state flags. See CPbkViewState::TFlags.

   175          * @return  View state object flags

   176          */

   177         IMPORT_C TUint Flags() const;

   178 

   179     public:  // Setters

   180         /**

   181          * Sets id of the focused contact to aId.

   182          * @param aId   Sets the focused contact id.

   183          */

   184         IMPORT_C void SetFocusedContactId(TContactItemId aId);

   185 

   186         /**

   187          * Sets id of the topmost contact to aId.

   188          * @param aId   Sets the topmost contact id.

   189          */

   190         IMPORT_C void SetTopContactId(TContactItemId aId);

   191 

   192         /**

   193          * Sets the array of marked contact ids to aArray. Destroys previous

   194 		 * array and takes ownership of aArray.

   195          * @param aArray    Sets the marked contact ids.

   196          */

   197         IMPORT_C void SetMarkedContactIds(CContactIdArray* aArray);

   198 

   199         /**

   200          * Sets index of the focused field to aIndex (field from

   201 		 * FocusedContactId()), -1 when no field focused.

   202          * @param aIndex    Sets focused field index.

   203          */

   204         IMPORT_C void SetFocusedFieldIndex(TInt aIndex);

   205 

   206         /**

   207          * Sets index of the topmost field to aIndex (field from

   208 		 * FocusedContactId()), -1 when no topmost field.

   209          * @param aIndex    Sets the topmost field index.

   210          */

   211         IMPORT_C void SetTopFieldIndex(TInt aIndex);

   212 

   213         /**

   214          * Sets field data array to aArray. Destroys previous array

   215          * and takes ownership of aArray.

   216          * @param aFieldDataArray   Sets the field data array.

   217          */

   218         IMPORT_C void SetFieldDataArray(CPbkFieldDataArray* aFieldDataArray);

   219 

   220         /**

   221          * Reset this state to empty.

   222          */

   223         IMPORT_C void Reset();

   224 

   225         /**

   226          * Sets the focused contact ids parent contact id.

   227          * @param aParentContactId  Sets the contact ids parent id.

   228          */

   229         IMPORT_C void SetParentContactId(TContactItemId aParentContactId);

   230 

   231         /**

   232          * Sets the view state flags.

   233          * @param aFlags    Sets the view state parameters. See CPbkViewState::TFlags.

   234          */

   235         IMPORT_C void SetFlags(TUint aFlags);

   236 

   237         /**

   238          * Merges another view state to this view state by setting values from the

   239          * parameter and overriding any previous values in this state.

   240          *

   241          * @param aOtherState   The state to merge to this state. The 

   242          *                      properties which have a value in aOtherState

   243          *                      override properties in this object. The aOtherState

   244          *                      object may be modified by this function.

   245          */

   246         /*IMPORT_C*/ void MergeViewState(CPbkViewState& aOtherState);

   247 

   248     public:  // Stream support

   249         /**

   250          * Packages and returns this object in a buffer. Caller is responsible

   251          * of deleting the buffer.

   252          * @return  Packaged state in a buffer.

   253          */

   254         IMPORT_C HBufC8* PackL() const;

   255 

   256         /**

   257          * Like PackL, but leaves the buffer on the cleanup stack.

   258          * @see PackL

   259          * @return Packaged state in a buffer.

   260          */

   261         IMPORT_C HBufC8* PackLC() const;

   262 

   263         /**

   264          * Sets this state from aPack previously created with PackL.

   265          * @see PackL

   266          * @see PackLC

   267          * @param aPack Previously packaged state.

   268          */

   269         IMPORT_C void UnpackL(const TDesC8& aPack);

   270 

   271         /**

   272          * Externalizes this object to aStream.

   273          * @see InternalizeL

   274          * @param aSteam    Stream where to externalize this objects state.

   275          */

   276         IMPORT_C void ExternalizeL(RWriteStream& aStream) const;

   277 

   278         /**

   279          * Internalizes this object from aStream.

   280          * @see ExternalizeL

   281          * @param aStream   A stream from where this objects state can be internalized from.

   282          */

   283         IMPORT_C void InternalizeL(RReadStream& aStream);

   284 

   285     public: // Support functions

   286         IMPORT_C TBool operator==(const CPbkViewState& aRhs) const; 

   287 

   288     private:  // Implementation

   289         CPbkViewState();

   290 

   291     private:  // data

   292         /// Own: Id of the focused contact

   293         TContactItemId iFocusedContactId;

   294         /// Own: Id of the topmost contact

   295         TContactItemId iTopContactId;

   296         /// Own: Index of the focused field

   297         TInt iFocusedFieldIndex;

   298         /// Own: Index of the top field

   299         TInt iTopFieldIndex;

   300         /// Own: Array of marked contacts

   301         CContactIdArray* iMarkedContactIds;

   302         /// Own: Field data array

   303         CPbkFieldDataArray* iFieldDataArray;

   304         /// Own: Id of the focused contacts parent

   305         TContactItemId iParentContactId;

   306         /// Own: Flags

   307         TUint iFlags;

   308 

   309     private:  // const static data

   310         static const TUid KUid;

   311     };

   312 

   313 

   314 /*

   315    ** View state binary stream format **

   316    

   317     - View parameter UID is 0x101f4ccf

   318 

   319     - Format of the stream in (slightly freeform) BNF:

   320 

   321     <stream>  ::= <command>+

   322     <command> ::= Int8(opcode) parameters

   323     <opcode>  ::= EEnd | EFocusedContactId | ETopContactId | EMarkedContactIds |

   324                   EFocusedFieldIndex | ETopFieldIndex | EFieldDataArray

   325     <command> ::= EEnd  // no further commands are read after EEnd. EEnd is not mandatory in a stream.

   326     <command> ::= EFocusedContactId Int32(TContactItemId)

   327     <command> ::= ETopContactId Int32(TContactItemId)

   328     <command> ::= EMarkedContactIds (Int32(count) { Int32(TContactItemId) })  // count is count TContactItemIds

   329     <command> ::= EFocusedFieldIndex Int32(index)

   330     <command> ::= ETopFieldIndex Int32(index)

   331     <command> ::= EFieldDataArray <contactdata>

   332     <command> ::= EParentContactId Int32(TContactItemId)

   333 

   334     <contactdata> ::= Int32(count) { fielddata }  // count is count of fieldatas

   335     <fielddata> ::= <fieldtype> data

   336     <fieldtype> ::= ETypeText | ETypeTime

   337     <fielddata> ::= ETypeText (Int32(length) text)  // length is length of text in chars, text is unicode

   338     <fielddata> ::= ETypeTime (Int32(high) Int32(low))  // high and low words of a TTime's internal Int64

   339 

   340     Constants:

   341         EEnd = 0,

   342         EFocusedContactId = 1,

   343         ETopContactId = 2,

   344         EMarkedContactIds = 3,

   345         EFocusedFieldIndex = 4,

   346         ETopFieldIndex = 5,

   347         EFieldDataArray = 6,

   348         EParentContactId = 7

   349 

   350     - Example:

   351     Activate Phonebook's contact info view to show contact with id 5 and field 

   352     at index 3 focused:

   353 

   354     // Write parameters in a buffer

   355     TBuf8<16> param;

   356     RDesWriteStream stream(param);

   357     stream.PushL();

   358     param.WriteInt8L(1);  // opcode EFocusedContactId

   359     param.WriteInt32L(5);  // Contact id 5

   360     param.WriteInt8L(4);  // opcode EFocusedFieldIndex

   361     param.WriteInt32L(3);  // field index 3

   362     stream.CommitL();

   363     CleanupStack::PopAndDestroy();  // stream

   364 

   365     // Make view id with Phonebook's app UID3 and Contact Info View's id

   366     const TVwsViewId viewId(0x101f4cce, 4);

   367 

   368     // Activate the view

   369     AppUi()->ActivateViewL(viewId, TUid::Uid(0x101f4ccf), param);

   370 

   371 

   372     - Same example as above, now using CPbkViewState:

   373 

   374     #include <CPbkViewState.h>  // need also to add PbkView.lib into projects .mmp

   375     #include <PbkUID.h> // Phonebook UIDs

   376 

   377     CPbkViewState* pbkViewParam = CPbkViewState::NewLC();

   378     pbkViewParam->SetFocusedContactId(5);

   379     pbkViewParam->SetFocusedFieldIndex(3);

   380     HBufC8* paramBuf = pbkViewParam->PackLC();

   381     

   382     // Make view id with Phonebook's app UID3 and Contact Info View's id

   383     const TVwsViewId viewId(KPbkUID3, 4);

   384 

   385     // Activate the view

   386     AppUi()->ActivateViewL(viewId, CPbkViewState::Uid(), *paramBuf);

   387 

   388     // Cleanup

   389     CleanupStack::PopAndDestroy(2);  // paramBuf, pbkViewParam

   390 

   391     - The latter example is cleaner, but using CPbkViewState from your 

   392     application means that your application will have a dependency to 

   393     CPbkViewState.h and PbkView.lib at compile time and to PbkView.dll at

   394     run time.

   395 

   396 */

   397 

   398 #endif // __CPbkViewState_H__

   399             

   400 // End of File