/*
* 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