1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/epoc32/include/app/cntviewsortplugin.h Wed Mar 31 12:33:34 2010 +0100
1.3 @@ -0,0 +1,255 @@
1.4 +// Copyright (c) 2004-2009 Nokia Corporation and/or its subsidiary(-ies).
1.5 +// All rights reserved.
1.6 +// This component and the accompanying materials are made available
1.7 +// under the terms of "Eclipse Public License v1.0"
1.8 +// which accompanies this distribution, and is available
1.9 +// at the URL "http://www.eclipse.org/legal/epl-v10.html".
1.10 +//
1.11 +// Initial Contributors:
1.12 +// Nokia Corporation - initial contribution.
1.13 +//
1.14 +// Contributors:
1.15 +//
1.16 +// Description:
1.17 +//
1.18 +
1.19 +#ifndef __CNTVIEWSORTPLUGIN_H__
1.20 +#define __CNTVIEWSORTPLUGIN_H__
1.21 +
1.22 +#include <e32base.h>
1.23 +#include "ecom/ecom.h" // For REComSession
1.24 +#include <cntviewbase.h>
1.25 +
1.26 +
1.27 +
1.28 +/** The UID of the ECOM contact view sort interface.
1.29 +@publishedAll
1.30 +@released
1.31 +*/
1.32 +const TUid KCntSortPluginInterfaceUid = {0x10200FBD};
1.33 +
1.34 +/** The name of the default ECOM contact view sort plug-in.
1.35 +@publishedAll
1.36 +@released
1.37 +*/
1.38 +_LIT8(KViewSortPluginDefaultName, "/default");
1.39 +
1.40 +#ifndef SYMBIAN_ENABLE_SPLIT_HEADERS
1.41 +
1.42 +//********************************************************************************************
1.43 +//
1.44 +// Parameter blocks passed to Sort Plug-in's NewL, where they should be copied.
1.45 +//
1.46 +
1.47 +/** The UID for the sort plug-in parameters (TSortPluginParams and
1.48 +TSortPluginViewParamsRev1) that are used to pass data to the ECOM plug-in DLL.
1.49 +@publishedPartner
1.50 +@released
1.51 +*/
1.52 +const TUid KCntSortPluginViewParamsRev1Uid = {0x10201325};
1.53 +
1.54 +/** Information block holding the sort plug-in's parameters.
1.55 +This is passed to the plug-in instance from the contact view via
1.56 +TSortPluginParams::iViewSortParams.
1.57 +
1.58 +It has an inline constructor to initialise the data members.
1.59 +
1.60 +@publishedPartner
1.61 +@released */
1.62 +class TSortPluginViewParamsRev1
1.63 + {
1.64 +public: // constructors
1.65 + /** Empty default constructor. */
1.66 + TSortPluginViewParamsRev1()
1.67 + {}
1.68 + /** Inline constructor, initialises all data members.
1.69 +
1.70 + @param aViewPreferences The view's view preferences.
1.71 + @param aCompareViewContactsL A pointer to a default function that is used
1.72 + to compare two contact items. The plug-in may call this function from its
1.73 + implementation of SortCompareViewContactsL().
1.74 + @param aIsSortable A pointer to a default function that is used to test
1.75 + whether a CViewContact is sortable. The plug-in may call this function
1.76 + from its implementation of ViewContactIsSortable(). */
1.77 + TSortPluginViewParamsRev1(TContactViewPreferences aViewPreferences,
1.78 + TInt(*aCompareViewContactsL)(const CViewContact& aFirst, const CViewContact& aSecond),
1.79 + TBool(*aIsSortable)(const CViewContact& aViewContact)) :
1.80 + iViewPreferences(aViewPreferences), iCompareViewContactsL(aCompareViewContactsL), iIsSortable(aIsSortable)
1.81 + {}
1.82 +public:
1.83 + // Fields in all versions
1.84 + /** The view's view preferences.*/
1.85 + TContactViewPreferences iViewPreferences; // preferences of view (at creation)
1.86 +
1.87 + // Default implementations of Compare and IsSortable methods
1.88 + // that the sort Plugin can call.
1.89 + // Must not be NULL !
1.90 + /** A pointer to a default function that is used to compare two contact
1.91 + items. The plug-in may call this function from its implementation of
1.92 + SortCompareViewContactsL(). */
1.93 + TInt (*iCompareViewContactsL)(const CViewContact& aFirst, const CViewContact& aSecond);
1.94 + /** A pointer to a default function that is used to test whether a contact item
1.95 + is sortable. The plug-in may call this function from its implementation of
1.96 + ViewContactIsSortable(). */
1.97 + TBool(*iIsSortable)(const CViewContact& aViewContact);
1.98 + };
1.99 +
1.100 +
1.101 +/** A data class used to pass initialization information to
1.102 +CViewContactSortPlugin::NewL().
1.103 +
1.104 +@publishedPartner
1.105 +@released */
1.106 +class TSortPluginParams
1.107 + {
1.108 +public: // constructors
1.109 + /** Empty default constructor. */
1.110 + TSortPluginParams() {}
1.111 +
1.112 + /** Inline constructor, initialises all data members.
1.113 +
1.114 + The parameter revision UID is initialised to KCntSortPluginViewParamsRev1Uid.
1.115 + @param aInterfaceUid Interface UID as specified in the INTERFACE_INFO resource struct,
1.116 + required by ECOM.
1.117 + @param aImplementationUid Implementation UID, as specified in the IMPLEMENTATION_INFO
1.118 + resource struct, required by ECOM.
1.119 + @param aViewSortParams View sort parameters pointer. This object should match the
1.120 + parameter revision UID value. */
1.121 + TSortPluginParams(TUid aInterfaceUid, TUid aImplementationUid, TSortPluginViewParamsRev1* aViewSortParams) :
1.122 + iParametersRevision(KCntSortPluginViewParamsRev1Uid), iInterfaceUid(aInterfaceUid),
1.123 + iImplementationUid(aImplementationUid), iViewSortParams(aViewSortParams)
1.124 + {}
1.125 +public:
1.126 + /** A UID that identifies the revision of the structure holding
1.127 + the view's sort parameters. A value of KCntSortPluginViewParamsRev1Uid
1.128 + indicates TSortPluginViewParamsRev1. */
1.129 + TUid iParametersRevision;
1.130 +
1.131 + // Information for ECOM to load the correct plug-in
1.132 + /** Interface UID as specified in the INTERFACE_INFO resource struct,
1.133 + required by ECOM.*/
1.134 + TUid iInterfaceUid;
1.135 + /** Implementation UID, as specified in the IMPLEMENTATION_INFO
1.136 + resource struct, required by ECOM.*/
1.137 + TUid iImplementationUid;
1.138 +
1.139 + // information block from Contact View
1.140 + /** View sort parameters pointer. This object should match the
1.141 + parameter revision UID value.*/
1.142 + TAny* iViewSortParams;
1.143 + };
1.144 +
1.145 +
1.146 +
1.147 +/** An interface class that enables implementers to configure the way in which
1.148 +contacts are sorted in a contact view.
1.149 +
1.150 +This is an abstract base class that will be derived from.
1.151 +
1.152 +@publishedPartner
1.153 +@released */
1.154 +class CViewContactSortPlugin : public CBase
1.155 + {
1.156 +public:
1.157 + /** Identifies the type of sort operation to SortStart().
1.158 +
1.159 + @publishedPartner
1.160 + @released */
1.161 + enum TSortStartTypes {
1.162 + /** No sort is in progress. */
1.163 + ESortNull = 0,
1.164 + /** A full sort or re-sort. */
1.165 + ESortStartFull,
1.166 + /** A single contact has been inserted or changed. */
1.167 + ESortStartInsertOne,
1.168 + /** Multiple contacts have been added. For example, ICC contacts arrived in a
1.169 + mixed view (one that also includes contacts from the phone's memory). */
1.170 + ESortStartInsertMultiple,
1.171 + // other values are reserved
1.172 + };
1.173 +
1.174 + /* aImplementationUid is used by ECOM to select plugin.
1.175 + Contacts model can use REComSession::ListImplementationsL() to determine
1.176 + DLLs that match the interface UID for this class. */
1.177 + static CViewContactSortPlugin* NewL(TSortPluginParams* aParams);
1.178 +
1.179 + /* Class must free all memory, implementation should include:
1.180 + iViewSortOrder.Close(); */
1.181 + inline virtual ~CViewContactSortPlugin();
1.182 +
1.183 +
1.184 + //pure virtual methods to be implemented by the plugin.
1.185 +
1.186 + /** Called by a contact view to pass the sort plug-in the required sort order.
1.187 + Any processing of the order information is done here.
1.188 +
1.189 + This function is called when the view is created and when a different sort order
1.190 + is requested.
1.191 +
1.192 + @param aViewSortOrder The requested sort order. */
1.193 + virtual void SetSortOrderL(const RContactViewSortOrder& aViewSortOrder) = 0;
1.194 +
1.195 + /** Called by a contact view to notify the sort plug-in that sorting is about to start.
1.196 +
1.197 + @param aSortStartType Indicates the type of sort operation required.
1.198 + @param aCount The approximate number of contacts to be processed.
1.199 + @return KErrNone if successful, otherwise another of the system-wide error codes. */
1.200 + virtual TInt SortStart(TSortStartTypes aSortStartType, TInt aCount) = 0;
1.201 +
1.202 + /** Called by a contact view to notify the sort plug-in that sorting is complete. */
1.203 + virtual void SortCompleted() = 0;
1.204 +
1.205 + /** Called by a contact view to compare two CViewContact items for sorting in the
1.206 + view.
1.207 +
1.208 + If TDesC::CompareC() is used to implement this function, the return value from
1.209 + TDesC::CompareC() can be used directly.
1.210 +
1.211 + @param aLhs The first item to compare.
1.212 + @param aRhs The second item to compare.
1.213 + @return Zero means that aLhs and aRhs have an equal sorting order.
1.214 + An arbitrary negative value means that aLhs is to be sorted before aRhs.
1.215 + An arbitrary positive value means that aRhs is to be sorted before aLhs. */
1.216 + virtual TInt SortCompareViewContactsL(const CViewContact& aLhs, const CViewContact& aRhs) = 0;
1.217 +
1.218 + /** Tests whether a CViewContact is sortable.
1.219 +
1.220 + For instance, a contact may be unsortable if none of the fields used to sort on
1.221 + contain any data.
1.222 + @param aViewContact The view contact to test.
1.223 + @return ETrue if the view contact is sortable, EFalse if not. */
1.224 + virtual TBool ViewContactIsSortable(const CViewContact& aViewContact) = 0;
1.225 +
1.226 +private:
1.227 + // The uid is stored here, so that it can be used during destruction of the instance.
1.228 + TUid iDtor_ID_Key;
1.229 + };
1.230 +
1.231 +
1.232 +//********************************************************************************************
1.233 +//
1.234 +// NewL() & destructor inline functions, placed in .h file for simplicity
1.235 +//
1.236 +
1.237 +// -----------------------CViewContactSortPlugin --------------------------------
1.238 +
1.239 +/** Allocates and constructs a sort plug-in instance.
1.240 +
1.241 +@param aParams The sort plug-in's parameters.
1.242 +@return Pointer to the newly created sort plug-in implementation. */
1.243 +inline CViewContactSortPlugin* CViewContactSortPlugin::NewL(TSortPluginParams* aParams)
1.244 + {
1.245 + TAny* ptr = REComSession::CreateImplementationL(aParams->iImplementationUid,
1.246 + _FOFF(CViewContactSortPlugin, iDtor_ID_Key),
1.247 + aParams);
1.248 + return reinterpret_cast<CViewContactSortPlugin*>(ptr);
1.249 + }
1.250 +
1.251 +/** Virtual destructor. */
1.252 +inline CViewContactSortPlugin::~CViewContactSortPlugin()
1.253 + {
1.254 + REComSession::DestroyedImplementation(iDtor_ID_Key);
1.255 + }
1.256 +#endif //SYMBIAN_ENABLE_SPLIT_HEADERS
1.257 +
1.258 +#endif