CAknProgressDialog Class Reference

API published in: S60 1st Ed

Link against: avkon.lib eikctl.lib eikcdlg.lib

Capability Information

Required Capabilities

None

#include <aknprogressdialog.h>

Inherits CAknNoteDialog.

Inherited by CAknWaitDialog.

Detailed Description

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:

Fixed process length

iProgressDialog = new(ELeave)CAknProgressDialog(model->FinalValue(),model->Increment(), model->Interval(), (REINTERPRET_CAST(CEikDialog**,&iProgressDialog))); iProgressDialog->ExecuteLD(R_PROGRESS_NOTE);

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
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
Setting label dynamically
iProgressDialog = new(ELeave)CAknProgressDialog( (REINTERPRET_CAST(CEikDialog**,&iProgressDialog))); iProgressDialog->PrepareLC(R_PROGRESS_NOTE); iProgressDialog->SetTextL(_L("Hello AVKON!")); iProgressDialog->RunLD();

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.

Resource flags:

Always set EEikDialogFlagNotifyEsc. (or use preset avkon dialog resource flag, i.e. EAknProgressNoteFlags).
To make a dialog modal use EEikDialogFlagWait

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.

For comprehensive example, see


Public Member Functions
IMPORT_C	CAknProgressDialog (TInt aFinalValue, TInt anIncrement, TInt anInterval, CEikDialog **aSelfPtr)
	Constructor Use this when the length (in time) of the process is known.
IMPORT_C	CAknProgressDialog (CEikDialog **aSelfPtr)
	Constructor Use this if the length of the process is unknown but the progress can be calculated.
IMPORT_C	CAknProgressDialog (CEikDialog **aSelfPtr, TBool aVisibilityDelayOff)
	Constructor Use this if the length of the process is unknown but the progress can be calculated.
virtual IMPORT_C	~CAknProgressDialog ()
	Destructor.
virtual IMPORT_C TInt	RunLD ()
	Executes the dialog (part of dialog framework).
IMPORT_C CEikProgressInfo *	GetProgressInfoL ()
	Get a handle to the progress bar.
IMPORT_C TKeyResponse	OfferKeyEventL (const TKeyEvent &aKeyEvent, TEventCode aType)
	Handle key events (part of CONE framework).
IMPORT_C void	ProcessFinishedL ()
	This must be called when the dialog must be dismissed.
IMPORT_C void	SetCallback (MProgressDialogCallback *aCallback)
	This callback notifies the client when the dialog is dismissed.
IMPORT_C void	HandlePointerEventL (const TPointerEvent &aPointerEvent)
	HandlePointerEventL processes pointer events directed at the ProgressDialog.
Protected Types
enum	TProgressDialogState { EProcessOnDisplayOff, EProcessOnDisplayOn, EProcessOffDisplayOff, EProcessOffDisplayOn, EProcessOffDisplayOnCanBeDismissed, EProcessOnDisplayOnCanBeDismissed }
	Enumeration to handle progress states. More...
Protected Member Functions
IMPORT_C void	PreLayoutDynInitL (void)
	Initializes dialog before layout is executed (part of dialog framework).
TInt	DialogTimerEvent ()
	Handles timer events.
IMPORT_C TBool	OkToExitL (TInt aButtonId)
	Called by the dialog framework, returns true if the dialog can exit, false otherwise.
Static Protected Member Functions
static TInt	DialogTimerCallback (TAny *aPtr)
	Timer callback.
Protected Attributes
CPeriodic *	iProgressDialogTimer
	Timer to handle dialog's visibility and existence.
TProgressDialogState	iState
	State to handle dialog's visibility and existence.
TTimerModel	iModel
	Contains progress timer's variables.
MProgressDialogCallback *	iCallback
	Callback pointer.
TBool	iVisibilityDelayOff
	Boolean to declare whether the visibility delay should be on or off.

Member Enumeration Documentation

enum CAknProgressDialog::TProgressDialogState [protected]

Enumeration to handle progress states.

Enumerator:

EProcessOnDisplayOff
EProcessOnDisplayOn	cannot be dismissed
EProcessOffDisplayOff	cannot be dismissed
EProcessOffDisplayOn	can be dismissed
EProcessOffDisplayOnCanBeDismissed	cannot be dismissed
EProcessOnDisplayOnCanBeDismissed	can be dismissed when process ends

Constructor & Destructor Documentation

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

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

Parameters:

	aFinalValue	Final value for the process
	anIncrement	Increment of the process
	anInterval	Interval of the process
	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::CAknProgressDialog

Constructor Use this if the length of the process is unknown but the progress can be calculated.

Parameters:

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::CAknProgressDialog	(	CEikDialog **	aSelfPtr,
		TBool	aVisibilityDelayOff
	)

Constructor Use this if the length of the process is unknown but the progress can be calculated.

Parameters:

	aSelfPtr	Pointer to itself. The pointer must be valid when the dialog is dismissed and it must not be on the stack.
	aVisibilityDelayOff	If set ETrue the dialog will be visible immediality. Use only when the length of the process is ALWAYS over 1.5 seconds.

virtual IMPORT_C CAknProgressDialog::~CAknProgressDialog ( ) [virtual]

Destructor.