MenuBar. Menu, MenuItem: Update documentation to new API

Also removed Menu.visibleParent since it had no apparent use. Likewise,
trigger(), and the triggered() signal are now only in MenuItem.

Change-Id: Ide194505664c60906019422a503b189250d6a86e
Reviewed-by: Jens Bache-Wiig <jens.bache-wiig@digia.com>

8 files changed, 143 insertions, 85 deletions

diff --git a/src/controls/ComboBox.qml b/src/controls/ComboBox.qml
index 9f430312..ca54d5c4 100644
--- a/src/controls/ComboBox.qml
+++ b/src/controls/ComboBox.qml
@@ -146,7 +146,7 @@ Control {
         property int x: 0
         property int y: centerSelectedText ? 0 : comboBox.height
         __minimumWidth: comboBox.width
-        visualParent: comboBox
+        __visualItem: comboBox
 
         function finalizeItem(item) {
             item.action.checkable = true
diff --git a/src/controls/Menu.qml b/src/controls/Menu.qml
index 3f258fa9..7ba8a41e 100644
--- a/src/controls/Menu.qml
+++ b/src/controls/Menu.qml
@@ -84,6 +84,11 @@ import "Styles/Settings.js" as Settings
     }
     \endcode
 
+    Note that some properties, like \c enabled, \c text, or \c iconSource, only make sense
+    depending on the context in which the menu is being used. The three main use cases are
+    as a \l MenuBar top-level menu, as a submenu inside another menu, or as a standalone,
+    or context, menu.
+
     \sa MenuBar, MenuItem, MenuSeparator
 */
 MenuPrivate {
@@ -182,8 +187,9 @@ MenuPrivate {
         function triggerAndDismiss() {
             var item = itemsRepeater.itemAt(root.__currentIndex)
             if (item && !item.isSeparator) {
-                item.menuItem.trigger()
                 root.__dismissMenu()
+                if (!item.hasSubmenu)
+                    item.menuItem.trigger()
             }
         }
 
@@ -269,11 +275,7 @@ MenuPrivate {
                             }
                         }
 
-                        Component.onCompleted: {
-                            menuItem.__visualItem = menuItemLoader
-                            if (hasSubmenu)
-                                menuItem.visualParent = menuItemLoader
-                        }
+                        Component.onCompleted: menuItem.__visualItem = menuItemLoader
                     }
                 }
 
diff --git a/src/controls/MenuBar.qml b/src/controls/MenuBar.qml
index 940abef6..eaf596e8 100644
--- a/src/controls/MenuBar.qml
+++ b/src/controls/MenuBar.qml
@@ -71,9 +71,19 @@ import "Styles/Settings.js" as Settings
     \sa ApplicationWindow::menuBar
 */
 
+/*!
+    \qmlproperty readonly list MenuBar::menus
+    \default
+
+    The list of menus in the menu bar.
+
+    \sa Menu
+*/
+
 MenuBarPrivate {
     id: root
 
+    //! \internal
     property Component style: Qt.createComponent(Settings.THEME_PATH + "/MenuBarStyle.qml", root)
 
     //! \internal
@@ -193,7 +203,7 @@ MenuBarPrivate {
                         }
 
                         Component.onCompleted: {
-                            menuItem.__visualItem = menuItem.visualParent = menuItemLoader
+                            menuItem.__visualItem = menuItemLoader
                             menuItem.__menuBar = menuBarLoader
                         }
                     }
diff --git a/src/controls/qtmenu.cpp b/src/controls/qtmenu.cpp
index cbfb0108..c7281774 100644
--- a/src/controls/qtmenu.cpp
+++ b/src/controls/qtmenu.cpp
@@ -65,40 +65,72 @@ QT_BEGIN_NAMESPACE
  */
 
 /*!
-    \qmlproperty readonly list Menu::menuItems
+    \qmlproperty readonly list Menu::items
     \default
+
+    The list of items in the menu.
+
+    \sa MenuItem, MenuSeparator
 */
 
 /*!
-    \qmlproperty var Menu::model
+    \qmlproperty bool Menu::visible
+
+    Whether the menu should be visible. This is only enabled when the menu is used as
+    a submenu.
 */
 
 /*!
-    \qmlproperty int Menu::selectedIndex
+    \qmlproperty string Menu::text
+
+    Text for the menu, whether in a \l MenuBar or as a submenu.
+    Accelerators are supported with the usual \& convention.
+*/
+
+/*!
+    \qmlproperty bool Menu::enabled
+
+    Whether the menu is enabled, and responsive to user interaction as a submenu.
 */
 
 /*!
-    \qmlproperty font Menu::font
+    \qmlproperty url Menu::iconSource
+
+    Sets the icon file or resource url for the menu icon as a submenu.
 
-    Write-only. For styling purposes only.
+    \sa iconName
 */
 
 /*!
-    \qmlproperty readonly bool Menu::popupVisible
+    \qmlproperty string Menu::iconName
+
+    Sets the icon name for the menu icon. This will pick the icon
+    with the given name from the current theme. Only works as a submenu.
+
+    \sa iconSource
 */
 
 /*!
-    \qmlmethod void Menu::popup(referenceItem, x, y, atIndex)
+    \qmlproperty int Menu::selectedIndex
 
-    Pops up this menu at the given position relative to \c referenceItem.
+    The index for the last selected item in the menu.
+*/
+
+/*!
+    \qmlmethod void Menu::popup()
+
+    Pops up this menu under the mouse cursor.
     It can block on some platforms, so test it accordingly.
 */
 
+/*!
+    \qmlproperty var Menu::model
+*/
+
 QtMenu::QtMenu(QObject *parent)
     : QtMenuText(parent),
       m_selectedIndex(-1),
       m_highlightedIndex(0),
-      m_visualParent(0),
       m_hasNativeModel(false),
       m_minimumWidth(0),
       m_popupWindow(0),
@@ -167,12 +199,9 @@ QQmlListProperty<QtMenuBase> QtMenu::menuItems()
 QQuickWindow *QtMenu::findParentWindow()
 {
     if (!m_parentWindow) {
-        m_parentWindow = m_visualParent ? m_visualParent->window() : 0;
-        if (!m_parentWindow) {
-            QQuickItem *parentAsItem = qobject_cast<QQuickItem *>(parent());
-            m_parentWindow = visualItem() ? visualItem()->window() :    // Menu as menu item case
-                             parentAsItem ? parentAsItem->window() : 0; //Menu as context menu/popup case
-        }
+        QQuickItem *parentAsItem = qobject_cast<QQuickItem *>(parent());
+        m_parentWindow = visualItem() ? visualItem()->window() :    // Menu as menu item case
+                         parentAsItem ? parentAsItem->window() : 0; //Menu as context menu/popup case
     }
     return m_parentWindow;
 }
@@ -204,8 +233,8 @@ void QtMenu::__popup(qreal x, qreal y, int atItemIndex)
 
     if (m_platformMenu) {
         QPointF screenPosition(x, y);
-        if (m_visualParent)
-            screenPosition = m_visualParent->mapToScene(screenPosition);
+        if (visualItem())
+            screenPosition = visualItem()->mapToScene(screenPosition);
         m_platformMenu->showPopup(parentWindow, screenPosition.toPoint(), atItem ? atItem->platformItem() : 0);
     } else {
         m_popupWindow = new QtMenuPopupWindow();
@@ -214,8 +243,8 @@ void QtMenu::__popup(qreal x, qreal y, int atItemIndex)
         connect(m_popupWindow, SIGNAL(visibleChanged(bool)), this, SLOT(windowVisibleChanged(bool)));
 
         if (parentWindow) {
-            if (m_visualParent) {
-                QPointF pos = m_visualParent->mapToItem(parentWindow->contentItem(), QPointF(x, y));
+            if (visualItem()) {
+                QPointF pos = visualItem()->mapToItem(parentWindow->contentItem(), QPointF(x, y));
                 x = pos.x();
                 y = pos.y();
             }
@@ -239,14 +268,6 @@ void QtMenu::__popup(qreal x, qreal y, int atItemIndex)
     }
 }
 
-void QtMenu::setVisualParent(QQuickItem *item)
-{
-    if (m_visualParent != item) {
-        m_visualParent = item;
-        emit visualParentChanged();
-    }
-}
-
 void QtMenu::setMenuContentItem(QQuickItem *item)
 {
     if (m_menuContentItem != item)
diff --git a/src/controls/qtmenu_p.h b/src/controls/qtmenu_p.h
index 4c0da38b..a66880cc 100644
--- a/src/controls/qtmenu_p.h
+++ b/src/controls/qtmenu_p.h
@@ -60,7 +60,6 @@ class QtMenu : public QtMenuText
     Q_PROPERTY(QQmlListProperty<QtMenuBase> items READ menuItems NOTIFY itemsChanged)
     Q_CLASSINFO("DefaultProperty", "items")
     Q_PROPERTY(int selectedIndex READ selectedIndex WRITE setSelectedIndex NOTIFY selectedIndexChanged)
-    Q_PROPERTY(QQuickItem *visualParent READ visualParent WRITE setVisualParent NOTIFY visualParentChanged)
     Q_PROPERTY(QVariant model READ model WRITE setModel NOTIFY modelChanged)
 
     Q_PROPERTY(bool __popupVisible READ popupVisible NOTIFY popupVisibleChanged)
@@ -85,7 +84,6 @@ public Q_SLOTS:
 
 Q_SIGNALS:
     void selectedIndexChanged();
-    void visualParentChanged();
     void modelChanged(const QVariant &newModel);
     void itemsChanged();
 
@@ -121,18 +119,16 @@ public:
     void setMenuContentItem(QQuickItem *);
     void setPopupVisible(bool);
 
-    QQuickItem *visualParent() const { return m_visualParent; }
-    void setVisualParent(QQuickItem *);
-
     bool isNative() { return m_platformMenu != 0; }
 
-    QQuickWindow *findParentWindow();
 
 protected Q_SLOTS:
     void windowVisibleChanged(bool);
     void updateSelectedIndex();
 
 private:
+    QQuickWindow *findParentWindow();
+
     static void append_menuItems(QQmlListProperty<QtMenuBase> *list, QtMenuBase *menuItem);
     static int count_menuItems(QQmlListProperty<QtMenuBase> *list);
     static QtMenuBase *at_menuItems(QQmlListProperty<QtMenuBase> *list, int index);
@@ -141,14 +137,13 @@ private:
     QList<QtMenuBase *> m_menuItems;
     int m_selectedIndex;
     int m_highlightedIndex;
-    QQuickItem *m_visualParent;
+    QQuickWindow *m_parentWindow;
     bool m_hasNativeModel;
     QVariant m_model;
     int m_minimumWidth;
     QtMenuPopupWindow *m_popupWindow;
     QQuickItem * m_menuContentItem;
     bool m_popupVisible;
-    QQuickWindow *m_parentWindow;
 
     friend class QtMenuBase;
 };
diff --git a/src/controls/qtmenubar.cpp b/src/controls/qtmenubar.cpp
index fafccf00..4f70fb55 100644
--- a/src/controls/qtmenubar.cpp
+++ b/src/controls/qtmenubar.cpp
@@ -60,6 +60,7 @@ QT_BEGIN_NAMESPACE
   \internal
   \inqmlmodule QtQuick.Controls 1.0
  */
+
 QtMenuBar::QtMenuBar(QObject *parent)
     : QObject(parent), m_contentItem(0), m_parentWindow(0)
 {
diff --git a/src/controls/qtmenuitem.cpp b/src/controls/qtmenuitem.cpp
index 4c43bac0..124ba4c8 100644
--- a/src/controls/qtmenuitem.cpp
+++ b/src/controls/qtmenuitem.cpp
@@ -108,6 +108,12 @@ void QtMenuBase::setVisualItem(QQuickItem *item)
     \sa Menu, MenuItem
 */
 
+/*!
+    \qmlproperty bool MenuSeparator::visible
+
+    Whether the menu separator should be visible.
+*/
+
 QtMenuSeparator::QtMenuSeparator(QObject *parent)
     : QtMenuBase(parent)
 {
@@ -125,12 +131,8 @@ QtMenuText::~QtMenuText()
 void QtMenuText::setParentMenu(QtMenu *parentMenu)
 {
     QtMenuBase::setParentMenu(parentMenu);
-    connect(this, SIGNAL(triggered()), parentMenu, SLOT(updateSelectedIndex()));
-}
-
-void QtMenuText::trigger()
-{
-    emit triggered();
+    if (qobject_cast<QtMenuItem *>(this))
+        connect(this, SIGNAL(triggered()), parentMenu, SLOT(updateSelectedIndex()));
 }
 
 void QtMenuText::setEnabled(bool enabled)
@@ -218,53 +220,38 @@ void QtMenuText::setIconName(const QString &iconName)
 */
 
 /*!
-    \qmlproperty string MenuItem::text
+    \qmlproperty bool MenuItem::visible
 
-    Text for the menu item.
+    Whether the menu item should be visible.
 */
 
 /*!
-    \qmlproperty string MenuItem::shortcut
-
-    Shorcut bound to the menu item.
-
-    \sa Action::shortcut
-*/
-
-/*!
-    \qmlproperty bool MenuItem::checkable
-
-    Whether the menu item can be toggled.
+    \qmlproperty string MenuItem::text
 
-    \sa checked
+    Text for the menu item. Accelerators are supported with the usual \& convention.
 */
 
 /*!
-    \qmlproperty bool MenuItem::checked
+    \qmlproperty bool MenuItem::enabled
 
-    If the menu item is checkable, this property reflects its checked state.
-
-    \sa chekcable, Action::toggled()
+    Whether the menu item is enabled, and responsive to user interaction.
 */
 
 /*!
     \qmlproperty url MenuItem::iconSource
 
+    Sets the icon file or resource url for the \l MenuItem icon.
+
     \sa iconName, Action::iconSource
 */
 
 /*!
     \qmlproperty string MenuItem::iconName
 
-    \sa iconSource, Action::iconName
-*/
-
-/*!
-    \qmlproperty Action MenuItem::action
-
-    The action bound to this menu item.
+    Sets the icon name for the \l MenuItem icon. This will pick the icon
+    with the given name from the current theme.
 
-    \sa Action
+    \sa iconSource, Action::iconName
 */
 
 /*! \qmlsignal MenuItem::triggered()
@@ -281,13 +268,59 @@ void QtMenuText::setIconName(const QString &iconName)
     \sa triggered(), Action::trigger()
 */
 
+/*!
+    \qmlproperty string MenuItem::shortcut
+
+    Shorcut bound to the menu item.
+
+    \sa Action::shortcut
+*/
+
+/*!
+    \qmlproperty bool MenuItem::checkable
+
+    Whether the menu item can be checked, or toggled.
+
+    \sa checked
+*/
+
+/*!
+    \qmlproperty bool MenuItem::checked
+
+    If the menu item is checkable, this property reflects its checked state.
+
+    \sa checkable, Action::toggled()
+*/
+
 /*! \qmlproperty ExclusiveGroup MenuItem::exclusiveGroup
 
-    ...
+    If a menu item is checkable, an \l ExclusiveGroup can be attached to it.
+    All the menu items sharing the same exclusive group become mutually exclusive
+    selectable, meaning that only the last checked menu item will actually be checked.
 
     \sa checked, checkable
 */
 
+/*! \qmlsignal MenuItem::toggled(checked)
+
+    Emitted whenever a menu item's \c checked property changes.
+    This usually happens at the same time as \l triggered().
+
+    \sa checked, triggered(), Action::triggered(), Action::toggled()
+*/
+
+/*!
+    \qmlproperty Action MenuItem::action
+
+    The action bound to this menu item. Setting this property to an valid
+    \l Action will override all the menu item's properties except \l text.
+
+    In addition, the menu item \c triggered() and \c toggled() signals will not be emitted.
+    Instead, the action \c triggered() and \c toggled() signals will be.
+
+    \sa Action
+*/
+
 QtMenuItem::QtMenuItem(QObject *parent)
     : QtMenuText(parent), m_action(0)
 { }
@@ -509,7 +542,7 @@ void QtMenuItem::trigger()
     if (m_action)
         m_action->trigger();
     else
-        QtMenuText::trigger();
+        emit triggered();
 }
 
 QT_END_NAMESPACE
diff --git a/src/controls/qtmenuitem_p.h b/src/controls/qtmenuitem_p.h
index 0dd4f424..8644a490 100644
--- a/src/controls/qtmenuitem_p.h
+++ b/src/controls/qtmenuitem_p.h
@@ -110,16 +110,11 @@ class QtMenuText: public QtMenuBase
     Q_PROPERTY(QUrl iconSource READ iconSource WRITE setIconSource NOTIFY iconSourceChanged)
     Q_PROPERTY(QString iconName READ iconName WRITE setIconName NOTIFY iconNameChanged)
 
-    Q_PROPERTY(QVariant __icon READ iconVariant  NOTIFY __iconChanged)
-
-public Q_SLOTS:
-    virtual void trigger();
+    Q_PROPERTY(QVariant __icon READ iconVariant NOTIFY __iconChanged)
 
 Q_SIGNALS:
-    void triggered();
     void textChanged();
     void enabledChanged();
-
     void iconSourceChanged();
     void iconNameChanged();
 
@@ -165,10 +160,11 @@ public Q_SLOTS:
     void trigger();
 
 Q_SIGNALS:
+    void triggered();
+    void toggled(bool checked);
+
     void checkableChanged();
-    void toggled(bool);
     void exclusiveGroupChanged();
-
     void shortcutChanged();
     void actionChanged();