FCL/sf/mw/hb: comparison src/hbwidgets/devicedialogs/hbdeviceprogressdialogsymbian.cpp

equal deleted inserted replaced

-:e6ad4ef83b23
+:b7da29130b0e
 aDialog->iShowLevel = aLevel;
 }
 /*!
 \class MHbDeviceProgressDialogObserver
-\brief MHbDeviceProgressDialogObserver is an observer interface for observing CHbDeviceProgressDialogSymbian.
+\brief MHbDeviceProgressDialogObserver is an observer interface for CHbDeviceProgressDialogSymbian.
+\sa CHbDeviceProgressDialogSymbian
 */
 /*!
 \fn void MHbDeviceProgressDialogObserver::ProgressDialogCancelled(const CHbDeviceProgressDialogSymbian* aDialog) = 0
 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
+<b>This class is Symbian only. Not available on other platforms.</b>
-and progress bar, when HbDeviceProgressDialog can not be used.
+CHbDeviceProgressDialogSymbian is intended for use by servers that don't run Qt event loop
-CHbDeviceProgressDialogSymbian provides similar interface and functionality as HbDeviceProgressDialog.
+and cannot use HbDeviceProgressDialog.
-Main difference is that signals are replaced by observer interface. Also the parameters of methods using Qt enumerations are changed to TInt.
+Device progress dialog is a modal dialog. It is shown on top of applications by device dialog
-Two progress dialog types are supported: wait and progress dialog.
+server. CHbDeviceProgressDialogSymbian is a client of the server.
-Wait dialog can be used when the progress of operation cannot be determined.
+To learn more about usage of device progress dialogs see HbDeviceProgressDialog
-As the delay is unknown, the waiting progress bar will be shown until either a user
+documentation.
-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.
+CHbDeviceProgressDialogSymbian provides similar interface and functionality as
+HbDeviceProgressDialog. Main difference is that signals are replaced by observer
-Progress dialog can be used when the progress of operation is known. For example
+interface MHbDeviceProgressDialogObserver. Also parameters of methods using
-when deleting a number of files, the progress of the operation could be shown as a
+Qt enumerations are changed to TInt.
-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
+Showing of a progress dialog is always asynchronous as an application needs to update the dialog
-the "cancel" button or the application showing the device progress dialog closes the
+according to current progress.
-dialog after the operation is finished or in case of error.
+ShowL() displays a progress dialog asynchronously. The function returns immediately.
-Progress dialogs are always asynchronous by nature as the client is responsible of updating the dialog
+A new dialog is lauched every time ShowL() is called. The launched
-according to current progress status.
+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
-The device dialog is only shown when ShowL() is called. Because each dialog update requires
+interprocess communication, it's advisable to fully construct the dialog before displaying it.
-IPC calls to be made, it's advisable to fully construct the device dialog before calling
-ShowL() or UpdateL().
+Below is an example of using a device wait dialog:
-Here is an example of using the infinite wait note:
 \code
 _LIT(KConnectText, "Connecting...");
 CHbDeviceProgressDialogSymbian *iDialog = CHbDeviceProgressDialogSymbian::NewL(CHbDeviceProgressDialogSymbian::EWaitDialog);
 iDialog->SetTextL(KConnectText);
 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();
 _LIT(KUpdatingText, "Updating...");
 iDialog->SetTextL(KUpdatingText);
 iDialog->SetMaximum(76);
 iDialog->SetProgressValue(25);
 iDialog->UpdateL();
 \endcode
-CHbDeviceProgressDialogSymbian supports animations.
+An example of showing an icon animation:
-Supported formats are the following:
-- GIF (.gif)
-- MNG (.mng)
-- Frame animations
-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.
 <animations>
 iDialog->SetAnimationDefinitionL(KAnimationDefinitionXML);
 iDialog->SetIconNameL(KIconName);
 iDialog->ShowL();
 \endcode
-\sa HbIconAnimationManager::addDefinitionFile
-\note Animation definition files must be stored to a place where they
+\sa MHbDeviceProgressDialogObserver, HbDeviceProgressDialog, HbDeviceDialog
-can be accessed.
-\sa HbDeviceProgressDialog, HbDeviceDialog
-\stable
-\hbwidgets
 */
 /*!
 \enum CHbDeviceProgressDialogSymbian::TType
 Progress dialog types.
+\sa HbProgressDialog::ProgressDialogType
 */
 /*!
 \var CHbDeviceProgressDialogSymbian::TType CHbDeviceProgressDialogSymbian::EProgressDialog
 Progress dialog.
 */
 Wait dialog.
 */
 /*!
 Symbian two phase constructor. Returns a pointer to CHbDeviceNotificationDialogSymbian instance.
 \param aType Must be one of the defined CHbDeviceProgressDialogSymbian::TType enumerations.
+Default value is CHbDeviceProgressDialogSymbian::EProgressDialog.
 \param aObserver Pointer to observer.
-Default value is CHbDeviceProgressDialogSymbian::EProgressDialog.
 */
 EXPORT_C CHbDeviceProgressDialogSymbian* CHbDeviceProgressDialogSymbian::NewL(
 TType aType,
 MHbDeviceProgressDialogObserver* aObserver)
 {
 CleanupStack::Pop(self);
 return self;
 }
 /*!
-Destructs the class.
+Destructor.
 */
 EXPORT_C CHbDeviceProgressDialogSymbian::~CHbDeviceProgressDialogSymbian()
 {
 delete d;
 }
 /*!
-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()
 {
 d->ShowL();
 }
 /*!
-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()
 {
 d->UpdateL();
 }
 /*!
-Closes the dialog.
+Closes a device progress dialog.
 */
 EXPORT_C void CHbDeviceProgressDialogSymbian::Close()
 {
 d->Close();
 }
 /*!
-Sets the minimum and maximum value of the progress bar within the dialog.
+Sets progress bar minimum and maximum values.
-\param aMin minimum value of the progress bar.
-\param aMax maximum value of the progress bar.
+\param aMin Progress bar minimum value.
+\param aMax Progress bar maximum value.
-\sa Minimum(), Maximum()
+\sa Minimum(), Maximum(), ShowL(), UpdateL()
 */
 EXPORT_C void CHbDeviceProgressDialogSymbian::SetRange(TInt aMin, TInt aMax)
 {
 SetMinimum(aMin);
 SetMaximum(aMax);
 }
 /*!
-Sets the maximum value of the progress bar within the dialog.
+Sets progress bar maximum value.
-\param aMax maximum value of the progress bar.
-\sa Maximum()
+\param aMax Progress bar maximum value.
+\sa Maximum(), ShowL(), UpdateL()
 */
 EXPORT_C void CHbDeviceProgressDialogSymbian::SetMaximum(TInt aMax)
 {
 // Don't allow wait dialog to set max/min other than zero as wait
 // animation bar doesn't work in that case.
 d->iMaximum = d->iType == EWaitDialog ? 0 : aMax;
 }
 /*!
-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
 {
 return d->iMaximum;
 }
 /*!
-Sets the minimum value of the progress bar within the dialog.
+Sets progress bar minimum value.
-\param aMin minimum value of the progress bar.
-\sa Minimum()
+\param aMin Progress bar minimum value.
+\sa Minimum(), ShowL(), UpdateL()
 */
 EXPORT_C void CHbDeviceProgressDialogSymbian::SetMinimum(TInt aMin)
 {
 // Don't allow wait dialog to set max/min other than zero as wait
 // animation bar doesn't work in that case.
 d->iMinimum = d->iType == EWaitDialog ? 0 : aMin;
 }
 /*!
-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
 {
 return d->iMinimum;
 }
 /*!
-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)
 {
 d->iAutoClose = aAutoClose;
 }
 /*!
-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
 {
 return d->iAutoClose;
 }
 /*!
-Sets dialog type.
+Sets dialog type. Dialog properties are set to default values. After setting type,
-\param aType defines the type of the dialog.
+ShowL() must be called to launch a new dialog.
-\sa ProgressType()
+\param aType Dialog type, wait or progress,
+\sa ProgressType(), ShowL()
 */
 EXPORT_C void CHbDeviceProgressDialogSymbian::SetProgressType(
 CHbDeviceProgressDialogSymbian::TType aType)
 {
 d->iType = aType;
 }
 }
 /*!
 Returns dialog's type.
 \sa SetProgressType()
 */
 EXPORT_C CHbDeviceProgressDialogSymbian::TType CHbDeviceProgressDialogSymbian::ProgressType() const
 {
 return static_cast<TType>(d->iType);
 }
 /*!
-Sets the value of the progress bar within the dialog.
+Sets progress bar value.
-\param aProgressValue value of the progress bar.
-\sa ProgressValue()
+\param aProgressValue Progress bar value.
+\sa ProgressValue(), ShowL(), UpdateL()
 */
 EXPORT_C void CHbDeviceProgressDialogSymbian::SetProgressValue(TInt aProgressValue)
 {
 d->iProgressValue = aProgressValue;
 }
 /*!
-Returns the value of the progress bar within the dialog.
+Returns progress bar value.
 \sa SetProgressValue()
 */
 EXPORT_C TInt CHbDeviceProgressDialogSymbian::ProgressValue() const
 {
 return d->iProgressValue;
 }
 /*!
-Sets text of the dialog.
+Sets dialog text.
-\param aText dialog text.
-\sa Text()
+\param aText Dialog text.
+\sa Text(), ShowL(), UpdateL()
 */
 EXPORT_C void CHbDeviceProgressDialogSymbian::SetTextL(const TDesC& aText)
 {
 TInt length = aText.Length();
 if (length > d->iText.MaxLength())
 }
 d->iText.Copy(aText);
 }
 /*!
-Returns text of the note.
+Returns dialog text.
 \sa SetTextL()
 */
 EXPORT_C const TPtrC CHbDeviceProgressDialogSymbian::Text() const
 {
 return d->iText;
 }
 /*!
-Sets message box icon name or animation logical name. The message box gets updated next time ShowL() or UpdateL()
+Sets dialog icon name or animation logical name.
-is called.
+\param aIconName Icon or animation name. Icon can be from Hb resources or themes. Or it can be a file in
-\param aIconName Icon 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)
 {
 TInt length = aIconName.Length();
 if (length > d->iIconName.MaxLength())
 }
 d->iIconName.Copy(aIconName);
 }
 /*!
-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()
 */
 EXPORT_C const TPtrC CHbDeviceProgressDialogSymbian::IconName() const
 {
 return d->iIconName;
 }
 /*!
-Sets notification dialog's animation definition name.  The dialogs get updated next when time ShowL() or UpdateL()
+Sets dialog animation definition name.
-is called.
+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)
 {
 TInt length = aAnimationDefinition.Length();
 if (length > d->iAnimationDefinition.MaxLength())
 }
 d->iAnimationDefinition.Copy(aAnimationDefinition);
 }
 /*!
-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;
 }
 /*!
-Sets progress dialog box button text. The dialog gets updated next time ShowL() or UpdateL()
+Sets dialog button text.
-is called.
 \param aText Button text.
-\sa ButtonText()
+\sa ButtonText(), ShowL(), UpdateL()
 */
 EXPORT_C void CHbDeviceProgressDialogSymbian::SetButtonTextL(const TDesC& aText)
 {
 TInt length = aText.Length();
 if (length > d->iButton.iText.MaxLength()) {
 d->iButton.iFlags.iTextValid = true;
 d->iButton.iFlags.iTextModified = true;
 }
 /*!
-Returns progress dialog button text.
+Returns dialog button text.
 \sa SetButtonTextL()
 */
 EXPORT_C const TPtrC CHbDeviceProgressDialogSymbian::ButtonText() const
 {
 return d->iButton.iText;
 }
 /*!
-Sets progress dialog button presence. The dialog updated next time ShowL() or UpdateL()
+Sets progress dialog button presence.
-is called.
 \param aEnable True enables (makes visible) the dialog button.
-\sa HasButton()
+\sa HasButton(), ShowL(), UpdateL()
 */
 EXPORT_C void CHbDeviceProgressDialogSymbian::SetButton(TBool aEnable)
 {
 d->iButton.iFlags.iIsNull = !aEnable;
 d->iButton.iFlags.iIsNullValid = true;
 d->iButton.iFlags.iIsNullModified = true;
 }
 /*!
-Returns progress dialog button presence.
+Returns dialog button presence.
-\param aButton Selects the button.
 \sa SetButton()
 */
 EXPORT_C TBool CHbDeviceProgressDialogSymbian::HasButton() const
 {
 return !d->iButton.iFlags.iIsNull;
 }
 /*!
-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
 */
 EXPORT_C void CHbDeviceProgressDialogSymbian::SetObserver(MHbDeviceProgressDialogObserver* aObserver)

changeset 28	b7da29130b0e
parent 23	e6ad4ef83b23
child 30	80e4d18b72f5