/****************************************************************************
**
** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
** All rights reserved.
** Contact: Nokia Corporation (qt-info@nokia.com)
**
** This file is part of the Qt Components project.
**
** $QT_BEGIN_LICENSE:BSD$
** You may use this file under the terms of the BSD license as follows:
**
** "Redistribution and use in source and binary forms, with or without
** modification, are permitted provided that the following conditions are
** met:
**   * Redistributions of source code must retain the above copyright
**     notice, this list of conditions and the following disclaimer.
**   * Redistributions in binary form must reproduce the above copyright
**     notice, this list of conditions and the following disclaimer in
**     the documentation and/or other materials provided with the
**     distribution.
**   * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor
**     the names of its contributors may be used to endorse or promote
**     products derived from this software without specific prior written
**     permission.
**
** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
** $QT_END_LICENSE$
**
****************************************************************************/
/*!
    \qmlclass Dialog
    \inherits Item
    \ingroup qt-components
    \since 4.7

    \brief
    Generic dialog component for creating custom dialogs.

    Dialogs are components for giving informations and asking for user inputs. They are shown on top of the whole screen
    or on top of an item, that is given with the \l visualParent property. Dialogs normally consist of three parts: a title,
    a content field (with a set of arbitrary components) and a button field. If another kind of dialog is needed, 
    leave the \l title and \l buttons property empty and fill the content field.
    
    Below is an example of a simple dialog:
    
        \qml
        // Create a simple "Hello World"-Dialog
        Dialog {
          id: myDialog
          title: Rectangle {
            id: titleField
            height: 2
            width: parent.width
            color: "red"
          }

          content:Item {
            id: name
            height: 50
            width: parent.width
            Text {
              id: text
              font.pixelSize: 22
              anchors.centerIn: parent
              color: "white"
              text: "Hello Dialog"
            }
          }

          buttons: ButtonRow {
            style: ButtonStyle { }
              anchors.horizontalCenter: parent.horizontalCenter
              Button {text: "OK"; onClicked: myDialog.accept()}
            }
          }
       \endqml
       
     The size computing dialog components of MeeGo works in the following way: The height for each field (that means,
     title, content or button field) is computed according to the children the field has, so whenever defining
     a field, a height must be distributed. On the other side, the dialog tries to fill the width of the parent minus
     some margins, so it is good style to have a "width: parent.width" for each field.

     The Dialog class delivers the most flexible way to create dialogs. For easier handling consider using the convenienence classes
     like SelectionDialog, MultiSelectionDialog or QueryDialog.
*/

/*!
    \qmlmethod Dialog::accept()

    Closes the dialog and fires the \l accepted signal.
*/

/*!
    \qmlsignal Dialog::accepted()

    This signal is fired when the function accept() is called. Normally this signal is associated with the "Ok" or "Save" button.
*/

/*!
    \qmlproperty Item Dialog::buttons

    The item to be placed inside the dialog buttons area. Normally one button or a row with buttons is set here.    
*/

/*!
    \qmlmethod Dialog::close()

    Closes the dialog. Neither the \l accepted nor the \l rejected signal is emitted.
*/

/*!
    \qmlproperty Item Dialog::content

    The Item to be placed inside the dialog content area.
*/

/*!
    \qmlmethod Dialog::open()

    Opens the dialog.
*/

/*!
    \qmlmethod Dialog::reject()

    Closes the dialog and fires the \l rejected signal.
*/

/*!
    \qmlsignal Dialog::rejected()

    This signal is fired when the function reject() is called. Normally this signal is associated with the "Cancel" or "Delete" button.
*/

/*!
    \qmlproperty enum Dialog::status

    This property holds the current status.
    
    \list
    \o  DialogStatus.Opening - The animation for opening the dialog is running
    \o  DialogStatus.Opened - The dialog has been opened and is visible
    \o  DialogStatus.Closing - The animation for closing the dialog is running
    \o DialogStatus.Closed - The dialog is closed and invisible
    \endlist

    
*/

/*!
    \qmlproperty Item Dialog::style

    Styling for the component.
*/

/*!
    \qmlproperty Item Dialog::title

    List of Items to be placed inside the dialog title area.
*/

/*!
    \qmlproperty Item Dialog::visualParent
    
    The visualParent property determines in which part of the application window the dialog appears.
    
    Whenever a dialog is shown, a fader darkens the background and the dialog centers inside this area.
    Mouse clicks are not distributed to this background area (that is the dialog gets modal). Normally the
    background comprises the whole screen, but sometimes it is desired to just fade out a special part
    of the application. This is for example the case, when the toolbar should not be faded out.
    
    The following snippet displays a dialog inside the left half of the page:
    
    \qml
    PageStackWindow {
    id: rootWindow

    initialPage: Page {
    id: emptyPage
    Rectangle {id: leftRect; x: 0; y:0; width: parent.width/2; height: parent.height}
    tools: ToolBarLayout {
            id: toolbar
            ToolIcon {iconId: "toolbar-back"}
        }
     }

    Dialog {
        id: myDialog
        visualParent: leftRect
        title:   Rectangle {id: tr; height: 20;  width: parent.width; color: "red"}
        content: Rectangle {id: cr; height: 240; width: parent.width; color: "blue"}
        buttons: Rectangle {id: br; height: 20;  width: parent.width; color: "green"}
    }
    Component.onCompleted: myDialog.open();
  }
  \endqml
    
   If you change the visualParent to pageStack, the dialog will lay over the whole page, but not
   over the toolbar. When you do not bind this property to an Item, the dialog searches for the
   window element and thereafter appear on top of the whole window.

*/

