williamr@2: /*
williamr@2: * Copyright (c) 2002 Nokia Corporation and/or its subsidiary(-ies).
williamr@2: * All rights reserved.
williamr@2: * This component and the accompanying materials are made available
williamr@4: * under the terms of "Eclipse Public License v1.0"
williamr@2: * which accompanies this distribution, and is available
williamr@4: * at the URL "http://www.eclipse.org/legal/epl-v10.html".
williamr@2: *
williamr@2: * Initial Contributors:
williamr@2: * Nokia Corporation - initial contribution.
williamr@2: *
williamr@2: * Contributors:
williamr@2: *
williamr@2: * Description: 
williamr@2: *       CAknProgressDialog should be used when the progress of the process
williamr@2: *       can be traced and the length of the process is known. If that's not
williamr@2: *       the case please use CAknWaitDialog.
williamr@2: *
williamr@2: */
williamr@2: 
williamr@2: 
williamr@2: #ifndef __AKN_PROGRESS_DIALOG__
williamr@2: #define __AKN_PROGRESS_DIALOG__
williamr@2: 
williamr@2: #include <aknnotedialog.h>
williamr@2: #include <aknprogresstimer.h>
williamr@2: 
williamr@2: class CEikProgressInfo;
williamr@2: 
williamr@2: /**
williamr@2:  * MProgressDialogCallBack
williamr@2:  *   Inherit from this class and implement DialogDismissed to
williamr@2:  *   get a callback when/if a dialog is dismissed.
williamr@2:  */
williamr@2: class MProgressDialogCallback
williamr@2:     {
williamr@2:     public:
williamr@2:         /**
williamr@2:         * Callback method
williamr@2:         *   Gets called when a dialog is dismissed.
williamr@2:         */
williamr@2:         virtual void DialogDismissedL( TInt aButtonId ) = 0;
williamr@2:     };
williamr@2: 
williamr@2: 
williamr@2: /**
williamr@2: * CAknProgressDialog
williamr@2: *
williamr@2: * A note dialog with a timer. Display the note only if the process is at least 1 second long
williamr@2: * in order to avoid a note quickly flashing on the screen. Display the note for at least 1.5
williamr@2: * seconds (even if the client process is shorter that this). The client can specify an initial
williamr@2: * delay when displaying the note. Timer events are used for displaying and dismissing the dialog.
williamr@2: * The client can set the progress by specifying the values in the constructors provided.
williamr@2: *
williamr@2: * Usage:<UL> 
williamr@2: *   <LI> Fixed process length
williamr@2: *      
williamr@2: *        iProgressDialog = new(ELeave)CAknProgressDialog(model->FinalValue(),model->Increment(),
williamr@2: *                                model->Interval(),
williamr@2: *                                (REINTERPRET_CAST(CEikDialog**,&iProgressDialog)));
williamr@2: *        iProgressDialog->ExecuteLD(R_PROGRESS_NOTE);
williamr@2: *   </LI>
williamr@2: *
williamr@2: *   <LI> Variable process length
williamr@2: *      
williamr@2: *        iProgressDialog = new(ELeave)CAknProgressDialog(
williamr@2: *                                (REINTERPRET_CAST(CEikDialog**,&iProgressDialog)));
williamr@2: *        iProgressInfo = iProgressDialog->GetProgressInfoL();
williamr@2: *        iProgressInfo->SetFinalValue(model->FinalValue());
williamr@2: *        iProgressDialog->ExecuteLD(R_PROGRESS_NOTE);
williamr@2: * 
williamr@2: *        // Incrementing progress of the process:
williamr@2: *        iProgressInfo->IncrementAndDraw(model->Increment());
williamr@2: * 
williamr@2: *        // Process finished
williamr@2: *        iProgressDialog->ProcessFinishedL(); // deletes the dialog
williamr@2: *   </LI> 
williamr@2: *   <LI> Variable process length, modal dialog
williamr@2: *      
williamr@2: *        Set following flags in resources: EEikDialogFlagWait and EAknProgressNoteFlags
williamr@2: *
williamr@2: *        iProgressDialog = new(ELeave)CAknProgressDialog(
williamr@2: *                                (REINTERPRET_CAST(CEikDialog**,&iProgressDialog)));
williamr@2: *        iProgressInfo = iProgressDialog->GetProgressInfoL();
williamr@2: *        iProgressInfo->SetFinalValue(model->FinalValue());
williamr@2: *        iProgressInfo->SetTone( CAknNoteDialog::EConfirmationTone );
williamr@2: *        iProgressDialog->ExecuteLD(R_PROGRESS_NOTE);
williamr@2: * 
williamr@2: *        // Incrementing progress of the process:
williamr@2: *        iProgressInfo->IncrementAndDraw(model->Increment());
williamr@2: * 
williamr@2: *        // Process finished
williamr@2: *        iProgressDialog->ProcessFinishedL(); // deletes the dialog
williamr@2: *
williamr@2: *   <LI> Setting label dynamically
williamr@2: *     
williamr@2: *        iProgressDialog = new(ELeave)CAknProgressDialog(
williamr@2: *                                (REINTERPRET_CAST(CEikDialog**,&iProgressDialog)));
williamr@2: *        iProgressDialog->PrepareLC(R_PROGRESS_NOTE);
williamr@2: *        iProgressDialog->SetTextL(_L("Hello AVKON!"));
williamr@2: *        iProgressDialog->RunLD();
williamr@2: *
williamr@2: *    </LI></UL>
williamr@2: * <P>Callback:
williamr@2: *       To get a callback when/if the dialog has been dismissed
williamr@2: *       use SetCallBack API:
williamr@2: *           With class which uses a progressdialog:
williamr@2: *           - Inherit from pure virtual class MProgressDialogCallback
williamr@2: *           - Implement DialogDismissedL
williamr@2: *           - Call CAknProgressDialog->SetCallback(this);
williamr@2: *       
williamr@2: *       Or make your dialog modal. If the dialog is used as a modal, RunLD
williamr@2: *       returns 0 if the dialog is dismissed and EAknSoftkeyDone if not.
williamr@2: * </P>
williamr@2: * <P>Resource flags:
williamr@2: *        -   Always set EEikDialogFlagNotifyEsc. (or use preset avkon
williamr@2: *                   dialog resource flag, i.e. EAknProgressNoteFlags).
williamr@2: *        -   To make a dialog modal use EEikDialogFlagWait
williamr@2: * </P>
williamr@2: * <P>Note! If aVisibilityDelayOff is set to ETrue in constructor the dialog
williamr@2: *   will be visible immediality. This should only be used in cases where
williamr@2: *   the process lasts ALWAYS atleast 1.5 seconds.
williamr@2: * </P>
williamr@2: *  <P> For comprehensive example, see \Akndemo\Notesapp </P>
williamr@2: */
williamr@2: 
williamr@2: class CAknProgressDialog : public CAknNoteDialog  
williamr@2: {
williamr@2: public:
williamr@2:     /**
williamr@2:     * Constructor
williamr@2:     *   Use this when the length (in time) of the process is known.
williamr@2:     * @param    aFinalValue     Final value for the process
williamr@2:     * @param    anIncrement     Increment of the process
williamr@2:     * @param    anInterval      Interval of the process
williamr@2:     * @param    aSelfPtr        Pointer to itself. The pointer must be
williamr@2:     *                           valid when the dialog is dismissed and it 
williamr@2: 	*                           must not be on the stack.
williamr@2:     */
williamr@2: 	IMPORT_C CAknProgressDialog(TInt aFinalValue,TInt anIncrement,TInt anInterval, CEikDialog** aSelfPtr);
williamr@2: 
williamr@2:     /**
williamr@2:     * Constructor
williamr@2:     *   Use this if the length of the process is unknown but the progress
williamr@2:     *   can be calculated.
williamr@2:     * @param    aSelfPtr        Pointer to itself. The pointer must be
williamr@2:     *                           valid when the dialog is dismissed and it
williamr@2: 	*                           must not be on the stack.
williamr@2:     */
williamr@2: 	IMPORT_C CAknProgressDialog(CEikDialog** aSelfPtr);
williamr@2: 
williamr@2:     /**
williamr@2:     * Constructor
williamr@2:     *   Use this if the length of the process is unknown but the progress
williamr@2:     *   can be calculated.
williamr@2:     * @param    aSelfPtr        Pointer to itself. The pointer must be
williamr@2:     *                           valid when the dialog is dismissed and it must
williamr@2: 	*                           not be on the stack.
williamr@2:     * @param    aVisibilityDelayOff If set ETrue the dialog will be visible
williamr@2:     *                                   immediality. Use only when the length of
williamr@2:     *                                   the process is ALWAYS over 1.5 seconds.
williamr@2:     */
williamr@2: 	IMPORT_C CAknProgressDialog(CEikDialog** aSelfPtr,TBool aVisibilityDelayOff);
williamr@2: 
williamr@2:     /**
williamr@2:     * Destructor
williamr@2:     */
williamr@2: 	IMPORT_C virtual ~CAknProgressDialog();
williamr@2: 
williamr@2: 	/**
williamr@2:     * Executes the dialog (part of dialog framework).
williamr@2: 	* PrepareLC needs to be called before this. 
williamr@2:     */
williamr@2: 	IMPORT_C virtual TInt RunLD();
williamr@2: 
williamr@2:     /**
williamr@2:     *   Get a handle to the progress bar.
williamr@2:     */
williamr@2: 	IMPORT_C CEikProgressInfo* GetProgressInfoL();
williamr@2: 
williamr@2:     /**
williamr@2:     *  Handle key events (part of CONE framework)
williamr@2:     */
williamr@2:     IMPORT_C TKeyResponse OfferKeyEventL(const TKeyEvent& aKeyEvent,TEventCode aType);
williamr@2: 
williamr@2:     /**
williamr@2:     * This must be called when the dialog must be dismissed. 
williamr@2: 	* It stops the timer and deletes the dialog.
williamr@2:     */
williamr@2:     IMPORT_C void ProcessFinishedL();
williamr@2: 
williamr@2:     /**
williamr@2:     * This callback notifies the client when the dialog is dismissed.
williamr@2:     * @param    aCallBack   A pointer to a class that inherits from
williamr@2:     *                       MProgressDialogCallback.
williamr@2:     */
williamr@2:     IMPORT_C void SetCallback( MProgressDialogCallback* aCallback );
williamr@2:     
williamr@2:      /**
williamr@2: 	 * HandlePointerEventL processes pointer events directed at the 
williamr@2: 	 * ProgressDialog.
williamr@2: 	 * @param aPointerEvent Pointerevent to be handled.
williamr@2: 	 */
williamr@2:     IMPORT_C void HandlePointerEventL(const TPointerEvent& aPointerEvent);
williamr@2: 
williamr@2: protected:
williamr@2:     /**
williamr@2:     * Enumeration to handle progress states
williamr@2:     */
williamr@2:     enum TProgressDialogState
williamr@2:         {
williamr@2:         EProcessOnDisplayOff, /// cannot be dismissed
williamr@2:         EProcessOnDisplayOn, /// cannot be dismissed
williamr@2:         EProcessOffDisplayOff, /// can be dismissed
williamr@2:         EProcessOffDisplayOn, /// cannot be dismissed
williamr@2:         EProcessOffDisplayOnCanBeDismissed, /// can be dismissed
williamr@2:         EProcessOnDisplayOnCanBeDismissed /// can be dismissed when process ends
williamr@2:         };
williamr@2: 
williamr@2:     /**
williamr@2:     *   Initializes dialog before layout is executed (part of dialog framework).
williamr@2:     */
williamr@2:     IMPORT_C void PreLayoutDynInitL(void);
williamr@2: 
williamr@2:     /**
williamr@2:     * Timer callback.
williamr@2: 	*
williamr@2:     * @param aPtr   Pointer to this
williamr@2:     */
williamr@2:     static TInt DialogTimerCallback(TAny* aPtr);
williamr@2: 
williamr@2:     /**
williamr@2:     *   Handles timer events.
williamr@2:     */
williamr@2:     TInt DialogTimerEvent();
williamr@2: 
williamr@2:     /**
williamr@2:     * Called by the dialog framework, returns true if the 
williamr@2: 	* dialog can exit, false otherwise.
williamr@2: 	*
williamr@2:     * @param aButtonId  Id of the softkey which was pressed
williamr@2:     * @return           ETrue if the dialog can exit, false otherwise.
williamr@2:     */
williamr@2:     IMPORT_C TBool OkToExitL(TInt aButtonId);
williamr@2: 
williamr@2: private:
williamr@2:     /**
williamr@2:     * From CAknControl
williamr@2:     */
williamr@2:     IMPORT_C void* ExtensionInterface( TUid aInterface );
williamr@2: 
williamr@2: protected:
williamr@2:     /// Timer to handle dialog's visibility and existence
williamr@2:     CPeriodic* iProgressDialogTimer;
williamr@2:     /// State to handle dialog's visibility and existence
williamr@2:     TProgressDialogState iState;
williamr@2:     /// Contains progress timer's variables
williamr@2:     TTimerModel iModel;
williamr@2:     /// Callback pointer
williamr@2:     MProgressDialogCallback* iCallback;
williamr@2:     /// Boolean to declare whether the visibility delay should
williamr@2:     ///  be on or off.
williamr@2:     TBool iVisibilityDelayOff;
williamr@2: 
williamr@2: private:
williamr@2:     // Boolean to declare whether the progress is handled by
williamr@2:     //  an internal timer
williamr@2: 	TBool iInternalTimerControl;
williamr@2:     // Timer to handle progress if iInternalTimerControl is
williamr@2:     //  set to ETrue
williamr@2:     CAknProgressTimer* iProgressTimer;
williamr@2: 
williamr@2: 	class CCancelWhileHidden;
williamr@2: 	CCancelWhileHidden* iCancelWhileHidden;
williamr@2: 	
williamr@2:     TInt iSpare[3];
williamr@2: 
williamr@2: private: 
williamr@2: 	IMPORT_C virtual void CEikDialog_Reserved_1();
williamr@2: 	IMPORT_C virtual void CEikDialog_Reserved_2();	
williamr@2: private: 
williamr@2: 	IMPORT_C virtual void CAknNoteDialog_Reserved();
williamr@2: };
williamr@2: 
williamr@2: #endif