|
1 // Copyright (c) 2004-2009 Nokia Corporation and/or its subsidiary(-ies). |
|
2 // All rights reserved. |
|
3 // This component and the accompanying materials are made available |
|
4 // under the terms of "Eclipse Public License v1.0" |
|
5 // which accompanies this distribution, and is available |
|
6 // at the URL "http://www.eclipse.org/legal/epl-v10.html". |
|
7 // |
|
8 // Initial Contributors: |
|
9 // Nokia Corporation - initial contribution. |
|
10 // |
|
11 // Contributors: |
|
12 // |
|
13 // Description: |
|
14 // |
|
15 |
|
16 #ifndef __CNTVIEWSORTPLUGIN_H__ |
|
17 #define __CNTVIEWSORTPLUGIN_H__ |
|
18 |
|
19 #include <e32base.h> |
|
20 #include "ecom/ecom.h" // For REComSession |
|
21 #include <cntviewbase.h> |
|
22 |
|
23 |
|
24 |
|
25 /** The UID of the ECOM contact view sort interface. |
|
26 @publishedAll |
|
27 @released |
|
28 */ |
|
29 const TUid KCntSortPluginInterfaceUid = {0x10200FBD}; |
|
30 |
|
31 /** The name of the default ECOM contact view sort plug-in. |
|
32 @publishedAll |
|
33 @released |
|
34 */ |
|
35 _LIT8(KViewSortPluginDefaultName, "/default"); |
|
36 |
|
37 #ifndef SYMBIAN_ENABLE_SPLIT_HEADERS |
|
38 |
|
39 //******************************************************************************************** |
|
40 // |
|
41 // Parameter blocks passed to Sort Plug-in's NewL, where they should be copied. |
|
42 // |
|
43 |
|
44 /** The UID for the sort plug-in parameters (TSortPluginParams and |
|
45 TSortPluginViewParamsRev1) that are used to pass data to the ECOM plug-in DLL. |
|
46 @publishedPartner |
|
47 @released |
|
48 */ |
|
49 const TUid KCntSortPluginViewParamsRev1Uid = {0x10201325}; |
|
50 |
|
51 /** Information block holding the sort plug-in's parameters. |
|
52 This is passed to the plug-in instance from the contact view via |
|
53 TSortPluginParams::iViewSortParams. |
|
54 |
|
55 It has an inline constructor to initialise the data members. |
|
56 |
|
57 @publishedPartner |
|
58 @released */ |
|
59 class TSortPluginViewParamsRev1 |
|
60 { |
|
61 public: // constructors |
|
62 /** Empty default constructor. */ |
|
63 TSortPluginViewParamsRev1() |
|
64 {} |
|
65 /** Inline constructor, initialises all data members. |
|
66 |
|
67 @param aViewPreferences The view's view preferences. |
|
68 @param aCompareViewContactsL A pointer to a default function that is used |
|
69 to compare two contact items. The plug-in may call this function from its |
|
70 implementation of SortCompareViewContactsL(). |
|
71 @param aIsSortable A pointer to a default function that is used to test |
|
72 whether a CViewContact is sortable. The plug-in may call this function |
|
73 from its implementation of ViewContactIsSortable(). */ |
|
74 TSortPluginViewParamsRev1(TContactViewPreferences aViewPreferences, |
|
75 TInt(*aCompareViewContactsL)(const CViewContact& aFirst, const CViewContact& aSecond), |
|
76 TBool(*aIsSortable)(const CViewContact& aViewContact)) : |
|
77 iViewPreferences(aViewPreferences), iCompareViewContactsL(aCompareViewContactsL), iIsSortable(aIsSortable) |
|
78 {} |
|
79 public: |
|
80 // Fields in all versions |
|
81 /** The view's view preferences.*/ |
|
82 TContactViewPreferences iViewPreferences; // preferences of view (at creation) |
|
83 |
|
84 // Default implementations of Compare and IsSortable methods |
|
85 // that the sort Plugin can call. |
|
86 // Must not be NULL ! |
|
87 /** A pointer to a default function that is used to compare two contact |
|
88 items. The plug-in may call this function from its implementation of |
|
89 SortCompareViewContactsL(). */ |
|
90 TInt (*iCompareViewContactsL)(const CViewContact& aFirst, const CViewContact& aSecond); |
|
91 /** A pointer to a default function that is used to test whether a contact item |
|
92 is sortable. The plug-in may call this function from its implementation of |
|
93 ViewContactIsSortable(). */ |
|
94 TBool(*iIsSortable)(const CViewContact& aViewContact); |
|
95 }; |
|
96 |
|
97 |
|
98 /** A data class used to pass initialization information to |
|
99 CViewContactSortPlugin::NewL(). |
|
100 |
|
101 @publishedPartner |
|
102 @released */ |
|
103 class TSortPluginParams |
|
104 { |
|
105 public: // constructors |
|
106 /** Empty default constructor. */ |
|
107 TSortPluginParams() {} |
|
108 |
|
109 /** Inline constructor, initialises all data members. |
|
110 |
|
111 The parameter revision UID is initialised to KCntSortPluginViewParamsRev1Uid. |
|
112 @param aInterfaceUid Interface UID as specified in the INTERFACE_INFO resource struct, |
|
113 required by ECOM. |
|
114 @param aImplementationUid Implementation UID, as specified in the IMPLEMENTATION_INFO |
|
115 resource struct, required by ECOM. |
|
116 @param aViewSortParams View sort parameters pointer. This object should match the |
|
117 parameter revision UID value. */ |
|
118 TSortPluginParams(TUid aInterfaceUid, TUid aImplementationUid, TSortPluginViewParamsRev1* aViewSortParams) : |
|
119 iParametersRevision(KCntSortPluginViewParamsRev1Uid), iInterfaceUid(aInterfaceUid), |
|
120 iImplementationUid(aImplementationUid), iViewSortParams(aViewSortParams) |
|
121 {} |
|
122 public: |
|
123 /** A UID that identifies the revision of the structure holding |
|
124 the view's sort parameters. A value of KCntSortPluginViewParamsRev1Uid |
|
125 indicates TSortPluginViewParamsRev1. */ |
|
126 TUid iParametersRevision; |
|
127 |
|
128 // Information for ECOM to load the correct plug-in |
|
129 /** Interface UID as specified in the INTERFACE_INFO resource struct, |
|
130 required by ECOM.*/ |
|
131 TUid iInterfaceUid; |
|
132 /** Implementation UID, as specified in the IMPLEMENTATION_INFO |
|
133 resource struct, required by ECOM.*/ |
|
134 TUid iImplementationUid; |
|
135 |
|
136 // information block from Contact View |
|
137 /** View sort parameters pointer. This object should match the |
|
138 parameter revision UID value.*/ |
|
139 TAny* iViewSortParams; |
|
140 }; |
|
141 |
|
142 |
|
143 |
|
144 /** An interface class that enables implementers to configure the way in which |
|
145 contacts are sorted in a contact view. |
|
146 |
|
147 This is an abstract base class that will be derived from. |
|
148 |
|
149 @publishedPartner |
|
150 @released */ |
|
151 class CViewContactSortPlugin : public CBase |
|
152 { |
|
153 public: |
|
154 /** Identifies the type of sort operation to SortStart(). |
|
155 |
|
156 @publishedPartner |
|
157 @released */ |
|
158 enum TSortStartTypes { |
|
159 /** No sort is in progress. */ |
|
160 ESortNull = 0, |
|
161 /** A full sort or re-sort. */ |
|
162 ESortStartFull, |
|
163 /** A single contact has been inserted or changed. */ |
|
164 ESortStartInsertOne, |
|
165 /** Multiple contacts have been added. For example, ICC contacts arrived in a |
|
166 mixed view (one that also includes contacts from the phone's memory). */ |
|
167 ESortStartInsertMultiple, |
|
168 // other values are reserved |
|
169 }; |
|
170 |
|
171 /* aImplementationUid is used by ECOM to select plugin. |
|
172 Contacts model can use REComSession::ListImplementationsL() to determine |
|
173 DLLs that match the interface UID for this class. */ |
|
174 static CViewContactSortPlugin* NewL(TSortPluginParams* aParams); |
|
175 |
|
176 /* Class must free all memory, implementation should include: |
|
177 iViewSortOrder.Close(); */ |
|
178 inline virtual ~CViewContactSortPlugin(); |
|
179 |
|
180 |
|
181 //pure virtual methods to be implemented by the plugin. |
|
182 |
|
183 /** Called by a contact view to pass the sort plug-in the required sort order. |
|
184 Any processing of the order information is done here. |
|
185 |
|
186 This function is called when the view is created and when a different sort order |
|
187 is requested. |
|
188 |
|
189 @param aViewSortOrder The requested sort order. */ |
|
190 virtual void SetSortOrderL(const RContactViewSortOrder& aViewSortOrder) = 0; |
|
191 |
|
192 /** Called by a contact view to notify the sort plug-in that sorting is about to start. |
|
193 |
|
194 @param aSortStartType Indicates the type of sort operation required. |
|
195 @param aCount The approximate number of contacts to be processed. |
|
196 @return KErrNone if successful, otherwise another of the system-wide error codes. */ |
|
197 virtual TInt SortStart(TSortStartTypes aSortStartType, TInt aCount) = 0; |
|
198 |
|
199 /** Called by a contact view to notify the sort plug-in that sorting is complete. */ |
|
200 virtual void SortCompleted() = 0; |
|
201 |
|
202 /** Called by a contact view to compare two CViewContact items for sorting in the |
|
203 view. |
|
204 |
|
205 If TDesC::CompareC() is used to implement this function, the return value from |
|
206 TDesC::CompareC() can be used directly. |
|
207 |
|
208 @param aLhs The first item to compare. |
|
209 @param aRhs The second item to compare. |
|
210 @return Zero means that aLhs and aRhs have an equal sorting order. |
|
211 An arbitrary negative value means that aLhs is to be sorted before aRhs. |
|
212 An arbitrary positive value means that aRhs is to be sorted before aLhs. */ |
|
213 virtual TInt SortCompareViewContactsL(const CViewContact& aLhs, const CViewContact& aRhs) = 0; |
|
214 |
|
215 /** Tests whether a CViewContact is sortable. |
|
216 |
|
217 For instance, a contact may be unsortable if none of the fields used to sort on |
|
218 contain any data. |
|
219 @param aViewContact The view contact to test. |
|
220 @return ETrue if the view contact is sortable, EFalse if not. */ |
|
221 virtual TBool ViewContactIsSortable(const CViewContact& aViewContact) = 0; |
|
222 |
|
223 private: |
|
224 // The uid is stored here, so that it can be used during destruction of the instance. |
|
225 TUid iDtor_ID_Key; |
|
226 }; |
|
227 |
|
228 |
|
229 //******************************************************************************************** |
|
230 // |
|
231 // NewL() & destructor inline functions, placed in .h file for simplicity |
|
232 // |
|
233 |
|
234 // -----------------------CViewContactSortPlugin -------------------------------- |
|
235 |
|
236 /** Allocates and constructs a sort plug-in instance. |
|
237 |
|
238 @param aParams The sort plug-in's parameters. |
|
239 @return Pointer to the newly created sort plug-in implementation. */ |
|
240 inline CViewContactSortPlugin* CViewContactSortPlugin::NewL(TSortPluginParams* aParams) |
|
241 { |
|
242 TAny* ptr = REComSession::CreateImplementationL(aParams->iImplementationUid, |
|
243 _FOFF(CViewContactSortPlugin, iDtor_ID_Key), |
|
244 aParams); |
|
245 return reinterpret_cast<CViewContactSortPlugin*>(ptr); |
|
246 } |
|
247 |
|
248 /** Virtual destructor. */ |
|
249 inline CViewContactSortPlugin::~CViewContactSortPlugin() |
|
250 { |
|
251 REComSession::DestroyedImplementation(iDtor_ID_Key); |
|
252 } |
|
253 #endif //SYMBIAN_ENABLE_SPLIT_HEADERS |
|
254 |
|
255 #endif |