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