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