1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/epoc32/include/app/CVPbkContactViewDefinition.h Wed Mar 31 12:33:34 2010 +0100
1.3 @@ -0,0 +1,343 @@
1.4 +/*
1.5 +* Copyright (c) 2004-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: A contact view definition.
1.18 +*
1.19 +*/
1.20 +
1.21 +
1.22 +#ifndef CVPBKCONTACTVIEWDEFINITION_H
1.23 +#define CVPBKCONTACTVIEWDEFINITION_H
1.24 +
1.25 +#include <e32base.h>
1.26 +#include <vpbkcontactview.hrh>
1.27 +
1.28 +class TResourceReader;
1.29 +class CVPbkFieldTypeSelector;
1.30 +class MVPbkContactSelector;
1.31 +
1.32 +/**
1.33 + * A contact view definition.
1.34 + *
1.35 + * This class is needed when a client needs to create a contact view.
1.36 + * A client can define a structure of VPBK_CONTACT_VIEW from VPbkContactView.rh
1.37 + * and use this class to read the definition or construct an empty definition
1.38 + * and then set the information to it.
1.39 + *
1.40 + * A view definition enables complex view structures. A client can e.g.
1.41 + * create a composite view that contains subviews from multiple contact
1.42 + * stores. However, it's up to client to understand that there are certain
1.43 + * limits for the structure. E.g. a contact view is a leaf view and can
1.44 + * not have subviews. Another important thing to keep in mind is that complex
1.45 + * view structures consumes more RAM that can be a problem if there are
1.46 + * thousands of contacts in the view.
1.47 + *
1.48 + * @see VPBK_CONTACT_VIEW in VPbkContactView.rh
1.49 + * @see CVPbkContactManager::CreateContactViewLC
1.50 + * @lib VPbkEng.lib
1.51 + */
1.52 +class CVPbkContactViewDefinition : public CBase
1.53 + {
1.54 + public: // Construction & destruction
1.55 + /**
1.56 + * Creates a new contact view definition and initializes
1.57 + * it from resource. Takes a VPBK_CONTACT_VIEW resource
1.58 + * structure as a parameter.
1.59 + *
1.60 + * @param aReader A resource reader to a VPBK_CONTACT_VIEW
1.61 + * structure.
1.62 + * @return A new instance of this class.
1.63 + */
1.64 + IMPORT_C static CVPbkContactViewDefinition* NewL(
1.65 + TResourceReader& aReader );
1.66 +
1.67 + /**
1.68 + * Creates a new empty contact view definition.
1.69 + * Client must then set the needed information.
1.70 + *
1.71 + * @return A new instance of this class.
1.72 + */
1.73 + IMPORT_C static CVPbkContactViewDefinition* NewL();
1.74 +
1.75 + /**
1.76 + * Constructs a new contact view definition from an existing one
1.77 + * by copying the data.
1.78 + *
1.79 + * @param aViewDef A view definition to copy.
1.80 + * @return A new instance of this class.
1.81 + */
1.82 + IMPORT_C static CVPbkContactViewDefinition* NewL(
1.83 + const CVPbkContactViewDefinition& aViewDef );
1.84 +
1.85 + /**
1.86 + * Creates a new contact view definition and initializes
1.87 + * it from resource. Takes a VPBK_CONTACT_VIEW resource
1.88 + * structure as a parameter.
1.89 + *
1.90 + * @param aReader A resource reader to a VPBK_CONTACT_VIEW
1.91 + * structure.
1.92 + * @return A new instance of this class.
1.93 + */
1.94 + IMPORT_C static CVPbkContactViewDefinition* NewLC(
1.95 + TResourceReader& aReader );
1.96 +
1.97 + /**
1.98 + * Creates a new empty contact view definition.
1.99 + * Client must then set the needed information.
1.100 + *
1.101 + * @return A new instance of this class.
1.102 + */
1.103 + IMPORT_C static CVPbkContactViewDefinition* NewLC();
1.104 +
1.105 + /**
1.106 + * Constructs a new contact view definition from an existing one
1.107 + * by copying the data.
1.108 + *
1.109 + * @param aViewDef A view definition to copy.
1.110 + * @return A new instance of this class.
1.111 + */
1.112 + IMPORT_C static CVPbkContactViewDefinition* NewLC(
1.113 + const CVPbkContactViewDefinition& aViewDef );
1.114 +
1.115 + /**
1.116 + * Destructor.
1.117 + */
1.118 + ~CVPbkContactViewDefinition();
1.119 +
1.120 + public: // Interface
1.121 + /**
1.122 + * Returns the number of sub views owned by this view.
1.123 + *
1.124 + * @return The number of sub views.
1.125 + */
1.126 + IMPORT_C TInt SubViewCount() const;
1.127 +
1.128 + /**
1.129 + * Returns the sub view definition at aIndex.
1.130 + *
1.131 + * @param aIndex The index of the sub view definition.
1.132 + * @return The sub view definition at aIndex.
1.133 + */
1.134 + IMPORT_C const CVPbkContactViewDefinition& SubViewAt(
1.135 + TInt aIndex ) const;
1.136 +
1.137 + /**
1.138 + * Returns the sub view definition at aIndex.
1.139 + *
1.140 + * @param aIndex The index to query.
1.141 + * @return The sub view definition.
1.142 + */
1.143 + IMPORT_C CVPbkContactViewDefinition& SubViewAt( TInt aIndex );
1.144 +
1.145 + /**
1.146 + * Returns the type of this view.
1.147 + *
1.148 + * @return The type of this view.
1.149 + */
1.150 + IMPORT_C TVPbkContactViewType Type() const;
1.151 +
1.152 + /**
1.153 + * Returns ETrue if aFlag is on, otherwise EFalse.
1.154 + *
1.155 + * @param aFlag The flag to check.
1.156 + * @return A flag state.
1.157 + */
1.158 + IMPORT_C TBool FlagIsOn( TVPbkContactViewFlag aFlag ) const;
1.159 +
1.160 + /**
1.161 + * Returns the URI of this view. KNullDesC if this is not a leaf node.
1.162 + *
1.163 + * @return The URI of this view or KNullDesC.
1.164 + */
1.165 + IMPORT_C const TDesC& Uri() const;
1.166 +
1.167 + /**
1.168 + * Returns the sorting policy of this view.
1.169 + *
1.170 + * @return The sorting policy of this view.
1.171 + */
1.172 + IMPORT_C TVPbkContactViewSortPolicy SortPolicy() const;
1.173 +
1.174 + /**
1.175 + * Returns the name of the view. Default is KNullDesC.
1.176 + *
1.177 + * In view types EVPbkContactsView and EVPbkGroupsView
1.178 + * the name can be used as a shared view identifier by the
1.179 + * store. Shared view creation is indicated by
1.180 + * TVPbkContactViewSharing. If the name is empty for shared
1.181 + * view then store implementation uses its default name.
1.182 + * This is a preferred way to use shared views in the platform.
1.183 + *
1.184 + * In view type EVPbkFoldingView the name is the label
1.185 + * of the only contact in the view.
1.186 + *
1.187 + * In view type EVPbkCompositeView the name has no meaning.
1.188 + *
1.189 + * @return The name of the view.
1.190 + */
1.191 + IMPORT_C const TDesC& Name() const;
1.192 +
1.193 + /**
1.194 + * Returns the view sharing type. The store can support
1.195 + * a shared view creation for saving RAM.
1.196 + *
1.197 + * Default value for types EVPbkContactsView and EVPbkGroupsView
1.198 + * is EVPbkSharedView. Store implementation creates
1.199 + * then a shared view if it's possible for the store.
1.200 + * Prefer using the default values for saving resources.
1.201 + *
1.202 + * For view types EVPbkFoldingView and EVPbkCompositeView the
1.203 + * sharing has no effect.
1.204 + *
1.205 + * See also the documentation of Name()
1.206 + *
1.207 + * @return The view sharing type.
1.208 + *
1.209 + */
1.210 + IMPORT_C TVPbkContactViewSharing Sharing() const;
1.211 +
1.212 + /**
1.213 + * Returns the field type selector used to filter the view or NULL.
1.214 + *
1.215 + * The view contains only contacts having the fields defined
1.216 + * by the field type filter.
1.217 + *
1.218 + * @return The field type filter.
1.219 + */
1.220 + IMPORT_C CVPbkFieldTypeSelector* FieldTypeFilter() const;
1.221 +
1.222 + /**
1.223 + * Returns the id of this view.
1.224 + *
1.225 + * @return the id of this view.
1.226 + */
1.227 + IMPORT_C TInt Id() const;
1.228 + /**
1.229 + * Adds new view as a subview. This object takes ownership
1.230 + * of the subview. If this function leaves ownership is not taken.
1.231 + *
1.232 + * @param aSubView The new subview to add.
1.233 + */
1.234 + IMPORT_C void AddSubViewL( CVPbkContactViewDefinition* aSubView );
1.235 +
1.236 + /**
1.237 + * Sets aType as this views type.
1.238 + *
1.239 + * @param aType The type to set.
1.240 + */
1.241 + IMPORT_C void SetType( TVPbkContactViewType aType );
1.242 +
1.243 + /**
1.244 + * Sets aId as this views id.
1.245 + *
1.246 + * @param aId the id to set.
1.247 + */
1.248 + IMPORT_C void SetId( TInt aId );
1.249 + /**
1.250 + * Sets the saFlag's state as aState.
1.251 + *
1.252 + * @param aFlag The flag to modify.
1.253 + * @param aState The state to set.
1.254 + */
1.255 + IMPORT_C void SetFlag( TVPbkContactViewFlag aFlag, TBool aState );
1.256 +
1.257 + /**
1.258 + * Sets aUri as this views URI. This function takes a copy of aUri.
1.259 + *
1.260 + * @param aUri The URI to set.
1.261 + */
1.262 + IMPORT_C void SetUriL( const TDesC& aUri );
1.263 +
1.264 + /**
1.265 + * Sets aSortPolicy as this views sorting policy.
1.266 + *
1.267 + * @param aSortPolicy The sort policy to set.
1.268 + */
1.269 + IMPORT_C void SetSortPolicy( TVPbkContactViewSortPolicy aSortPolicy );
1.270 +
1.271 + /**
1.272 + * Sets aName as this views Name. This function takes a copy of aName.
1.273 + *
1.274 + * @param aName The name to set.
1.275 + */
1.276 + IMPORT_C void SetNameL( const TDesC& aName );
1.277 +
1.278 + /**
1.279 + * Sets the view sharing type.
1.280 + *
1.281 + * @param aViewSharing One of the values defined in
1.282 + * VPbkContactView.hrh.
1.283 + */
1.284 + IMPORT_C void SetSharing( TVPbkContactViewSharing aViewSharing );
1.285 +
1.286 + /**
1.287 + * Sets the field type selector used to filter the view.
1.288 + *
1.289 + * The view contains only contacts having the fields defined
1.290 + * by the field type filter.
1.291 + *
1.292 + * @param aFilter The field type filter. Use NULL to
1.293 + * filter nothing.
1.294 + */
1.295 + IMPORT_C void SetFieldTypeFilterL( CVPbkFieldTypeSelector* aFilter );
1.296 +
1.297 + /**
1.298 + * Sets the contact selector used to filter the view.
1.299 + *
1.300 + * The view contains only contacts accepted by the selector.
1.301 + *
1.302 + * @param aContactSelector The contact selector. Use NULL to
1.303 + * filter nothing. Ownership not transferred.
1.304 + */
1.305 + IMPORT_C void SetContactSelector( MVPbkContactSelector* aContactSelector );
1.306 +
1.307 + /**
1.308 + * Gives either the contact selector or NULL. Ownership is not transferred.
1.309 + */
1.310 + IMPORT_C MVPbkContactSelector* ContactSelector() const;
1.311 +
1.312 + private: // Implementation
1.313 + CVPbkContactViewDefinition();
1.314 + void ConstructL();
1.315 + void ConstructL(
1.316 + const CVPbkContactViewDefinition& aViewDef );
1.317 + void ConstructFromResourceL(
1.318 + TResourceReader& aReader );
1.319 + void InitializeSharing();
1.320 +
1.321 + private: // Data
1.322 + /// Own: URI of this view, may be NULL if this is inner node
1.323 + HBufC* iUri;
1.324 + /// Own: Type of this view
1.325 + TVPbkContactViewType iType;
1.326 + /// Own: Flags for this view
1.327 + TUint32 iFlags;
1.328 + /// Own: Sorting policy for this view
1.329 + TVPbkContactViewSortPolicy iSortPolicy;
1.330 + /// Own: Subviews of this view
1.331 + RPointerArray<CVPbkContactViewDefinition> iSubViews;
1.332 + /// Own: Name of the view, may be NULL if name is not applicable
1.333 + HBufC* iName;
1.334 + /// Own: Field type filter
1.335 + CVPbkFieldTypeSelector* iFilter;
1.336 + /// Own: Defines the sharing of the view
1.337 + TVPbkContactViewSharing iSharing;
1.338 + /// Not owned
1.339 + MVPbkContactSelector* iContactSelector;
1.340 + /// Own: Id for this view
1.341 + TInt iId;
1.342 + };
1.343 +
1.344 +#endif // CVPBKCONTACTVIEWDEFINITION_H
1.345 +
1.346 +// End of File