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

equal deleted inserted replaced

-:7516d6d86cf5
+:ed14f46c0e55
 }
 HbDeviceMessageBoxPrivate::~HbDeviceMessageBoxPrivate()
 {
 TRACE_ENTRY
-// information/warning dialogs may be left at server when client is deleted. If there are no connected
+// Dialogs may be left at server when client is deleted. If there are no connected
 // signals, device dialog widget is not deleted but runs at server and is closed by a timeout.
-if (mProperties[Type].mValue.toInt() != HbMessageBox::MessageTypeQuestion &&
+if (q_ptr->receivers(SIGNAL(aboutToClose())) <= 0) {
-q_ptr->receivers(SIGNAL(aboutToClose())) <= 0) {
 mDeviceDialog->disconnect(q_ptr, SLOT(aboutToClose()));
 mDeviceDialog->disconnect(this, SLOT(triggerAction(QVariantMap)));
 if (mUpdateTimerId != 0) {
 // There's a pending update
 sendToServer(false); // this also kills the timer
 static const struct { HbPopup::DefaultTimeout timeout; int value; } timeoutValues[] = {
 {HbPopup::NoTimeout,0},
 {HbPopup::ConfirmationNoteTimeout,1500},
 {HbPopup::StandardTimeout,3000},
-{HbPopup::ContextMenuTimeout,6000},
+{HbPopup::ContextMenuTimeout,6000}
 };
 int count = sizeof(timeoutValues) / sizeof(timeoutValues[0]);
 if (timeout < 0 || timeout >= count) {
 TRACE_EXIT
 return timeoutValues[HbPopup::NoTimeout].value;
 /*!
 @stable
 @hbwidgets
 \class HbDeviceMessageBox
-\brief HbDeviceMessageBox displays a message box on top of any running applications.
+\brief HbDeviceMessageBox displays a message box on top all applications.
-HbDeviceMessageBox is a device dialog version of HbMessageBox. It displays a message box
+HbDeviceMessageBox is a device-dialog version of HbMessageBox. It is a modal
-with text, icon or animation and optional accept and reject buttons. It is not a widget.
+dialog and displayed on top all applications by a device-dialog service.
-The message box is displayed by a device dialog service which HbDeviceMessageBox is a
+HbDeviceMessageBox is a client of the service.
-client of.
+For content it provides text, icon or animation and optional accept and reject buttons.
-Device dialogs are shown on top of any running applications and are always modal by nature.
 A device message box is lauched by a show(). A new message box is lauched every time show()
 is called. aboutToClose() signal is emitted when the box has closed. There is also syncronous
 exec() function which launches a message box and waits for it close. exec() is not compatible
 with gestures and cannot be used from applications that have an user interface.
 Static convenience functions are provided for launching message boxes. They launch message boxes
 containing default properties appropriate for the message box type and their contents cannot
 be updated. Information and warning convenience methods return immediately. Question waits for
 a message box to close and is not compatible with gestures.
+If none of HbDeviceMessageBox signals have been connected to, the object can be deleted after
+show() has been called and device-dialog service takes care showing the message box. If any
+signals are connected, message box is closed when HbDeviceMessageBox object goes out of scope.
 Four types of message boxes are predefined. The type determines a set of default properties that
 are set on construction. Below is a table listing types and their default properties.
 <table border="1">
 <tr><td>Information</td><td>Info icon</td><td>"Ok" button</td><td>Standard timeout</td><td>Tap anywhere</td><td>Info sound</td></tr>
 <tr><td>Warning</td><td>Warning icon</td><td>"Ok" button</td><td>Standard timeout</td><td>Tap anywhere</td><td>Warn sound</td></tr>
 <tr><td>Question</td><td>Question icon</td><td>"Yes" and "No" buttons</td><td>No timeout</td><td>Button press</td><td>Question sound</td></tr>
 </table>
-In place of an icon, message box may conatain an animation. Supported icon animation formats are:
+In place of an icon, message box may contain an animation. Supported icon animation formats are:
 - GIF (.gif)
 - MNG (.mng)
 - Frame animations (.axml)
-Sample code:
+\section _platform_spec Platform-specific implementation notes for HbDeviceNotificationDialog
+\subsection _nonsymbian Non-Symbian
+Device dialog service is implemented only for the Symbian platform. On other platforms device
+message boxes are displayed on client's main window.
+\section _code_samples Sample code
 \code
 // Ask from user whether to continue operation or not.
 // Uses default accept/reject buttons (yes/no).
 msg->setAnimationDefinition(animationDefinitionXML);
 msg->setIconName(logicalIconName);
 msg->show();
 \endcode
-\sa HbMessageBox, HbDialog, HbDeviceDialog
+\sa HbMessageBox, HbDialog, HbDeviceDialog, CHbDeviceMessageBoxSymbian
 */
 /*!
 \fn void HbDeviceMessageBox::aboutToClose();
 \var HbDeviceMessageBox::ActionRole HbDeviceMessageBox::RejectButtonRole
 Reject button action.
 */
 /*!
-Constructor.
+Constructs HbDeviceMessageBox.
 \param type Type of the message box.
-\param parent An optional parameter.
+\param parent Parent pointer or 0.
 */
 HbDeviceMessageBox::HbDeviceMessageBox(HbMessageBox::MessageBoxType type, QObject *parent) :
 QObject(parent), d_ptr(new HbDeviceMessageBoxPrivate)
 {
 TRACE_ENTRY
 d_ptr->init();
 TRACE_EXIT
 }
 /*!
-Constructor.
+Constructs HbDeviceMessageBox.
 \param text Message box text.
 \param type Type of the message box.
-\param parent An optional parameter.
+\param parent Parent pointer or 0.
 */
 HbDeviceMessageBox::HbDeviceMessageBox(const QString &text, HbMessageBox::MessageBoxType type,
 QObject *parent) : QObject(parent), d_ptr(new HbDeviceMessageBoxPrivate)
 {
 TRACE_ENTRY
 setText(text);
 TRACE_EXIT
 }
 /*!
-Destructs the class.
+Destructs HbDeviceMessageBox. The message box launched by show() is closed if aboutToClose()
+signal is connected to by an application. Otherwise the box is left executing
+and should close itself by a timeout.
 */
 HbDeviceMessageBox::~HbDeviceMessageBox()
 {
 TRACE_ENTRY
 delete d_ptr;
 TRACE_EXIT
 }
 /*!
-Shows a message box and returns immediately without waiting for it to close. Closing of the
+Shows a message box and returns immediately without waiting for it to close. A new message box
+is launched each time show() is called. Closing of the
 message box is indicated by aboutToClose() signal. Button presses are indicated by
 QAction::triggered() signals. The message box can be updated while showing by property
 setters.
 \sa update(), aboutToClose()
 Type of a showing message box cannot be changed on the fly. show() must be called to launch
 a new message box after setMessageBoxType() has been called.
 \param type Message box type.
-\sa setMessageBoxType()
+\sa messageBoxType(), show()
 */
 void HbDeviceMessageBox::setMessageBoxType(HbMessageBox::MessageBoxType type)
 {
 TRACE_ENTRY
 // After setType(), a new message is launched by a show()
 \param buttons Message box buttons. A combination of flags,
 eg. HbMessageBox::Yes | HbMessageBox::No. Button flags are scanned starting from lsb.
 First button found goes to accept position and so forth.
-\sa standardButtons()
+\sa standardButtons(), show(), update()
 */
 void HbDeviceMessageBox::setStandardButtons(HbMessageBox::StandardButtons buttons)
 {
 TRACE_ENTRY
 d_ptr->setStandardButtons(buttons);
 Default actions are owned and deleted by the message box.
 \param action Action or null. Ownership does not transfer.
 \param role Selects an action.
-\sa action()
+\sa action(), show(), update()
 */
 void HbDeviceMessageBox::setAction(QAction *action, ActionRole role)
 {
 TRACE_ENTRY
 HbDeviceMessageBoxPrivate::ActionSelector  actionSelector =
 /*!
 Sets message box text. Supported text formats are the same as HbMessageBox::setText().
 \param text Message box text.
-\sa text(), HbMessageBox::setText()
+\sa text(), show(), update(), HbMessageBox::setText()
 */
 void HbDeviceMessageBox::setText(const QString &text)
 {
 TRACE_ENTRY
 d_ptr->setProperty(HbDeviceMessageBoxPrivate::Text, text);
 Sets message box icon name or animation logical name.
 \param aIconName Icon name. Icon can be from Hb resources or themes. Or can be a file in
 a file system.
-\sa IconName()
+\sa IconName(), show(), update()
 */
 void HbDeviceMessageBox::setIconName(const QString &iconName)
 {
 TRACE_ENTRY
 d_ptr->setProperty(HbDeviceMessageBoxPrivate::IconName, iconName);
 /*!
 Enables/disables icon visibility.
 \param visible Enables icon visibility.
-\sa iconVisible()
+\sa iconVisible(), show(), update()
 */
 void HbDeviceMessageBox::setIconVisible(bool visible)
 {
 TRACE_ENTRY
 d_ptr->setProperty(HbDeviceMessageBoxPrivate::IconVisible, visible);
 /*!
 Sets message box timeout.
 \param timeout Timeout in milliseconds. 0 denotes no timeout (infinite).
-\sa timeout() setTimeout(HbPopup::DefaultTimeout)
+\sa timeout(), setTimeout(HbPopup::DefaultTimeout), show(), update()
 */
 void HbDeviceMessageBox::setTimeout(int timeout)
 {
 TRACE_ENTRY
 d_ptr->setProperty(HbDeviceMessageBoxPrivate::Timeout, timeout);
 Sets timeout to one of HbPopup::DefaultTimeout values. Helps achieving
 common look and feel of message boxes.
 \param timeout Timeout as an enumerated constant.
-\sa enum HbPopup::DefaultTimeout timeout() setTimeout(int)
+\sa enum HbPopup::DefaultTimeout, timeout(), setTimeout(int), show(), update()
 */
 void HbDeviceMessageBox::setTimeout(HbPopup::DefaultTimeout timeout)
 {
 TRACE_ENTRY
 setTimeout(HbDeviceMessageBoxPrivate::timeoutValue(timeout));
 /*!
 Sets message box dismiss policy.
 \param dismissPolicy Dismiss policy.
-\sa dismissPolicy()
+\sa dismissPolicy(), show(), update()
 */
 void HbDeviceMessageBox::setDismissPolicy(HbPopup::DismissPolicy dismissPolicy)
 {
 TRACE_ENTRY
 d_ptr->setProperty(HbDeviceMessageBoxPrivate::DismissPolicy, dismissPolicy);
 - MNG (.mng)
 - Frame animations
 \param animationDefinition Path and name of the animation definition file.
-\sa setIcon(), animationDefinition(), HbIconAnimationManager::addDefinitionFile()
+\sa setIcon(), animationDefinition(), HbIconAnimationManager::addDefinitionFile(), show(), update()
 */
 void HbDeviceMessageBox::setAnimationDefinition(QString &animationDefinition)
 {
 TRACE_ENTRY
 d_ptr->setProperty(HbDeviceMessageBoxPrivate::AnimationDefinition, animationDefinition);

changeset 34	ed14f46c0e55
parent 7	923ff622b8b9