diff -r e6ad4ef83b23 -r b7da29130b0e src/hbwidgets/popups/hbnotificationdialog.cpp --- a/src/hbwidgets/popups/hbnotificationdialog.cpp Thu Sep 02 20:44:51 2010 +0300 +++ b/src/hbwidgets/popups/hbnotificationdialog.cpp Fri Sep 17 08:32:10 2010 +0300 @@ -52,6 +52,7 @@ #define V_MARGIN QString("hb-param-margin-gene-middle-vertical") // Container to encapsulate device dialog server status and sequential show +/// \cond class SequentialShow : public HbWidgetSequentialShow { public: @@ -60,6 +61,8 @@ private: HbDeviceDialogServerStatus mServerStatus; }; +/// \endcond + // Constructor SequentialShow::SequentialShow() : HbWidgetSequentialShow(SequentialShow::allowNotification, &mServerStatus), mServerStatus(false) @@ -87,45 +90,73 @@ } /*! - @beta + @stable @hbwidgets + \class HbNotificationDialog - \brief HbNotificationDialog can be used to notify users of system - generated or user activated events in the UI. + \brief HbNotificationDialog is a non-modal dialog for displaying application notifications. + + HbNotificationDialog is displayed at top left corner of a display. It is intended for + applications to show notifications to user in non-intrusive way. The dialog does not + require user input and is usually closed by timeout. - HbNotificationDialog is a non-modal dialog displayed on top of applications. - These notifications do not require - user input. + For content, HbNotificationDialog supports two rows of text and an icon. 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. Alternatively, a custom widget can be created and set as + content by an inherited method setContentWidget(). - Optionally, an action can be activated with a tap to the notification dialog. This is enabled - by first enabling the touch activation with - enableTouchActivation() and then starting the action with the signal - HbNotificationDialog::activated(). + HbNotificationDialog closes when tapped. A tap triggers HbNotificationDialog::activated() signal + if enabled by enableTouchActivation(). + + Notification dialog is displayed by show() or open() methods. Static helper functions + launchDialog() can be used to show dialogs. - HbNotificationDialog is a concrete class. For the content, you can use the default content - widgets which provides two rows of text (title spanning both lines, or title and text) and optionally an icon. - You can use the default content widget by invoking the HbNotificationDialog with its - static launch-methods or by using the methods setText(), setTitle() and setIcon(). + By default, notification dialogs are synchronized with device dialogs. The display of + notification dialogs is delayed until there are no device dialogs on display. + Notifications dialogs are also synchronized with each other. If several of them + are shown at the same time, they are shown sequentially instead of on top of each other. + The synchronization with device dialogs and sequential display of notification dialogs + can be disabled using the setSequentialShow() function. + + Following sample code sets dialog title, text, icon and shows it. + \code + HbNotificationDialog *dialog = new HbNotificationDialog(); + dialog->setAttribute(Qt::WA_DeleteOnClose, true); + dialog->setTitle("My title"); + dialog->setText("My text"); + dialog->setIcon(HbIcon("qtg_large_info")); + dialog->show(); + \endcode - Alternatively, you can create a separate widget, and set it to the dialog with the inherited method - HbNotificationDialog::setContentWidget(). + Using a static helper to show a dialog. + \code + HbNotificationDialog::launchDialog(HbIcon("qtg_large_info"), "My title", "My text"); + \endcode - To display a notification dialog, show() or open() must be called. By default, notifications - are synchronized with device dialogs. The display of notification dialogs is delayed until there - are no device dialogs on display. Notifications are also synchronized with each other. - If several notifications are shown at the same time with the show() function, they are shown - sequentially instead of on top of each other. The synchronization of dialogs and sequential display of dialogs - can be disabled using the setSequentialShow() function. + Connecting to activated signal. + \code + HbNotificationDialog *dialog = new HbNotificationDialog(); + connect(dialog, SIGNAL(activated()), this, SLOT(dialogActivated())); + dialog->enableTouchActivation(true); + dialog->setAttribute(Qt::WA_DeleteOnClose, true); + dialog->setTitle("My title"); + dialog->setText("My text"); + dialog->setIcon(HbIcon("qtg_large_info")); + dialog->show(); + \endcode */ /*! \fn void HbNotificationDialog::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() */ /*! - Constructor. + Default constructor. */ HbNotificationDialog::HbNotificationDialog() : HbDialog(*new HbNotificationDialogPrivate, 0) { @@ -142,8 +173,6 @@ setPreferredPos(QPointF(hMargin, vMargin)); } - //d->setPriority(1); - setModal(false); setBackgroundFaded(false); @@ -173,7 +202,8 @@ /*! Enable user interaction on dialog. - \param enabled - When enabled, the activated() signal is emitted on user action. + + \param enabled True enables activated() signal on user action. \sa isTouchActivating() */ @@ -198,8 +228,12 @@ } /*! - Convenience method for using HbNotificationDialog. Shows a notification dialog with - the given parameters. The dialog is owned by HbNotificationDialog. + Convenience method to display HbNotificationDialog. Constructs a notification dialog and shows + it. Constructed object is deleted on close. + + \param title Dialog title. + \param text Dialog text. + \param scene Scene to add the dialog into (optional). */ void HbNotificationDialog::launchDialog(const QString &title, const QString &text, QGraphicsScene* scene) { @@ -214,8 +248,11 @@ } /*! - Convenience method for using HbNotificationDialog. Shows a notification dialog with - the given parameters. The dialog is owned by NotificationDialog. + Convenience method to display HbNotificationDialog. Constructs a notification dialog and shows + it. Constructed object is deleted on close. + + \param title Dialog title. + \param scene Scene to add the dialog into (optional). */ void HbNotificationDialog::launchDialog(const QString &title, QGraphicsScene* scene) { @@ -229,11 +266,16 @@ } /*! - Convenience method for using HbNotificationDialog. Shows a notification dialog with - the given parameters. The dialog is owned by HbNotificationDialog. + Convenience method to display HbNotificationDialog. Constructs a notification dialog and shows + it. Constructed object is deleted on close. + + \param icon Dialog icon. + \param title Dialog title. + \param text Dialog text. + \param scene Scene to add the dialog into (optional). */ void HbNotificationDialog::launchDialog(const HbIcon &icon, const QString &title, - const QString &text, QGraphicsScene* scene) + const QString &text, QGraphicsScene* scene) { HbNotificationDialog *self = new HbNotificationDialog(); if (scene) { @@ -247,9 +289,7 @@ } /*! - Returns the title text. - - If a default content widget doesn't exist, it is created. + Returns title text. If a default content widget doesn't exist, it is created. \sa setTitle() */ @@ -264,7 +304,7 @@ } /*! - Set the dialog title text. + Sets title text. \sa title() */ @@ -277,9 +317,7 @@ } /*! - Returns the text for the dialog. - - If a default content widget doesn't exist, it is created. + Returns dialog text. If a default content widget doesn't exist, it is created. \sa setText() */ @@ -294,9 +332,10 @@ } /*! - Set the text for the dialog. + Sets dialog text. Changes also title text wrapping. If text is empty, + sets title text wrapping to Hb::TextWordWrap, otherwise Hb::TextNoWrap. - \sa text() + \sa text(), setTitleTextWrapping() */ void HbNotificationDialog::setText(const QString& text) { @@ -312,9 +351,7 @@ } /*! - Returns the icon for the dialog. - - If a default content widget doesn't exist, it is created. + Returns dialog icon. If a default content widget doesn't exist, it is created. \sa setIcon() */ @@ -329,7 +366,7 @@ } /*! - Set the icon. + Sets dialog icon. \sa icon() */ @@ -342,12 +379,12 @@ } /*! - Returns the style of text wrapping for the title. + Returns title text wrapping. - The title can wrap only if there is no other text for the dialog. The title can wrap to a maximum of two lines. + 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(), HbNotificationDialog::title, HbNotificationDialog::text + \sa setTitleTextWrapping(), title(), text() */ Hb::TextWrapping HbNotificationDialog::titleTextWrapping() const { @@ -356,10 +393,10 @@ } /*! - Sets whether the text for the title is wrapped. + 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. - The title can wrap only if there is no text for the dialog. The title can wrap to a maximum of two lines. - \sa titleTextWrapping() + \sa titleTextWrapping(), setText() */ void HbNotificationDialog::setTitleTextWrapping(Hb::TextWrapping wrapping) { @@ -374,15 +411,17 @@ } /*! - Enables or disables sequential display of the Notification Dialog. + Enables or disables sequential display of notification dialog. - When enabled, notification dialogs are shown sequentially. If multiple calls to show() occur at the same time then the dialogs are displayed - in sequence instead of on top of each other. The display of the dialogs is also synchronized - with the device dialogs such that the notification dialogs do not appear until there are no device dialogs being displayed. + When enabled, the dialog is synchronized with other notification dialogs. If multiple calls + to show() occur at the same time then dialogs are displayed in sequence instead of on top + of each other. The display of the dialog is also synchronized with device dialogs such + that it does not appear until there are no device dialogs being displayed. - With sequential show disabled, - HbNotificationDialog behaves like other popups. While a dialog is waiting to be shown, - setVisible(), hide() and show() have no effect. To remove a dialog from the wait queue, call setSequentialShow(false). + With sequential show disabled, HbNotificationDialog behaves like other popups. + + While a dialog is waiting to be shown, setVisible(), hide() and show() have no effect. + To remove a dialog from the wait queue, call setSequentialShow(false). This setting is enabled by default.