--- a/src/hbwidgets/devicedialogs/hbdevicenotificationdialog.cpp Thu Sep 02 20:44:51 2010 +0300
+++ b/src/hbwidgets/devicedialogs/hbdevicenotificationdialog.cpp Fri Sep 17 08:32:10 2010 +0300
@@ -34,21 +34,60 @@
/*!
@stable
@hbwidgets
+
\class HbDeviceNotificationDialog
- \brief HbDeviceNotificationDialog is a non-modal dialog displayed on the top of
- running applications. Functionality is based on HbNotificationDialog and it uses
- HbDeviceDialog framework.
+
+ \brief HbDeviceNotificationDialog is a non-modal dialog for displaying device-wide notifications.
+
+ HbDeviceNotificationDialog is device dialog version of HbNotificationDialog and offers
+ similar API.
+
+ The dialog is shown by device dialog service which HbNotificationDialog is a client of.
+
+ The dialog is displayed on top of all applications. It appears at top left corner of a display.
+ It is intended for applications to show device-wide notifications to user in non-intrusive way.
+ It can also be used by server components which don't have HbMainWindow.
+
+ HbDeviceNotificationDialog does not require user input and is usually closed by timeout.
+ For content, it supports two rows of text and an icon or animation. Two text rows may consist
+ either of a title spanning two lines or title and text. Setters are provided for setting
+ title, text and icon.
+
+ An asynchronous show() method launches a dialog. Device dialog framework decides when the
+ dialog is actually shown. There may be a delay untill dialog appears on display. close()
+ closes a dialog.
+
+ After dialog has been lauched, properties may be updated by setters and calling update().
+ Calling update() is optional as setters schedule an automatic update event which
+ updates dialog parameters next time event loop is entered.
- HbDeviceNotificationDialog is a concrete class. For the content it provides two rows of text,
- an image or an animation. Interface of HbDeviceNotificationDialog is similar to HbNotificationDialog
- with additional show(), update() and close() methods. Dialog is shown when show() is
- called.
- It is recommended that the dialog data is initialized before calling show() or update()
- methods, because those methods use interprocess communication.
+ It is recommended that dialog properties are set before calling show() as updating them after
+ causes interprocess communication.
+
+ The dialog closes when tapped. A tap triggers activated() signal if enabled by
+ enableTouchActivation().
+
+ If there is no need to update or receive activation from a launched dialog,
+ HbDeviceNotificationDialog object can be deleted after show() returns. Device
+ dialog framework takes care of displaying the dialog.
+
+ Device notifications dialogs are synchronized with each other. If several of them
+ are to be shown at the same time, they are shown sequentially instead of on top of each other.
- Main use of HbDeviceNotificationDialog is to show information to user without user input.
+ In place of an icon, notification dialog may contain an animation. Supported icon animation
+ formats are:
+ - GIF (.gif)
+ - MNG (.mng)
+ - Frame animations (.axml)
- \section _usecases HbDeviceNotificationDialog use cases
+ \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
+ notification dialogs are displayed on client's main window.
+
+
+ \section _usecases HbDeviceNotificationDialog use cases
Use cases in this section:
- \ref _uc2
@@ -60,10 +99,8 @@
The following code snippet creates a device notification dialog containing title, text and icon.
\code
- QString iconName("C:/xxxx.png");
-
HbDeviceNotificationDialog notificationDialog;
- notificationDialog.setIconName(iconName);
+ notificationDialog.setIconName("qtg_large_info");
notificationDialog.setTitle("Title");
notificationDialog.setText("Text");
notificationDialog.show();
@@ -72,7 +109,7 @@
or equivalent dialog can be created using convenience method:
\code
- HbDeviceNotificationDialog::notification(iconName, "Text", "Title");
+ HbDeviceNotificationDialog::notification("qtg_large_info", "Text", "Title");
\endcode
When using convenience methods, it is not possible to receive user interaction events,
@@ -83,8 +120,8 @@
\subsection _uc2_001 Receiving user interactions events
Below is an example of receiving user interaction events from device notification dialog. With
- following example user is able to receive activated and close events. Note that
- dialog is cancelled, if it goes out of scope.
+ following example user is able to receive activated and close events. Note that in this case the
+ dialog is closed by device dialog framework if HbDeviceNotificationDialog object is deleted.
\code
mNotificationDialog = new HbDeviceNotificationDialog;
@@ -98,16 +135,7 @@
\subsection _uc2_002 Using animations in a device notification dialog
- HbDeviceNotificationDialog supports animations.
- Supported formats are the following.
-
- - GIF (.gif)
- - MNG (.mng)
- - Frame animations (.axml)
-
- There is a built-in support for GIF and MNG animations.
-
- Frame animations can be used by first creating an animation definition file:
+ Create an animation definition file:
\code
<animations>
@@ -119,7 +147,7 @@
</animations>
\endcode
- After this, create a HbDeviceNotificationDialog as described above and
+ Create a HbDeviceNotificationDialog as described above and
set the definition file and the logical name of the animation:
\code
@@ -128,25 +156,38 @@
mNotificationDialog->setAnimationDefinition(animationDefinitionXML);
mNotificationDialog->setIconName(logicalIconName);
+ mNotificationDialog->show();
\endcode
- \sa HbIconAnimationManager::addDefinitionFile
- \note Animation definition files must be stored in a place where they can
- be accessed.
+
+ \sa HbNotificationDialog, HbDeviceDialog
*/
/*!
\fn void HbDeviceNotificationDialog::aboutToClose();
- This signal is emitted when the dialog is closed with a timeout
+ This signal is emitted when notification dialog has closed.
+
+ \sa show()
*/
/*!
\fn void HbDeviceNotificationDialog::activated();
- This signal is emitted when the dialog is closed with a pointer tap
+ This signal is emitted when the dialog is tapped and touch activation is
+ enabled.
+
+ \sa enableTouchActivation()
*/
+static const char keyTimeout[] = "timeout";
+static const char keyIconName[] = "iconName";
+static const char keyText[] = "text";
+static const char keyTitle[] = "title";
+static const char keyTouchActivation[] = "touchActivation";
+static const char keyTitleTextWrapping[] = "titleTextWrapping";
+static const char keyAnimationDefinition[] = "animationDefinition";
+
HbDeviceNotificationDialogPrivate::HbDeviceNotificationDialogPrivate()
: QObject(), mDeviceDialog(0), mUpdateTimerId(0), mShowing(false)
{
@@ -190,7 +231,7 @@
connect(mDeviceDialog, SIGNAL(deviceDialogClosed()), this, SLOT(deviceDialogClosed()));
- if (mData["touchActivation"].toBool()) {
+ if (q_func()->isTouchActivating()) {
connect(mDeviceDialog, SIGNAL(dataReceived(QVariantMap)), this, SLOT(dataReceived(QVariantMap)));
}
if (!mDeviceDialog->show("com.nokia.hb.devicenotificationdialog/1.0", mData)) {
@@ -266,9 +307,6 @@
d->q_ptr = this;
QVariantMap data;
- data["touchActivation"] = false;
- data["titleTextWrapping"] = Hb::TextWordWrap;
- data["timeout"] = 3000;
d->init(data);
TRACE_EXIT
@@ -286,8 +324,9 @@
/*!
Convenience method for showing notification dialog with text and title.
- \param iconName - path and name of the icon shown on dialog.
- \param title - title shown on dialog. By default: empty.
+
+ \param iconName Path and name of the icon shown on dialog.
+ \param title Title shown on dialog. Default is empty.
*/
void HbDeviceNotificationDialog::notification(const QString &iconName, const QString& title)
{
@@ -303,9 +342,10 @@
/*!
Convenience method for showing notification dialog with icon, text and title.
- \param iconName - path and name of the icon shown on dialog.
- \param text - text shown on dialog.
- \param title - title shown on dialog.
+
+ \param iconName Path and name of the icon shown on dialog.
+ \param text Text shown on dialog.
+ \param title Title shown on dialog.
*/
void HbDeviceNotificationDialog::notification(const QString &iconName, const QString &text, const QString &title)
{
@@ -321,140 +361,143 @@
}
/*!
- Sets message box icon name or animation logical name. The dialog gets updated next time ShowL() or UpdateL()
- is called.
+ Sets icon name or animation logical name.
\param iconName 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 HbDeviceNotificationDialog::setIconName(const QString &iconName)
{
TRACE_ENTRY
Q_D(HbDeviceNotificationDialog);
- d->mData["iconName"] = iconName;
+ d->mData[keyIconName] = iconName;
d->scheduleUpdateEvent();
TRACE_EXIT
}
/*!
- Set and update text on dialog. Text is not set, if show() or update()
- is not called.
- \param text - text shown on dialog.
- \sa show(), update()
+ Sets dialog text. Changes also title text wrapping. If text is empty,
+ sets title text wrapping to Hb::TextWordWrap, otherwise Hb::TextNoWrap.
+
+ \param text Dialog text.
+
+ \sa text(), show(), update()
*/
void HbDeviceNotificationDialog::setText(const QString &text)
{
TRACE_ENTRY
Q_D(HbDeviceNotificationDialog);
- d->mData["text"] = text;
+ d->mData[keyText] = text;
d->scheduleUpdateEvent();
TRACE_EXIT
}
/*!
- Set and update title on dialog. Title is not set, if show() or update()
- is not called.
- \param title - title shown on dialog.
- \sa show(), update()
+ Sets title text.
+
+ \param title Title text.
+
+ \sa title(), show(), update()
*/
void HbDeviceNotificationDialog::setTitle(const QString &title)
{
TRACE_ENTRY
Q_D(HbDeviceNotificationDialog);
- d->mData["title"] = title;
+ d->mData[keyTitle] = title;
d->scheduleUpdateEvent();
TRACE_EXIT
}
/*!
- Enable user interaction on dialog. Setting is not set, if show() or update()
- is not called.
- \param enable - When enabled, activated() signal is emitted on user action.
+ Enables user interaction on dialog.
- Default value is false.
- \sa show(), update()
+ \param enable True enableds activated() signal on user action.
+
+ \sa isTouchActivating(), show(), update()
*/
void HbDeviceNotificationDialog::enableTouchActivation(bool enable)
{
TRACE_ENTRY
Q_D(HbDeviceNotificationDialog);
- d->mData["touchActivation"] = enable;
+ d->mData[keyTouchActivation] = enable;
d->scheduleUpdateEvent();
TRACE_EXIT
}
/*!
- Set dialog timeout. Timeout is not set, if show() or update()
- is not called.
- \param timeout - Set timeout for dialog.
+ Sets dialog timeout.
- Default value is HbPopup::StandardTimeout (3000 ms).
- \sa show(), update()
+ \param timeout Timeout is milliseconds.
+
+ \sa timeout(), show(), update()
*/
void HbDeviceNotificationDialog::setTimeout(int timeout)
{
TRACE_ENTRY
Q_D(HbDeviceNotificationDialog);
- d->mData["timeout"] = timeout;
+ d->mData[keyTimeout] = timeout;
d->scheduleUpdateEvent();
TRACE_EXIT
}
/*!
- Set dialog title text wrapping.
- \param wrapping - Set wrapping for dialog title text.
+ Sets title text wrapping. The title can wrap only if there is no text for the dialog.
+ The title can wrap to a maximum of two lines. setText() also changes title text wrapping.
- Default value is NoWrap.
- \sa show(), update()
+ \param wrapping Title text wrapping.
+
+ \sa titleTextWrapping(), setText(), show(), update()
*/
void HbDeviceNotificationDialog::setTitleTextWrapping(Hb::TextWrapping wrapping)
{
TRACE_ENTRY
Q_D(HbDeviceNotificationDialog);
- d->mData["titleTextWrapping"] = wrapping;
+ d->mData[keyTitleTextWrapping] = wrapping;
d->scheduleUpdateEvent();
TRACE_EXIT
}
/*!
- Set animation definition on dialog. Animation logical name has to be set
- using setIcon(). Animation is not set, if show() or update()
- is not called.
- \param animationDefinition - path and name animation definition file shown in dialog.
- \sa show(), update(), setIconName()
+ Set animation definition. Animation logical name has to be set
+ using setIcon(). Animation definition files must be stored to a place where they
+ can be accessed by device dialog service.
+
+ Supported animation formats are following:
+ - GIF (.gif)
+ - MNG (.mng)
+ - Frame animations
+
+ \param animationDefinition Path and name of the animation definition file.
+
+ \sa setIconName(), animationDefinition(), HbIconAnimationManager::addDefinitionFile(), show(), update()
*/
void HbDeviceNotificationDialog::setAnimationDefinition(QString &animationDefinition)
{
TRACE_ENTRY
Q_D(HbDeviceNotificationDialog);
- d->mData["animationDefinition"] = animationDefinition;
+ d->mData[keyAnimationDefinition] = animationDefinition;
d->scheduleUpdateEvent();
TRACE_EXIT
}
/*!
- Returns name and path of the icon shown on dialog. If not set, returns empty string.
+ Returns icon or animation file name.
- \sa setIconName
+ \sa setIconName()
*/
QString HbDeviceNotificationDialog::iconName() const
{
TRACE_ENTRY
Q_D(const HbDeviceNotificationDialog);
- const char *key = "iconName";
- QVariantMap::const_iterator i = d->mData.find(key);
- if (i != d->mData.end() && i.key() == "iconName") {
- return i.value().toString();
- }
TRACE_EXIT
- return QString();
+ return d->mData.value(keyIconName).toString();
}
/*!
- Get text shown on dialog. If not set, returns empty string.
+ Returns dialog text.
\sa setText()
*/
@@ -463,17 +506,12 @@
TRACE_ENTRY
Q_D(const HbDeviceNotificationDialog);
- const char *key = "text";
- QVariantMap::const_iterator i = d->mData.find(key);
- if (i != d->mData.end() && i.key() == "text") {
- return i.value().toString();
- }
TRACE_EXIT
- return QString();
+ return d->mData.value(keyText).toString();
}
/*!
- Get title shown on dialog. If not set, returns empty string.
+ Returns title text.
\sa setTitle()
*/
@@ -482,30 +520,27 @@
TRACE_ENTRY
Q_D(const HbDeviceNotificationDialog);
- const char *key = "title";
- QVariantMap::const_iterator i = d->mData.find(key);
- if (i != d->mData.end() && i.key() == "title") {
- return i.value().toString();
- }
TRACE_EXIT
- return QString();
+ return d->mData.value(keyTitle).toString();
}
/*!
- Get trigger action setting.
+ Returns whether touch activation is enabled. Default value is false.
- \sa setTriggerAction()
+ \sa enableTouchActivation()
*/
bool HbDeviceNotificationDialog::isTouchActivating() const
{
TRACE_ENTRY
Q_D(const HbDeviceNotificationDialog);
TRACE_EXIT
- return d->mData["touchActivation"].toBool();
+ return d->mData.value(keyTouchActivation).toBool();
}
/*!
- Get timeout setting.
+ Returns timeout.
+
+ Default value is HbPopup::StandardTimeout (3000 ms).
\sa setTimeout()
*/
@@ -514,12 +549,14 @@
TRACE_ENTRY
Q_D(const HbDeviceNotificationDialog);
TRACE_EXIT
- return d->mData["timeout"].toInt();
+ const QVariant defaultValue(3000); // HbPopup::StandardTimeout
+ return d->mData.value(keyTimeout, defaultValue).toInt();
}
/*!
- Returns the style of text wrapping for the title.
-
+ Returns title text wrapping.
+
+ The title can wrap only if dialog text is empty. The title can wrap to a maximum of two lines.
The default is Hb::TextWordWrap.
\sa setTitleTextWrapping()
@@ -529,11 +566,14 @@
TRACE_ENTRY
Q_D(const HbDeviceNotificationDialog);
TRACE_EXIT
- return (Hb::TextWrapping)d->mData["titleTextWrapping"].toInt();
+ const QVariant defaultValue(
+ static_cast<int>(text().isEmpty() ? Hb::TextWordWrap : Hb::TextNoWrap));
+ return static_cast<Hb::TextWrapping>(d->mData.value(keyTitleTextWrapping,
+ defaultValue).toInt());
}
/*!
- Returns the animation definition file name.
+ Returns animation definition file name.
\sa setAnimationDefinition()
*/
@@ -542,22 +582,18 @@
TRACE_ENTRY
Q_D(const HbDeviceNotificationDialog);
- const char *key = "animationDefinition";
- QVariantMap::const_iterator i = d->mData.find(key);
- if (i != d->mData.end() && i.key() == "animationDefinition") {
- return i.value().toString();
- }
TRACE_EXIT
- return QString();
+ return d->mData.value(keyAnimationDefinition).toString();
}
/*!
- Show the dialog.
- \code
- // example to show dialog.
- mNotificationDialog->setText("Dialog text");
- mNotificationDialog->show();
- \endcode
+ Shows a notification dialog and returns immediately without waiting for it to close.
+ Closing of the dialog is indicated by aboutToClose() signal. Tapping of dialog is
+ indicated by activated() signal. Dialog can be updated while showing by property
+ setters.
+
+ \sa update(), aboutToClose(), activated()
+
*/
void HbDeviceNotificationDialog::show()
{
@@ -567,12 +603,12 @@
}
/*!
- Update the dialog.
- \code
- // example to update already showing dialog.
- mNotificationDialog->setText("Update title");
- mNotificationDialog->update();
- \endcode
+ Updates changed properties to a showing notification dialog via interprocess
+ communication. Has no effect if show() has not been called or the dialog has
+ closed already. Calling update() is optional as setting any property schedules
+ an event and the showing notification is updated next time Qt event loop executes.
+
+ \sa show()
*/
void HbDeviceNotificationDialog::update()
{
@@ -581,8 +617,7 @@
TRACE_EXIT
}
/*!
- Close the dialog. Method has no effect if convenience methods
- are used to show device notification dialog.
+ Closes a device notification dialog.
*/
void HbDeviceNotificationDialog::close()
{