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