--- a/src/hbcore/gui/hbdialog.cpp Tue Jul 06 14:36:53 2010 +0300
+++ b/src/hbcore/gui/hbdialog.cpp Wed Aug 18 10:05:37 2010 +0300
@@ -54,65 +54,154 @@
@beta
@hbcore
\class HbDialog
- \brief HbDialog is a base class for different dialogs in Hb library.
+ \brief The HbDialog class is a concrete class for simple application dialogs
+ and a base class for a variety of convenience application dialog and popup classes.
+
+ An application dialog is a popup that opens in response to application events.
+ Popup dialogs float above the top layer of the application view, usually overlapping
+ the area reserved for the application content. An application can use a dialog to
+ provide information, give warnings, and ask the user to answer a question or
+ select an option. Avoid overusing dialogs because they can interrupt the user's
+ workflow. When dialogs appear too frequently, users tend to dismiss them without
+ reading them properly, just to get them out of the way.
+
+ %HbDialog is a concrete class that you can use directly in your applications.
+ However, there are a variety of convenience classes that derive from it,
+ so check whether there is one that meets your needs. You can create a custom
+ dialog by deriving a class from %HbDialog and adding a custom widget to it.
- \image html hbpopup.png "A dialog with a header widget, a list as a content widget, and two action buttons."
+ \image html hbpopup.png "A dialog with a heading widget, a list content widget, and two action buttons"
+
+ You can add three types of content to an %HbDialog object. If you do not add any
+ content, an %HbDialog object is simply a bordered rectangle. The three types of
+ content are:
+
+ - <b>A heading widget</b>. This is shown at the top of the dialog and is typically
+ a simple HbLabel object that describes the purpose of the dialog. To add a heading
+ widget, call setHeadingWidget().
+
+ - <b>A content widget</b>. Positioned below the heading, this contains the main
+ dialog content. To add a content widget, call setContentWidget().
- HbDialog is a concrete class. The content for a custom dialog is
- implemented in a separate widget, which is set to the dialog with
- method setContentWidget().
+ - \b Actions. These are generic command (HbAction) objects, which you add to the
+ dialog by calling the QGraphicsWidget::addAction() family of functions. The actions
+ appear as buttons on a toolbar at the bottom of the dialog. (The toolbar appears when
+ you add the first action to the dialog.) When the user taps one of these buttons, it
+ dismisses the dialog and the action's \link HbAction::triggered() triggered()\endlink
+ signal is emitted. Connect this signal to the slot that will perform the command.
+ %HbDialog is derived from HbPopup, which provides generic features for all popup
+ classes. These features include properties that control the dialog's dismiss policy,
+ background fade policy, timeout, frame background type, and whether it is modal.
+
+ Unlike a non-modal dialog, a modal dialog stops the user interacting with anything outside
+ of the dialog until it closes. You set and get the modality by calling setModal()
+ and isModal(), respectively. Typically modal dialogs use the fade background feature,
+ whereas non-modal dialogs do not. How you open a dialog depends on whether it is
+ modal: if the dialog is modal use one of the open() overloads and otherwise use
+ \link QGraphicsItem::show() show()\endlink. Make sure you use the appropriate method,
+ because this ensures the correct touch event handling.
- An example of how to create a simple modal dialog and show it.
+ \note Services that generate device-wide and system-wide messages use the HbDeviceDialog
+ class and not HbDialog.
+
+ \section _usecases_hbdialog Using the HbDialog class
+
+ \subsection _uc_001_hbdialog Creating and showing a simple modal dialog
+
+ This example demonstrates how to create a simple modal dialog and show it. Notice
+ that we show a modal dialog by calling one of the open() overloads.
\snippet{ultimatecodesnippet/ultimatecodesnippet.cpp,13}
- An example of how to handle dialog signals from previous example.
+ \subsection _uc_002_hbdialog Handling dialog signals
+
+ This example continues the previous one, which connects the dialog's
+ finished(HbAction*) signal to the following slot in the call to
+ open(QObject *,const char*) on the final line. This example shows how this slot
+ handles the finished(HbAction*) signal.
+
\snippet{ultimatecodesnippet/ultimatecodesnippet.cpp,53}
- An example of how to handle if finished(int) is connected instead of finished(HbAction*) in above example.
- \snippet{ultimatecodesnipped/ultimatecodesnippet.cpp,55}
+ \subsection _uc_003_hbdialog Handling dialog signals: alternative method
- An example of how to create a non-modal dialog and show it.
+ This example demonstrates an alternative way of handling dialog signals.
+ This example assumes that the finished(int) overload is connected instead of
+ finished(HbAction*); for example, by using open(QObject *, const char *), like
+ this:
+
+ \code
+ dialog->open(this, SLOT(dialogClosed(int)));
+ \endcode
+
+ The finished(int) signal is emitted by calling accept() and reject() or done().
+
+ Here is an example of a function that handles finished(int):
+ \snippet{ultimatecodesnippet/ultimatecodesnippet.cpp,58}
+
+ \subsection _uc_004_hbdialog Creating and showing a non-modal dialog
+
+ This final example shows how to create a non-modal dialog and show it.
+ Notice that we display a non-modal dialog by calling \link QGraphicsItem::show()
+ show()\endlink.
\snippet{ultimatecodesnippet/ultimatecodesnippet.cpp,26}
+ \sa HbPopup, HbDeviceDialog, HbInputDialog, HbMessageBox, HbProgressDialog,
+ HbNotificationDialog, HbColorDialog, HbSelectionDialog, HbVolumeSliderPopup,
+ HbZoomSliderPopup
*/
/*!
+ \enum HbDialog::DialogCode
+ Indicates whether the dialog was accepted or rejected.
+
+ \sa finished(int), done()
+
+ */
+
+/*!
+ \var HbDialog::Rejected
+ Indicates that the user selected the Cancel action (or equivalent).
+ */
+
+/*!
+ \var HbDialog::Accepted
+ Indicates that the user selected the OK action (or equivalent).
+ */
+
+/*!
\fn void HbDialog::finished( int code )
- This signal is emitted when the dialog is closed.
- This will have the HbDialog::DialogCode as the parameter code.
+ This signal is emitted when the dialog closes. \a code is an
+ HbDialog::DialogCode value.
\sa done(), accept(), reject()
*/
/*!
\fn void HbDialog::finished( HbAction *action )
- This signal is emitted when an action has been triggered in a dialog.
- The parameter will be the triggered action.
+ This signal is emitted when an action is triggered in a dialog.
+ The parameter is the action that was triggered.
*/
/*!
\fn void HbDialog::accepted( )
- This signal is emitted when the dialog is closed and the user
- has accepted the dialog. which implies that either action has triggered
- or through function call the accept method is called, causing this signal.
+ This signal is emitted by a call to accept() or to \link done()
+ done(HbDialog::Accepted)\endlink. Typically this means that the user
+ has selected the OK button (or equivalent).
\sa done(), accept(), reject()
*/
/*!
\fn void HbDialog::rejected( )
-
- This signal is emitted when the dialog is closed and the user
- has rejected the dialog. which implies that either action triggered
- or through function call the reject method is called, causing this signal.
+
+ This signal is emitted by a call to reject() or to \link done()
+ done(HbDialog::Rejected)\endlink. Typically this means that the user
+ has selected the Cancel action (or equivalent).
\sa done(), accept(), reject()
*/
-
/*!
- \reimp
\fn int HbDialog::type() const
*/
@@ -122,7 +211,8 @@
primaryAction(0),
secondaryAction(0),
closingAction(0),
- toolBar(0)
+ toolBar(0),
+ dismissOnAction(true)
{
}
@@ -130,7 +220,7 @@
{
}
-/*!
+/*
Relayouts the popup. If expandSize is true it the new calculated size of the popup
cannot be smaller than the current size.
*/
@@ -153,7 +243,14 @@
q->updateGeometry();
}
-/*!
+void HbDialogPrivate::_q_actionTriggered() {
+ Q_Q(HbDialog);
+ if (dismissOnAction) {
+ q->close();
+ }
+}
+
+/*
Utility function removes the spaces from string if any
*/
void HbDialogPrivate::removeSpaces(QString& string)
@@ -168,9 +265,15 @@
}
/*!
- Constructs a dialog with given \a parent graphics item.\n
- Note: dialogs with \a parent set as 0 are behaving as real popups.
- This is actually the intended use. \sa HbPopup::HbPopup
+ Constructs a dialog with the given \a parent. For a popup dialog (which
+ means that it opens above all other objects, at the highest z-order),
+ set \a parent to 0. This is the primary intended use of this class.
+
+ If \a parent is non-zero, the dialog is embedded in the parent QGraphicsItem.
+ The properties provided by HbPopup are then ignored and the aboutToClose() signal is
+ not emitted.
+
+ \sa HbPopup::HbPopup()
*/
HbDialog::HbDialog(QGraphicsItem *parent) :
HbPopup(*new HbDialogPrivate, parent)
@@ -192,15 +295,16 @@
}
/*!
- Destroys the popup.
+ Destructor.
*/
HbDialog::~HbDialog()
{
}
/*!
- Returns the widget which is being added to the heading area
- \sa setHeadingWidget()
+ Returns the heading widget, if one has been added to the dialog; otherwise this
+ function returns null.
+ \sa setHeadingWidget()
*/
QGraphicsWidget * HbDialog::headingWidget() const
{
@@ -209,9 +313,11 @@
}
/*!
- Adds \a widget to the heading area. Ownership of the widget is transferred
- to popup. If \a headingWidget is 0 the heading widget is removed.
- \sa headingWidget()
+ Adds \a headingWidget to the heading area of the dialog. This transfers ownership
+ of the heading widget to the dialog.
+
+ To remove a heading widget from a dialog, set \a headingWidget to 0.
+ \sa headingWidget()
*/
void HbDialog::setHeadingWidget(QGraphicsWidget *headingWidget)
{
@@ -232,9 +338,13 @@
}
/*!
- Returns the content widget property of the popup.
- HbDialog only draws a bordered rect, the rest is drawn by the content widget.
- \sa setContentWidget()
+ Returns the content widget, if one has been added to the dialog; otherwise this
+ function returns null.
+
+ The content widget provides the main content for the dialog. Without a content
+ widget (and a heading widget and some actions), an HbDialog object is simply a
+ bordered rectangle.
+ \sa setContentWidget()
*/
QGraphicsWidget *HbDialog::contentWidget() const
{
@@ -243,11 +353,12 @@
}
/*!
- Sets the content widget property of the popup.
- HbDialog only draws a bordered rect, the rest is drawn by the content widget.
- Ownership of the widget is transferred
- to popup. If \a contentWidget is 0 the content widget is removed.
- \sa contentWidget()
+ Adds \a contentWidget to the dialog. This transfers ownership of the content
+ widget to the dialog.
+
+ To remove a content widget from a dialog, set \a headingWidget to 0.
+
+ \sa contentWidget()
*/
void HbDialog::setContentWidget(QGraphicsWidget *contentWidget)
{
@@ -267,10 +378,9 @@
}
/*!
- \deprecated HbDialog::primaryAction() const
- is deprecated.
- It returns the primary action added to the control area
- \sa setPrimaryAction()
+ \deprecated This function is deprecated.
+
+ Returns the action added by calling setPrimaryAction().
*/
HbAction* HbDialog::primaryAction() const
{
@@ -280,13 +390,35 @@
}
/*!
- \deprecated HbDialog::setPrimaryAction(HbAction*)
- is deprecated. Please use QGraphicsWidget::addAction() family of functions instead.
- It adds the given action to the control area.
- It is added to the left side of the control area if the layout direction of the application
- is left-to-right and in the vice-versa if the layout direction of the application
- is right-to-left.
- \sa primaryAction()
+ Returns the \c dismissOnAction property, which controls whether the dialog closes
+ when one of its actions is triggered.
+ \sa setDismissOnAction()
+*/
+bool HbDialog::dismissOnAction() const
+{
+ Q_D(const HbDialog);
+ return d->dismissOnAction;
+}
+
+/*!
+ Sets the \c dismissOnAction property, which controls whether the dialog closes
+ when one of its actions is triggered.
+ \sa dismissOnAction()
+*/
+void HbDialog::setDismissOnAction( bool dismissOnAction )
+{
+ Q_D(HbDialog);
+ d->dismissOnAction = dismissOnAction;
+}
+
+/*!
+ \deprecated This function is deprecated. Add actions by calling one of
+ the QGraphicsWidget::addAction() family of functions instead.
+
+ Adds \a action to the left side of the dialog's toolbar if the layout is left
+ to right and to the right side of the toolbar if the layout is right to left.
+
+ \sa primaryAction()
*/
void HbDialog::setPrimaryAction(HbAction *action)
{
@@ -304,10 +436,9 @@
}
/*!
- \deprecated HbDialog::secondaryAction() const
- is deprecated.
- It returns the secondary action added to the control area
- \sa setSecondaryAction()
+ \deprecated This function is deprecated.
+
+ Returns the action added by calling setSecondaryAction().
*/
HbAction* HbDialog::secondaryAction() const
{
@@ -317,13 +448,13 @@
}
/*!
- \deprecated HbDialog::setSecondaryAction(HbAction*)
- is deprecated. Please use QGraphicsWidget::addAction() family of functions instead.
- It adds the given action to the control area.
- It is added to the right side of the control area if the layout direction of the application
- is left-to-right and in the vice-versa if the layout direction of the application
- is right-to-left.
- \sa secondaryAction()
+ \deprecated This function is deprecated. Add actions by calling one of
+ the QGraphicsWidget::addAction() family of functions instead.
+
+ Adds \a action to the right side of the dialog's toolbar if the layout is left
+ to right and to the left side of the toolbar if the layout is right to left.
+
+ \sa secondaryAction()
*/
void HbDialog::setSecondaryAction(HbAction *action)
{
@@ -337,25 +468,35 @@
}
/*!
- This is a slot which shows the dialog and returns immediately.
-
- \sa open(QObject*,const char*)
+ Displays the dialog and returns immediately.
+
+ Use this function to open \b modal dialogs. To open \b non-modal dialogs,
+ call \link QGraphicsItem::show() show()\endlink.
+
+ \overload
+
+ \sa open(QObject*, const char*), HbPopup::isModal()
*/
void HbDialog::open()
{
open(0,0);
}
/*!
-
- Shows the dialog as modal dialog returning immediately.
+ Displays the dialog, connects the finished(HbAction*) or finished(int) signal to a
+ receiver object's slot, and returns immediately. Disambiguation between the two
+ signals is done at runtime. The signal is disconnected from the slot when the dialog
+ closes.
- Connects finished(HbAction*) or finished(int) signal to the slot specified by \a receiver and
- \a member. The signal will be disconnected from the slot when the
- popup is closed. disambiguation between which method to connect to is done at runtime.
-
- For non modal popups, use show().
+ Use this function to open \b modal dialogs. To open \b non-modal dialogs,
+ call \link QGraphicsItem::show() show()\endlink.
+
+ \overload
+
+ \param receiver The object that is to receive the signal.
+ \param member The slot on the receiver to which the signal is to connect.
+
+ \sa HbPopup::isModal()
*/
-
void HbDialog::open( QObject* receiver, const char* member )
{
Q_D(HbDialog);
@@ -378,14 +519,18 @@
show();
}
/*!
- Closes the dialog and emits finished ,accepted and rejected signals appropriately.
+ Closes the dialog and emits the \link finished(int) finished(HbDialog::DialogCode)
+ \endlink signal and either the accepted() or rejected() signal, depending on the
+ value of \a code.
- If the dialog is accepted the code is HbDialog::Accepted, if it is rejected code
- is HbDialog::Rejected.
- As with HbWidget::close(), done() deletes the dialog if the
- Qt::WA_DeleteOnClose flag is set.
+ Like \link QGraphicsWidget::close() close()\endlink, this function deletes the
+ dialog if the Qt::WA_DeleteOnClose flag is set.
+
+ \param code Pass HbDialog::Accepted to indicate that the user clicked the OK
+ button (or equivalent) and HbDialog::Rejected to indicate that the user
+ clicked the Cancel button (or equivalent).
- \sa accept(), reject()
+ \sa accept(), reject()
*/
void HbDialog::done( int code )
{
@@ -410,18 +555,52 @@
}
}
/*!
- Hides the modal dialog and emits finished(HbDialog::Accepted),accepted() and finished(HbAction*) signals.
+ Closes the dialog and emits the \link finished(int) finished(HbDialog::Accepted)\endlink,
+ accepted(), and finished(HbAction*) signals. Typically, you call this function when the
+ user selects the OK action (or equivalent).
+
+ Like \link QGraphicsWidget::close() close()\endlink, this function deletes the
+ dialog if the Qt::WA_DeleteOnClose flag is set.
+
+ \b Example:
+ \code
+ // Create the OK action.
+ mOkAction = new HbAction("OK");
+
+ // Connect its triggered signal to the dialog's accept() slot.
+ connect(mOkAction, SIGNAL(triggered()), this, SLOT(accept()));
+
+ // Add the action to the dialog.
+ addAction(mOkAction);
+ \endcode
- \sa reject(), done()
+ \sa reject(), done()
*/
void HbDialog::accept()
{
done(Accepted);
}
/*!
- Hides the modal dialog and emits finished(HbDialog::Rejected),rejected() and finished(HbAction*) signals.
+ Closes the dialog and emits the \link finished(int) finished(HbDialog::Rejected)\endlink,
+ rejected(), and finished(HbAction*) signals. Typically, you call this function when
+ the user selects the Cancel action (or equivalent).
+
+ Like \link QGraphicsWidget::close() close()\endlink, this function deletes the
+ dialog if the Qt::WA_DeleteOnClose flag is set.
+
+ \b Example:
+ \code
+ // Create the Cancel action.
+ mCancelAction = new HbAction("Cancel");
+
+ // Connect its triggered signal to the dialog's reject() slot.
+ connect(mCancelAction, SIGNAL(triggered()), this, SLOT(reject()));
+
+ // Add the action to the dialog.
+ addAction(mCancelAction);
+ \endcode
- \sa accept(), done()
+ \sa accept(), done()
*/
void HbDialog::reject()
{
@@ -429,7 +608,7 @@
}
/*!
- \reimp
+
*/
//
// Sets the focus to its content widget.
@@ -443,7 +622,7 @@
}
/*!
- \reimp
+
*/
void HbDialog::closeEvent ( QCloseEvent * event )
{
@@ -469,7 +648,7 @@
}
/*!
- \reimp
+
*/
void HbDialog::changeEvent(QEvent *event)
{
@@ -483,7 +662,7 @@
}
/*!
- \reimp
+
*/
bool HbDialog::event(QEvent *event)
{
@@ -492,21 +671,21 @@
event->accept();
if (event->type() == QEvent::ActionAdded) {
- if (!d->toolBar) {
- // TODO: HbToolBar private interface should make it possible to choose
- // different graphics for tool buttons.
+ if (!d->toolBar) {
d->toolBar = new HbToolBar();
+ d->toolBar->setFlag(QGraphicsItem::ItemIsPanel, false);
d->toolBar->setParentItem(this);
HbStyle::setItemName(d->toolBar ,"controls");
setProperty("controls_layout", true);
d->toolBar->setOrientation(Qt::Horizontal);
+ // Choose different graphics for tool buttons.
HbToolBarPrivate::d_ptr(d->toolBar)->mDialogToolBar = true;
repolish();
}
QActionEvent *actionEvent = static_cast<QActionEvent *>(event);
d->toolBar->insertAction (actionEvent->before(), actionEvent->action());
if (!parentItem()) { // only for popup without parent
- connect(actionEvent->action(), SIGNAL(triggered()), this, SLOT(close()));
+ connect(actionEvent->action(), SIGNAL(triggered()), this, SLOT(_q_actionTriggered()));
}
d->doLayout();
return true;
@@ -547,7 +726,7 @@
}
/*!
- \reimp
+ Reimplemented from QGraphicsWidget.
*/
QSizeF HbDialog::sizeHint(Qt::SizeHint which, const QSizeF &constraint) const
{