/*

* 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: 

*    Phonebook Data Save service helper. Implements "Save to phonebook" 

*    menu functionality for external applications.

*

*/

#ifndef __CPbkDataSaveAppUi_H__

#define __CPbkDataSaveAppUi_H__

//  INCLUDES

#include <e32base.h>

// FORWARD DECLARATIONS

class CEikMenuPane;

class CPbkContactEngine;

class CPbkContactItem;

class CPbkFieldInfo;

class MPbkDataSaveCallback;

class CPbkFFSCheck;

class CPbkExtGlobals;

// CLASS DECLARATION

/**

 * Phonebook Data Save service helper. Implements "Save to phonebook" 

 * menu functionality for external applications.

 *

 * Note that in most cases current status pane layout is replaced with the

 * Phonebook one. Restoring the original pane is left to be

 * the responsibility of the client.

 */

class CPbkDataSaveAppUi : public CBase

    {

    public:  // Interface

        /**

         * Creates an instance of this class.

         *

         * @param aEngine   Phonebook engine instance.

         */

        IMPORT_C static CPbkDataSaveAppUi* NewL(CPbkContactEngine& aEngine);

        /**

         * Destructor. Destroys this object and cancels any open dialogs.

         */

        ~CPbkDataSaveAppUi();

        /**

         * Adds Phonebook data save menu items to a menu pane. Called from 

         * applications DynInitMenuPaneL. This call is not mandatory: 

         * if the application provides its own menus it may call

         * HandleCommandL directly from menu's command handler.

         *

         * @param aMenuPane     Menu pane where to add the menu items.

         * @param aCommandId    Id of command which to replace with Phonebook

         *                      data save menu items. This command id is stored

         *                      into this object as the base id after which are

         *                      app-specific command Ids reserved for Phonebook

         *                      data save API usage.

         * @see DynInitMenuPaneL

         * @see HandleCommandL

         */

        IMPORT_C void AddMenuItemsL(CEikMenuPane* aMenuPane, TInt aCommandId);

        /**

         * Updates Phonebook data save menu items. Called from applications 

         * DynInitMenuPaneL. This call is not mandatory: if the application 

         * provides its own menus it may call HandleCommandL directly 

         * from menu's command handler.

         *

         * @param aResourceId   Resource id of the menu pane as passed to 

         *                      MEikMenuObserver::DynInitMenuPaneL. If this 

         *                      resource id does not match with Phonebook data

         *                      save submenu this function does nothing.

         * @param aMenuPane     Menu pane as passed to 

         *                      MEikMenuObserver::DynInitMenuPaneL.

         * @see AddMenuItemsL

         */

        IMPORT_C void DynInitMenuPaneL(TInt aResourceId, CEikMenuPane* aMenuPane);

        /**

         * Handles a menu command inserted by AddMenuItemsL.

         *

         * @param aCommandId        Command to execute. iBaseCommandId+1 is

         *                          Create New Entry and iBaseCommandId+2 is

         *                          Add to Existing Entry. Use directly 

         *                          EPbkCmdDataSaveCreateNew or EPbkCmdDataSaveAddToExisting

         *                          if AddMenuItemsL is not called.

         * @param aFieldTypes       Field types where the user can select from.

         *                          If there is only one field type selection

         *                          list is not displayed.

         * @param aText             Text to put to the selected field.

         * @param aCallback         Calls back to this object if there are 

         *                          problems in adding the field. See 

         *                          MPbkDataSaveCallback class for details.

         * @return  ETrue if the command was executed and the data added, 

         *          EFalse if the operation was canceled in any stage.

         * @see AddMenuItemsL

         * @see MPbkDataSaveCallback

         * @see TPbkDataSaveCommandId in PbkDataSaveAppUi.hrh

         */

        IMPORT_C TBool HandleCommandL

            (TInt aCommandId, 

            CArrayPtr<CPbkFieldInfo>& aFieldTypes,

            const TDesC& aText,

            MPbkDataSaveCallback* aCallback=NULL);

        /**

         * Handles a menu command inserted by AddMenuItemsL.

         *

         * @param aCommandId        Command to execute. iBaseCommandId+1 is

         *                          Create New Entry and iBaseCommandId+2 is

         *                          Add to Existing Entry. Use directly 

         *                          EPbkCmdDataSaveCreateNew or EPbkCmdDataSaveAddToExisting

         *                          if AddMenuItemsL is not called.

         * @param aFieldTypes       Field types where the user can select from.

         *                          If there is only one field type selection

         *                          list is not displayed.

         * @param aDate             Date to put to the selected field.

         * @param aCallback         Calls back to this object if there are 

         *                          problems in adding the field. See 

         *                          MPbkDataSaveCallback class for details.

         * @return  ETrue if the command was executed and the data added, 

         *          EFalse if the operation was canceled in any stage.

         * @see AddMenuItemsL

         * @see MPbkDataSaveCallback

         * @see TPbkDataSaveCommandId in PbkDataSaveAppUi.hrh

         */

        IMPORT_C TBool HandleCommandL

            (TInt aCommandId, 

            CArrayPtr<CPbkFieldInfo>& aFieldTypes,

            const TTime& aDate,

            MPbkDataSaveCallback* aCallback=NULL);

        /**

         * Hides the "Exit" command from contact editor's options menu.

         * Call this function after creating this object.

         */

        IMPORT_C void HideEditorExitCommand();

    private:  // Implementation

        class MFieldData;

        class CTextFieldData;

        class CDateFieldData;

        class CCommandBase;

        class CCreateNewCommand;

        class CAddToExistingCommand;

        CPbkDataSaveAppUi(CPbkContactEngine& aEngine);

        void ConstructL();

        TBool DoHandleCommandL

            (TInt aCommandId, 

            CArrayPtr<CPbkFieldInfo>& aFieldTypes,

            MFieldData& aFieldData,

            MPbkDataSaveCallback* aCallback);

    private:  // Data

        /// Ref: Phonebook engine instance

        CPbkContactEngine* iEngine;

        /// Own: FFS space checker

        CPbkFFSCheck* iFFSCheck;

        /// Own: base command id

        TInt iBaseCommandId;

        /// Own: the currently executing command

        CCommandBase* iExecutingCommand;

        /// Own: flags

        TUint iFlags;

        /// Own: handle to UI extension factory

        CPbkExtGlobals* iExtGlobals;

    };

/**

 * Callback interface for CPbkDataSaveAppUi::HandleCommandL.

 */

class MPbkDataSaveCallback

    {

    public:  // Interface

        /**

         * Called by CPbkDataSaveAppUi::HandleCommandL if there is no field

         * available where to save the data and no new field could be added.

         * Default implementation does nothing.

         *

         * @param aContact  Contact where the field cannot be added.

         */

        IMPORT_C virtual void PbkDataSaveNoFieldL(CPbkContactItem& aContact);

        /**

         * Called from CPbkDataSaveAppUi::HandleCommandL if the aText is too 

         * long to fit into field.

         * Default implementation clips aText from the end. If an empty 

         * string is returned the field addition is canceled.

         *

         * @param aText         The original text.

         * @param aFieldInfo    The type of field where the text should be 

         *                      inserted.

         * @return  A substring of aText so that the substring's length is 

         *          <=aFieldInfo.MaxLength().

         */

        IMPORT_C virtual TPtrC PbkDataSaveClipTextL

            (const TDesC& aText, CPbkFieldInfo& aFieldInfo);

    };

#endif // __CPbkDataSaveAppUi_H__

// End of File