/*

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

*       CAknProgressDialog should be used when the progress of the process

*       can be traced and the length of the process is known. If that's not

*       the case please use CAknWaitDialog.

*

*/

#ifndef __AKN_PROGRESS_DIALOG__

#define __AKN_PROGRESS_DIALOG__

#include <aknnotedialog.h>

#include <aknprogresstimer.h>

class CEikProgressInfo;

/**

 * MProgressDialogCallBack

 *   Inherit from this class and implement DialogDismissed to

 *   get a callback when/if a dialog is dismissed.

 */

class MProgressDialogCallback

    {

    public:

        /**

        * Callback method

        *   Gets called when a dialog is dismissed.

        */

        virtual void DialogDismissedL( TInt aButtonId ) = 0;

    };

/**

* CAknProgressDialog

*

* A note dialog with a timer. Display the note only if the process is at least 1 second long

* in order to avoid a note quickly flashing on the screen. Display the note for at least 1.5

* seconds (even if the client process is shorter that this). The client can specify an initial

* delay when displaying the note. Timer events are used for displaying and dismissing the dialog.

* The client can set the progress by specifying the values in the constructors provided.

*

* Usage:<UL> 

*   <LI> Fixed process length

*      

*        iProgressDialog = new(ELeave)CAknProgressDialog(model->FinalValue(),model->Increment(),

*                                model->Interval(),

*                                (REINTERPRET_CAST(CEikDialog**,&iProgressDialog)));

*        iProgressDialog->ExecuteLD(R_PROGRESS_NOTE);

*   </LI>

*

*   <LI> Variable process length

*      

*        iProgressDialog = new(ELeave)CAknProgressDialog(

*                                (REINTERPRET_CAST(CEikDialog**,&iProgressDialog)));

*        iProgressInfo = iProgressDialog->GetProgressInfoL();

*        iProgressInfo->SetFinalValue(model->FinalValue());

*        iProgressDialog->ExecuteLD(R_PROGRESS_NOTE);

* 

*        // Incrementing progress of the process:

*        iProgressInfo->IncrementAndDraw(model->Increment());

* 

*        // Process finished

*        iProgressDialog->ProcessFinishedL(); // deletes the dialog

*   </LI> 

*   <LI> Variable process length, modal dialog

*      

*        Set following flags in resources: EEikDialogFlagWait and EAknProgressNoteFlags

*

*        iProgressDialog = new(ELeave)CAknProgressDialog(

*                                (REINTERPRET_CAST(CEikDialog**,&iProgressDialog)));

*        iProgressInfo = iProgressDialog->GetProgressInfoL();

*        iProgressInfo->SetFinalValue(model->FinalValue());

*        iProgressInfo->SetTone( CAknNoteDialog::EConfirmationTone );

*        iProgressDialog->ExecuteLD(R_PROGRESS_NOTE);

* 

*        // Incrementing progress of the process:

*        iProgressInfo->IncrementAndDraw(model->Increment());

* 

*        // Process finished

*        iProgressDialog->ProcessFinishedL(); // deletes the dialog

*

*   <LI> Setting label dynamically

*     

*        iProgressDialog = new(ELeave)CAknProgressDialog(

*                                (REINTERPRET_CAST(CEikDialog**,&iProgressDialog)));

*        iProgressDialog->PrepareLC(R_PROGRESS_NOTE);

*        iProgressDialog->SetTextL(_L("Hello AVKON!"));

*        iProgressDialog->RunLD();

*

*    </LI></UL>

* <P>Callback:

*       To get a callback when/if the dialog has been dismissed

*       use SetCallBack API:

*           With class which uses a progressdialog:

*           - Inherit from pure virtual class MProgressDialogCallback

*           - Implement DialogDismissedL

*           - Call CAknProgressDialog->SetCallback(this);

*       

*       Or make your dialog modal. If the dialog is used as a modal, RunLD

*       returns 0 if the dialog is dismissed and EAknSoftkeyDone if not.

* </P>

* <P>Resource flags:

*        -   Always set EEikDialogFlagNotifyEsc. (or use preset avkon

*                   dialog resource flag, i.e. EAknProgressNoteFlags).

*        -   To make a dialog modal use EEikDialogFlagWait

* </P>

* <P>Note! If aVisibilityDelayOff is set to ETrue in constructor the dialog

*   will be visible immediality. This should only be used in cases where

*   the process lasts ALWAYS atleast 1.5 seconds.

* </P>

*  <P> For comprehensive example, see \Akndemo\Notesapp </P>

*/

class CAknProgressDialog : public CAknNoteDialog  

{

public:

    /**

    * Constructor

    *   Use this when the length (in time) of the process is known.

    * @param    aFinalValue     Final value for the process

    * @param    anIncrement     Increment of the process

    * @param    anInterval      Interval of the process

    * @param    aSelfPtr        Pointer to itself. The pointer must be

    *                           valid when the dialog is dismissed and it 

	*                           must not be on the stack.

    */

	IMPORT_C CAknProgressDialog(TInt aFinalValue,TInt anIncrement,TInt anInterval, CEikDialog** aSelfPtr);

    /**

    * Constructor

    *   Use this if the length of the process is unknown but the progress

    *   can be calculated.

    * @param    aSelfPtr        Pointer to itself. The pointer must be

    *                           valid when the dialog is dismissed and it

	*                           must not be on the stack.

    */

	IMPORT_C CAknProgressDialog(CEikDialog** aSelfPtr);

    /**

    * Constructor

    *   Use this if the length of the process is unknown but the progress

    *   can be calculated.

    * @param    aSelfPtr        Pointer to itself. The pointer must be

    *                           valid when the dialog is dismissed and it must

	*                           not be on the stack.

    * @param    aVisibilityDelayOff If set ETrue the dialog will be visible

    *                                   immediality. Use only when the length of

    *                                   the process is ALWAYS over 1.5 seconds.

    */

	IMPORT_C CAknProgressDialog(CEikDialog** aSelfPtr,TBool aVisibilityDelayOff);

    /**

    * Destructor

    */

	IMPORT_C virtual ~CAknProgressDialog();

	/**

    * Executes the dialog (part of dialog framework).

	* PrepareLC needs to be called before this. 

    */

	IMPORT_C virtual TInt RunLD();

    /**

    *   Get a handle to the progress bar.

    */

	IMPORT_C CEikProgressInfo* GetProgressInfoL();

    /**

    *  Handle key events (part of CONE framework)

    */

    IMPORT_C TKeyResponse OfferKeyEventL(const TKeyEvent& aKeyEvent,TEventCode aType);

    /**

    * This must be called when the dialog must be dismissed. 

	* It stops the timer and deletes the dialog.

    */

    IMPORT_C void ProcessFinishedL();

    /**

    * This callback notifies the client when the dialog is dismissed.

    * @param    aCallBack   A pointer to a class that inherits from

    *                       MProgressDialogCallback.

    */

    IMPORT_C void SetCallback( MProgressDialogCallback* aCallback );

     /**

	 * HandlePointerEventL processes pointer events directed at the 

	 * ProgressDialog.

	 * @param aPointerEvent Pointerevent to be handled.

	 */

    IMPORT_C void HandlePointerEventL(const TPointerEvent& aPointerEvent);

protected:

    /**

    * Enumeration to handle progress states

    */

    enum TProgressDialogState

        {

        EProcessOnDisplayOff, /// cannot be dismissed

        EProcessOnDisplayOn, /// cannot be dismissed

        EProcessOffDisplayOff, /// can be dismissed

        EProcessOffDisplayOn, /// cannot be dismissed

        EProcessOffDisplayOnCanBeDismissed, /// can be dismissed

        EProcessOnDisplayOnCanBeDismissed /// can be dismissed when process ends

        };

    /**

    *   Initializes dialog before layout is executed (part of dialog framework).

    */

    IMPORT_C void PreLayoutDynInitL(void);

    /**

    * Timer callback.

	*

    * @param aPtr   Pointer to this

    */

    static TInt DialogTimerCallback(TAny* aPtr);

    /**

    *   Handles timer events.

    */

    TInt DialogTimerEvent();

    /**

    * Called by the dialog framework, returns true if the 

	* dialog can exit, false otherwise.

	*

    * @param aButtonId  Id of the softkey which was pressed

    * @return           ETrue if the dialog can exit, false otherwise.

    */

    IMPORT_C TBool OkToExitL(TInt aButtonId);

private:

    /**

    * From CAknControl

    */

    IMPORT_C void* ExtensionInterface( TUid aInterface );

protected:

    /// Timer to handle dialog's visibility and existence

    CPeriodic* iProgressDialogTimer;

    /// State to handle dialog's visibility and existence

    TProgressDialogState iState;

    /// Contains progress timer's variables

    TTimerModel iModel;

    /// Callback pointer

    MProgressDialogCallback* iCallback;

    /// Boolean to declare whether the visibility delay should

    ///  be on or off.

    TBool iVisibilityDelayOff;

private:

    // Boolean to declare whether the progress is handled by

    //  an internal timer

	TBool iInternalTimerControl;

    // Timer to handle progress if iInternalTimerControl is

    //  set to ETrue

    CAknProgressTimer* iProgressTimer;

	class CCancelWhileHidden;

	CCancelWhileHidden* iCancelWhileHidden;

    TInt iSpare[3];

private: 

	IMPORT_C virtual void CEikDialog_Reserved_1();

	IMPORT_C virtual void CEikDialog_Reserved_2();	

private: 

	IMPORT_C virtual void CAknNoteDialog_Reserved();

};

#endif