--- a/epoc32/include/mw/aknprogressdialog.h Tue Nov 24 13:55:44 2009 +0000
+++ b/epoc32/include/mw/aknprogressdialog.h Tue Mar 16 16:12:26 2010 +0000
@@ -1,1 +1,285 @@
-aknprogressdialog.h
+/*
+* 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