/*

 * Copyright (c) 2002 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: 

 *       Generic Phonebook address selection dialog. Used for selecting recipient

 *       address from a contact for Call, Send SMS, email and MMS.

 *

 */

 #ifndef __CPbkAddressSelect_H__

 #define __CPbkAddressSelect_H__

 //  INCLUDES

 #include <e32base.h>

 #include <coedef.h> // TKeyResponse

 #include <w32std.h> // TKeyEvent, TEventCode

 // FORWARD DECLARATIONS

 class CPbkContactItem;

 class TPbkContactItemField;

 class CPbkSelectFieldDlg;

 class CPbkFieldArray;

 // CLASS DECLARATION

 /**

  * This class is the abstrack base class for Phonebook address selection

  * dialogs. Address selection dialogs are used for selecting recipient

  * address from a contact for Call, Send SMS, email and MMS. Select one 

  * of the derived classes for a particular concrete dialog implementation.

  */

 class CPbkAddressSelect : public CBase

     {

     public:  // Interface

         /**

          * Parameters for ExecuteLD(TBaseParams&).

          * @see ExecuteLD(TBaseParams&)

          */

         class TBaseParams

             {

             public:  // Interface

                 /**

                  * Returns the contact supplied to constructor.

                  * @return Contact item.

                  */

                 IMPORT_C const CPbkContactItem& ContactItem();

                 /**

                  * Sets the focused field of the contact item. If focused field

                  * is a non-empty address field it is returned directly by

                  * ExecuteLD. The default value is NULL.

 				 * @param aFocusedField The focused field to set

                  */

                 IMPORT_C void SetFocusedField(const TPbkContactItemField* aFocusedField);

                 /**

                  * Set to ETrue to use default address of the contact directly.

                  * Focused field overrides default address if both are

                  * available. The default value is EFalse.

 				 * @param aUseDefaultDirectly   Defines whether the default address

 				 *                              should be used directly

                  */

                 IMPORT_C void SetUseDefaultDirectly(TBool aUseDefaultDirectly);

                 /**

                  * Returns the selected field or NULL if no selection was made.

                  * @return  Selected contact item field.

                  */

                 IMPORT_C const TPbkContactItemField* SelectedField() const;

                 /**

                  * Returns the focused field or NULL if there was no field

                  * level focus.

                  * @return  Focused contact item field.

                  */

                 IMPORT_C const TPbkContactItemField* FocusedField() const;

             protected:  // Derived class interface

                 /**

                  * Constructor.

                  *

                  * @param aContact      Contact from which to select an address.

                  * @param aDefaultField The field to use as the default. NULL if 

                  *                      no default is set for aContact.

                  */

                 IMPORT_C TBaseParams

                     (const CPbkContactItem& aContact, 

                     const TPbkContactItemField* aDefaultField);

             private:  // Data

 				/// Ref: the contact where to select an address

                 const CPbkContactItem& iContact;

 				/// Ref: the default field of the contact

                 const TPbkContactItemField* iDefaultField;

 				/// Ref: the focused field of the contact

                 const TPbkContactItemField* iFocusedField;

 				/// Own: is the default address to be used directly

                 TBool iUseDefaultDirectly;

 				/// Own: the selected field of the contact

                 const TPbkContactItemField* iSelectedField;

 				/// Spare data

                 TInt32 iSpare1;

 				/// Spare data

                 TInt32 iSpare2;

             private:  // friends

                 friend class CPbkAddressSelect;

             };

         /**

          * Destructor. Cancels address selection query if active.

          */

         IMPORT_C ~CPbkAddressSelect();

     protected:  // Base class interface

         /**

          * Constructor.

          */

         IMPORT_C CPbkAddressSelect();

         /**

          * Runs an address selection query (if necessary).

          *

          * @param aParams   see TBaseParams.

          * @return ETrue if query was accepted, EFalse if canceled.

          */

         IMPORT_C TBool ExecuteLD(TBaseParams& aParams);

         /**

          * Returns aItem passed to ExecuteLD.

          * @return  Contact item.

          */

         IMPORT_C const CPbkContactItem& ContactItem() const;

         /**

          * Exit any address selection query. Makes ExecuteLD return which means

          * this object is destroyed after this function returns!

          * @param aAccept   ETrue means the query selection is accepted and

          *                  EFalse that query is canceled.

          */ 

 	    IMPORT_C void AttemptExitL(TBool aAccept);

     private:    // Base class interface. Private because these functions are

                 // only to be called from this classes implementation.

         /**

          * Returns ETrue if aField is an applicable address field.

          * @param aField    Contact item field.

          * @return  ETrue if the contact item field is an applicable address field.

          */

         virtual TBool AddressField(const TPbkContactItemField& aField) const = 0;

         /**

          * Called if there are no applicable address fields in aItem passed

          * to ExecuteLD.

          */

         virtual void NoAddressesL() = 0;

         /**

          * Returns title to use for the address selection list query.

          * @return Title used for the address selection list query.

          */

         virtual const TDesC& QueryTitleL() = 0;

         /**

          * Returns a softkey resource id to use for the address 

          * selection list query.

          * @return  Softkey resource if that is used for the address 

          *          selection list query.

          */

         virtual TInt QuerySoftkeysResource() const = 0;

         /**

          * Override to handle key events in the list query.

          * The default implementation is empty.

          * @param aKeyEvent The key event.

          * @param aType The key event type.

          */

         IMPORT_C virtual TKeyResponse PbkControlKeyEventL

             (const TKeyEvent& aKeyEvent,TEventCode aType);

         // Spare virtual functions

         IMPORT_C virtual void Reserved_1();

         IMPORT_C virtual void Reserved_2();

     private: // data members

         /// Ref: aItem passed to ExecuteLD

         const CPbkContactItem* iContactItem;

         /// Field selection dialog for this class

         class CSelectFieldDlg;

         friend class CSelectFieldDlg;

         /// Own: field selection dialog

         CPbkSelectFieldDlg* iFieldDlg;

         /// Own: field array for iFieldDlg

         CPbkFieldArray* iFields;

         /// Ref: set to ETrue when exeuction enters destructor

         TBool* iDestroyedPtr;

         // Spare data

         TInt32 iSpare1;

     }; 

 #endif // __CPbkAddressSelect_H__

 // End of File