--- a/src/hbwidgets/devicedialogs/hbdeviceprogressdialogsymbian.cpp Thu Sep 02 20:44:51 2010 +0300
+++ b/src/hbwidgets/devicedialogs/hbdeviceprogressdialogsymbian.cpp Fri Sep 17 08:32:10 2010 +0300
@@ -332,7 +332,9 @@
/*!
\class MHbDeviceProgressDialogObserver
- \brief MHbDeviceProgressDialogObserver is an observer interface for observing CHbDeviceProgressDialogSymbian.
+ \brief MHbDeviceProgressDialogObserver is an observer interface for CHbDeviceProgressDialogSymbian.
+
+ \sa CHbDeviceProgressDialogSymbian
*/
/*!
@@ -340,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.
+ <b>This class is Symbian only. Not available on other platforms.</b>
- 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...");
@@ -394,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();
@@ -408,16 +411,7 @@
iDialog->UpdateL();
\endcode
- CHbDeviceProgressDialogSymbian supports animations.
- 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:
+ An example of showing an icon animation:
\code
Create an animation definition file.
@@ -440,17 +434,14 @@
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
@@ -463,10 +454,10 @@
/*!
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,
@@ -481,7 +472,7 @@
}
/*!
- Destructs the class.
+ Destructor.
*/
EXPORT_C CHbDeviceProgressDialogSymbian::~CHbDeviceProgressDialogSymbian()
{
@@ -489,7 +480,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()
{
@@ -497,7 +494,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()
{
@@ -505,7 +506,7 @@
}
/*!
- Closes the dialog.
+ Closes a device progress dialog.
*/
EXPORT_C void CHbDeviceProgressDialogSymbian::Close()
{
@@ -513,11 +514,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)
{
@@ -526,9 +528,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)
{
@@ -538,9 +542,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
@@ -549,9 +552,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)
{
@@ -561,9 +566,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
@@ -572,10 +576,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)
{
@@ -583,10 +589,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
@@ -595,9 +600,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)
@@ -618,6 +626,7 @@
/*!
Returns dialog's type.
+
\sa SetProgressType()
*/
EXPORT_C CHbDeviceProgressDialogSymbian::TType CHbDeviceProgressDialogSymbian::ProgressType() const
@@ -626,9 +635,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)
{
@@ -636,7 +647,8 @@
}
/*!
- Returns the value of the progress bar within the dialog.
+ Returns progress bar value.
+
\sa SetProgressValue()
*/
EXPORT_C TInt CHbDeviceProgressDialogSymbian::ProgressValue() const
@@ -645,9 +657,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)
{
@@ -660,7 +674,8 @@
}
/*!
- Returns text of the note.
+ Returns dialog text.
+
\sa SetTextL()
*/
EXPORT_C const TPtrC CHbDeviceProgressDialogSymbian::Text() const
@@ -669,13 +684,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)
{
@@ -688,7 +702,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()
*/
@@ -698,13 +712,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)
{
@@ -717,7 +736,7 @@
}
/*!
- Returns an animation definition set for a dialog. If not set, return string.
+ Returns dialog icon animation definition name.
\sa SetAnimationDefinitionL()
*/
@@ -727,12 +746,11 @@
}
/*!
- 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)
{
@@ -746,7 +764,7 @@
}
/*!
- Returns progress dialog button text.
+ Returns dialog button text.
\sa SetButtonTextL()
*/
@@ -756,12 +774,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)
{
@@ -771,9 +788,7 @@
}
/*!
- Returns progress dialog button presence.
-
- \param aButton Selects the button.
+ Returns dialog button presence.
\sa SetButton()
*/
@@ -783,7 +798,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