1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/epoc32/include/app/MVPbkContactViewFiltering.h Wed Mar 31 12:33:34 2010 +0100
1.3 @@ -0,0 +1,120 @@
1.4 +/*
1.5 +* Copyright (c) 2006-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: An interface for text based contact view filtering.
1.18 +*
1.19 +*/
1.20 +
1.21 +
1.22 +#ifndef M_MVPBKCONTACTVIEWFILTERING_H
1.23 +#define M_MVPBKCONTACTVIEWFILTERING_H
1.24 +
1.25 +#include <e32def.h>
1.26 +#include <bamdesca.h>
1.27 +
1.28 +// FORWARDS DECLARATIONS
1.29 +class MVPbkContactViewBase;
1.30 +class MVPbkContactViewObserver;
1.31 +class MVPbkContactBookmarkCollection;
1.32 +
1.33 +/**
1.34 + * An interface for text based contact view filtering.
1.35 + *
1.36 + * Contact views can support filtering based on search string and
1.37 + * always included contacts by implementing this interface.
1.38 + *
1.39 + * A view stack usage:
1.40 + *
1.41 + * The client can create a stack structure of filtered views. E.g
1.42 + *
1.43 + * 1) Client creates a filtered view using find text "J"
1.44 + * 2) It then waits that the new view becomes ready.
1.45 + * 3) Then it uses the new view to create next level view for "Jo".
1.46 + * 4) The client waits that the new view becomes ready.
1.47 + * 5) The client again uses the new view for creating third level view "Joe"
1.48 + * 6) After the third filtered view becomes ready the client has 4 views:
1.49 + * The base view that includes all the contacts and 3 filtered views
1.50 + * for texts "J", "Jo" and "Joe". It's up to store implementation
1.51 + * to optimize the used resources in case the store supports thousands
1.52 + * of contacts.
1.53 + *
1.54 + * If client uses always included contacts then they must be same for all
1.55 + * views in a stack.
1.56 + *
1.57 + * View events must come in order: bottom view first.
1.58 + */
1.59 +class MVPbkContactViewFiltering
1.60 + {
1.61 +public:
1.62 + /**
1.63 + * Creates a new filtered view asynchronously.
1.64 + *
1.65 + * The parent view will be filtered according to given criteria and
1.66 + * then the client will be notified via MVPbkContactViewObserver.
1.67 + * The parent view must be ready before creating a new filtered view,
1.68 + * The created view must be destroyed before the parent view and
1.69 + * not vice versa.
1.70 + *
1.71 + * @param aObserver The observer that will be notified when the view
1.72 + * is ready. Client shouldn't use the view before
1.73 + * it has been notified.
1.74 + * @param aFindWords An array of words that must match to the contact.
1.75 + * @param aAlwaysIncluded Contacts that must be in the view
1.76 + * even they don't match to aFindWords.
1.77 + * This an optional parameter. Give
1.78 + * NULL if not needed. Client must keep
1.79 + * the instance alive while the view exists.
1.80 + * @return a filtered view that must also support view filtering.
1.81 + */
1.82 + virtual MVPbkContactViewBase* CreateFilteredViewLC(
1.83 + MVPbkContactViewObserver& aObserver,
1.84 + const MDesCArray& aFindWords,
1.85 + const MVPbkContactBookmarkCollection* aAlwaysIncluded ) = 0;
1.86 +
1.87 + /**
1.88 + * Updates an existing filtered view asynchronously.
1.89 + *
1.90 + * This must be implemented by the views that were previously
1.91 + * created by CreateFilteredViewLC. Otherwise leaves with KErrNotSupported.
1.92 + *
1.93 + * @param aFindWords an array of words that must match to the contact.
1.94 + * @param aAlwaysIncluded Contacts that must be in the view
1.95 + * even they don't match to aFindWords.
1.96 + * This an optional parameter. Give
1.97 + * NULL if not needed. Client must keep
1.98 + * the instance alive while the view exists.
1.99 + * @exception KErrNotSupported if the view itself is not a filtered view.
1.100 + */
1.101 + virtual void UpdateFilterL(
1.102 + const MDesCArray& aFindWords,
1.103 + const MVPbkContactBookmarkCollection* aAlwaysIncluded ) = 0;
1.104 +
1.105 + /**
1.106 + * Returns an extension point for this interface or NULL.
1.107 + *
1.108 + * @param aExtensionUid no extensions defined currently.
1.109 + * @return an extension point for this interface or NULL.
1.110 + */
1.111 + virtual TAny* ContactViewFilteringExtension(TUid /*aExtensionUid*/)
1.112 + { return NULL; }
1.113 +
1.114 +protected:
1.115 +
1.116 + /**
1.117 + * Virtual Phonebook client doesn't own this instance.
1.118 + */
1.119 + ~MVPbkContactViewFiltering() {}
1.120 + };
1.121 +
1.122 +
1.123 +#endif // M_MVPBKCONTACTVIEWFILTERING_H