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