diff -r 7516d6d86cf5 -r ed14f46c0e55 src/hbwidgets/devicedialogs/hbdeviceprogressdialogsymbian.cpp --- a/src/hbwidgets/devicedialogs/hbdeviceprogressdialogsymbian.cpp Mon Oct 04 17:49:30 2010 +0300 +++ b/src/hbwidgets/devicedialogs/hbdeviceprogressdialogsymbian.cpp Mon Oct 18 18:23:13 2010 +0300 @@ -38,6 +38,7 @@ _LIT(KCancelAction, "cancelAction"); _LIT(KPluginIdentifier, "com.nokia.hb.deviceprogressdialog/1.0"); _LIT(KAnimationDefinition, "animationDefinition"); +_LIT(KShowLevel, "showLevel"); NONSHARABLE_CLASS(CHbDeviceProgressDialogSymbianPrivate) : public CBase, public MHbDeviceDialogObserver @@ -80,6 +81,7 @@ RBuf iText; RBuf iIconName; RBuf iAnimationDefinition; + TInt iShowLevel; struct { RBuf iText; struct { @@ -134,6 +136,9 @@ AddVariantL(KDialogMinimum, &iMinimum, CHbSymbianVariant::EInt, iVariantMap); AddVariantL(KDialogAutoClose, &iAutoClose, CHbSymbianVariant::EBool, iVariantMap); AddVariantL(KDialogValue, &iProgressValue, CHbSymbianVariant::EInt, iVariantMap); + if (iShowLevel) { // send only if non-default + AddVariantL(KShowLevel, &iShowLevel, CHbSymbianVariant::EInt, iVariantMap); + } if (iText.Length() > 0) { @@ -171,6 +176,7 @@ void CHbDeviceProgressDialogSymbianPrivate::UpdateL() { CHbSymbianVariantMap* map = CHbSymbianVariantMap::NewL(); + CleanupStack::PushL(map); const CHbSymbianVariant* variant = Variant(KDialogMaximum); if (variant && *variant->Value() != iMaximum) @@ -238,7 +244,8 @@ } TInt error = iDeviceDialog->Update(*map); - delete map; map = 0; + CleanupStack::PopAndDestroy(map); + map = 0; if (error != KErrNone) { User::Leave(error); // error can be positive or negative } @@ -317,9 +324,17 @@ return actionData; } +// Set dialog show level +void SetShowLevel(CHbDeviceProgressDialogSymbianPrivate *aDialog, TInt aLevel) +{ + aDialog->iShowLevel = aLevel; +} + /*! \class MHbDeviceProgressDialogObserver - \brief MHbDeviceProgressDialogObserver is an observer interface for observing CHbDeviceProgressDialogSymbian. + \brief MHbDeviceProgressDialogObserver is an observer interface for CHbDeviceProgressDialogSymbian. + + \sa CHbDeviceProgressDialogSymbian */ /*! @@ -327,52 +342,53 @@ This callback is called when the device progress dialog is closed by user pressing the "cancel" button. - \a aDialog - Pointer to dialog that was cancelled. + \param aDialog Pointer to dialog that was cancelled. */ /*! \fn void MHbDeviceProgressDialogObserver::ProgressDialogClosed(const CHbDeviceProgressDialogSymbian* aDialog) = 0 This callback is called when a device progress dialog is has closed. The closing may - be a result of Close() being called, a dialog with autoClose property has reached + be a result of Close() being called, a auto-closing dialog has reached its maximum value or user pressing cancel button. It is not called if Close() is called before ShowL(). - \a aDialog - Pointer to dialog instance that has closed. + \param aDialog Pointer to dialog instance that has closed. */ /*! + \stable + \hbwidgets + \class CHbDeviceProgressDialogSymbian \brief CHbDeviceProgressDialogSymbian is a Symbian implementation of HbDeviceProgressDialog. - It is a client interface for s60 native application to notify user with a text message, icon - and progress bar, when HbDeviceProgressDialog can not be used. + This class is Symbian only. Not available on other platforms. - CHbDeviceProgressDialogSymbian provides similar interface and functionality as HbDeviceProgressDialog. - Main difference is that signals are replaced by observer interface. Also the parameters of methods using Qt enumerations are changed to TInt. + CHbDeviceProgressDialogSymbian is intended for use by servers that don't run Qt event loop + and cannot use HbDeviceProgressDialog. - Two progress dialog types are supported: wait and progress dialog. + Device progress dialog is a modal dialog. It is shown on top of applications by device dialog + server. CHbDeviceProgressDialogSymbian is a client of the server. - Wait dialog can be used when the progress of operation cannot be determined. - As the delay is unknown, the waiting progress bar will be shown until either a user - cancels the dialog by pressing the "cancel" button or the application showing the device - wait dialog closes the dialog after the operation has finished or in case of timeout. + To learn more about usage of device progress dialogs see HbDeviceProgressDialog + documentation. - Progress dialog can be used when the progress of operation is known. For example - when deleting a number of files, the progress of the operation could be shown as a - percentage of the files deleted. Application sets the progress value during the - operation and the dialog will be shown until either a user cancels the dialog by pressing - the "cancel" button or the application showing the device progress dialog closes the - dialog after the operation is finished or in case of error. + CHbDeviceProgressDialogSymbian provides similar interface and functionality as + HbDeviceProgressDialog. Main difference is that signals are replaced by observer + interface MHbDeviceProgressDialogObserver. Also parameters of methods using + Qt enumerations are changed to TInt. + + Showing of a progress dialog is always asynchronous as an application needs to update the dialog + according to current progress. - Progress dialogs are always asynchronous by nature as the client is responsible of updating the dialog - according to current progress status. + ShowL() displays a progress dialog asynchronously. The function returns immediately. + A new dialog is lauched every time ShowL() is called. The launched + dialog can be updated by setters and then calling UpdateL(). Closing and cancellation + can be observed by a callbacks. Because each UpdateL() after the ShowL() requires + interprocess communication, it's advisable to fully construct the dialog before displaying it. - The device dialog is only shown when ShowL() is called. Because each dialog update requires - IPC calls to be made, it's advisable to fully construct the device dialog before calling - ShowL() or UpdateL(). - - Here is an example of using the infinite wait note: + Below is an example of using a device wait dialog: \code _LIT(KConnectText, "Connecting..."); @@ -381,7 +397,7 @@ iDialog->ShowL(); \endcode - Below is an example of using the device progress dialog: + Below is an example of using a device progress dialog: \code CHbDeviceProgressDialogSymbian* iDialog = CHbDeviceProgressDialogSymbian::NewL(); @@ -395,49 +411,37 @@ iDialog->UpdateL(); \endcode - CHbDeviceProgressDialogSymbian supports animations. - Supported formats are the following: + An example of showing an icon animation: - - GIF (.gif) - - MNG (.mng) - - Frame animations + \code + Create an animation definition file. - There is a built-in support for GIF and MNG animations. - - Frame animations can be created by following way: - - \code - Create an animation definition file. + + + c:\icon1.svg + c:\icon2.svg + c:\icon3.svg + + - - - c:\icon1.svg - c:\icon2.svg - c:\icon3.svg - - + Create CHbDeviceProgressDialogSymbian in a way described before and + set definition file and animation's logical name. - Create CHbDeviceProgressDialogSymbian in a way described before and - set definition file and animation's logical name. + _LIT(KAnimationDefinitionXML, "C:\animation.axml"); + _LITK(KLogicalIconName, "frame_anim_looping"); - _LIT(KAnimationDefinitionXML, "C:\animation.axml"); - _LITK(KLogicalIconName, "frame_anim_looping"); + iDialog->SetAnimationDefinitionL(KAnimationDefinitionXML); + iDialog->SetIconNameL(KIconName); + iDialog->ShowL(); + \endcode - iDialog->SetAnimationDefinitionL(KAnimationDefinitionXML); - iDialog->SetIconNameL(KIconName); - iDialog->ShowL(); - \endcode - \sa HbIconAnimationManager::addDefinitionFile - \note Animation definition files must be stored to a place where they - can be accessed. - - \sa HbDeviceProgressDialog, HbDeviceDialog - \stable - \hbwidgets + \sa MHbDeviceProgressDialogObserver, HbDeviceProgressDialog, HbDeviceDialog */ /*! \enum CHbDeviceProgressDialogSymbian::TType Progress dialog types. + + \sa HbProgressDialog::ProgressDialogType */ /*! \var CHbDeviceProgressDialogSymbian::TType CHbDeviceProgressDialogSymbian::EProgressDialog @@ -449,11 +453,11 @@ */ /*! - Symbian two phase constructor. Returns a pointer to CHbDeviceNotificationDialogSymbian instance. + Constructs a new CHbDeviceNotificationDialogSymbian and returns a pointer it. + \param aType Must be one of the defined CHbDeviceProgressDialogSymbian::TType enumerations. - \param aObserver Pointer to observer. - Default value is CHbDeviceProgressDialogSymbian::EProgressDialog. + \param aObserver Pointer to event observer. 0 if no observer. */ EXPORT_C CHbDeviceProgressDialogSymbian* CHbDeviceProgressDialogSymbian::NewL( TType aType, @@ -468,7 +472,8 @@ } /*! - Destructs the class. + Destructs CHbDeviceProgressDialogSymbian. Closes also the dialog widget launched by + ShowL(). */ EXPORT_C CHbDeviceProgressDialogSymbian::~CHbDeviceProgressDialogSymbian() { @@ -476,7 +481,13 @@ } /*! - Executes the dialog asynchronously. + Shows a device progress dialog asyncronously. Function launches the dialog and returns + immediately. Closing of the dialog can be observer with MHbDeviceProgressDialogObserver. + CHbDeviceProgressDialogSymbian object can be used to launch several dialogs. A new one + is launched every time ShowL() is called. Observer receives events for the latest dialog + launched. + + \sa SetObserver(), UpdateL() */ EXPORT_C void CHbDeviceProgressDialogSymbian::ShowL() { @@ -484,7 +495,11 @@ } /*! - Updates the dialog asynchronously. + Updates a device progress dialog asyncronously. Dialog that was launched with a lates ShowL() + is updated. Properties that were modified since the last ShowL() or UpdateL() are sent to + device dialog server. + + \sa ShowL() */ EXPORT_C void CHbDeviceProgressDialogSymbian::UpdateL() { @@ -492,7 +507,7 @@ } /*! - Closes the dialog. + Closes a device progress dialog. */ EXPORT_C void CHbDeviceProgressDialogSymbian::Close() { @@ -500,11 +515,12 @@ } /*! - Sets the minimum and maximum value of the progress bar within the dialog. - \param aMin minimum value of the progress bar. - \param aMax maximum value of the progress bar. + Sets progress bar minimum and maximum values. - \sa Minimum(), Maximum() + \param aMin Progress bar minimum value. + \param aMax Progress bar maximum value. + + \sa Minimum(), Maximum(), ShowL(), UpdateL() */ EXPORT_C void CHbDeviceProgressDialogSymbian::SetRange(TInt aMin, TInt aMax) { @@ -513,9 +529,11 @@ } /*! - Sets the maximum value of the progress bar within the dialog. - \param aMax maximum value of the progress bar. - \sa Maximum() + Sets progress bar maximum value. + + \param aMax Progress bar maximum value. + + \sa Maximum(), ShowL(), UpdateL() */ EXPORT_C void CHbDeviceProgressDialogSymbian::SetMaximum(TInt aMax) { @@ -525,9 +543,8 @@ } /*! - Returns the maximum value of the progress bar within the dialog. + Returns progress bar maximum value. Default value is 100. - The default value is 100. \sa SetMaximum() */ EXPORT_C TInt CHbDeviceProgressDialogSymbian::Maximum() const @@ -536,9 +553,11 @@ } /*! - Sets the minimum value of the progress bar within the dialog. - \param aMin minimum value of the progress bar. - \sa Minimum() + Sets progress bar minimum value. + + \param aMin Progress bar minimum value. + + \sa Minimum(), ShowL(), UpdateL() */ EXPORT_C void CHbDeviceProgressDialogSymbian::SetMinimum(TInt aMin) { @@ -548,9 +567,8 @@ } /*! - Returns the minimum value of the progress bar within the dialog. + Returns progress bar minimum value. Default value is 0. - The default value is 0. \sa SetMinimumL() */ EXPORT_C TInt CHbDeviceProgressDialogSymbian::Minimum() const @@ -559,10 +577,12 @@ } /*! - Sets the autoClose property value of the dialog. + Sets dialog auto-closing. + \param aAutoClose When set, the dialog is closed when value of the progress bar reaches the maximum value of the progress bar. - \sa AutoClose() + + \sa AutoClose(), ShowL(), UpdateL() */ EXPORT_C void CHbDeviceProgressDialogSymbian::SetAutoClose(TBool aAutoClose) { @@ -570,10 +590,9 @@ } /*! - Returns the value of the autoClose property of the dialog. + Returns dialog auto-closing property. Default value is true for progress dialog and false + for wait dialog. - The default value is true for CHbDeviceProgressDialogSymbian::ProgressDialod and false - for CHbDeviceProgressDialogSymbian::WaitDialog. \sa SetAutoCloseL() */ EXPORT_C TBool CHbDeviceProgressDialogSymbian::AutoClose() const @@ -582,9 +601,12 @@ } /*! - Sets dialog type. - \param aType defines the type of the dialog. - \sa ProgressType() + Sets dialog type. Dialog properties are set to default values. After setting type, + ShowL() must be called to launch a new dialog. + + \param aType Dialog type, wait or progress, + + \sa ProgressType(), ShowL() */ EXPORT_C void CHbDeviceProgressDialogSymbian::SetProgressType( CHbDeviceProgressDialogSymbian::TType aType) @@ -605,6 +627,7 @@ /*! Returns dialog's type. + \sa SetProgressType() */ EXPORT_C CHbDeviceProgressDialogSymbian::TType CHbDeviceProgressDialogSymbian::ProgressType() const @@ -613,9 +636,11 @@ } /*! - Sets the value of the progress bar within the dialog. - \param aProgressValue value of the progress bar. - \sa ProgressValue() + Sets progress bar value. + + \param aProgressValue Progress bar value. + + \sa ProgressValue(), ShowL(), UpdateL() */ EXPORT_C void CHbDeviceProgressDialogSymbian::SetProgressValue(TInt aProgressValue) { @@ -623,7 +648,8 @@ } /*! - Returns the value of the progress bar within the dialog. + Returns progress bar value. + \sa SetProgressValue() */ EXPORT_C TInt CHbDeviceProgressDialogSymbian::ProgressValue() const @@ -632,9 +658,11 @@ } /*! - Sets text of the dialog. - \param aText dialog text. - \sa Text() + Sets dialog text. + + \param aText Dialog text. + + \sa Text(), ShowL(), UpdateL() */ EXPORT_C void CHbDeviceProgressDialogSymbian::SetTextL(const TDesC& aText) { @@ -647,7 +675,8 @@ } /*! - Returns text of the note. + Returns dialog text. + \sa SetTextL() */ EXPORT_C const TPtrC CHbDeviceProgressDialogSymbian::Text() const @@ -656,13 +685,12 @@ } /*! - Sets message box icon name or animation logical name. The message box gets updated next time ShowL() or UpdateL() - is called. + Sets dialog icon name or animation logical name. - \param aIconName Icon name. Icon can be from Hb resources or themes. Or it can be a file in + \param aIconName Icon or animation name. Icon can be from Hb resources or themes. Or it can be a file in a file system. - \sa IconName() + \sa IconName(), ShowL(), UpdateL() */ EXPORT_C void CHbDeviceProgressDialogSymbian::SetIconNameL(const TDesC& aIconName) { @@ -675,7 +703,7 @@ } /*! - Returns name and path of the icon shown on dialog or animation's logical name. + Returns name and path of icon or animation. \sa SetIconNameL() */ @@ -685,13 +713,18 @@ } /*! - Sets notification dialog's animation definition name. The dialogs get updated next when time ShowL() or UpdateL() - is called. + Sets dialog animation definition name. + + Supported icon animation formats are following: + - GIF (.gif) + - MNG (.mng) + - Frame animations \param aAnimationDefinition Animation definition file name. Definition can be from Hb resources or themes. - Or can be a file in a file system. + Or can be a file in a file system. The definition must be stored to a place where it can be accessed by + device dialog service. - \sa AnimationDefinition() + \sa AnimationDefinition() SetIconNameL() HbIconAnimationManager::addDefinitionFile(), ShowL(), UpdateL() */ EXPORT_C void CHbDeviceProgressDialogSymbian::SetAnimationDefinitionL(const TDesC& aAnimationDefinition) { @@ -704,22 +737,21 @@ } /*! - Returns an animation definition set for a dialog. If not set, return string. + Returns dialog icon animation definition name. \sa SetAnimationDefinitionL() */ EXPORT_C TPtrC CHbDeviceProgressDialogSymbian::AnimationDefinition() const - { - return d->iAnimationDefinition; - } + { + return d->iAnimationDefinition; + } /*! - Sets progress dialog box button text. The dialog gets updated next time ShowL() or UpdateL() - is called. + Sets dialog button text. \param aText Button text. - \sa ButtonText() + \sa ButtonText(), ShowL(), UpdateL() */ EXPORT_C void CHbDeviceProgressDialogSymbian::SetButtonTextL(const TDesC& aText) { @@ -733,7 +765,7 @@ } /*! - Returns progress dialog button text. + Returns dialog button text. \sa SetButtonTextL() */ @@ -743,12 +775,11 @@ } /*! - Sets progress dialog button presence. The dialog updated next time ShowL() or UpdateL() - is called. + Sets progress dialog button presence. \param aEnable True enables (makes visible) the dialog button. - \sa HasButton() + \sa HasButton(), ShowL(), UpdateL() */ EXPORT_C void CHbDeviceProgressDialogSymbian::SetButton(TBool aEnable) { @@ -758,9 +789,7 @@ } /*! - Returns progress dialog button presence. - - \param aButton Selects the button. + Returns dialog button presence. \sa SetButton() */ @@ -770,7 +799,8 @@ } /*! - Sets progress dialog observer. The observer is called when progress dialog is closed. + Sets dialog observer. The observer is called when the dialog is closed or cancelled. + \param aObserver Pointer to observer. \sa MHbDeviceProgressDialogObserver @@ -780,8 +810,8 @@ d->iObserver = aObserver; } -/* - Constructor. +/*! + Constructs CHbDeviceProgressDialogSymbian. */ CHbDeviceProgressDialogSymbian::CHbDeviceProgressDialogSymbian() {