2 * Copyright (c) 2005-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: Phonebook 2 contact name formatter interface.
19 #ifndef MPBK2CONTACTNAMEFORMATTER_H
20 #define MPBK2CONTACTNAMEFORMATTER_H
25 // FORWARD DECLARATIONS
26 class MVPbkBaseContactFieldCollection;
28 class MVPbkFieldTypeList;
29 class CVPbkFieldTypeRefsList;
30 class MVPbkBaseContactField;
31 class CVPbkBaseContactFieldTypeListIterator;
33 //Use this UID to access field property interface extension 2. Used as
34 //a parameter to ContactNameFormatterExtension() method.
35 const TUid MPbk2ContactNameFormatterExtension2Uid = { 2 };
37 * Abstract Phonebook 2 contact name formatter interface.
39 class MPbk2ContactNameFormatter
44 enum TPbk2ContactTitleFormattingFlags
46 /// Formatter preserves all leading spaces
47 /// in the formatted title
48 EPreserveLeadingSpaces = 0x0001,
49 /// Formatter uses custom separator
50 /// for separating firstname and lastname
51 EUseSeparator = 0x0002,
52 /// Formatter replaces all non-graphical
53 /// characters with space character
54 EReplaceNonGraphicChars = 0x0004,
55 /// Formatter to retain all original space characters
56 EPreserveAllOriginalSpaces = 0x0008
62 virtual ~MPbk2ContactNameFormatter()
66 * Returns the title text for a contact.
68 * @param aContactFields Field collection representing
69 * the data in a contact.
70 * @param aFormattingFlags @see TPbk2ContactTitleFormattingFlags
71 * @return A buffer containing the formatted title,
72 * NULL if no title can be created.
74 virtual HBufC* GetContactTitleOrNullL(
75 const MVPbkBaseContactFieldCollection& aContactFields,
76 TUint32 aFormattingFlags ) = 0;
79 * Returns the title text for a contact.
81 * @param aContactFields Field collection representing
82 * the data in a contact.
83 * @param aFormattingFlags Formatting flags,
84 * see TPbk2ContactTitleFormattingFlags.
85 * @return A buffer containing the formatted title,
86 * or the UnnamedText() method's result if no title
89 virtual HBufC* GetContactTitleL(
90 const MVPbkBaseContactFieldCollection& aContactFields,
91 TUint32 aFormattingFlags ) = 0;
94 * Returns the title text for a contact.
96 * @param aContactFields Field collection representing
97 * the data in a contact.
98 * @param aTitle Buffer containing the formatted title.
99 * @param aFormattingFlags @see TPbk2ContactTitleFormattingFlags
101 virtual void GetContactTitle(
102 const MVPbkBaseContactFieldCollection& aContactFields,
104 TUint32 aFormattingFlags ) = 0;
107 * Returns the title text for a contact. Unlike GetContactTitle,
108 * this method will build the title using all the possible fields
109 * (not restricting the field count). Should not be used for
110 * regular name formatting needs.
112 * @param aContactFields Field collection representing
113 * the data in a contact.
114 * @param aTitle Buffer containing the formatted title.
115 * @param aFormattingFlags @see TPbk2ContactTitleFormattingFlags
117 virtual void GetContactTitleForFind(
118 const MVPbkBaseContactFieldCollection& aContactFields,
120 TUint32 aFormattingFlags ) = 0;
123 * Returns the name text to be used for unnamed contacts.
125 * @return Text used with unnamed contacts.
127 virtual const TDesC& UnnamedText() const = 0;
130 * Returns ETrue if the given field is part of the fields used to
131 * build the contact title.
133 * @param aContactField The contact field to inspect.
134 * @return ETrue if the given field is used when building
137 virtual TBool IsTitleField(
138 const MVPbkBaseContactField& aContactField ) const = 0;
141 * Returns ETrue if the given field is part of the fields used to
142 * build the contact title.
144 * @param aFieldType Type of the field to inspect.
145 * @return ETrue if the given field type is used when
146 * building contact titles.
148 virtual TBool IsTitleFieldType(
149 const MVPbkFieldType& aFieldType ) const = 0;
152 * Return iterator that contains all fields that are used for making
153 * the formatted name.
155 * @param aFieldTypeList Field type list that is used to store
156 * field types for the iterator. The list
157 * will be resetted before use.
158 * @param aContactFields Field collection representing
159 * the data in a contact.
160 * @return Iterator for fields that are used for the formated title.
162 virtual CVPbkBaseContactFieldTypeListIterator* ActualTitleFieldsLC(
163 CVPbkFieldTypeRefsList& aFieldTypeList,
164 const MVPbkBaseContactFieldCollection& aContactFields ) = 0;
167 * Returns the length of the formatted name.
169 * @param aContactFields Field collection representing
170 * the data in a contact.
171 * @param aFormattingFlags @see TPbk2ContactTitleFormattingFlags
172 * @return Length of the formatted name.
174 virtual TInt MaxTitleLength(
175 const MVPbkBaseContactFieldCollection& aContactFields,
176 const TUint32 aFormattingFlags ) = 0;
179 * Returns the length of the formatted name. Unlike MaxTitleLength,
180 * this method will count the length using all the possible fields
181 * (not restricting the field count). Should not be used for
182 * regular name formatting needs.
184 * @param aContactFields Field collection representing
185 * the data in a contact.
186 * @param aFormattingFlags @see TPbk2ContactTitleFormattingFlags
187 * @return Length of the formatted name.
189 virtual TInt MaxTitleLengthForFind(
190 const MVPbkBaseContactFieldCollection& aContactFields,
191 const TUint32 aFormattingFlags ) = 0;
194 * Checks whether the given character is a separator character.
196 * @param aChar Character that will be checked.
197 * @return ETrue if character is a separator character.
199 virtual TBool IsFindSeparatorChar(
203 * Returns an extension point for this interface or NULL.
205 * @param aExtensionUid Extension UID.
206 * @return Extension point.
208 virtual TAny* ContactNameFormatterExtension(
209 TUid /*aExtensionUid*/ )
215 #endif // MPBK2CONTACTNAMEFORMATTER_H