FCL/sf/mw/hb: comparison src/hbwidgets/popups/hbnotificationdialog.cpp

equal deleted inserted replaced

-:e6ad4ef83b23
+:b7da29130b0e
 #define H_MARGIN QString("hb-param-margin-gene-middle-horizontal")
 #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:
 SequentialShow();
 static bool allowNotification(void *serverStatus);
 private:
 HbDeviceDialogServerStatus mServerStatus;
 };
+/// \endcond
 // Constructor
 SequentialShow::SequentialShow() :
 HbWidgetSequentialShow(SequentialShow::allowNotification, &mServerStatus), mServerStatus(false)
 {
 connect(&mServerStatus, SIGNAL(statusChanged()), SLOT(externalStatusChanged()));
 {
 return notificationDialogSequentialShowInstance();
 }
 /*!
-@beta
+@stable
 @hbwidgets
 \class HbNotificationDialog
-\brief HbNotificationDialog can be used to notify users of system
+\brief HbNotificationDialog is a non-modal dialog for displaying application notifications.
-generated or user activated events in the UI.
+HbNotificationDialog is displayed at top left corner of a display. It is intended for
-HbNotificationDialog is a non-modal dialog displayed on top of applications.
+applications to show notifications to user in non-intrusive way. The dialog does not
-These notifications do not require
+require user input and is usually closed by timeout.
-user input.
+For content, HbNotificationDialog supports two rows of text and an icon. Two text rows may
-Optionally, an action can be activated with a tap to the notification dialog. This is enabled
+consist either of a title spanning two lines or title and text. Setters are provided for
-by first enabling the touch activation with
+setting title, text and icon. Alternatively, a custom widget can be created and set as
-enableTouchActivation() and then starting the action with the signal
+content by an inherited method setContentWidget().
-HbNotificationDialog::activated().
+HbNotificationDialog closes when tapped. A tap triggers HbNotificationDialog::activated() signal
-HbNotificationDialog is a concrete class. For the content, you can use the default content
+if enabled by enableTouchActivation().
-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
+Notification dialog is displayed by show() or open() methods. Static helper functions
-static launch-methods or by using the methods setText(), setTitle() and setIcon().
+launchDialog() can be used to show dialogs.
-Alternatively, you can create a separate widget, and set it to the dialog with the inherited method
+By default, notification dialogs are synchronized with device dialogs. The display of
-HbNotificationDialog::setContentWidget().
+notification dialogs is delayed until there are no device dialogs on display.
+Notifications dialogs are also synchronized with each other. If several of them
-To display a notification dialog, show() or open() must be called. By default, notifications
+are shown at the same time, they are shown sequentially instead of on top of each other.
-are synchronized with device dialogs. The display of notification dialogs is delayed until there
+The synchronization with device dialogs and sequential display of notification dialogs
-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.
+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
+Using a static helper to show a dialog.
+\code
+HbNotificationDialog::launchDialog(HbIcon("qtg_large_info"), "My title", "My text");
+\endcode
+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)
 {
 Q_D(HbNotificationDialog);
 d->q_ptr = this;
 if ((style()->parameter(H_MARGIN, hMargin)) &&
 (style()->parameter(V_MARGIN, vMargin))) {
 setPreferredPos(QPointF(hMargin, vMargin));
 }
-//d->setPriority(1);
 setModal(false);
 setBackgroundFaded(false);
 setDismissPolicy(HbPopup::NoDismiss);
 setTimeout(HbPopup::StandardTimeout);
 }
 }
 /*!
 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()
 */
 void HbNotificationDialog::enableTouchActivation(bool enabled)
 {
 Q_D(const HbNotificationDialog);
 return d->isTouchActivating;
 }
 /*!
-Convenience method for using HbNotificationDialog. Shows a notification dialog with
+Convenience method to display HbNotificationDialog. Constructs a notification dialog and shows
-the given parameters. The dialog is owned by HbNotificationDialog.
+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)
 {
 HbNotificationDialog *self = new HbNotificationDialog();
 if (scene) {
 self->setTitle(title);
 self->show();
 }
 /*!
-Convenience method for using HbNotificationDialog. Shows a notification dialog with
+Convenience method to display HbNotificationDialog. Constructs a notification dialog and shows
-the given parameters. The dialog is owned by NotificationDialog.
+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)
 {
 HbNotificationDialog *self = new HbNotificationDialog();
 if (scene) {
 self->setTitle(title);
 self->show();
 }
 /*!
-Convenience method for using HbNotificationDialog. Shows a notification dialog with
+Convenience method to display HbNotificationDialog. Constructs a notification dialog and shows
-the given parameters. The dialog is owned by HbNotificationDialog.
+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)
 {
 HbNotificationDialog *self = new HbNotificationDialog();
 if (scene) {
 scene->addItem(self);
 }
 self->setTitle(title);
 self->show();
 }
 /*!
-Returns the title text.
+Returns title text. If a default content widget doesn't exist, it is created.
-If a default content widget doesn't exist, it is created.
 \sa setTitle()
 */
 QString HbNotificationDialog::title() const
 {
 return QString();
 }
 }
 /*!
-Set the dialog title text.
+Sets title text.
 \sa title()
 */
 void HbNotificationDialog::setTitle(const QString& title)
 {
 d->content->setTitle(title);
 d->setNotificationDialogContent();
 }
 /*!
-Returns the text for the dialog.
+Returns dialog text. If a default content widget doesn't exist, it is created.
-If a default content widget doesn't exist, it is created.
 \sa setText()
 */
 QString HbNotificationDialog::text() const
 {
 return QString();
 }
 }
 /*!
-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)
 {
 Q_D(HbNotificationDialog);
 d->checkAndCreateContentWidget();
 }
 d->setNotificationDialogContent();
 }
 /*!
-Returns the icon for the dialog.
+Returns dialog icon. If a default content widget doesn't exist, it is created.
-If a default content widget doesn't exist, it is created.
 \sa setIcon()
 */
 HbIcon HbNotificationDialog::icon() const
 {
 return QString();
 }
 }
 /*!
-Set the icon.
+Sets dialog icon.
 \sa icon()
 */
 void HbNotificationDialog::setIcon(const HbIcon& icon)
 {
 d->content->setIcon( icon );
 d->setNotificationDialogContent();
 }
 /*!
-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
 {
 Q_D(const HbNotificationDialog);
 return d->titleTextWrapping;
 }
 /*!
-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)
 {
 Q_D(HbNotificationDialog);
 if (d->titleTextWrapping != wrapping) {
 d->doLayout();
 }
 }
 /*!
-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
+When enabled, the dialog is synchronized with other notification dialogs. If multiple calls
-in sequence instead of on top of each other. The display of the dialogs is also synchronized
+to show() occur at the same time then dialogs are displayed in sequence instead of on top
-with the device dialogs such that the notification dialogs do not appear until there are no device dialogs being displayed.
+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,
+With sequential show disabled, HbNotificationDialog behaves like other popups.
-setVisible(), hide() and show() have no effect. To remove a dialog from the wait queue, call setSequentialShow(false).
+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.
 \sa isSequentialShow()
 */

changeset 28	b7da29130b0e
parent 23	e6ad4ef83b23
child 30	80e4d18b72f5