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