1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/epoc32/include/app/MPbk2ContactNameFormatter.h Wed Mar 31 12:33:34 2010 +0100
1.3 @@ -0,0 +1,217 @@
1.4 +/*
1.5 +* Copyright (c) 2005-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: Phonebook 2 contact name formatter interface.
1.18 +*
1.19 +*/
1.20 +
1.21 +
1.22 +#ifndef MPBK2CONTACTNAMEFORMATTER_H
1.23 +#define MPBK2CONTACTNAMEFORMATTER_H
1.24 +
1.25 +// INCLUDE FILES
1.26 +#include <e32std.h>
1.27 +
1.28 +// FORWARD DECLARATIONS
1.29 +class MVPbkBaseContactFieldCollection;
1.30 +class MVPbkFieldType;
1.31 +class MVPbkFieldTypeList;
1.32 +class CVPbkFieldTypeRefsList;
1.33 +class MVPbkBaseContactField;
1.34 +class CVPbkBaseContactFieldTypeListIterator;
1.35 +
1.36 +//Use this UID to access field property interface extension 2. Used as
1.37 +//a parameter to ContactNameFormatterExtension() method.
1.38 +const TUid MPbk2ContactNameFormatterExtension2Uid = { 2 };
1.39 +/**
1.40 + * Abstract Phonebook 2 contact name formatter interface.
1.41 + */
1.42 +class MPbk2ContactNameFormatter
1.43 + {
1.44 + public: // Interface
1.45 +
1.46 + /// Flags
1.47 + enum TPbk2ContactTitleFormattingFlags
1.48 + {
1.49 + /// Formatter preserves all leading spaces
1.50 + /// in the formatted title
1.51 + EPreserveLeadingSpaces = 0x0001,
1.52 + /// Formatter uses custom separator
1.53 + /// for separating firstname and lastname
1.54 + EUseSeparator = 0x0002,
1.55 + /// Formatter replaces all non-graphical
1.56 + /// characters with space character
1.57 + EReplaceNonGraphicChars = 0x0004,
1.58 + /// Formatter to retain all original space characters
1.59 + EPreserveAllOriginalSpaces = 0x0008
1.60 + };
1.61 +
1.62 + /**
1.63 + * Destructor.
1.64 + */
1.65 + virtual ~MPbk2ContactNameFormatter()
1.66 + {}
1.67 +
1.68 + /**
1.69 + * Returns the title text for a contact.
1.70 + *
1.71 + * @param aContactFields Field collection representing
1.72 + * the data in a contact.
1.73 + * @param aFormattingFlags @see TPbk2ContactTitleFormattingFlags
1.74 + * @return A buffer containing the formatted title,
1.75 + * NULL if no title can be created.
1.76 + */
1.77 + virtual HBufC* GetContactTitleOrNullL(
1.78 + const MVPbkBaseContactFieldCollection& aContactFields,
1.79 + TUint32 aFormattingFlags ) = 0;
1.80 +
1.81 + /**
1.82 + * Returns the title text for a contact.
1.83 + *
1.84 + * @param aContactFields Field collection representing
1.85 + * the data in a contact.
1.86 + * @param aFormattingFlags Formatting flags,
1.87 + * see TPbk2ContactTitleFormattingFlags.
1.88 + * @return A buffer containing the formatted title,
1.89 + * or the UnnamedText() method's result if no title
1.90 + * can be created.
1.91 + */
1.92 + virtual HBufC* GetContactTitleL(
1.93 + const MVPbkBaseContactFieldCollection& aContactFields,
1.94 + TUint32 aFormattingFlags ) = 0;
1.95 +
1.96 + /**
1.97 + * Returns the title text for a contact.
1.98 + *
1.99 + * @param aContactFields Field collection representing
1.100 + * the data in a contact.
1.101 + * @param aTitle Buffer containing the formatted title.
1.102 + * @param aFormattingFlags @see TPbk2ContactTitleFormattingFlags
1.103 + */
1.104 + virtual void GetContactTitle(
1.105 + const MVPbkBaseContactFieldCollection& aContactFields,
1.106 + TDes& aTitle,
1.107 + TUint32 aFormattingFlags ) = 0;
1.108 +
1.109 + /**
1.110 + * Returns the title text for a contact. Unlike GetContactTitle,
1.111 + * this method will build the title using all the possible fields
1.112 + * (not restricting the field count). Should not be used for
1.113 + * regular name formatting needs.
1.114 + *
1.115 + * @param aContactFields Field collection representing
1.116 + * the data in a contact.
1.117 + * @param aTitle Buffer containing the formatted title.
1.118 + * @param aFormattingFlags @see TPbk2ContactTitleFormattingFlags
1.119 + */
1.120 + virtual void GetContactTitleForFind(
1.121 + const MVPbkBaseContactFieldCollection& aContactFields,
1.122 + TDes& aTitle,
1.123 + TUint32 aFormattingFlags ) = 0;
1.124 +
1.125 + /**
1.126 + * Returns the name text to be used for unnamed contacts.
1.127 + *
1.128 + * @return Text used with unnamed contacts.
1.129 + */
1.130 + virtual const TDesC& UnnamedText() const = 0;
1.131 +
1.132 + /**
1.133 + * Returns ETrue if the given field is part of the fields used to
1.134 + * build the contact title.
1.135 + *
1.136 + * @param aContactField The contact field to inspect.
1.137 + * @return ETrue if the given field is used when building
1.138 + * contact titles.
1.139 + */
1.140 + virtual TBool IsTitleField(
1.141 + const MVPbkBaseContactField& aContactField ) const = 0;
1.142 +
1.143 + /**
1.144 + * Returns ETrue if the given field is part of the fields used to
1.145 + * build the contact title.
1.146 + *
1.147 + * @param aFieldType Type of the field to inspect.
1.148 + * @return ETrue if the given field type is used when
1.149 + * building contact titles.
1.150 + */
1.151 + virtual TBool IsTitleFieldType(
1.152 + const MVPbkFieldType& aFieldType ) const = 0;
1.153 +
1.154 + /**
1.155 + * Return iterator that contains all fields that are used for making
1.156 + * the formatted name.
1.157 + *
1.158 + * @param aFieldTypeList Field type list that is used to store
1.159 + * field types for the iterator. The list
1.160 + * will be resetted before use.
1.161 + * @param aContactFields Field collection representing
1.162 + * the data in a contact.
1.163 + * @return Iterator for fields that are used for the formated title.
1.164 + */
1.165 + virtual CVPbkBaseContactFieldTypeListIterator* ActualTitleFieldsLC(
1.166 + CVPbkFieldTypeRefsList& aFieldTypeList,
1.167 + const MVPbkBaseContactFieldCollection& aContactFields ) = 0;
1.168 +
1.169 + /**
1.170 + * Returns the length of the formatted name.
1.171 + *
1.172 + * @param aContactFields Field collection representing
1.173 + * the data in a contact.
1.174 + * @param aFormattingFlags @see TPbk2ContactTitleFormattingFlags
1.175 + * @return Length of the formatted name.
1.176 + */
1.177 + virtual TInt MaxTitleLength(
1.178 + const MVPbkBaseContactFieldCollection& aContactFields,
1.179 + const TUint32 aFormattingFlags ) = 0;
1.180 +
1.181 + /**
1.182 + * Returns the length of the formatted name. Unlike MaxTitleLength,
1.183 + * this method will count the length using all the possible fields
1.184 + * (not restricting the field count). Should not be used for
1.185 + * regular name formatting needs.
1.186 + *
1.187 + * @param aContactFields Field collection representing
1.188 + * the data in a contact.
1.189 + * @param aFormattingFlags @see TPbk2ContactTitleFormattingFlags
1.190 + * @return Length of the formatted name.
1.191 + */
1.192 + virtual TInt MaxTitleLengthForFind(
1.193 + const MVPbkBaseContactFieldCollection& aContactFields,
1.194 + const TUint32 aFormattingFlags ) = 0;
1.195 +
1.196 + /**
1.197 + * Checks whether the given character is a separator character.
1.198 + *
1.199 + * @param aChar Character that will be checked.
1.200 + * @return ETrue if character is a separator character.
1.201 + */
1.202 + virtual TBool IsFindSeparatorChar(
1.203 + TChar aCh ) = 0;
1.204 +
1.205 + /**
1.206 + * Returns an extension point for this interface or NULL.
1.207 + *
1.208 + * @param aExtensionUid Extension UID.
1.209 + * @return Extension point.
1.210 + */
1.211 + virtual TAny* ContactNameFormatterExtension(
1.212 + TUid /*aExtensionUid*/ )
1.213 + {
1.214 + return NULL;
1.215 + }
1.216 + };
1.217 +
1.218 +#endif // MPBK2CONTACTNAMEFORMATTER_H
1.219 +
1.220 +// End of File