epoc32/include/app/tpbkcontactitemfield.h
author William Roberts <williamr@symbian.org>
Tue, 16 Mar 2010 16:12:26 +0000
branchSymbian2
changeset 2 2fe1408b6811
parent 1 666f914201fb
child 4 837f303aceeb
permissions -rw-r--r--
Final list of Symbian^2 public API header files
     1 /*
     2 * Copyright (c) 2002 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 the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members
     6 * which accompanies this distribution, and is available
     7 * at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
     8 *
     9 * Initial Contributors:
    10 * Nokia Corporation - initial contribution.
    11 *
    12 * Contributors:
    13 *
    14 * Description: 
    15 *     This class extends Symbian Contacts model CContactItemField class capabilities
    16 *	  to better suit Phonebook's needs.
    17 *
    18 */
    19 
    20 
    21 #ifndef __TPbkContactItemField_H__
    22 #define __TPbkContactItemField_H__
    23 
    24 //  INCLUDES
    25 #include    <e32std.h>
    26 #include    "MPbkFieldData.h"
    27 #include    <cntdef.h>  // TStorageType
    28 #include    "PbkIconId.hrh"
    29 
    30 // These two includes are not needed here anymore
    31 // and might be removed in the future
    32 #include    <cntitem.h> // CContactItem
    33 #include    <cntfldst.h> // CContactItemField storage types
    34 
    35 
    36 // FORWARD DECLARATIONS
    37 class CPbkFieldInfo;
    38 class CContactItemField;
    39 class CContactTextField;
    40 class CPbkContactItem;
    41 class CContactDateField;
    42 
    43 
    44 // CLASS DECLARATION
    45 
    46 /**
    47  * Phonebook Contact item field class.
    48  * This class extends Symbian Contacts model CContactItemField class 
    49  * capabilities to better suit Phonebook's needs.
    50  */
    51 class TPbkContactItemField : public MPbkFieldData
    52     {
    53     public:  // Constructors and destructor
    54         /**
    55          * C++ default constructor.
    56          */
    57         IMPORT_C TPbkContactItemField();
    58 
    59         /**
    60          * C++ constructor.
    61          *
    62          * @param aField        Contacts Model field this object is wrapping.
    63          * @param aFieldInfo    Phonebook field type of aField.
    64          */
    65         IMPORT_C TPbkContactItemField(CContactItemField* aField,
    66 			CPbkFieldInfo* aFieldInfo);
    67 
    68         /**
    69          * Sets the contents of this object after construction.
    70          * @param aField        Contacts Model field this object is wrapping
    71          * @param aFieldInfo    Phonebook field type of aField
    72          */
    73         IMPORT_C void Set(CContactItemField* aField,
    74 			CPbkFieldInfo* aFieldInfo);
    75 
    76     public: // New functions
    77         /**
    78          * Returns an Phonebook icon id for this field.
    79          * @return The Phonebook icon id for this field.
    80          */
    81         IMPORT_C TPbkIconId IconId() const;
    82 
    83         /**
    84          * Returns the Phonebook field info object of this field.
    85          * @return  Field info for this field.
    86          */
    87         IMPORT_C CPbkFieldInfo& FieldInfo() const;
    88 
    89         /**
    90          * Returns this field's textual content.
    91          * @return This field's textual content.
    92          * @precond StorageType()==KStorageTypeText.
    93          */ 
    94         IMPORT_C TPtrC Text() const;
    95 
    96         /**
    97          * Returns this field's date/time content.
    98          * @return This field's date/time content.
    99          * @precond StorageType()==KStorageTypeDateTime.
   100          */ 
   101         IMPORT_C TTime Time() const;
   102 
   103         /**
   104          * Fills aText with field's text content. If field is of date
   105 		 * type formats the date as text.
   106          * @param aText Fills parameter with field's content.
   107          *
   108          * @exception KErrOverflow  if aText is not big enough for
   109 		 * the text. aText contents will be clipped to aText.MaxLength().
   110          * @exception KErrNotSupported  if the field content cannot be
   111 		 * represented as text.
   112          */
   113         IMPORT_C void GetTextL(TDes& aText) const;
   114 
   115         /**
   116          * Returns the storage type of this field.
   117          * @return The storage type of this field.
   118          */
   119         IMPORT_C TStorageType StorageType() const;
   120 
   121         /**
   122          * Returns the embedded contact item field.
   123          * @return The embedded contact item field.
   124          */
   125         IMPORT_C CContactItemField& ItemField() const;
   126 
   127         /**
   128          * Returns the text storage object of this field. If the storage type is
   129          * not KStorageTypeText the function raises a panic.
   130          * @return The text storage object of this field.
   131          */
   132         IMPORT_C CContactTextField* TextStorage() const;
   133 
   134         /**
   135          * Returns the label text of this field.
   136          * @return The label text of this field.
   137          */
   138         IMPORT_C TPtrC Label() const;
   139 
   140         /**
   141          * Sets the label text of this field to aLabel.
   142          * @param aLabel Text to set as the label of this field.
   143          */
   144         IMPORT_C void SetLabelL(const TDesC& aLabel);
   145 
   146         /**
   147          * Marks this field as hidden or unhidden.
   148          * @param aHidden   ETrue marks as hidden EFalse removes the mark.
   149          */
   150         IMPORT_C void SetHidden(TBool aHidden);
   151 
   152         /**
   153          * Check if field is marked hidden.
   154          * @return ETrue if this field is hidden, EFalse if not.
   155          */
   156         IMPORT_C TBool IsHidden() const;
   157 
   158         /**
   159          * Returns time storage of this field. If the storage type is
   160          * not KStorageTypeDateTime the function raises a panic.
   161          * @return The time storage object of this field.
   162          */
   163         IMPORT_C CContactDateField* DateTimeStorage() const;
   164 
   165         /**
   166          * Returns ETrue if this is the same field as aField.
   167          * @return ETrue if this is the same field as aField.
   168          */
   169         IMPORT_C TBool IsSame(const TPbkContactItemField& aField) const;
   170 
   171         /**
   172          * Converts this field to a CContactItemField.
   173          * @return The embedded CContactItemField object.
   174          */
   175         IMPORT_C CContactItemField& ContactItemField();
   176 
   177         /**
   178          * Converts this field to a const CContactItemField.
   179          * @return The embedded CContactItemField object.
   180          */
   181         IMPORT_C const CContactItemField& ContactItemField() const;
   182 
   183         /**
   184          * Compares two items against the group ordering.
   185          * @param aRhs  Contact item field to compare to this field.
   186          */
   187         IMPORT_C TInt Compare(const TPbkContactItemField& aRhs) const;
   188 
   189         /**
   190          * Returns an unique id for this field.
   191          * NOTE: Returned id is valid only as long as this object is in memory
   192          * in other words the id is not persistent!
   193          * @return The unique id for this field.
   194          */
   195         IMPORT_C TInt UniqueFieldIdentity() const;
   196 
   197         /**
   198          * Returns ETrue if this field's contents is empty.
   199          * @return ETrue if this field's contents is empty.
   200          */
   201         IMPORT_C TBool IsEmpty() const;
   202         
   203         /**
   204          * Returns ETrue if this field's contents is empty or all spaces.
   205          * @return ETrue if this field's contents is empty or all spaces.
   206          */
   207         IMPORT_C TBool IsEmptyOrAllSpaces() const;
   208 
   209         /**
   210          * Returns ETrue is this field is a default phone number field.
   211          * @see CPbkContactItem::DefaultPhoneNumberField
   212          * @see CPbkContactItem::SetDefaultPhoneNumberField
   213          * @return ETrue is this field is a default phone number field.
   214          */
   215         IMPORT_C TBool DefaultPhoneNumberField() const;
   216         
   217         /**
   218          * Returns ETrue if this field is a default video number field.
   219          * @see CPbkContactItem::DefaultVideoNumberField
   220          * @see CPbkContactItem::SetDefaultVideoNumberField
   221          * @return ETrue if this field is a default video number field.
   222          */
   223         IMPORT_C TBool DefaultVideoNumberField() const;
   224 
   225         /**
   226          * Returns ETrue is this field is a default SMS field.
   227          * @see CPbkContactItem::DefaultSmsField
   228          * @see CPbkContactItem::SetDefaultSmsField
   229          * @return ETrue is this field is a default SMS field.
   230          */
   231         IMPORT_C TBool DefaultSmsField() const;
   232 
   233         /**
   234          * Returns ETrue is this field is a default SMS With Email field.
   235          * @see CPbkContactItem::DefaultEmailOverSmsField
   236          * @see CPbkContactItem::SetDefaultEmailOverSmsField
   237          * @return ETrue is this field is a default SMS With Email field.
   238          */
   239         IMPORT_C TBool DefaultEmailOverSmsField() const;
   240 
   241         /**
   242          * Returns ETrue is this field is a default email field.
   243          * @see CPbkContactItem::DefaultEmailField
   244          * @see CPbkContactItem::SetDefaultEmailField
   245          * @return ETrue is this field is a default email field.
   246          */
   247         IMPORT_C TBool DefaultEmailField() const;
   248 
   249         /**
   250          * Returns ETrue is this field is a default MMS field.
   251          * @see CPbkContactItem::DefaultMmsField
   252          * @see CPbkContactItem::SetDefaultMmsField
   253          * @return ETrue is this field is a default MMS field.
   254          */
   255         IMPORT_C TBool DefaultMmsField() const;
   256 
   257         /**
   258          * Returns ETrue is this field is a default POC field.
   259          * @see CPbkContactItem::DefaultPocField
   260          * @see CPbkContactItem::SetDefaultPocField
   261          * @return ETrue is this field is a default POC field.
   262          */
   263         IMPORT_C TBool DefaultPocField() const;
   264         
   265         /**
   266          * Returns ETrue is this field is a default VOIP field.
   267          * @see CPbkContactItem::DefaultVoipField
   268          * @see CPbkContactItem::SetDefaultVoipField
   269          * @return ETrue is this field is a default VOIP field.
   270          */
   271         IMPORT_C TBool DefaultVoipField() const;
   272 
   273         /**
   274          * Returns an array of speed dial indexes assigned to this field, 
   275          * NULL if none.
   276          * @return An array of speed dial indexes assigned to this field, 
   277          *         NULL if none.
   278          */
   279         IMPORT_C CArrayFix<TInt>* SpeedDialIndexesL() const;
   280 
   281     public:  // from MPbkFieldData
   282         IMPORT_C TStorageType PbkFieldType() const;
   283         IMPORT_C TPbkFieldId PbkFieldId() const;
   284         IMPORT_C TPtrC PbkFieldText() const;
   285         IMPORT_C TTime PbkFieldTime() const;
   286         
   287     private: // CPbkContactItem support functions
   288         /// CPbkContactItem calls private functions of this class
   289         friend class CPbkContactItem;
   290         void PrepareForSaveL();
   291         void PrepareAfterLoadL();
   292         TBool HasInvalidDate();
   293 
   294     private:    // Data
   295         /// Ref: Contact item field to be expanded into greater heights
   296         CContactItemField* iField;
   297         /// Ref: field info object matching iField's type
   298         CPbkFieldInfo* iFieldInfo;
   299 
   300     private:  // Friend declarations
   301         friend IMPORT_C TBool operator==
   302             (const TPbkContactItemField& aLeft, 
   303             const TPbkContactItemField& aRight);
   304     };
   305 
   306 
   307 // FUNCTION DECLARATIONS
   308 
   309 /**
   310  * Returns ETrue if aLeft has same contents as aRight.
   311  * Doesn't compare everything (all field flags etc.) but all the attributes
   312  * that could affect how this field looks like in the Phonebook UI. This 
   313  * function can be used to determine wheter to update this field in the UI.
   314  */
   315 IMPORT_C TBool operator==
   316     (const TPbkContactItemField& aLeft, 
   317     const TPbkContactItemField& aRight);
   318 
   319 /**
   320  * Returns !(aLeft==aRight).
   321  */
   322 inline TBool operator!=
   323     (const TPbkContactItemField& aLeft, 
   324     const TPbkContactItemField& aRight)
   325     {
   326     return !(aLeft==aRight);
   327     }
   328 
   329 
   330 #endif // __TPbkContactItemField_H__
   331             
   332 // End of File