Doc: More work on QML reference documentation.

Reviewed-by: Trust Me

4 files changed, 159 insertions, 30 deletions

diff --git a/doc/src/snippets/declarative/keys/keys-handler.qml b/doc/src/snippets/declarative/keys/keys-handler.qml
new file mode 100644
index 0000000..9e3a3b4
--- /dev/null
+++ b/doc/src/snippets/declarative/keys/keys-handler.qml
@@ -0,0 +1,60 @@
+/****************************************************************************
+**
+** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $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$
+**
+****************************************************************************/
+
+import Qt 4.7
+
+Item {
+    width: 400; height: 400
+
+//! [key item]
+Item {
+    anchors.fill: parent
+    focus: true
+    Keys.onLeftPressed: console.log("move left")
+}
+//! [key item]
+
+Text {
+    anchors.fill: parent
+    text: "Press a cursor key"
+    horizontalAlignment: Text.AlignHCenter
+    verticalAlignment: Text.AlignVCenter
+}
+}
diff --git a/doc/src/snippets/declarative/keys/keys-pressed.qml b/doc/src/snippets/declarative/keys/keys-pressed.qml
new file mode 100644
index 0000000..523c95b
--- /dev/null
+++ b/doc/src/snippets/declarative/keys/keys-pressed.qml
@@ -0,0 +1,65 @@
+/****************************************************************************
+**
+** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $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$
+**
+****************************************************************************/
+
+import Qt 4.7
+
+Item {
+    width: 400; height: 400
+
+//! [key item]
+Item {
+    anchors.fill: parent
+    focus: true
+    Keys.onPressed: {
+        if (event.key == Qt.Key_Left) {
+            console.log("move left");
+            event.accepted = true;
+        }
+    }
+}
+//! [key item]
+
+Text {
+    anchors.fill: parent
+    text: "Press a cursor key"
+    horizontalAlignment: Text.AlignHCenter
+    verticalAlignment: Text.AlignVCenter
+}
+}
diff --git a/src/declarative/graphicsitems/qdeclarativeevents.cpp b/src/declarative/graphicsitems/qdeclarativeevents.cpp
index dbfb3fb..61fd562 100644
--- a/src/declarative/graphicsitems/qdeclarativeevents.cpp
+++ b/src/declarative/graphicsitems/qdeclarativeevents.cpp
@@ -113,11 +113,13 @@ Item {
     \qmlclass MouseEvent QDeclarativeMouseEvent
     \since 4.7
     \ingroup qml-event-elements
-    
+
     \brief The MouseEvent object provides information about a mouse event.
 
-    The position of the mouse can be found via the x and y properties.
-    The button that caused the event is available via the button property.
+    The position of the mouse can be found via the \l x and \l y properties.
+    The button that caused the event is available via the \l button property.
+
+    \sa MouseArea
 */
 
 /*!
@@ -129,7 +131,7 @@ Item {
     \qmlproperty int MouseEvent::x
     \qmlproperty int MouseEvent::y
 
-    These properties hold the position of the mouse event.
+    These properties hold the coordinates of the position supplied by the mouse event.
 */
 
 
@@ -186,7 +188,7 @@ Item {
     It contains a bitwise combination of:
     \list
     \o Qt.NoModifier - No modifier key is pressed.
-    \o Qt.ShiftModifier	- A Shift key on the keyboard is pressed.
+    \o Qt.ShiftModifier - A Shift key on the keyboard is pressed.
     \o Qt.ControlModifier - A Ctrl key on the keyboard is pressed.
     \o Qt.AltModifier - An Alt key on the keyboard is pressed.
     \o Qt.MetaModifier - A Meta key on the keyboard is pressed.
@@ -195,9 +197,12 @@ Item {
 
     For example, to react to a Shift key + Left mouse button click:
     \qml
-MouseArea {
-    onClicked: { if (mouse.button == Qt.LeftButton && mouse.modifiers & Qt.ShiftModifier) doSomething(); }
-}
+    MouseArea {
+        onClicked: {
+            if (mouse.button == Qt.LeftButton && mouse.modifiers & Qt.ShiftModifier)
+                doSomething();
+        }
+    }
     \endqml
 */
 
diff --git a/src/declarative/graphicsitems/qdeclarativeitem.cpp b/src/declarative/graphicsitems/qdeclarativeitem.cpp
index bd2d52c..e2123cf 100644
--- a/src/declarative/graphicsitems/qdeclarativeitem.cpp
+++ b/src/declarative/graphicsitems/qdeclarativeitem.cpp
@@ -728,41 +728,39 @@ void QDeclarativeKeyNavigationAttached::keyReleased(QKeyEvent *event, bool post)
     \since 4.7
     \brief The Keys attached property provides key handling to Items.
 
-    All visual primitives support key handling via the \e Keys
-    attached property.  Keys can be handled via the \e onPressed
-    and \e onReleased signal properties.
+    All visual primitives support key handling via the Keys
+    attached property.  Keys can be handled via the onPressed
+    and onReleased signal properties.
 
     The signal properties have a \l KeyEvent parameter, named
     \e event which contains details of the event.  If a key is
     handled \e event.accepted should be set to true to prevent the
     event from propagating up the item hierarchy.
 
-    \code
-    Item {
-        focus: true
-        Keys.onPressed: {
-            if (event.key == Qt.Key_Left) {
-                console.log("move left");
-                event.accepted = true;
-            }
-        }
-    }
-    \endcode
+    \section1 Example Usage
+
+    The following example shows how the general onPressed handler can
+    be used to test for a certain key; in this case, the left cursor
+    key:
+
+    \snippet doc/src/snippets/declarative/keys/keys-pressed.qml key item
 
     Some keys may alternatively be handled via specific signal properties,
     for example \e onSelectPressed.  These handlers automatically set
     \e event.accepted to true.
 
-    \code
-    Item {
-        focus: true
-        Keys.onLeftPressed: console.log("move left")
-    }
-    \endcode
+    \snippet doc/src/snippets/declarative/keys/keys-handler.qml key item
+
+    See \l{Qt::Key}{Qt.Key} for the list of keyboard codes.
 
-    See \l {Qt::Key}{Qt.Key} for the list of keyboard codes.
+    \section1 Key Handling Priorities
 
-    If priority is Keys.BeforeItem (default) the order of key event processing is:
+    The Keys attached property can be configured to handle key events
+    before or after the item it is attached to. This makes it possible
+    to intercept events in order to override an item's default behavior,
+    or act as a fallback for keys not handled by the item.
+
+    If \l priority is Keys.BeforeItem (default) the order of key event processing is:
 
     \list 1
     \o Items specified in \c forwardTo
@@ -773,6 +771,7 @@ void QDeclarativeKeyNavigationAttached::keyReleased(QKeyEvent *event, bool post)
     \endlist
 
     If priority is Keys.AfterItem the order of key event processing is:
+
     \list 1
     \o Item specific key handling, e.g. TextInput key handling
     \o Items specified in \c forwardTo