epoc32/include/app/MPbk2ContactNameFormatter.h
author William Roberts <williamr@symbian.org>
Wed, 31 Mar 2010 12:33:34 +0100
branchSymbian3
changeset 4 837f303aceeb
permissions -rw-r--r--
Current Symbian^3 public API header files (from PDK 3.0.h)
This is the epoc32/include tree with the "platform" subtrees removed, and
all but a selected few mbg and rsg files removed.
     1 /*
     2 * Copyright (c) 2005-2007 Nokia Corporation and/or its subsidiary(-ies).
     3 * All rights reserved.
     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".
     8 *
     9 * Initial Contributors:
    10 * Nokia Corporation - initial contribution.
    11 *
    12 * Contributors:
    13 *
    14 * Description:  Phonebook 2 contact name formatter interface.
    15 *
    16 */
    17 
    18 
    19 #ifndef MPBK2CONTACTNAMEFORMATTER_H
    20 #define MPBK2CONTACTNAMEFORMATTER_H
    21 
    22 // INCLUDE FILES
    23 #include <e32std.h>
    24 
    25 // FORWARD DECLARATIONS
    26 class MVPbkBaseContactFieldCollection;
    27 class MVPbkFieldType;
    28 class MVPbkFieldTypeList;
    29 class CVPbkFieldTypeRefsList;
    30 class MVPbkBaseContactField;
    31 class CVPbkBaseContactFieldTypeListIterator;
    32 
    33 //Use this UID to access field property interface extension 2. Used as
    34 //a parameter to ContactNameFormatterExtension() method.
    35 const TUid MPbk2ContactNameFormatterExtension2Uid = { 2 };
    36 /**
    37  * Abstract Phonebook 2 contact name formatter interface.
    38  */
    39 class MPbk2ContactNameFormatter
    40     {
    41     public: // Interface
    42 
    43         /// Flags
    44         enum TPbk2ContactTitleFormattingFlags
    45             {
    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
    57             };
    58 
    59         /**
    60          * Destructor.
    61          */
    62         virtual ~MPbk2ContactNameFormatter()
    63                 {}
    64 
    65         /**
    66          * Returns the title text for a contact.
    67          *
    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.
    73          */
    74         virtual HBufC* GetContactTitleOrNullL(
    75                 const MVPbkBaseContactFieldCollection& aContactFields,
    76                 TUint32 aFormattingFlags ) = 0;
    77 
    78         /**
    79          * Returns the title text for a contact.
    80          *
    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 
    87          *          can be created.
    88          */
    89         virtual HBufC* GetContactTitleL(
    90                 const MVPbkBaseContactFieldCollection& aContactFields,
    91                 TUint32 aFormattingFlags ) = 0;
    92 
    93         /**
    94          * Returns the title text for a contact.
    95          *
    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
   100          */
   101         virtual void GetContactTitle(
   102                 const MVPbkBaseContactFieldCollection& aContactFields,
   103                 TDes& aTitle,
   104                 TUint32 aFormattingFlags ) = 0;
   105 
   106         /**
   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.
   111          *
   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
   116          */
   117         virtual void GetContactTitleForFind(
   118                 const MVPbkBaseContactFieldCollection& aContactFields,
   119                 TDes& aTitle,
   120                 TUint32 aFormattingFlags ) = 0;
   121 
   122         /**
   123          * Returns the name text to be used for unnamed contacts.
   124          *
   125          * @return  Text used with unnamed contacts.
   126          */
   127         virtual const TDesC& UnnamedText() const = 0;
   128 
   129         /**
   130          * Returns ETrue if the given field is part of the fields used to
   131          * build the contact title.
   132          *
   133          * @param aContactField     The contact field to inspect.
   134          * @return  ETrue if the given field is used when building
   135          *          contact titles.
   136          */
   137         virtual TBool IsTitleField(
   138                 const MVPbkBaseContactField& aContactField ) const = 0;
   139 
   140         /**
   141          * Returns ETrue if the given field is part of the fields used to
   142          * build the contact title.
   143          *
   144          * @param aFieldType    Type of the field to inspect.
   145          * @return  ETrue if the given field type is used when
   146          *          building contact titles.
   147          */
   148         virtual TBool IsTitleFieldType(
   149                 const MVPbkFieldType& aFieldType ) const = 0;
   150 
   151         /**
   152          * Return iterator that contains all fields that are used for making
   153          * the formatted name.
   154          *
   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.
   161          */
   162         virtual CVPbkBaseContactFieldTypeListIterator* ActualTitleFieldsLC(
   163                 CVPbkFieldTypeRefsList& aFieldTypeList,
   164                 const MVPbkBaseContactFieldCollection& aContactFields ) = 0;
   165 
   166         /**
   167          * Returns the length of the formatted name.
   168          *
   169          * @param aContactFields    Field collection representing
   170          *                          the data in a contact.
   171          * @param aFormattingFlags  @see TPbk2ContactTitleFormattingFlags
   172          * @return  Length of the formatted name.
   173          */
   174         virtual TInt MaxTitleLength(
   175                 const MVPbkBaseContactFieldCollection& aContactFields,
   176                 const TUint32 aFormattingFlags ) = 0;
   177 
   178         /**
   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.
   183          *
   184          * @param aContactFields    Field collection representing
   185          *                          the data in a contact.
   186          * @param aFormattingFlags  @see TPbk2ContactTitleFormattingFlags
   187          * @return  Length of the formatted name.
   188          */
   189         virtual TInt MaxTitleLengthForFind(
   190                 const MVPbkBaseContactFieldCollection& aContactFields,
   191                 const TUint32 aFormattingFlags ) = 0;
   192 
   193         /**
   194          * Checks whether the given character is a separator character.
   195          *
   196          * @param aChar     Character that will be checked.
   197          * @return ETrue if character is a separator character.
   198          */
   199         virtual TBool IsFindSeparatorChar(
   200                 TChar aCh ) = 0;
   201 
   202         /**
   203          * Returns an extension point for this interface or NULL.
   204          *
   205          * @param aExtensionUid     Extension UID.
   206          * @return  Extension point.
   207          */
   208         virtual TAny* ContactNameFormatterExtension(
   209                 TUid /*aExtensionUid*/ )
   210             {
   211             return NULL;
   212             }
   213     };
   214 
   215 #endif // MPBK2CONTACTNAMEFORMATTER_H
   216 
   217 // End of File