1 /*

     2 * Copyright (c) 2002 Nokia Corporation and/or its subsidiary(-ies).

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description: 

    15 *       CAknProgressDialog should be used when the progress of the process

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

    17 *       the case please use CAknWaitDialog.

    18 *

    19 */

    20 

    21 

    22 #ifndef __AKN_PROGRESS_DIALOG__

    23 #define __AKN_PROGRESS_DIALOG__

    24 

    25 #include <aknnotedialog.h>

    26 #include <aknprogresstimer.h>

    27 

    28 class CEikProgressInfo;

    29 

    30 /**

    31  * MProgressDialogCallBack

    32  *   Inherit from this class and implement DialogDismissed to

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

    34  */

    35 class MProgressDialogCallback

    36     {

    37     public:

    38         /**

    39         * Callback method

    40         *   Gets called when a dialog is dismissed.

    41         */

    42         virtual void DialogDismissedL( TInt aButtonId ) = 0;

    43     };

    44 

    45 

    46 /**

    47 * CAknProgressDialog

    48 *

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

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

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

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

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

    54 *

    55 * Usage:<UL> 

    56 *   <LI> Fixed process length

    57 *      

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

    59 *                                model->Interval(),

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

    61 *        iProgressDialog->ExecuteLD(R_PROGRESS_NOTE);

    62 *   </LI>

    63 *

    64 *   <LI> Variable process length

    65 *      

    66 *        iProgressDialog = new(ELeave)CAknProgressDialog(

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

    68 *        iProgressInfo = iProgressDialog->GetProgressInfoL();

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

    70 *        iProgressDialog->ExecuteLD(R_PROGRESS_NOTE);

    71 * 

    72 *        // Incrementing progress of the process:

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

    74 * 

    75 *        // Process finished

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

    77 *   </LI> 

    78 *   <LI> Variable process length, modal dialog

    79 *      

    80 *        Set following flags in resources: EEikDialogFlagWait and EAknProgressNoteFlags

    81 *

    82 *        iProgressDialog = new(ELeave)CAknProgressDialog(

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

    84 *        iProgressInfo = iProgressDialog->GetProgressInfoL();

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

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

    87 *        iProgressDialog->ExecuteLD(R_PROGRESS_NOTE);

    88 * 

    89 *        // Incrementing progress of the process:

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

    91 * 

    92 *        // Process finished

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

    94 *

    95 *   <LI> Setting label dynamically

    96 *     

    97 *        iProgressDialog = new(ELeave)CAknProgressDialog(

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

    99 *        iProgressDialog->PrepareLC(R_PROGRESS_NOTE);

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

   101 *        iProgressDialog->RunLD();

   102 *

   103 *    </LI></UL>

   104 * <P>Callback:

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

   106 *       use SetCallBack API:

   107 *           With class which uses a progressdialog:

   108 *           - Inherit from pure virtual class MProgressDialogCallback

   109 *           - Implement DialogDismissedL

   110 *           - Call CAknProgressDialog->SetCallback(this);

   111 *       

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

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

   114 * </P>

   115 * <P>Resource flags:

   116 *        -   Always set EEikDialogFlagNotifyEsc. (or use preset avkon

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

   118 *        -   To make a dialog modal use EEikDialogFlagWait

   119 * </P>

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

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

   122 *   the process lasts ALWAYS atleast 1.5 seconds.

   123 * </P>

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

   125 */

   126 

   127 class CAknProgressDialog : public CAknNoteDialog  

   128 {

   129 public:

   130     /**

   131     * Constructor

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

   133     * @param    aFinalValue     Final value for the process

   134     * @param    anIncrement     Increment of the process

   135     * @param    anInterval      Interval of the process

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

   137     *                           valid when the dialog is dismissed and it 

   138 	*                           must not be on the stack.

   139     */

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

   141 

   142     /**

   143     * Constructor

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

   145     *   can be calculated.

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

   147     *                           valid when the dialog is dismissed and it

   148 	*                           must not be on the stack.

   149     */

   150 	IMPORT_C CAknProgressDialog(CEikDialog** aSelfPtr);

   151 

   152     /**

   153     * Constructor

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

   155     *   can be calculated.

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

   157     *                           valid when the dialog is dismissed and it must

   158 	*                           not be on the stack.

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

   160     *                                   immediality. Use only when the length of

   161     *                                   the process is ALWAYS over 1.5 seconds.

   162     */

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

   164 

   165     /**

   166     * Destructor

   167     */

   168 	IMPORT_C virtual ~CAknProgressDialog();

   169 

   170 	/**

   171     * Executes the dialog (part of dialog framework).

   172 	* PrepareLC needs to be called before this. 

   173     */

   174 	IMPORT_C virtual TInt RunLD();

   175 

   176     /**

   177     *   Get a handle to the progress bar.

   178     */

   179 	IMPORT_C CEikProgressInfo* GetProgressInfoL();

   180 

   181     /**

   182     *  Handle key events (part of CONE framework)

   183     */

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

   185 

   186     /**

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

   188 	* It stops the timer and deletes the dialog.

   189     */

   190     IMPORT_C void ProcessFinishedL();

   191 

   192     /**

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

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

   195     *                       MProgressDialogCallback.

   196     */

   197     IMPORT_C void SetCallback( MProgressDialogCallback* aCallback );

   198     

   199      /**

   200 	 * HandlePointerEventL processes pointer events directed at the 

   201 	 * ProgressDialog.

   202 	 * @param aPointerEvent Pointerevent to be handled.

   203 	 */

   204     IMPORT_C void HandlePointerEventL(const TPointerEvent& aPointerEvent);

   205 

   206 protected:

   207     /**

   208     * Enumeration to handle progress states

   209     */

   210     enum TProgressDialogState

   211         {

   212         EProcessOnDisplayOff, /// cannot be dismissed

   213         EProcessOnDisplayOn, /// cannot be dismissed

   214         EProcessOffDisplayOff, /// can be dismissed

   215         EProcessOffDisplayOn, /// cannot be dismissed

   216         EProcessOffDisplayOnCanBeDismissed, /// can be dismissed

   217         EProcessOnDisplayOnCanBeDismissed /// can be dismissed when process ends

   218         };

   219 

   220     /**

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

   222     */

   223     IMPORT_C void PreLayoutDynInitL(void);

   224 

   225     /**

   226     * Timer callback.

   227 	*

   228     * @param aPtr   Pointer to this

   229     */

   230     static TInt DialogTimerCallback(TAny* aPtr);

   231 

   232     /**

   233     *   Handles timer events.

   234     */

   235     TInt DialogTimerEvent();

   236 

   237     /**

   238     * Called by the dialog framework, returns true if the 

   239 	* dialog can exit, false otherwise.

   240 	*

   241     * @param aButtonId  Id of the softkey which was pressed

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

   243     */

   244     IMPORT_C TBool OkToExitL(TInt aButtonId);

   245 

   246 private:

   247     /**

   248     * From CAknControl

   249     */

   250     IMPORT_C void* ExtensionInterface( TUid aInterface );

   251 

   252 protected:

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

   254     CPeriodic* iProgressDialogTimer;

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

   256     TProgressDialogState iState;

   257     /// Contains progress timer's variables

   258     TTimerModel iModel;

   259     /// Callback pointer

   260     MProgressDialogCallback* iCallback;

   261     /// Boolean to declare whether the visibility delay should

   262     ///  be on or off.

   263     TBool iVisibilityDelayOff;

   264 

   265 private:

   266     // Boolean to declare whether the progress is handled by

   267     //  an internal timer

   268 	TBool iInternalTimerControl;

   269     // Timer to handle progress if iInternalTimerControl is

   270     //  set to ETrue

   271     CAknProgressTimer* iProgressTimer;

   272 

   273 	class CCancelWhileHidden;

   274 	CCancelWhileHidden* iCancelWhileHidden;

   275 	

   276     TInt iSpare[3];

   277 

   278 private: 

   279 	IMPORT_C virtual void CEikDialog_Reserved_1();

   280 	IMPORT_C virtual void CEikDialog_Reserved_2();	

   281 private: 

   282 	IMPORT_C virtual void CAknNoteDialog_Reserved();

   283 };

   284 

   285 #endif