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

   123 	set the definition file and the logical name of the animation:

   151     set the definition file and the logical name of the animation:

   133     \sa HbIconAnimationManager::addDefinitionFile

   162 

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

   163     \sa HbNotificationDialog, HbDeviceDialog, CHbDeviceNotificationDialogSymbian

   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()) {

   259     Constructor.

   300     Constructs HbDeviceNotificationDialog with \a parent.

   278     Destructor.

   316     Destructs HbDeviceNotificationDialog. The dialog launched by show() is closed if aboutToClose()

   317     or activated() signals are connected to by an application. Otherwise the dialog is left

   318     executing and closes itself by a timeout.

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

   329 

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

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

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

   295     HbDeviceNotificationDialog *self = new HbDeviceNotificationDialog;

   336     HbDeviceNotificationDialog dialog;

   296     self->setIconName(iconName);

   337     dialog.setIconName(iconName);

   297     self->setTitle(title);

   338     dialog.setTitle(title);

   298     self->show();

   339     dialog.show();

   299     self->deleteLater();

   300     self = 0;

   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.

   313     HbDeviceNotificationDialog *self = new HbDeviceNotificationDialog;

   353     HbDeviceNotificationDialog dialog;

   314     self->setIconName(iconName);

   354     dialog.setIconName(iconName);

   315     self->setText(text);

   355     dialog.setText(text);

   316     self->setTitle(title);

   356     dialog.setTitle(title);

   317     self->show();

   357     dialog.show();

   318     self->deleteLater();

   358     TRACE_EXIT

   319     self = 0;

   359 }

   320     TRACE_EXIT

   360 

   321 }

   361 /*!

   322 

   362     Sets icon name or animation logical name.

   323 /*!

   363 

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

   364     \param iconName Icon name. Icon can be from Hb resources or themes. Or can be a file in

   325     is called.

   326 

   327     \param aIconName Icon name. Icon can be from Hb resources or themes. Or can be a file in

   330     \sa IconName()

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

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

   373     d->mData[keyIconName] = iconName;

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

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

   343     is not called.

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

   344     \param text - text shown on dialog.

   381 

   345     \sa show(), update()

   382     \param text Dialog text.

   383 

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

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

   390     d->mData[keyText] = text;

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

   396     Sets title text.

   358     is not called.

   397 

   359     \param title - title shown on dialog.

   398     \param title Title text.

   360     \sa show(), update()

   399 

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

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

   406     d->mData[keyTitle] = title;

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

   412     Enables user interaction on dialog.

   373     is not called.

   413 

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

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

   375 

   415 

   376     Default value is false.

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

   377     \sa show(), update()

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

   422     d->mData[keyTouchActivation] = enable;

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

   428     Sets dialog timeout.

   390     is not called.

   429 

   391     \param timeout - Set timeout for dialog.

   430     \param timeout Timeout is milliseconds.

   431 

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

   433 */

   434 void HbDeviceNotificationDialog::setTimeout(int timeout)

   435 {

   436     TRACE_ENTRY

   437     Q_D(HbDeviceNotificationDialog);

   438     d->mData[keyTimeout] = timeout;

   439     d->scheduleUpdateEvent();

   440     TRACE_EXIT

   441 }

   442 

   443 /*!

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

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

   446 

   447     \param wrapping Title text wrapping.

   448 

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

   450 */

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

   452 {

   453     TRACE_ENTRY

   454     Q_D(HbDeviceNotificationDialog);

   455     d->mData[keyTitleTextWrapping] = wrapping;

   456     d->scheduleUpdateEvent();

   457     TRACE_EXIT

   458 }

   459 

   460 /*!

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

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

   463     can be accessed by device dialog service.

   464 

   465     Supported animation formats are following:

   466     - GIF (.gif)

   467     - MNG (.mng)

   468         - Frame animations

   469 

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

   471 

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

   473 */

   474 void HbDeviceNotificationDialog::setAnimationDefinition(QString &animationDefinition)

   475 {

   476     TRACE_ENTRY

   477     Q_D(HbDeviceNotificationDialog);

   478     d->mData[keyAnimationDefinition] = animationDefinition;

   479     d->scheduleUpdateEvent();

   480     TRACE_EXIT

   481 }

   482 

   483 /*!

   484     Returns icon or animation file name.

   485 

   486     \sa setIconName()

   487 */

   488 QString HbDeviceNotificationDialog::iconName() const

   489 {

   490     TRACE_ENTRY

   491     Q_D(const HbDeviceNotificationDialog);

   492 

   493     TRACE_EXIT

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

   495 }

   496 

   497 /*!

   498     Returns dialog text.

   499 

   500     \sa setText()

   501 */

   502 QString HbDeviceNotificationDialog::text() const

   503 {

   504     TRACE_ENTRY

   505     Q_D(const HbDeviceNotificationDialog);

   506 

   507     TRACE_EXIT

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

   509 }

   510 

   511 /*!

   512     Returns title text.

   513 

   514     \sa setTitle()

   515 */

   516 QString HbDeviceNotificationDialog::title() const

   517 {

   518     TRACE_ENTRY

   519     Q_D(const HbDeviceNotificationDialog);

   520 

   521     TRACE_EXIT

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

   523 }

   524 

   525 /*!

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

   527 

   528     \sa enableTouchActivation()

   529 */

   530 bool HbDeviceNotificationDialog::isTouchActivating() const

   531 {

   532     TRACE_ENTRY

   533     Q_D(const HbDeviceNotificationDialog);

   534     TRACE_EXIT

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

   536 }

   537 

   538 /*!

   539     Returns timeout.

   394     \sa show(), update()

   542 

   395 */

   543     \sa setTimeout()

   396 void HbDeviceNotificationDialog::setTimeout(int timeout)

   544 */

   397 {

   545 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 

   549     TRACE_EXIT

   447     const char *key = "iconName";

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

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

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

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

   552 }

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

   553 

   451     }

   554 /*!

   452     TRACE_EXIT

   555     Returns title text wrapping.

   453     return QString();

   556     

   454 }

   557     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();

   567     const QVariant defaultValue(

   533 }

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

   534 

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

   535 /*!

   570         defaultValue).toInt());

   536     Returns the animation definition file name.

   571 }

   572 

   573 /*!

   574     Returns animation definition file name.

   545     const char *key = "animationDefinition";

   583     TRACE_EXIT

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

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

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

   585 }

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

   586 

   549     }

   587 /*!

   550     TRACE_EXIT

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

   551     return QString();

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

   552 }

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

   553 

   591     setters.

   554 /*!

   592 

   555     Show the dialog.

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

   556     \code

   594 

   557     // example to show dialog.

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

   559     mNotificationDialog->show();

   560     \endcode

   570     Update the dialog.

   604     Updates changed properties to a showing notification dialog via interprocess

   571     \code

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

   572     // example to update already showing dialog.

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

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

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

   574     mNotificationDialog->update();

   608 

   575     \endcode

   609     \sa show()

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

   618     Closes a device notification dialog.

   585     are used to show device notification dialog.