epoc32/include/app/CPbk2ViewState.h
branchSymbian3
changeset 4 837f303aceeb
     1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/epoc32/include/app/CPbk2ViewState.h	Wed Mar 31 12:33:34 2010 +0100
     1.3 @@ -0,0 +1,492 @@
     1.4 +/*
     1.5 +* Copyright (c) 2005-2007 Nokia Corporation and/or its subsidiary(-ies).
     1.6 +* All rights reserved.
     1.7 +* This component and the accompanying materials are made available
     1.8 +* under the terms of "Eclipse Public License v1.0"
     1.9 +* which accompanies this distribution, and is available
    1.10 +* at the URL "http://www.eclipse.org/legal/epl-v10.html".
    1.11 +*
    1.12 +* Initial Contributors:
    1.13 +* Nokia Corporation - initial contribution.
    1.14 +*
    1.15 +* Contributors:
    1.16 +*
    1.17 +* Description:  Phonebook 2 view state.
    1.18 +*
    1.19 +*/
    1.20 +
    1.21 +
    1.22 +
    1.23 +/**
    1.24 + *  VIEW STATE BINARY STREAM FORMAT
    1.25 + *
    1.26 + *  - View parameter UID is 0x102072a0
    1.27 + *
    1.28 + *  - Format of the stream in (slightly freeform) EBNF:
    1.29 + *
    1.30 + *  stream  ::= version , { command } ;
    1.31 + *  version ::= Int8(1) ;
    1.32 + *  command ::= Int8(EFocusedContact) , contactlink ;
    1.33 + *  command ::= Int8(ETopContact) , contactlink ;
    1.34 + *  command ::= Int8(EMarkedContacts) , Uint16(length) , MVPbkContactLinkArray(links) ;
    1.35 + *  command ::= Int8(EFocusedFieldIndex) , Int32(index) ;
    1.36 + *  command ::= Int8(ETopFieldIndex) , Int32(index) ;
    1.37 + *  command ::= Int8(EParentContact) , contactlink ;
    1.38 + *  command ::= Int8(EFocusedPropertiesIndex) , Int32(index) ;
    1.39 + *  command ::= Int8(ETopPropertiesIndex) , Int32(index) ;
    1.40 + *  command ::= Int8(EFlags) , Int32(flags) ;
    1.41 + *  command ::= EEnd ; // no further commands are read after EEnd,
    1.42 + *                     // EEnd is not mandatory in a stream
    1.43 + *  contactlink ::= Uint16(length) , MVPbkContactLink(link) ;
    1.44 + *
    1.45 + *  Constants:
    1.46 + *      EEnd                    = 0,
    1.47 + *      EFocusedContact         = 1,
    1.48 + *      ETopContact             = 2,
    1.49 + *      EMarkedContacts         = 3,
    1.50 + *      EFocusedFieldIndex      = 4,
    1.51 + *      ETopFieldIndex          = 5,
    1.52 + *      EParentContact          = 6
    1.53 + *      EFlags                  = 7
    1.54 + *      EFocusedPropertiesIndex = 8,
    1.55 + *      ETopPropertiesIndex     = 9,
    1.56 + *
    1.57 + *  - Example:
    1.58 + *  Activate Phonebook2's contact info view to show a contact
    1.59 + *  with field at index 3 focused. This example assumes there
    1.60 + *  is a contactLink variable of type MVPbkContactLink.
    1.61 + *
    1.62 + *  // Write parameters in a buffer
    1.63 + *  TBuf8<256> param;
    1.64 + *  RDesWriteStream stream( param );
    1.65 + *  stream.PushL();
    1.66 + *  stream.WriteInt8L(1);                   // version number
    1.67 + *  stream.WriteInt8L( 1 );                 // opcode EFocusedContact
    1.68 + *  HBufC8* buf = contactLink->PackLC();   // pack the contact link
    1.69 + *  stream.WriteUint16L( buf->Length() );   // write link length
    1.70 + *  stream.WriteL( *buf );                  // write the actual link buffer
    1.71 + *  CleanupStack::PopAndDestroy();         // cleanup buf
    1.72 + *  stream.WriteInt8L( 4 );                 // opcode EFocusedFieldIndex
    1.73 + *  stream.WriteInt32L( 3 );                // field index 3
    1.74 + *  stream.CommitL();
    1.75 + *  CleanupStack::PopAndDestroy();         // cleanup stream
    1.76 + *
    1.77 + *  // Make view id with Phonebook2's app UID3 and Contact Info View's id
    1.78 + *  // (view ids are defined in Pbk2ViewId.hrh)
    1.79 + *  const TVwsViewId viewId( TUid::Uid(0x101f4cce), 4 );
    1.80 + *
    1.81 + *  // Activate the view
    1.82 + *  AppUi()->ActivateViewL( viewId, TUid::Uid( 0x102072a0 ), param );
    1.83 + *
    1.84 + *
    1.85 + *  - Same example as above, now using CPbk2ViewState:
    1.86 + *
    1.87 + *  #include <Pbk2UID.h>           // Phonebook 2 UIDs
    1.88 + *  #include <CPbk2ViewState.h>    // need also to add Pbk2CommonUI.lib
    1.89 + *                                 // into projects .mmp
    1.90 + *
    1.91 + *  CPbk2ViewState* pbk2ViewParam = CPbk2ViewState::NewLC();
    1.92 + *  pbk2ViewParam->SetFocusedContact( contactLink );
    1.93 + *  pbk2ViewParam->SetFocusedFieldIndex( 3 );
    1.94 + *  HBufC8* paramBuf = pbk2ViewParam->PackLC();
    1.95 + *
    1.96 + *  // Make view id with Phonebook2's app UID3 and Contact Info View's id
    1.97 + *  const TVwsViewId viewId( TUid::Uid(0x101f4cce), EPbk2ContactInfoViewId );
    1.98 + *
    1.99 + *  // Activate the view
   1.100 + *  AppUi()->ActivateViewL( viewId, CPbk2ViewState::Uid(), *paramBuf );
   1.101 + *
   1.102 + *  // Cleanup
   1.103 + *  CleanupStack::PopAndDestroy( 2 ); // paramBuf, pbk2ViewParam
   1.104 + *
   1.105 + *  - The latter example is cleaner, but using CPbk2ViewState from your
   1.106 + *  application means that your application will have a dependency to
   1.107 + *  CPbk2ViewState.h and Pbk2CommonUI.lib at compile time and to
   1.108 + *  Pbk2CommonUI.dll at run time.
   1.109 + */
   1.110 +
   1.111 +#ifndef CPBK2VIEWSTATE_H
   1.112 +#define CPBK2VIEWSTATE_H
   1.113 +
   1.114 +//  INCLUDES
   1.115 +#include <e32base.h>
   1.116 +
   1.117 +// FORWARD DECLARATIONS
   1.118 +class RReadStream;
   1.119 +class RWriteStream;
   1.120 +class MVPbkContactLink;
   1.121 +class MVPbkContactLinkArray;
   1.122 +
   1.123 +// CLASS DECLARATION
   1.124 +
   1.125 +/**
   1.126 + * Phonebook 2 view state.
   1.127 + *
   1.128 + * Responsible for storing the state of a Phonebook 2 view.
   1.129 + * The state includes, for example, focused contact, focused
   1.130 + * contact field and other information for restoring the state later.
   1.131 + * This state object can be externalized to a buffer and
   1.132 + * initialized from a buffer.
   1.133 + */
   1.134 +class CPbk2ViewState : public CBase
   1.135 +    {
   1.136 +    public: // Types
   1.137 +
   1.138 +        /// View state data types
   1.139 +        enum TDataType
   1.140 +            {
   1.141 +            EEnd = 0,
   1.142 +            /// Focused contact
   1.143 +            EFocusedContact,
   1.144 +            // Top most contact of the view
   1.145 +            ETopContact,
   1.146 +            /// Array of marked contacts
   1.147 +            EMarkedContacts,
   1.148 +            /// Index of the focused field
   1.149 +            EFocusedFieldIndex,
   1.150 +            /// Index of the topmost field of the view
   1.151 +            ETopFieldIndex,
   1.152 +            /// Parent contact
   1.153 +            EParentContact,
   1.154 +            /// View state flags
   1.155 +            EFlags,
   1.156 +            /// Index of the focused properties item
   1.157 +            EFocusedPropertiesIndex,
   1.158 +            /// Index of the topmost properties item of the view
   1.159 +            ETopPropertiesIndex
   1.160 +            };
   1.161 +
   1.162 +        /// View state flags
   1.163 +        enum TFlags
   1.164 +            {
   1.165 +            /// Reset flags
   1.166 +            ENullFlags = 0,
   1.167 +            /// Focus the first item in list views
   1.168 +            EFocusFirst  = 0x0001,
   1.169 +            /// Focus the last item in list views
   1.170 +            EFocusLast   = 0x0002,
   1.171 +            /// Reset state to the view's initial state
   1.172 +            EInitialized = 0x0004,
   1.173 +            /// Send application to background
   1.174 +            ESendToBackground = 0x0008
   1.175 +            };
   1.176 +
   1.177 +    public: // Constructors and destructor
   1.178 +
   1.179 +        /**
   1.180 +         * Creates a new instace of this class.
   1.181 +         *
   1.182 +         * @return  A new instance of this class.
   1.183 +         */
   1.184 +        IMPORT_C static CPbk2ViewState* NewL();
   1.185 +
   1.186 +        /**
   1.187 +         * Creates a new instace of this class.
   1.188 +         *
   1.189 +         * @return  A new instance of this class.
   1.190 +         */
   1.191 +        IMPORT_C static CPbk2ViewState* NewLC();
   1.192 +
   1.193 +        /**
   1.194 +         * Creates a new instace of this class initialized from a buffer.
   1.195 +         * @see CPbk2ViewState::PackL and CPbk2ViewState::PackLC for
   1.196 +         * constructing the buffer.
   1.197 +         *
   1.198 +         * @param aBuf  Buffer to initialize this instance from.
   1.199 +         * @return  A new instance of this class.
   1.200 +         */
   1.201 +        IMPORT_C static CPbk2ViewState* NewL(
   1.202 +                const TDesC8& aBuf );
   1.203 +
   1.204 +        /**
   1.205 +         * Creates a new instace of this class initialized from a buffer.
   1.206 +         * @see CPbk2ViewState::PackL and CPbk2ViewState::PackLC for
   1.207 +         * constructing the buffer.
   1.208 +         *
   1.209 +         * @param aBuf  Buffer to initialize this instance from.
   1.210 +         * @return  A new instance of this class.
   1.211 +         */
   1.212 +        IMPORT_C static CPbk2ViewState* NewLC(
   1.213 +                const TDesC8& aBuf );
   1.214 +
   1.215 +        /**
   1.216 +         * Destructor.
   1.217 +         */
   1.218 +        ~CPbk2ViewState();
   1.219 +
   1.220 +    public: // Getters
   1.221 +
   1.222 +        /**
   1.223 +         * Returns the message uid for use with view server messages.
   1.224 +         *
   1.225 +         * @return  Message uid.
   1.226 +         */
   1.227 +        IMPORT_C static TUid Uid();
   1.228 +
   1.229 +        /**
   1.230 +         * Returns a link to the focused contact.
   1.231 +         * Null if not set.
   1.232 +         *
   1.233 +         * @return  Link to the focused contact.
   1.234 +         */
   1.235 +        IMPORT_C const MVPbkContactLink* FocusedContact() const;
   1.236 +
   1.237 +        /**
   1.238 +         * Returns a link to the focused contact.
   1.239 +         * Null if not set. Ownership is transferred to the caller.
   1.240 +         *
   1.241 +         * @return  Link to the focused contact.
   1.242 +         */
   1.243 +        IMPORT_C MVPbkContactLink* TakeFocusedContact();
   1.244 +
   1.245 +        /**
   1.246 +         * Returns a link to the the topmost contact.
   1.247 +         * Null if not set.
   1.248 +         *
   1.249 +         * @return  Link to the topmost contact.
   1.250 +         */
   1.251 +        IMPORT_C const MVPbkContactLink* TopContact() const;
   1.252 +
   1.253 +        /**
   1.254 +         * Returns a link to the topmost contact.
   1.255 +         * Null if not set. Ownership is transferred to caller.
   1.256 +         *
   1.257 +         * @return  Link to the topmost contact.
   1.258 +         */
   1.259 +        IMPORT_C MVPbkContactLink* TakeTopContact();
   1.260 +
   1.261 +        /**
   1.262 +         * Returns a link to the parent contact.
   1.263 +         *
   1.264 +         * @return  Link to the parent contact.
   1.265 +         */
   1.266 +        IMPORT_C const MVPbkContactLink* ParentContact() const;
   1.267 +
   1.268 +        /**
   1.269 +         * Returns a link to the parent contact.
   1.270 +         * Null if not set. Ownership is transferred to caller.
   1.271 +         *
   1.272 +         * @return  Link to the parent contact.
   1.273 +         */
   1.274 +        IMPORT_C MVPbkContactLink* TakeParentContact();
   1.275 +
   1.276 +        /**
   1.277 +         * Returns const array of marked contacts.
   1.278 +         * NULL if not set.
   1.279 +         *
   1.280 +         * @return  Marked contacts in a link array.
   1.281 +         */
   1.282 +        IMPORT_C const MVPbkContactLinkArray* MarkedContacts() const;
   1.283 +
   1.284 +        /**
   1.285 +         * Returns const array of marked contacts.
   1.286 +         * NULL if not set. Ownership is transferred to caller.
   1.287 +         *
   1.288 +         * @return  Marked contacts in a link array.
   1.289 +         */
   1.290 +        IMPORT_C MVPbkContactLinkArray* TakeMarkedContacts();
   1.291 +
   1.292 +        /**
   1.293 +         * Returns the index of the focused field.
   1.294 +         * KErrNotFound indicates there is no
   1.295 +         * focused field information available.
   1.296 +         *
   1.297 +         * @return  Field index.
   1.298 +         */
   1.299 +        IMPORT_C TInt FocusedFieldIndex() const;
   1.300 +
   1.301 +        /**
   1.302 +         * Returns the index of the top field.
   1.303 +         * KErrNotFound indicates there is no
   1.304 +         * focused field information available.
   1.305 +         *
   1.306 +         * @return  Field index.
   1.307 +         */
   1.308 +        IMPORT_C TInt TopFieldIndex() const;
   1.309 +        
   1.310 +        /**
   1.311 +         * Returns the index of the focused properties item.
   1.312 +         * KErrNotFound indicates there is no
   1.313 +         * focused properties item information available.
   1.314 +         *
   1.315 +         * @return  Properties item index.
   1.316 +         */
   1.317 +        IMPORT_C TInt FocusedPropertiesIndex() const;
   1.318 +
   1.319 +        /**
   1.320 +         * Returns the index of the top properties item.
   1.321 +         * KErrNotFound indicates there is no
   1.322 +         * focused properties item information available.
   1.323 +         *
   1.324 +         * @return  Properties item index.
   1.325 +         */
   1.326 +        IMPORT_C TInt TopPropertiesIndex() const;
   1.327 +
   1.328 +        /**
   1.329 +         * Returns the view state flags.
   1.330 +         *
   1.331 +         * @return  View state flags.
   1.332 +         */
   1.333 +        IMPORT_C TUint Flags() const;
   1.334 +
   1.335 +    public: // Setters
   1.336 +
   1.337 +        /**
   1.338 +         * Sets focused contact to given contact.
   1.339 +         *
   1.340 +         * @param aContact  The contact to set.
   1.341 +         */
   1.342 +        IMPORT_C void SetFocusedContact(
   1.343 +                MVPbkContactLink* aContact );
   1.344 +
   1.345 +        /**
   1.346 +         * Sets top contact to given contact.
   1.347 +         *
   1.348 +         * @param aTopContact  The contact to set.
   1.349 +         */
   1.350 +        IMPORT_C void SetTopContact(
   1.351 +                MVPbkContactLink* aTopContact );
   1.352 +
   1.353 +        /**
   1.354 +         * Sets parent contact to given contact.
   1.355 +         *
   1.356 +         * @param aParentContact  The contact to set.
   1.357 +         */
   1.358 +        IMPORT_C void SetParentContact(
   1.359 +                MVPbkContactLink* aParentContact );
   1.360 +
   1.361 +        /**
   1.362 +         * Sets marked contacts according to given array of contact links.
   1.363 +         *
   1.364 +         * @param aArray  The contacts to set marked.
   1.365 +         */
   1.366 +        IMPORT_C void SetMarkedContacts(
   1.367 +                MVPbkContactLinkArray* aArray );
   1.368 +
   1.369 +        /**
   1.370 +         * Sets the index of the focused field to the given index.
   1.371 +         * KErrNotFound indicates there is no focused field
   1.372 +         * information available.
   1.373 +         *
   1.374 +         * @param aIndex    The index to set.
   1.375 +         */
   1.376 +        IMPORT_C void SetFocusedFieldIndex(
   1.377 +                TInt aIndex );
   1.378 +
   1.379 +        /**
   1.380 +         * Sets the index of the topmost field to the given index.
   1.381 +         * KErrNotFound indicates there is no topmost field
   1.382 +         * information available.
   1.383 +         *
   1.384 +         * @param aIndex    The index to set.
   1.385 +         */
   1.386 +        IMPORT_C void SetTopFieldIndex(
   1.387 +                TInt aIndex );
   1.388 +        
   1.389 +        /**
   1.390 +         * Sets the index of the focused properties item to the given index.
   1.391 +         * KErrNotFound indicates there is no focused properties item
   1.392 +         * information available.
   1.393 +         *
   1.394 +         * @param aIndex    The index to set.
   1.395 +         */
   1.396 +        IMPORT_C void SetFocusedPropertiesIndex(
   1.397 +                TInt aIndex );
   1.398 +
   1.399 +        /**
   1.400 +         * Sets the index of the topmost properties item to the given index.
   1.401 +         * KErrNotFound indicates there is no topmost properties item
   1.402 +         * information available.
   1.403 +         *
   1.404 +         * @param aIndex    The index to set.
   1.405 +         */
   1.406 +        IMPORT_C void SetTopPropertiesIndex(
   1.407 +                TInt aIndex );
   1.408 +
   1.409 +        /**
   1.410 +         * Reset this view state to an empty state.
   1.411 +         */
   1.412 +        IMPORT_C void Reset();
   1.413 +
   1.414 +        /**
   1.415 +         * Sets the view state flags.
   1.416 +         *
   1.417 +         * @param aFlags    The flags to set.
   1.418 +         */
   1.419 +        IMPORT_C void SetFlags(
   1.420 +                TUint aFlags );
   1.421 +
   1.422 +    public: // Client-server support
   1.423 +
   1.424 +        /**
   1.425 +         * Packages and returns this object in a buffer.
   1.426 +         * Caller is responsible for deleting the buffer.
   1.427 +         *
   1.428 +         * @return  This view state instance packaged into a buffer.
   1.429 +         */
   1.430 +        IMPORT_C HBufC8* PackL() const;
   1.431 +
   1.432 +        /**
   1.433 +         * Packages and returns this object in a buffer.
   1.434 +         * Caller is responsible for deleting the buffer.
   1.435 +         *
   1.436 +         * @return  This view state instance packaged into a buffer.
   1.437 +         */
   1.438 +        IMPORT_C HBufC8* PackLC() const;
   1.439 +
   1.440 +        /**
   1.441 +         * Sets this view state from given packaged buffer.
   1.442 +         *
   1.443 +         * @param aPack     Packaged view state buffer.
   1.444 +         */
   1.445 +        IMPORT_C void UnpackL(
   1.446 +                const TDesC8& aPack );
   1.447 +
   1.448 +
   1.449 +    public: // Support functions
   1.450 +
   1.451 +        /**
   1.452 +         * Comparison operator.
   1.453 +         *
   1.454 +         * @param aRhs  View state instance to compare to this instance.
   1.455 +         * @return  ETrue if view states are equal, EFalse otherwise.
   1.456 +         */
   1.457 +        IMPORT_C TBool operator==(
   1.458 +                const CPbk2ViewState& aRhs ) const;
   1.459 +
   1.460 +    private: // Implementation
   1.461 +        CPbk2ViewState();
   1.462 +        void ConstructL(
   1.463 +                const TDesC8& aBuf );
   1.464 +        void ExternalizeL(
   1.465 +                RWriteStream& aStream ) const;
   1.466 +        void InternalizeL(
   1.467 +                RReadStream& aStream );
   1.468 +
   1.469 +    private: // Data
   1.470 +        /// Own: Link to the focused contact.
   1.471 +        MVPbkContactLink* iFocusedContact;
   1.472 +        /// Own: Link to the topmost contact.
   1.473 +        MVPbkContactLink* iTopContact;
   1.474 +        /// Own: Link to the parent contact.
   1.475 +        MVPbkContactLink* iParentContact;
   1.476 +        /// Own: Array of marked contacts.
   1.477 +        MVPbkContactLinkArray* iArray;
   1.478 +        /// Own: Index of the focused field
   1.479 +        TInt iFocusedFieldIndex;
   1.480 +        /// Own: Index of the top field
   1.481 +        TInt iTopFieldIndex;
   1.482 +        /// Own: Index of the properties item
   1.483 +        TInt iFocusedPropertiesIndex;
   1.484 +        /// Own: Index of the top properties item
   1.485 +        TInt iTopPropertiesIndex;
   1.486 +        /// Own: Flags
   1.487 +        TUint iFlags;
   1.488 +
   1.489 +    private: // Const static data
   1.490 +        static const TUid KUid;
   1.491 +    };
   1.492 +
   1.493 +#endif // CPBK2VIEWSTATE_H
   1.494 +
   1.495 +// End of File