--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/contacts_plat/phonebook_2_presentation_api/inc/MPbk2ContactNameFormatter.h Wed Sep 01 12:29:52 2010 +0100
@@ -0,0 +1,220 @@
+/*
+* Copyright (c) 2005-2007 Nokia Corporation and/or its subsidiary(-ies).
+* All rights reserved.
+* This component and the accompanying materials are made available
+* under the terms of "Eclipse Public License v1.0"
+* which accompanies this distribution, and is available
+* at the URL "http://www.eclipse.org/legal/epl-v10.html".
+*
+* Initial Contributors:
+* Nokia Corporation - initial contribution.
+*
+* Contributors:
+*
+* Description: Phonebook 2 contact name formatter interface.
+*
+*/
+
+
+#ifndef MPBK2CONTACTNAMEFORMATTER_H
+#define MPBK2CONTACTNAMEFORMATTER_H
+
+// INCLUDE FILES
+#include <e32std.h>
+
+// FORWARD DECLARATIONS
+class MVPbkBaseContactFieldCollection;
+class MVPbkFieldType;
+class MVPbkFieldTypeList;
+class CVPbkFieldTypeRefsList;
+class MVPbkBaseContactField;
+class CVPbkBaseContactFieldTypeListIterator;
+
+//Use this UID to access field property interface extension 2. Used as
+//a parameter to ContactNameFormatterExtension() method.
+const TUid MPbk2ContactNameFormatterExtension2Uid = { 2 };
+/**
+ * Abstract Phonebook 2 contact name formatter interface.
+ */
+class MPbk2ContactNameFormatter
+ {
+ public: // Interface
+
+ /// Flags
+ enum TPbk2ContactTitleFormattingFlags
+ {
+ /// Formatter preserves all leading spaces
+ /// in the formatted title
+ EPreserveLeadingSpaces = 0x0001,
+ /// Formatter uses custom separator
+ /// for separating firstname and lastname
+ EUseSeparator = 0x0002,
+ /// Formatter replaces all non-graphical
+ /// characters with space character
+ EReplaceNonGraphicChars = 0x0004,
+ /// Formatter to retain all original space characters
+ EPreserveAllOriginalSpaces = 0x0008,
+ /// Formatter by default uses coma separator
+ /// for separating company name
+ EDisableCompanyNameSeparator = 0x0010
+ };
+
+ /**
+ * Destructor.
+ */
+ virtual ~MPbk2ContactNameFormatter()
+ {}
+
+ /**
+ * Returns the title text for a contact.
+ *
+ * @param aContactFields Field collection representing
+ * the data in a contact.
+ * @param aFormattingFlags @see TPbk2ContactTitleFormattingFlags
+ * @return A buffer containing the formatted title,
+ * NULL if no title can be created.
+ */
+ virtual HBufC* GetContactTitleOrNullL(
+ const MVPbkBaseContactFieldCollection& aContactFields,
+ TUint32 aFormattingFlags ) = 0;
+
+ /**
+ * Returns the title text for a contact.
+ *
+ * @param aContactFields Field collection representing
+ * the data in a contact.
+ * @param aFormattingFlags Formatting flags,
+ * see TPbk2ContactTitleFormattingFlags.
+ * @return A buffer containing the formatted title,
+ * or the UnnamedText() method's result if no title
+ * can be created.
+ */
+ virtual HBufC* GetContactTitleL(
+ const MVPbkBaseContactFieldCollection& aContactFields,
+ TUint32 aFormattingFlags ) = 0;
+
+ /**
+ * Returns the title text for a contact.
+ *
+ * @param aContactFields Field collection representing
+ * the data in a contact.
+ * @param aTitle Buffer containing the formatted title.
+ * @param aFormattingFlags @see TPbk2ContactTitleFormattingFlags
+ */
+ virtual void GetContactTitle(
+ const MVPbkBaseContactFieldCollection& aContactFields,
+ TDes& aTitle,
+ TUint32 aFormattingFlags ) = 0;
+
+ /**
+ * Returns the title text for a contact. Unlike GetContactTitle,
+ * this method will build the title using all the possible fields
+ * (not restricting the field count). Should not be used for
+ * regular name formatting needs.
+ *
+ * @param aContactFields Field collection representing
+ * the data in a contact.
+ * @param aTitle Buffer containing the formatted title.
+ * @param aFormattingFlags @see TPbk2ContactTitleFormattingFlags
+ */
+ virtual void GetContactTitleForFind(
+ const MVPbkBaseContactFieldCollection& aContactFields,
+ TDes& aTitle,
+ TUint32 aFormattingFlags ) = 0;
+
+ /**
+ * Returns the name text to be used for unnamed contacts.
+ *
+ * @return Text used with unnamed contacts.
+ */
+ virtual const TDesC& UnnamedText() const = 0;
+
+ /**
+ * Returns ETrue if the given field is part of the fields used to
+ * build the contact title.
+ *
+ * @param aContactField The contact field to inspect.
+ * @return ETrue if the given field is used when building
+ * contact titles.
+ */
+ virtual TBool IsTitleField(
+ const MVPbkBaseContactField& aContactField ) const = 0;
+
+ /**
+ * Returns ETrue if the given field is part of the fields used to
+ * build the contact title.
+ *
+ * @param aFieldType Type of the field to inspect.
+ * @return ETrue if the given field type is used when
+ * building contact titles.
+ */
+ virtual TBool IsTitleFieldType(
+ const MVPbkFieldType& aFieldType ) const = 0;
+
+ /**
+ * Return iterator that contains all fields that are used for making
+ * the formatted name.
+ *
+ * @param aFieldTypeList Field type list that is used to store
+ * field types for the iterator. The list
+ * will be resetted before use.
+ * @param aContactFields Field collection representing
+ * the data in a contact.
+ * @return Iterator for fields that are used for the formated title.
+ */
+ virtual CVPbkBaseContactFieldTypeListIterator* ActualTitleFieldsLC(
+ CVPbkFieldTypeRefsList& aFieldTypeList,
+ const MVPbkBaseContactFieldCollection& aContactFields ) = 0;
+
+ /**
+ * Returns the length of the formatted name.
+ *
+ * @param aContactFields Field collection representing
+ * the data in a contact.
+ * @param aFormattingFlags @see TPbk2ContactTitleFormattingFlags
+ * @return Length of the formatted name.
+ */
+ virtual TInt MaxTitleLength(
+ const MVPbkBaseContactFieldCollection& aContactFields,
+ const TUint32 aFormattingFlags ) = 0;
+
+ /**
+ * Returns the length of the formatted name. Unlike MaxTitleLength,
+ * this method will count the length using all the possible fields
+ * (not restricting the field count). Should not be used for
+ * regular name formatting needs.
+ *
+ * @param aContactFields Field collection representing
+ * the data in a contact.
+ * @param aFormattingFlags @see TPbk2ContactTitleFormattingFlags
+ * @return Length of the formatted name.
+ */
+ virtual TInt MaxTitleLengthForFind(
+ const MVPbkBaseContactFieldCollection& aContactFields,
+ const TUint32 aFormattingFlags ) = 0;
+
+ /**
+ * Checks whether the given character is a separator character.
+ *
+ * @param aChar Character that will be checked.
+ * @return ETrue if character is a separator character.
+ */
+ virtual TBool IsFindSeparatorChar(
+ TChar aCh ) = 0;
+
+ /**
+ * Returns an extension point for this interface or NULL.
+ *
+ * @param aExtensionUid Extension UID.
+ * @return Extension point.
+ */
+ virtual TAny* ContactNameFormatterExtension(
+ TUid /*aExtensionUid*/ )
+ {
+ return NULL;
+ }
+ };
+
+#endif // MPBK2CONTACTNAMEFORMATTER_H
+
+// End of File