38     \brief HbDeviceNotificationDialog is a non-modal dialog displayed on the top of

    39 

    39     running applications. Functionality is based on HbNotificationDialog and it uses

    40     \brief HbDeviceNotificationDialog is a non-modal dialog for displaying device-wide notifications.

    40     HbDeviceDialog framework.

    41 

    41 

    42     HbDeviceNotificationDialog is device dialog version of HbNotificationDialog and offers

    42     HbDeviceNotificationDialog is a concrete class. For the content it provides two rows of text,

    43     similar API.

    43     an image or an animation. Interface of HbDeviceNotificationDialog is similar to HbNotificationDialog

    44 

    44     with additional show(), update() and close() methods. Dialog is shown when show() is

    45     The dialog is shown by device dialog service which HbNotificationDialog is a client of.

    45     called.

    46  

    46     It is recommended that the dialog data is initialized before calling show() or update()

    47     The dialog is displayed on top of all applications. It appears at top left corner of a display.

    47     methods, because those methods use interprocess communication.

    48     It is intended for applications to show device-wide notifications to user in non-intrusive way.

    48 

    49     It can also be used by server components which don't have HbMainWindow.

    49     Main use of HbDeviceNotificationDialog is to show information to user without user input.

    50 

    50 

    51     HbDeviceNotificationDialog does not require user input and is usually closed by timeout.

    51      \section _usecases HbDeviceNotificationDialog use cases

    52     For content, it supports two rows of text and an icon or animation. Two text rows may consist

    53     either of a title spanning two lines or title and text. Setters are provided for setting

    54     title, text and icon.

    55 

    56     An asynchronous show() method launches a dialog. Device dialog framework decides when the

    57     dialog is actually shown. There may be a delay untill dialog appears on display. close()

    58     closes a dialog.

    59 

    60     After dialog has been lauched, properties may be updated by setters and calling update().

    61     Calling update() is optional as setters schedule an automatic update event which

    62     updates dialog parameters next time event loop is entered.

    63 

    64     It is recommended that dialog properties are set before calling show() as updating them after

    65     causes interprocess communication.

    66 

    67     The dialog closes when tapped. A tap triggers activated() signal if enabled by

    68     enableTouchActivation().

    69 

    70     If there is no need to update or receive activation from a launched dialog,

    71     HbDeviceNotificationDialog object can be deleted after show() returns. Device

    72     dialog framework takes care of displaying the dialog.

    73  

    74     Device notifications dialogs are synchronized with each other. If several of them

    75     are to be shown at the same time, they are shown sequentially instead of on top of each other.

    76 

    77     In place of an icon, notification dialog may contain an animation. Supported icon animation

    78     formats are:

    79     - GIF (.gif)

    80     - MNG (.mng)

    81     - Frame animations (.axml)

    82 

    83     \section _platform_spec Platform-specific implementation notes for HbDeviceNotificationDialog

    84 

    85     \subsection _nonsymbian Non-Symbian

    86     Device dialog service is implemented only for the Symbian platform. On other platforms device 

    87     notification dialogs are displayed on client's main window.

    88  

    89 

    90     \section _usecases HbDeviceNotificationDialog use cases

    66     notificationDialog.setIconName(iconName);

   103     notificationDialog.setIconName("qtg_large_info");

    75     HbDeviceNotificationDialog::notification(iconName, "Text", "Title");

   112     HbDeviceNotificationDialog::notification("qtg_large_info", "Text", "Title");

    86     following example user is able to receive activated and close events. Note that

   123     following example user is able to receive activated and close events. Note that in this case the

    87     dialog is cancelled, if it goes out of scope.

   124     dialog is closed by device dialog framework if HbDeviceNotificationDialog object is deleted.

   101     HbDeviceNotificationDialog supports animations.

   138     Create an animation definition file:

   102     Supported formats are the following.

   103 

   104     - GIF (.gif)

   105     - MNG (.mng)

   106     - Frame animations (.axml)

   107 

   108     There is a built-in support for GIF and MNG animations.

   109 

   110     Frame animations can be used by first creating an animation definition file:

   122     After this, create a HbDeviceNotificationDialog as described above and

   150     Create a HbDeviceNotificationDialog as described above and

   133     \sa HbIconAnimationManager::addDefinitionFile

   162 

   134     \note Animation definition files must be stored in a place where they can 

   163     \sa HbNotificationDialog, HbDeviceDialog

   135     be accessed.

   141     This signal is emitted when the dialog is closed with a timeout

   169     This signal is emitted when notification dialog has closed.

   170 

   171     \sa show()

   147     This signal is emitted when the dialog is closed with a pointer tap

   177     This signal is emitted when the dialog is tapped and touch activation is

   148 */

   178     enabled.

   179     

   180     \sa enableTouchActivation()

   181 */

   182 

   183 static const char keyTimeout[] = "timeout";

   184 static const char keyIconName[] = "iconName";

   185 static const char keyText[] = "text";

   186 static const char keyTitle[] = "title";

   187 static const char keyTouchActivation[] = "touchActivation";

   188 static const char keyTitleTextWrapping[] = "titleTextWrapping";

   189 static const char keyAnimationDefinition[] = "animationDefinition";

   193     if (mData["touchActivation"].toBool()) {

   234     if (q_func()->isTouchActivating()) {

   289     \param iconName - path and name of the icon shown on dialog.

   327 

   290     \param title - title shown on dialog. By default: empty.

   328     \param iconName Path and name of the icon shown on dialog.

   329     \param title Title shown on dialog. Default is empty.

   306     \param iconName - path and name of the icon shown on dialog.

   345 

   307     \param text - text shown on dialog.

   346     \param iconName Path and name of the icon shown on dialog.

   308     \param title - title shown on dialog.

   347     \param text Text shown on dialog.

   348     \param title Title shown on dialog.

   324     Sets message box icon name or animation logical name. The dialog gets updated next time ShowL() or UpdateL()

   364     Sets icon name or animation logical name.

   325     is called.

   330     \sa IconName()

   369     \sa iconName(), show(), update() 

   336     d->mData["iconName"] = iconName;

   375     d->mData[keyIconName] = iconName;

   342     Set and update text on dialog. Text is not set, if show() or update()

   381     Sets dialog text. Changes also title text wrapping. If text is empty,

   343     is not called.

   382     sets title text wrapping to Hb::TextWordWrap, otherwise Hb::TextNoWrap.

   344     \param text - text shown on dialog.

   383 

   345     \sa show(), update()

   384     \param text Dialog text.

   385 

   386     \sa text(), show(), update()

   351     d->mData["text"] = text;

   392     d->mData[keyText] = text;

   357     Set and update title on dialog. Title is not set, if show() or update()

   398     Sets title text.

   358     is not called.

   399 

   359     \param title - title shown on dialog.

   400     \param title Title text.

   360     \sa show(), update()

   401 

   402     \sa title(), show(), update()

   366     d->mData["title"] = title;

   408     d->mData[keyTitle] = title;

   372     Enable user interaction on dialog. Setting is not set, if show() or update()

   414     Enables user interaction on dialog.

   373     is not called.

   415 

   374     \param enable - When enabled, activated() signal is emitted on user action.

   416     \param enable True enableds activated() signal on user action.

   375 

   417 

   376     Default value is false.

   418     \sa isTouchActivating(), show(), update()

   377     \sa show(), update()

   383     d->mData["touchActivation"] = enable;

   424     d->mData[keyTouchActivation] = enable;

   389     Set dialog timeout. Timeout is not set, if show() or update()

   430     Sets dialog timeout.

   390     is not called.

   431 

   391     \param timeout - Set timeout for dialog.

   432     \param timeout Timeout is milliseconds.

   433 

   434     \sa timeout(), show(), update()

   435 */

   436 void HbDeviceNotificationDialog::setTimeout(int timeout)

   437 {

   438     TRACE_ENTRY

   439     Q_D(HbDeviceNotificationDialog);

   440     d->mData[keyTimeout] = timeout;

   441     d->scheduleUpdateEvent();

   442     TRACE_EXIT

   443 }

   444 

   445 /*!

   446     Sets title text wrapping. The title can wrap only if there is no text for the dialog.

   447     The title can wrap to a maximum of two lines. setText() also changes title text wrapping.

   448 

   449     \param wrapping Title text wrapping.

   450 

   451     \sa titleTextWrapping(), setText(), show(), update()

   452 */

   453 void HbDeviceNotificationDialog::setTitleTextWrapping(Hb::TextWrapping wrapping)

   454 {

   455     TRACE_ENTRY

   456     Q_D(HbDeviceNotificationDialog);

   457     d->mData[keyTitleTextWrapping] = wrapping;

   458     d->scheduleUpdateEvent();

   459     TRACE_EXIT

   460 }

   461 

   462 /*!

   463     Set animation definition. Animation logical name has to be set

   464     using setIcon(). Animation definition files must be stored to a place where they

   465     can be accessed by device dialog service.

   466 

   467     Supported animation formats are following:

   468     - GIF (.gif)

   469     - MNG (.mng)

   470         - Frame animations

   471 

   472     \param animationDefinition Path and name of the animation definition file.

   473 

   474     \sa setIconName(), animationDefinition(), HbIconAnimationManager::addDefinitionFile(), show(), update()

   475 */

   476 void HbDeviceNotificationDialog::setAnimationDefinition(QString &animationDefinition)

   477 {

   478     TRACE_ENTRY

   479     Q_D(HbDeviceNotificationDialog);

   480     d->mData[keyAnimationDefinition] = animationDefinition;

   481     d->scheduleUpdateEvent();

   482     TRACE_EXIT

   483 }

   484 

   485 /*!

   486     Returns icon or animation file name.

   487 

   488     \sa setIconName()

   489 */

   490 QString HbDeviceNotificationDialog::iconName() const

   491 {

   492     TRACE_ENTRY

   493     Q_D(const HbDeviceNotificationDialog);

   494 

   495     TRACE_EXIT

   496     return d->mData.value(keyIconName).toString();

   497 }

   498 

   499 /*!

   500     Returns dialog text.

   501 

   502     \sa setText()

   503 */

   504 QString HbDeviceNotificationDialog::text() const

   505 {

   506     TRACE_ENTRY

   507     Q_D(const HbDeviceNotificationDialog);

   508 

   509     TRACE_EXIT

   510     return d->mData.value(keyText).toString();

   511 }

   512 

   513 /*!

   514     Returns title text.

   515 

   516     \sa setTitle()

   517 */

   518 QString HbDeviceNotificationDialog::title() const

   519 {

   520     TRACE_ENTRY

   521     Q_D(const HbDeviceNotificationDialog);

   522 

   523     TRACE_EXIT

   524     return d->mData.value(keyTitle).toString();

   525 }

   526 

   527 /*!

   528     Returns whether touch activation is enabled. Default value is false.

   529 

   530     \sa enableTouchActivation()

   531 */

   532 bool HbDeviceNotificationDialog::isTouchActivating() const

   533 {

   534     TRACE_ENTRY

   535     Q_D(const HbDeviceNotificationDialog);

   536     TRACE_EXIT

   537     return d->mData.value(keyTouchActivation).toBool();

   538 }

   539 

   540 /*!

   541     Returns timeout.

   394     \sa show(), update()

   544 

   395 */

   545     \sa setTimeout()

   396 void HbDeviceNotificationDialog::setTimeout(int timeout)

   546 */

   397 {

   547 int HbDeviceNotificationDialog::timeout() const

   398     TRACE_ENTRY

   399     Q_D(HbDeviceNotificationDialog);

   400     d->mData["timeout"] = timeout;

   401     d->scheduleUpdateEvent();

   402     TRACE_EXIT

   403 }

   404 

   405 /*!

   406     Set dialog title text wrapping.

   407     \param wrapping - Set wrapping for dialog title text.

   408 

   409     Default value is NoWrap.

   410     \sa show(), update()

   411 */

   412 void HbDeviceNotificationDialog::setTitleTextWrapping(Hb::TextWrapping wrapping)

   413 {

   414     TRACE_ENTRY

   415     Q_D(HbDeviceNotificationDialog);

   416     d->mData["titleTextWrapping"] = wrapping;

   417     d->scheduleUpdateEvent();

   418     TRACE_EXIT

   419 }

   420 

   421 /*!

   422     Set animation definition on dialog. Animation logical name has to be set

   423     using setIcon(). Animation is not set, if show() or update()

   424     is not called.

   425     \param animationDefinition - path and name animation definition file shown in dialog.

   426     \sa show(), update(), setIconName()

   427 */

   428 void HbDeviceNotificationDialog::setAnimationDefinition(QString &animationDefinition)

   429 {

   430     TRACE_ENTRY

   431     Q_D(HbDeviceNotificationDialog);

   432     d->mData["animationDefinition"] = animationDefinition;

   433     d->scheduleUpdateEvent();

   434     TRACE_EXIT

   435 }

   436 

   437 /*!

   438     Returns name and path of the icon shown on dialog. If not set, returns empty string.

   439 

   440     \sa setIconName

   441 */

   442 QString HbDeviceNotificationDialog::iconName() const

   446 

   551     TRACE_EXIT

   447     const char *key = "iconName";

   552     const QVariant defaultValue(3000); // HbPopup::StandardTimeout

   448     QVariantMap::const_iterator i = d->mData.find(key);

   553     return d->mData.value(keyTimeout, defaultValue).toInt();

   449     if (i != d->mData.end() && i.key() == "iconName") {

   554 }

   450         return i.value().toString();

   555 

   451     }

   556 /*!

   452     TRACE_EXIT

   557     Returns title text wrapping.

   453     return QString();

   558     

   454 }

   559     The title can wrap only if dialog text is empty. The title can wrap to a maximum of two lines.

   455 

   456 /*!

   457     Get text shown on dialog. If not set, returns empty string.

   458 

   459     \sa setText()

   460 */

   461 QString HbDeviceNotificationDialog::text() const

   462 {

   463     TRACE_ENTRY

   464     Q_D(const HbDeviceNotificationDialog);

   465 

   466     const char *key = "text";

   467     QVariantMap::const_iterator i = d->mData.find(key);

   468     if (i != d->mData.end() && i.key() == "text") {

   469         return i.value().toString();

   470     }

   471     TRACE_EXIT

   472     return QString();

   473 }

   474 

   475 /*!

   476     Get title shown on dialog. If not set, returns empty string.

   477 

   478     \sa setTitle()

   479 */

   480 QString HbDeviceNotificationDialog::title() const

   481 {

   482     TRACE_ENTRY

   483     Q_D(const HbDeviceNotificationDialog);

   484 

   485     const char *key = "title";

   486     QVariantMap::const_iterator i = d->mData.find(key);

   487     if (i != d->mData.end() && i.key() == "title") {

   488         return i.value().toString();

   489     }

   490     TRACE_EXIT

   491     return QString();

   492 }

   493 

   494 /*!

   495     Get trigger action setting.

   496 

   497     \sa setTriggerAction()

   498 */

   499 bool HbDeviceNotificationDialog::isTouchActivating() const

   500 {

   501     TRACE_ENTRY

   502     Q_D(const HbDeviceNotificationDialog);

   503     TRACE_EXIT

   504     return d->mData["touchActivation"].toBool();

   505 }

   506 

   507 /*!

   508     Get timeout setting.

   509 

   510     \sa setTimeout()

   511 */

   512 int HbDeviceNotificationDialog::timeout() const

   513 {

   514     TRACE_ENTRY

   515     Q_D(const HbDeviceNotificationDialog);

   516     TRACE_EXIT

   517     return d->mData["timeout"].toInt();

   518 }

   519 

   520 /*!

   521     Returns the style of text wrapping for the title.

   522 

   532     return (Hb::TextWrapping)d->mData["titleTextWrapping"].toInt();

   569     const QVariant defaultValue(

   533 }

   570         static_cast<int>(text().isEmpty() ? Hb::TextWordWrap : Hb::TextNoWrap));

   534 

   571     return static_cast<Hb::TextWrapping>(d->mData.value(keyTitleTextWrapping,

   535 /*!

   572         defaultValue).toInt());

   536     Returns the animation definition file name.

   573 }

   574 

   575 /*!

   576     Returns animation definition file name.

   545     const char *key = "animationDefinition";

   585     TRACE_EXIT

   546     QVariantMap::const_iterator i = d->mData.find(key);

   586     return d->mData.value(keyAnimationDefinition).toString();

   547     if (i != d->mData.end() && i.key() == "animationDefinition") {

   587 }

   548         return i.value().toString();

   588 

   549     }

   589 /*!

   550     TRACE_EXIT

   590     Shows a notification dialog and returns immediately without waiting for it to close.

   551     return QString();

   591     Closing of the dialog is indicated by aboutToClose() signal. Tapping of dialog is

   552 }

   592     indicated by activated() signal. Dialog can be updated while showing by property

   553 

   593     setters.

   554 /*!

   594 

   555     Show the dialog.

   595     \sa update(), aboutToClose(), activated()

   556     \code

   596 

   557     // example to show dialog.

   558     mNotificationDialog->setText("Dialog text");

   559     mNotificationDialog->show();

   560     \endcode

   570     Update the dialog.

   606     Updates changed properties to a showing notification dialog via interprocess

   571     \code

   607     communication. Has no effect if show() has not been called or the dialog has

   572     // example to update already showing dialog.

   608     closed already. Calling update() is optional as setting any property schedules

   573     mNotificationDialog->setText("Update title");

   609     an event and the showing notification is updated next time Qt event loop executes.

   574     mNotificationDialog->update();

   610 

   575     \endcode

   611     \sa show()

   584     Close the dialog. Method has no effect if convenience methods

   620     Closes a device notification dialog.

   585     are used to show device notification dialog.