/*

* 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 the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members

* which accompanies this distribution, and is available

* at the URL "http://www.symbianfoundation.org/legal/licencesv10.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