/****************************************************************************
**
** 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 ContextMenu
    \inherits Item
    \ingroup qt-components
    \since 4.7
    
    \brief
    A Context Menu component for selecting a menu item from a list of menu items.    

    A Context Menu componentis for selecting a menu item from a list of menu items. 
    Each menu item displays some text and can be associated with a custom action that is 
    performed on the \l clicked signal.

    The menu items are arranged in a layout via the MenuLayout element. Note that this layout and its 
    implementation can vary depending on the UI guidelines of the platform.
    
    \qml
    PageStackWindow {
      id: rootWindow
      initialPage: Page {
        
        // long press rectangle to open the ContextMenu
        Rectangle {
            id: contextColorRect
            anchors.centerIn: parent
            width: 100; height: 100
            color: "black"
            MouseArea {
                id: longPressArea
                anchors.fill: parent
                onPressAndHold: myContextMenu.open()
            } 
        }
        
        // Create a menu with different menu items.
        ContextMenu {
            id: myContextMenu
            MenuLayout {
                MenuItem {text: "Red"; onClicked: { contextColorRect.color = "darkred" } }
                MenuItem {text: "Green"; onClicked: { contextColorRect.color = "darkgreen" }}
                MenuItem {text: "Blue"; onClicked: { contextColorRect.color = "darkblue" }}
                MenuItem {text: "Black is an extremely beautiful and stylish color"; onClicked: { contextColorRect.color = "black" }}
            }
          } 
       }  
     }
    \endqml

    The visual parent property is used to specify which area of the screen is grayed out
    while the menu is opened. If no visual parent is set then it is determined automatically and 
    falls back to the root item.

    The ContextMenu shares most of its API with the ContextMenu component.

    \sa MenuItem

    \section1 Common API
    \code
        default property alias content: contentField.children

        // Common API inherited from Popup:
        function open()
        function close()

        property QDeclarativeItem* visualParent
        property int status
        
        property list<Item> title: titleBar.children

        // platformStyle API
        property Style platformStyle
        property string platformTitleText
        property Item platformIcon
        
        property Style style // Deprecated
    \endcode
*/

/*!
    \qmlproperty Item ContextMenu::content

    The content to be placed inside the menu.
*/

/*!
    \qmlmethod ContextMenu::open()

    Opens the menu and changes the status to DialogStatus.Opening
    for the animation phase. 
    Once the menu is opened the status is changed to DialogStatus.Open. 
*/

/*!
    \qmlmethod ContextMenu::close()

    Closes the menu and changes the status to DialogStatus.Closing
    for the animation phase. 
    Once the menu is opened the status is changed to DialogStatus.Closed. 
*/

/*!
    \qmlproperty QDeclarativeItem* ContextMenu::visualParent
    
    Property default is the root element.
    
    The visual parent marks the element that occupies the area which is 
    supposed to be grayed out while the menu is open.
*/

/*!
    \qmlproperty int ContextMenu::status
    
    Returns the current status of the menu during its life cycle. 
    Possible values: DialogStatus.Opening, DialogStatus.Opened, 
    DialogStatus.Closing and DialogStatus.Closed.
*/

/*!
    \qmlproperty list<Item> ContextMenu::title

    The items that provide the title information.
*/

/*!
    \qmlproperty Style ContextMenu::platformStyle
    
    Property default is \c MenuStyle{}.

    Property for styling the component.
*/

