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

equal deleted inserted replaced

-:e6ad4ef83b23
+:b7da29130b0e
 }
 }
 }
 /*!
+\stable
+\hbwidgets
 \class HbDeviceProgressDialog
-\brief HbDeviceProgressDialog is a device dialog version of HbProgressDialog.
+\brief HbDeviceProgressDialog displays a progress dialog on top all applications.
-It displays a dialog with a wait animation or progress bar, text, icon or animation and a
+HbDeviceProgressDialog is a device-dialog version of HbProgressDialog. It is a modal
+dialog and displayed on top all applications by a device-dialog service.
+HbDeviceProgressDialog is a client of the service.
+HbDeviceProgressDialog provides a similar kind of interface as HbProgressDialog.
+Progress dialogs are always shown asynchronously as application needs to perform an operation
+and update the dialog while the dialog is showing.
+For content it provides wait animation or progress bar, text, icon or icon-animation and a
 cancel button.
-Device dialogs are shown on top of any running applications and are always modal by nature.
+Two different dialogs are supported: wait and progress. Progress dialog displays a progress
+bar indicating progress of the operation. Wait dialog displays a wait animation in place of
-Two different dialogs are supported: wait and progress. The wait dialog displays an animated
+the progress bar.
-bar and progress dialog a progress bar indicating progress of the operation.
+Wait dialog is used when length of an operation cannot be determined beforehand.
-Wait dialog is used when length of an operation cannot be determined beforehand. It displays
+The dialog is closed by user pressing dialog cancel button or by an application closing
-an animated bar to indicate an action. The dialog is closed by the user pressing the cancel
+the dialog after the operation has finished by HbDeviceProgressDialog::close().
-button, the application closing the dialog after the operation is finished.
+Progress dialog is used when the length of operation can be determined. beforehand.
-Progress dialog is used when the length of operation can be determined. For example
+For example when deleting a number of files, the progress could be shown as a
-when deleting a number of files, the progress of the operation could be shown as a
 percentage of the files deleted. Application updates the progress bar during the
 operation. The dialog closes by user pressing the cancel button, the application closing the
 dialog after the operation is finished or automatically when progress value reaches a
-maximum.
+maximum, HbDeviceProgressDialog::autoClose().
-HbDeviceProgressDialog provides a similar kind of interface as HbProgressDialog, excluding
+Device progress dialog is launched when show() is called. Launched dialog can be updated by
-functions which handle concrete UI-component related information. Progress dialogs are
+setters. Changed properties are updated to the displayed dialog automatically next time event
-always asynchronous by as the client needs to perform the operation and update the dialog
+loop is entered or updated values can be sent immediately by calling update().
-while the dialog is showing.
-Device progress dialog is launched when show() is called. Launched dialog can be updated by setters.
 Because updating a dialog requires interprocess communication, it's advisable to fully construct the
 progress dialog before calling show().
-Supported icon animation formats are following:
+An animation can replace an icon on device progress dialog. Supported icon animation formats are
+following:
 - GIF (.gif)
 - MNG (.mng)
 - Frame animations
-Sample code:
+\section _platform_spec Platform-specific implementation notes for HbDeviceProgressDialog
-An example showing the wait dialog:
+\subsection _nonsymbian Non-Symbian
+Device dialog service is implemented only for the Symbian platform. On other platforms device
+progress dialogs are displayed on client's main window.
+\section _code_samples Sample code
+An example showing a wait dialog:
 \code
 mDialog = new HbDeviceProgressDialog(HbProgressDialog::WaitDialog);
 mDialog->setText("Connecting...");
 mDialog->show();
 \endcode
-An example showing the progress dialog:
+An example showing a progress dialog:
-\include deviceprogressdialog/main.cpp
+\include tsrc/fute/ultimatecodesnippet/deviceprogressdialog.cpp
-Creating a frame animation.
+Showing an icon animation.
 Create an animation definition file:
 \code
 <animations>
 <icon name="frame_anim_looping" playmode="loop">
 msg->setIconName(logicalIconName);
 msg->show();
 \endcode
 \sa HbProgressDialog, HbDialog, HbDeviceDialog
-\stable
-\hbwidgets
 */
 /*!
 \fn void HbDeviceProgressDialog::aboutToClose();
 d->init(HbProgressDialog::ProgressDialog);
 TRACE_EXIT
 }
 /*!
-Destructs the class.
+Destructor.
 */
 HbDeviceProgressDialog::~HbDeviceProgressDialog()
 {
 TRACE_ENTRY
 delete d;
 TRACE_EXIT
 }
 /*!
-Executes the dialog asynchronously.
+Shows a dialog and returns immediately without waiting for it to close. Closing
+is indicated by aboutToClose() signal. User cancellation is indicated by cancelled()
+signal. Button press is also indicated by QAction::triggered() signal.
+The dialog can be updated while showing by property setters. A new dialog is launched
+each time show() is called.
+\sa update(), aboutToClose(), cancelled()
 */
 void HbDeviceProgressDialog::show()
 {
 TRACE_ENTRY
 d->sendToServer(true);
 }
 /*!
 Updates changed properties of a launched progress dialog to device dialog service using
 interprocess communication. Has no effect if show() has not been called or dialog has
-closed already. Calling show() is optional as updating any property schedules an event
+closed already. Calling update() is optional as updating any property schedules an event
 and the dialog is updated next time Qt event loop executes.
 \sa show()
 */
 void HbDeviceProgressDialog::update()
 }
 return 0;
 }
 /*!
-Sets the maximum value of the progress bar within the dialog.
+Sets progress bar maximum value.
 \sa maximum()
 */
 void HbDeviceProgressDialog::setMaximum(int max)
 {
 d->setProperty(HbDeviceProgressDialogPrivate::Maximum, max);
 TRACE_EXIT
 }
 /*!
-Returns the maximum value of the progress bar within the dialog. Default value is 100.
+Returns progress bar maximum value. Default value is 100.
 \sa setMaximum()
 */
 int HbDeviceProgressDialog::maximum() const
 {
 return d->mProperties[HbDeviceProgressDialogPrivate::Maximum].mValue.toInt();
 }
 /*!
-Sets the minimum value of the progress bar within the dialog.
+Sets progress bar minimum value.
 \sa minimum()
 */
 void HbDeviceProgressDialog::setMinimum(int min)
 {
 d->setProperty(HbDeviceProgressDialogPrivate::Minimum, min);
 TRACE_EXIT
 }
 /*!
-Returns the minimum value of the progress bar within the dialog. Default value is 0.
+Returns progress bar minimum value. Default value is 0.
 \sa setMinimum()
 */
 int HbDeviceProgressDialog::minimum() const
 {
 return d->mProperties[HbDeviceProgressDialogPrivate::Minimum].mValue.toInt();
 }
 /*!
-Sets the minimum and maximum value of the progress bar within the dialog.
+Sets progress bar minimum and maximum values.
 \sa minimum(), maximum()
 */
 void HbDeviceProgressDialog::setRange(int min, int max)
 {
 setMinimum(min);
 setMaximum(max);
 }
 /*!
-Sets the value of the progress bar within the dialog.
+Sets progress bar value.
 \sa progressValue()
 */
 void HbDeviceProgressDialog::setProgressValue(int progressValue)
 {
 d->setProperty(HbDeviceProgressDialogPrivate::Value, progressValue);
 TRACE_EXIT
 }
 /*!
-Returns the value of the progress bar within the dialog.
+Returns progress bar value.
 \sa setProgressValue()
 */
 int HbDeviceProgressDialog::progressValue() const
 {
 return d->mProperties[HbDeviceProgressDialogPrivate::Value].mValue.toInt();
 }
 /*!
-Sets the autoClose property value of the dialog.
+Sets dialog auto-closing.
 \param autoClose When set, the dialog is closed when value of the progress bar reaches
 the maximum value of the progress bar.
 \sa autoClose()
 d->setProperty(HbDeviceProgressDialogPrivate::AutoClose, autoClose);
 TRACE_EXIT
 }
 /*!
-Returns the value of the autoClose property of the dialog.
+Returns auto-closing property of a dialog.
 The default value is true for HbProgressDialog::ProgressDialog and false
 for HbProgressDialog::WaitDialog.
 \sa setAutoClose()
 {
 return d->mProperties[HbDeviceProgressDialogPrivate::AutoClose].mValue.toInt();
 }
 /*!
-Sets dialog's progress type. After setProgressType(), a new dialog is launched by a show().
+Sets dialog's progress type. All dialog properties are initialized to default values.
+After setProgressType(), a new dialog is launched by a show().
 \sa progressType()
 */
 void HbDeviceProgressDialog::setProgressType(HbProgressDialog::ProgressDialogType type)
 {
 return static_cast<HbProgressDialog::ProgressDialogType>
 (d->mProperties[HbDeviceProgressDialogPrivate::ProgressType].mValue.toInt());
 }
 /*!
-Sets text of the dialog.
+Sets dialog text.
 \sa text()
 */
 void HbDeviceProgressDialog::setText(const QString &text)
 {
 d->setProperty(HbDeviceProgressDialogPrivate::Text, text);
 TRACE_EXIT
 }
 /*!
-Returns text of the dialog.
+Returns dialog text.
 \sa setText()
 */
 QString HbDeviceProgressDialog::text() const
 {
 return d->mProperties[HbDeviceProgressDialogPrivate::Text].mValue.toString();
 return d->mProperties[HbDeviceProgressDialogPrivate::AnimationDefinition].mValue.toString();
 }
 /*!
 Sets a new action into progress dialog. When users presses a button on dialog, triggered()
-signal of the action is emitted. HbDeviceProgressDialog constructor sets a default action
+signal of the action is emitted. HbDeviceProgressDialog sets a default action
-into a dialog.
+into a dialog on construction.
 \param action Action or Null. Ownership is not transferred.
 \param role Selects an action to set.
 \sa action()

changeset 28	b7da29130b0e
parent 21	4633027730f5
child 30	80e4d18b72f5