2 * Copyright (c) 2006-2007 Nokia Corporation and/or its subsidiary(-ies).
4 * This component and the accompanying materials are made available
5 * under the terms of "Eclipse Public License v1.0"
6 * which accompanies this distribution, and is available
7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".
9 * Initial Contributors:
10 * Nokia Corporation - initial contribution.
14 * Description: An interface for text based contact view filtering.
19 #ifndef M_MVPBKCONTACTVIEWFILTERING_H
20 #define M_MVPBKCONTACTVIEWFILTERING_H
25 // FORWARDS DECLARATIONS
26 class MVPbkContactViewBase;
27 class MVPbkContactViewObserver;
28 class MVPbkContactBookmarkCollection;
31 * An interface for text based contact view filtering.
33 * Contact views can support filtering based on search string and
34 * always included contacts by implementing this interface.
38 * The client can create a stack structure of filtered views. E.g
40 * 1) Client creates a filtered view using find text "J"
41 * 2) It then waits that the new view becomes ready.
42 * 3) Then it uses the new view to create next level view for "Jo".
43 * 4) The client waits that the new view becomes ready.
44 * 5) The client again uses the new view for creating third level view "Joe"
45 * 6) After the third filtered view becomes ready the client has 4 views:
46 * The base view that includes all the contacts and 3 filtered views
47 * for texts "J", "Jo" and "Joe". It's up to store implementation
48 * to optimize the used resources in case the store supports thousands
51 * If client uses always included contacts then they must be same for all
54 * View events must come in order: bottom view first.
56 class MVPbkContactViewFiltering
60 * Creates a new filtered view asynchronously.
62 * The parent view will be filtered according to given criteria and
63 * then the client will be notified via MVPbkContactViewObserver.
64 * The parent view must be ready before creating a new filtered view,
65 * The created view must be destroyed before the parent view and
68 * @param aObserver The observer that will be notified when the view
69 * is ready. Client shouldn't use the view before
70 * it has been notified.
71 * @param aFindWords An array of words that must match to the contact.
72 * @param aAlwaysIncluded Contacts that must be in the view
73 * even they don't match to aFindWords.
74 * This an optional parameter. Give
75 * NULL if not needed. Client must keep
76 * the instance alive while the view exists.
77 * @return a filtered view that must also support view filtering.
79 virtual MVPbkContactViewBase* CreateFilteredViewLC(
80 MVPbkContactViewObserver& aObserver,
81 const MDesCArray& aFindWords,
82 const MVPbkContactBookmarkCollection* aAlwaysIncluded ) = 0;
85 * Updates an existing filtered view asynchronously.
87 * This must be implemented by the views that were previously
88 * created by CreateFilteredViewLC. Otherwise leaves with KErrNotSupported.
90 * @param aFindWords an array of words that must match to the contact.
91 * @param aAlwaysIncluded Contacts that must be in the view
92 * even they don't match to aFindWords.
93 * This an optional parameter. Give
94 * NULL if not needed. Client must keep
95 * the instance alive while the view exists.
96 * @exception KErrNotSupported if the view itself is not a filtered view.
98 virtual void UpdateFilterL(
99 const MDesCArray& aFindWords,
100 const MVPbkContactBookmarkCollection* aAlwaysIncluded ) = 0;
103 * Returns an extension point for this interface or NULL.
105 * @param aExtensionUid no extensions defined currently.
106 * @return an extension point for this interface or NULL.
108 virtual TAny* ContactViewFilteringExtension(TUid /*aExtensionUid*/)
114 * Virtual Phonebook client doesn't own this instance.
116 ~MVPbkContactViewFiltering() {}
120 #endif // M_MVPBKCONTACTVIEWFILTERING_H