From b604dc0b77a3a4b9001d682925006a3438e00cb7 Mon Sep 17 00:00:00 2001
From: Bea Lam <bea.lam@nokia.com>
Date: Thu, 25 Nov 2010 10:56:20 +1000
Subject: Move KeyNavigation example to snippets, plus some doc rewording

---
 doc/src/snippets/declarative/keynavigation.qml     | 45 ++++++++++++++
 src/declarative/graphicsitems/qdeclarativeitem.cpp | 72 +++++++---------------
 2 files changed, 66 insertions(+), 51 deletions(-)
 create mode 100644 doc/src/snippets/declarative/keynavigation.qml

diff --git a/doc/src/snippets/declarative/keynavigation.qml b/doc/src/snippets/declarative/keynavigation.qml
new file mode 100644
index 0000000..d72bb3a
--- /dev/null
+++ b/doc/src/snippets/declarative/keynavigation.qml
@@ -0,0 +1,45 @@
+//![0]
+import QtQuick 1.0
+
+Grid {
+    width: 100; height: 100
+    columns: 2
+
+    Rectangle {
+        id: topLeft
+        width: 50; height: 50
+        color: focus ? "red" : "lightgray"
+        focus: true
+
+        KeyNavigation.right: topRight
+        KeyNavigation.down: bottomLeft
+    }
+
+    Rectangle {
+        id: topRight
+        width: 50; height: 50
+        color: focus ? "red" : "lightgray"
+
+        KeyNavigation.left: topLeft
+        KeyNavigation.down: bottomRight
+    }
+
+    Rectangle {
+        id: bottomLeft
+        width: 50; height: 50
+        color: focus ? "red" : "lightgray"
+
+        KeyNavigation.right: bottomRight
+        KeyNavigation.up: topLeft
+    }
+
+    Rectangle {
+        id: bottomRight
+        width: 50; height: 50
+        color: focus ? "red" : "lightgray"
+
+        KeyNavigation.left: bottomLeft
+        KeyNavigation.up: topRight
+    }
+}
+//![0]
diff --git a/src/declarative/graphicsitems/qdeclarativeitem.cpp b/src/declarative/graphicsitems/qdeclarativeitem.cpp
index e0df751..9d6fe12 100644
--- a/src/declarative/graphicsitems/qdeclarativeitem.cpp
+++ b/src/declarative/graphicsitems/qdeclarativeitem.cpp
@@ -421,58 +421,28 @@ void QDeclarativeItemKeyFilter::componentComplete()
     \since 4.7
     \brief The KeyNavigation attached property supports key navigation by arrow keys.
 
-    It is common in key-based UIs to use arrow keys to navigate
-    between focused items.  The KeyNavigation property provides a
-    convenient way of specifying which item will gain focus
-    when an arrow key is pressed.  The following example provides
-    key navigation for a 2x2 grid of items.
-
-    \code
-    Grid {
-        columns: 2
-        width: 100; height: 100
-        Rectangle {
-            id: item1
-            focus: true
-            width: 50; height: 50
-            color: focus ? "red" : "lightgray"
-            KeyNavigation.right: item2
-            KeyNavigation.down: item3
-        }
-        Rectangle {
-            id: item2
-            width: 50; height: 50
-            color: focus ? "red" : "lightgray"
-            KeyNavigation.left: item1
-            KeyNavigation.down: item4
-        }
-        Rectangle {
-            id: item3
-            width: 50; height: 50
-            color: focus ? "red" : "lightgray"
-            KeyNavigation.right: item4
-            KeyNavigation.up: item1
-        }
-        Rectangle {
-            id: item4
-            width: 50; height: 50
-            color: focus ? "red" : "lightgray"
-            KeyNavigation.left: item3
-            KeyNavigation.up: item2
-        }
-    }
-    \endcode
+    Key-based user interfaces commonly allow the use of arrow keys to navigate between
+    focusable items.  The KeyNavigation attached property enables this behavior by providing a
+    convenient way to specify the item that should gain focus when an arrow or tab key is pressed.
+
+    The following example provides key navigation for a 2x2 grid of items:
 
-    By default KeyNavigation receives key events after the item it is attached to.
-    If the item accepts an arrow key event, the KeyNavigation
-    attached property will not receive an event for that key.  Setting the
-    \l priority property to KeyNavigation.BeforeItem allows handling
-    of the key events before normal item processing.
+    \snippet doc/src/snippets/declarative/keynavigation.qml 0
 
-    If an item has been set for a direction and the KeyNavigation
-    attached property receives the corresponding
-    key press and release events, the events will be accepted by
-    KeyNavigation and will not propagate any further.
+    The top-left item initially receives focus by setting \l {Item::}{focus} to
+    \c true. When an arrow key is pressed, the focus will move to the
+    appropriate item, as defined by the value that has been set for
+    the KeyNavigation \l left, \l right, \l up or \l down properties.
+
+    Note that if a KeyNavigation attached property receives the key press and release
+    events for a requested arrow or tab key, the event is accepted and does not
+    propagate any further.
+
+    By default, KeyNavigation receives key events after the item to which it is attached.
+    If the item accepts the key event, the KeyNavigation attached property will not
+    receive an event for that key.  Setting the \l priority property to
+    \c KeyNavigation.BeforeItem allows the event to be used for key navigation
+    before the item, rather than after.
 
     \sa {Keys}{Keys attached property}
 */
@@ -599,7 +569,7 @@ void QDeclarativeKeyNavigationAttached::setBacktab(QDeclarativeItem *i)
 
     \list
     \o KeyNavigation.BeforeItem - process the key events before normal
-    item key processing.  If the event is accepted it will not
+    item key processing.  If the event is used for key navigation, it will be accepted and will not
     be passed on to the item.
     \o KeyNavigation.AfterItem (default) - process the key events after normal item key
     handling.  If the item accepts the key event it will not be
-- 
cgit v0.12