\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 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(). 

    - \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.

    \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.

    \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.

    \subsection _uc_003_hbdialog Handling dialog signals: alternative method

    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.

    \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).

 */

/*!

    This signal is emitted when the dialog closes. \a code is an 

    HbDialog::DialogCode value.

    This signal is emitted when an action is triggered in a dialog.

    The parameter is the action that was triggered.

    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).

    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).

    toolBar(0),

    dismissOnAction(true)

/*

void HbDialogPrivate::_q_actionTriggered() {

    Q_Q(HbDialog);

    if (dismissOnAction) {

        q->close();

    }

}

/*

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

    Destructor.

    Returns the heading widget, if one has been added to the dialog; otherwise this

    function returns null.

    \sa setHeadingWidget()

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

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

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

    \deprecated This function is deprecated. 

    Returns the action added by calling setPrimaryAction().

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

    \deprecated This function is deprecated.

     Returns the action added by calling setSecondaryAction().

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

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

    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.

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