Fixed the QML Focus document. Fixed snippets, images, and formatting.

Reviewed-by: David Boddie

17 files changed, 713 insertions, 219 deletions

diff --git a/doc/src/declarative/focus.qdoc b/doc/src/declarative/focus.qdoc
index 2e74fe0..ae72c3c 100644
--- a/doc/src/declarative/focus.qdoc
+++ b/doc/src/declarative/focus.qdoc
@@ -31,7 +31,7 @@
 \title Keyboard Focus in QML
 
 When a key is pressed or released, a key event is generated and delivered to the
-focused QML \l Item.  To facilitate the construction of reusable components
+focused QML \l Item. To facilitate the construction of reusable components
 and to address some of the cases unique to fluid user interfaces, the QML items add a
 \e scope based extension to Qt's traditional keyboard focus model.
 
@@ -42,27 +42,21 @@ and to address some of the cases unique to fluid user interfaces, the QML items
 When the user presses or releases a key, the following occurs:
 \list 1
 \o Qt receives the key action and generates a key event.
-\o If the Qt widget containing the \l QDeclarativeView has focus, the key event is delivered to it. Otherwise, regular Qt key handling continues.
-\o The key event is delivered by the scene to the QML \l Item with \e {active focus}.  If no \l Item has \e {active focus}, the key event is \l {QEvent::ignore()}{ignored} and regular Qt key handling continues.
-\o If the QML \l Item with \e {active focus} accepts the key event, propagation stops.  Otherwise the event is "bubbled up", by recursively passing it to each \l Item's parent until either the event is accepted, or the root \l Item is reached.
-
-If the \c {Rectangle} element in the following example has active focus and the \e A key is pressed,
-it will bubble up to its parent.  However, pressing the \e B key will bubble up to the root
-item and thus subsequently be \l {QEvent::ignore()}{ignored}.
-
-\code
-Item {
-    Item {
-        Keys.onPressed: {
-            if (event.key == Qt.Key_A) { 
-                console.log('Key A was pressed');
-                event.accepted = true;
-            }
-        }
-        Rectangle {}
-    }
-}
-\endcode
+\o If the Qt widget containing the \l QDeclarativeView has focus, the key event
+is delivered to it. Otherwise, regular Qt key handling continues.
+\o The key event is delivered by the scene to the QML \l Item with
+\e {active focus}. If no Item has active focus, the key event is
+\l {QEvent::ignore()}{ignored} and regular Qt key handling continues.
+\o If the QML Item with active focus accepts the key event, propagation
+stops. Otherwise the event is "bubbled up", by recursively passing it to each
+Item's parent until either the event is accepted, or the root Item is reached.
+
+If the \c {Rectangle} element in the following example has active focus and the \c A key is pressed,
+it will bubble up to its parent. However, pressing the \c B key will bubble up to the root
+item and thus subsequently be ignored.
+
+\snippet doc/src/snippets/declarative/focus/rectangle.qml simple key event
+\snippet doc/src/snippets/declarative/focus/rectangle.qml simple key event end
 
 \o If the root \l Item is reached, the key event is \l {QEvent::ignore()}{ignored} and regular Qt key handling continues.
 
@@ -72,232 +66,139 @@ See also the \l {Keys}{Keys attached property} and \l {KeyNavigation}{KeyNavigat
 
 \section1 Querying the Active Focus Item
 
-Whether or not an \l Item has \e {active focus} can be queried through the
-property \c {Item::activeFocus}.  For example, here we have a \l Text
-element whose text is determined by whether or not it has \e {active focus}.
+Whether or not an \l Item has active focus can be queried through the
+property \c {Item::activeFocus} property. For example, here we have a \l Text
+element whose text is determined by whether or not it has active focus.
 
-\code
-Text {
-    text: activeFocus ? "I have active focus!" : "I do not have active focus"
-}
-\endcode
+\snippet doc/src/snippets/declarative/focus/rectangle.qml active focus
 
 \section1 Acquiring Focus and Focus Scopes
 
-An \l Item requests focus by setting the \c {Item::focus} property to true.
-
-For very simple cases simply setting the \c {Item::focus} property is sometimes
-sufficient.  If we run the following example with the \l {QML Viewer}, we see that
-the \c {keyHandler} element has \e {active focus} and pressing the 'A', 'B'
-or 'C' keys modifies the text appropriately.
-
-\table
-\row
-\o \code
-    Rectangle {
-        color: "lightsteelblue"; width: 240; height: 25
-        Text { id: myText }
-        Item {
-            id: keyHandler
-            focus: true
-            Keys.onPressed: {
-                if (event.key == Qt.Key_A)
-                    myText.text = 'Key A was pressed'
-                else if (event.key == Qt.Key_B)
-                    myText.text = 'Key B was pressed'
-                else if (event.key == Qt.Key_C)
-                    myText.text = 'Key C was pressed'
-            }
-        }
-    }
-\endcode
-\o \image declarative-qmlfocus1.png
-\endtable
-
-However, were the above example to be used as a self-contained component, this
-simple use of the \c {Item::focus} property is no longer sufficient.  The left
-hand side of the following table shows what we would like to be able to write.
-Here we create two instances of our previously defined component, and set the
-second one to have focus.  The intention is that when the \e A, \e B, or \e C
-keys are pressed, the second of the two components receives the event and
+An \l Item requests focus by setting the \c focus property to \c true.
+
+For very simple cases simply setting the \c focus property is sometimes
+sufficient. If we run the following example with the \l {QML Viewer}, we see that
+the \c {keyHandler} element has active focus and pressing the \c A, \c B,
+or \c C keys modifies the text appropriately.
+
+\snippet doc/src/snippets/declarative/focus/basicwidget.qml focus true
+
+\image declarative-qmlfocus1.png
+
+However, were the above example to be used as a reusable or imported component,
+this simple use of the \c focus property is no longer sufficient.
+
+To demonstrate, we create two instances of our previously defined component and
+set the first one to have focus. The intention is that when the \c A, \c B, or
+\c C keys are pressed, the first of the two components receives the event and
 responds accordingly.
 
-\table
-\row
-\o \code
-Rectangle {
-    color: "red"; width: 240; height: 55
-    MyWidget {}
-    MyWidget { y: 30; focus: true }
-}
-\endcode
-\o \code
-Rectangle {
-    color: "red"; width: 240; height: 55
-    Rectangle {
-        color: "lightsteelblue"; width: 240; height: 25
-        Text { id: myText }
-        Item {
-            id: keyHandler
-            focus: true
-            Keys.onPressed: {
-                if (event.key == Qt.Key_A)
-                    myText.text = 'Key A was pressed'
-                else if (event.key == Qt.Key_B)
-                    myText.text = 'Key B was pressed'
-                else if (event.key == Qt.Key_C)
-                    myText.text = 'Key C was pressed'
-            }
-        }
-    }
-    Rectangle {
-        y: 30; focus: true
-        color: "lightsteelblue"; width: 240; height: 25
-        Text { id: myText }
-        Item {
-            id: keyHandler
-            focus: true
-            Keys.onPressed: {
-                if (event.key == Qt.Key_A)
-                    myText.text = 'Key A was pressed'
-                else if (event.key == Qt.Key_B)
-                    myText.text = 'Key B was pressed'
-                else if (event.key == Qt.Key_C)
-                    myText.text = 'Key C was pressed'
-            }
-        }
-    }
-}
-\endcode
-\endtable
-
-The right hand side of the example shows the expanded code - the equivalent QML
-without the use of the component \c {MyWidget}.  From this, the problem is
-evident - there are no less than three elements that have the \c {Item::focus}
-property set to true.  Ultimately only one element can have keyboard focus, and the
-system has to decide which on.  In this case the first appearance of the
-\c {Item::focus} property being set to true on line 4 is selected, and the value
-of \c {Item::focus} in the other two instances is reverted back to false.  This
-is exactly the opposite of what was wanted!
-
-This problem is fundamentally one of visibility.  The \c {MyWidget}
-components each set their \c {keyHandler} Items as focused as that is all they can
-do - they don't know how they are going to be used, but they do know that when
-they're in use their \c {keyHandler} element is what needs focus.  Likewise
-the code that uses the two \c {MyWidgets} sets the second \c {MyWidget} as
-focused. While it doesn't know exactly how the \c {MyWidget} is
-implemented, it knows that it wants the second one to be focused.  This allows us
-to achieve encapsulation, allowing each widget to focus on it's appropriate behaviour
-itself.
-
-To solve this problem - allowing components to care about what they know about
-and ignore everything else - the QML items introduce a concept known as a
-\e {focus scope}.  For existing Qt users, a \e {focus scope} is like an
-automatic focus proxy.  A \e {focus scope} is created using the \l FocusScope
-element.
-
-In the next example, a \l FocusScope is added to the component, and the visual
-result shown.
-
-\table
-\row
-\o \code
-FocusScope {
-    width: 240; height: 25
-    Rectangle {
-        color: "lightsteelblue"; width: 240; height: 25
-        Text { id: myText }
-        Item {
-            id: keyHandler
-            focus: true
-            Keys.onPressed: {
-                if (event.key == Qt.Key_A)
-                    myText.text = 'Key A was pressed'
-                else if (event.key == Qt.Key_B)
-                    myText.text = 'Key B was pressed'
-                else if (event.key == Qt.Key_C)
-                    myText.text = 'Key C was pressed'
-            }
-        }
-    }
-}
-\endcode
-\o \image declarative-qmlfocus2.png
-\endtable
+The code that imports and creates two MyWidget instances:
+\snippet doc/src/snippets/declarative/focus/widget.qml window
+
+The MyWidget code:
+\snippet doc/src/snippets/declarative/focus/mywidget.qml mywidget
+
+We would like to have the first MyWidget object to have the focus by setting its
+\c focus property to \c true. However, by running the code, we can confirm that
+the second widget receives the focus.
+
+\image declarative-qmlfocus2.png
+
+Looking at both \c MyWidget and \c window code, the problem is evident - there
+are three elements that set the \c focus property set to \c true. The two
+MyWidget sets the \c focus to \c true and the \c window component also sets the
+focus. Ultimately, only one element can have keyboard focus, and the system has
+to decide which element receives the focus. When the second MyWidget is created,
+it receives the focus because it is the last element to set its \c focus
+property to \c true.
+
+This problem is due to visibility. The \c MyWidget component would like to have
+the focus, but it cannot control the focus when it is imported or reused.
+Likewise, the \c window component does not have the ability to know if its
+imported components are requesting the focus.
+
+To solve this problem, the QML introduces a concept known as a \e {focus scope}.
+For existing Qt users, a focus scope is like an automatic focus proxy.
+A focus scope is created by declaring the \l FocusScope element.
+
+In the next example, a \l FocusScope element is added to the component, and the
+visual result shown.
+
+\snippet doc/src/snippets/declarative/focus/myfocusscopewidget.qml widget in focusscope
+
+\image declarative-qmlfocus3.png
+
 
 Conceptually \e {focus scopes} are quite simple.
 \list
-\o Within each \e {focus scope} one element may have \c {Item::focus} set to true.
-If more than one \l Item has the \c {Item::focus} property set, the first is selected
-and the others are unset, just like when there are no \e {focus scopes}.
-\o When a \e {focus scope} receives \e {active focus}, the contained element with
-\c {Item::focus} set (if any) also gets \e {active focus}.  If this element is
-also a \l FocusScope, the proxying behaviour continues.  Both the
-\e {focus scope} and the sub-focused item will have \c {Item::activeFocus} set.
+\o Within each focus scope one element may have \c {Item::focus} set to
+\c true. If more than one \l Item has the \c focus property set, the
+last element to set the \c focus will have the focus and the others are unset,
+similar to when there are no focus scopes.
+\o When a focus scope receives active focus, the contained element with
+\c focus set (if any) also gets the active focus. If this element is
+also a \l FocusScope, the proxying behavior continues. Both the
+focus scope and the sub-focused item will have \c activeFocus property set.
 \endlist
 
-So far the example has the second component statically selected.  It is trivial
+Note that, since the FocusScope element is not a visual element, the properties
+of its children need to be exposed to the parent item of the FocusScope. Layouts
+and positioning elements will use these visual and styling properties to create
+the layout. In our example, the \c Column element cannot display the two widgets
+properly because the FocusScope lacks visual properties of its own. The MyWidget
+component directly binds to the \c rectangle properties to allow the \c Column
+element to create the layout containing the children of the FocusScope.
+
+So far, the example has the second component statically selected. It is trivial
 now to extend this component to make it clickable, and add it to the original
-application.  We still set a one of the widgets as focused by default, but from
-then on clicking the either one gives it focus.
-
-\table
-\row
-\o \code
-Rectangle {
-    color: "red"; width: 240; height: 55
-    MyClickableWidget {}
-    MyClickableWidget { y: 30; focus: true }
-}
-\endcode
-\o \code
-FocusScope {
-    id: page; width: 240; height: 25
-    MyWidget { focus: true }
-    MouseArea { anchors.fill: parent; onClicked: { page.focus = true } }
-}
-\endcode
-\endtable
+application. We still set one of the widgets as focused by default.
+Now, clicking either MyClickableWidget gives it focus and the other widget
+loses the focus.
 
-\image declarative-qmlfocus3.png
+The code that imports and creates two MyClickableWidget instances:
+\snippet doc/src/snippets/declarative/focus/clickablewidget.qml clickable window
+
+The MyClickableWidget code:
+\snippet doc/src/snippets/declarative/focus/myclickablewidget.qml clickable in focusscope
 
-When a QML item explicitly relinquishes focus (by setting its
-\c {Item::focus} property to false while it has \e {active focus}), the system
-does not automatically select another element to receive focus.  That is, it
-is possible for there to be no currently \e {active focus}.
+\image declarative-qmlfocus4.png
 
-See the \l{declarative/keyinteraction/focus}{Keyboard Focus example} for a 
+When a QML \l Item explicitly relinquishes focus (by setting its
+\c focus property to \c false while it has active focus), the
+system does not automatically select another element to receive focus. That is,
+it is possible for there to be no currently active focus.
+
+See the \l{declarative/keyinteraction/focus}{Keyboard Focus example} for a
 demonstration of moving keyboard focus between multiple areas using FocusScope
 elements.
 
 \section1 Advanced uses of Focus Scopes
 
-Focus scopes allow focus to allocation to be easily partitioned.  Several
+Focus scopes allow focus to allocation to be easily partitioned. Several
 QML items use it to this effect.
 
-\l ListView, for example, is itself a focus scope.  Generally this isn't
+\l ListView, for example, is itself a focus scope. Generally this isn't
 noticeable as \l ListView doesn't usually have manually added visual children.
 By being a focus scope, \l ListView can focus the current list item without
-worrying about how that will effect the rest of the application.  This allows
-the current item delegate to react to key presses.
+worrying about how that will effect the rest of the application. This allows the
+current item delegate to react to key presses.
 
-This contrived example shows how this works.  Pressing the \c Return key will
+This contrived example shows how this works. Pressing the \c Return key will
 print the name of the current list item.
 
-\table
-\row
-\o \snippet doc/src/snippets/declarative/focusscopes.qml 0
-\o \image declarative-qmlfocus4.png
-\endtable
+\snippet doc/src/snippets/declarative/focus/advancedFocus.qml FocusScope delegate
+
+\image declarative-qmlfocus5.png
 
-While the example is simple, there's a lot going on behind the scenes.  Whenever
+While the example is simple, there are a lot going on behind the scenes. Whenever
 the current item changes, the \l ListView sets the delegate's \c {Item::focus}
-property.  As the \l ListView is a \e {focus scope}, this doesn't effect the
-rest of the application.  However, if the \l ListView itself has
-\e {active focus} this causes the delegate itself to receive \e {active focus}.
-In this example, the root element of the delegate is also a \e {focus scope},
-which in turn gives \e {active focus} to the \c {Text} element that
-actually performs the work of handling the \e {Return} key.
+property. As the \l ListView is a focus scope, this doesn't affect the
+rest of the application. However, if the \l ListView itself has
+active focus this causes the delegate itself to receive active focus.
+In this example, the root element of the delegate is also a focus scope,
+which in turn gives active focus to the \c {Text} element that actually performs
+the work of handling the \c {Return} key.
 
 All of the QML view classes, such as \l PathView and \l GridView, behave
 in a similar manner to allow key handling in their respective delegates.
diff --git a/doc/src/images/declarative-qmlfocus1.png b/doc/src/images/declarative-qmlfocus1.png
new file mode 100644
index 0000000..317b34b
--- /dev/null
+++ b/doc/src/images/declarative-qmlfocus1.png
diff --git a/doc/src/images/declarative-qmlfocus2.png b/doc/src/images/declarative-qmlfocus2.png
new file mode 100644
index 0000000..e3f9643
--- /dev/null
+++ b/doc/src/images/declarative-qmlfocus2.png
diff --git a/doc/src/images/declarative-qmlfocus3.png b/doc/src/images/declarative-qmlfocus3.png
new file mode 100644
index 0000000..a5897ce
--- /dev/null
+++ b/doc/src/images/declarative-qmlfocus3.png
diff --git a/doc/src/images/declarative-qmlfocus4.png b/doc/src/images/declarative-qmlfocus4.png
new file mode 100644
index 0000000..f2e64cd
--- /dev/null
+++ b/doc/src/images/declarative-qmlfocus4.png
diff --git a/doc/src/images/declarative-qmlfocus5.png b/doc/src/images/declarative-qmlfocus5.png
new file mode 100644
index 0000000..ec7307b
--- /dev/null
+++ b/doc/src/images/declarative-qmlfocus5.png
diff --git a/doc/src/snippets/declarative/focus/advancedFocus.qml b/doc/src/snippets/declarative/focus/advancedFocus.qml
new file mode 100644
index 0000000..274f54f
--- /dev/null
+++ b/doc/src/snippets/declarative/focus/advancedFocus.qml
@@ -0,0 +1,67 @@
+/****************************************************************************
+**
+** 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 FOO module 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 QtQuick 1.0
+
+//! [FocusScope delegate]
+Rectangle {
+    color: "lightsteelblue"; width: 100; height: 50
+
+    ListView {
+        anchors.fill: parent
+        focus: true
+
+        model: ListModel {
+            ListElement { name: "Bob" }
+            ListElement { name: "John" }
+            ListElement { name: "Michael" }
+        }
+
+        delegate: FocusScope {
+                width: childrenRect.width; height: childrenRect.height
+                x:childrenRect.x; y: childrenRect.y
+                TextInput {
+                    focus: true
+                    text: name
+                    Keys.onReturnPressed: console.log(name)
+                }
+        }
+    }
+}
+//! [FocusScope delegate]
diff --git a/doc/src/snippets/declarative/focus/basicwidget.qml b/doc/src/snippets/declarative/focus/basicwidget.qml
new file mode 100644
index 0000000..71e75ff
--- /dev/null
+++ b/doc/src/snippets/declarative/focus/basicwidget.qml
@@ -0,0 +1,59 @@
+/****************************************************************************
+**
+** 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 FOO module 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 QtQuick 1.0
+
+//! [focus true]
+Rectangle {
+    color: "lightsteelblue"; width: 240; height: 25
+    Text { id: myText }
+    Item {
+        id: keyHandler
+        focus: true
+        Keys.onPressed: {
+            if (event.key == Qt.Key_A)
+                myText.text = 'Key A was pressed'
+            else if (event.key == Qt.Key_B)
+                myText.text = 'Key B was pressed'
+            else if (event.key == Qt.Key_C)
+                myText.text = 'Key C was pressed'
+        }
+    }
+}
+//! [focus true]
diff --git a/doc/src/snippets/declarative/focus/clickablewidget.qml b/doc/src/snippets/declarative/focus/clickablewidget.qml
new file mode 100644
index 0000000..34b0d87
--- /dev/null
+++ b/doc/src/snippets/declarative/focus/clickablewidget.qml
@@ -0,0 +1,61 @@
+/****************************************************************************
+**
+** 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 FOO module 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 QtQuick 1.0
+
+//! [clickable window]
+Rectangle {
+    id: window
+
+    color: "white"; width: 240; height: 150
+
+    Column {
+        anchors.centerIn: parent; spacing: 15
+
+        MyClickableWidget {
+            focus: true             //set this MyWidget to receive the focus
+            color: "lightblue"
+        }
+        MyClickableWidget {
+            color: "palegreen"
+        }
+    }
+
+}
+//! [clickable window]
diff --git a/doc/src/snippets/declarative/focus/focusColumn.qml b/doc/src/snippets/declarative/focus/focusColumn.qml
new file mode 100644
index 0000000..eb59309
--- /dev/null
+++ b/doc/src/snippets/declarative/focus/focusColumn.qml
@@ -0,0 +1,25 @@
+import QtQuick 1.0
+
+Rectangle {
+    width: 200; height: 200
+
+  //  Column {
+        FocusScope {
+            x: rect1.x; y:rect1.y; width: rect1.width; height: rect1.height
+            Rectangle {id: rect1; width: 50; height: 50; focus:true
+                   color: focus ? "red":"blue"
+            }
+            Rectangle {id: rect2; width: 50; height: 50; focus:true
+                   color: focus ? "red":"blue"
+                    y: 75
+            }
+//        }
+/*
+        FocusScope {
+            x: rect2.x; y:rect2.y; width: rect2.width; height: rect2.height
+            Rectangle {id: rect2; width: 50; height: 50; color: "red"}
+       }
+*/
+    }
+
+}
diff --git a/doc/src/snippets/declarative/focus/focusscopewidget.qml b/doc/src/snippets/declarative/focus/focusscopewidget.qml
new file mode 100644
index 0000000..48e5750
--- /dev/null
+++ b/doc/src/snippets/declarative/focus/focusscopewidget.qml
@@ -0,0 +1,61 @@
+/****************************************************************************
+**
+** 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 FOO module 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 QtQuick 1.0
+
+//! [focusscope window]
+Rectangle {
+    id: window
+
+    color: "white"; width: 240; height: 150
+
+    Column {
+        anchors.centerIn: parent; spacing: 15
+
+        MyFocusScopeWidget {
+            focus: true             //set this MyWidget to receive the focus
+            color: "lightblue"
+        }
+        MyFocusScopeWidget {
+            color: "palegreen"
+        }
+    }
+
+}
+//! [focusscope window]
diff --git a/doc/src/snippets/declarative/focus/myclickablewidget.qml b/doc/src/snippets/declarative/focus/myclickablewidget.qml
new file mode 100644
index 0000000..3294662
--- /dev/null
+++ b/doc/src/snippets/declarative/focus/myclickablewidget.qml
@@ -0,0 +1,69 @@
+/****************************************************************************
+**
+** 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 FOO module 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 QtQuick 1.0
+
+//! [clickable in focusscope]
+FocusScope {
+
+    id: scope
+
+    //FocusScope needs to bind to visual properties of the children
+    property alias color: rectangle.color
+    x: rectangle.x; y: rectangle.y
+    width: rectangle.width; height: rectangle.height
+
+    Rectangle {
+        id: rectangle
+        anchors.centerIn: parent
+        color: "lightsteelblue"; width: 175; height: 25; radius: 10; smooth: true
+        Text { id: label; anchors.centerIn: parent }
+        focus: true
+        Keys.onPressed: {
+            if (event.key == Qt.Key_A)
+                label.text = 'Key A was pressed'
+            else if (event.key == Qt.Key_B)
+                label.text = 'Key B was pressed'
+            else if (event.key == Qt.Key_C)
+                label.text = 'Key C was pressed'
+        }
+    }
+    MouseArea { anchors.fill: parent; onClicked: { scope.focus = true } }
+}
+//! [clickable in focusscope]
diff --git a/doc/src/snippets/declarative/focus/myfocusscopewidget.qml b/doc/src/snippets/declarative/focus/myfocusscopewidget.qml
new file mode 100644
index 0000000..231ae3a
--- /dev/null
+++ b/doc/src/snippets/declarative/focus/myfocusscopewidget.qml
@@ -0,0 +1,66 @@
+/****************************************************************************
+**
+** 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 FOO module 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 QtQuick 1.0
+
+//! [widget in focusscope]
+FocusScope {
+
+    //FocusScope needs to bind to visual properties of the children
+    property alias color: rectangle.color
+    x: rectangle.x; y: rectangle.y
+    width: rectangle.width; height: rectangle.height
+
+    Rectangle {
+        id: rectangle
+        anchors.centerIn: parent
+        color: "lightsteelblue"; width: 175; height: 25; radius: 10; smooth: true
+        Text { id: label; anchors.centerIn: parent }
+        focus: true
+        Keys.onPressed: {
+            if (event.key == Qt.Key_A)
+                label.text = 'Key A was pressed'
+            else if (event.key == Qt.Key_B)
+                label.text = 'Key B was pressed'
+            else if (event.key == Qt.Key_C)
+                label.text = 'Key C was pressed'
+        }
+    }
+}
+//! [widget in focusscope]
diff --git a/doc/src/snippets/declarative/focus/mywidget.qml b/doc/src/snippets/declarative/focus/mywidget.qml
new file mode 100644
index 0000000..bea723d
--- /dev/null
+++ b/doc/src/snippets/declarative/focus/mywidget.qml
@@ -0,0 +1,58 @@
+/****************************************************************************
+**
+** 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 FOO module 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 QtQuick 1.0
+
+//! [mywidget]
+//MyWidget code
+Rectangle {
+    id: widget
+    color: "lightsteelblue"; width: 175; height: 25; radius: 10; smooth: true
+    Text { id: label; anchors.centerIn: parent}
+    focus: true
+    Keys.onPressed: {
+        if (event.key == Qt.Key_A)
+            label.text = 'Key A was pressed'
+        else if (event.key == Qt.Key_B)
+            label.text = 'Key B was pressed'
+        else if (event.key == Qt.Key_C)
+            label.text = 'Key C was pressed'
+    }
+}
+//! [mywidget]
diff --git a/doc/src/snippets/declarative/focus/qmldir b/doc/src/snippets/declarative/focus/qmldir
new file mode 100644
index 0000000..d0683b2
--- /dev/null
+++ b/doc/src/snippets/declarative/focus/qmldir
@@ -0,0 +1,4 @@
+MyWidget 1.0 mywidget.qml
+MyFocusScopeWidget 1.0 myfocusscopewidget.qml
+MyClickableWidget 1.0 myclickablewidget.qml
+
diff --git a/doc/src/snippets/declarative/focus/rectangle.qml b/doc/src/snippets/declarative/focus/rectangle.qml
new file mode 100644
index 0000000..01d1f0c
--- /dev/null
+++ b/doc/src/snippets/declarative/focus/rectangle.qml
@@ -0,0 +1,62 @@
+/****************************************************************************
+**
+** 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 FOO module 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 QtQuick 1.0
+
+//! [simple key event]
+Rectangle {
+    width: 100; height: 100
+    focus: true
+    Keys.onPressed: {
+        if (event.key == Qt.Key_A) {
+            console.log('Key A was pressed');
+            event.accepted = true;
+        }
+    }
+//! [simple key event]
+
+//! [active focus]
+    Text {
+        text: activeFocus ? "I have active focus!" : "I do not have active focus"
+    }
+//! [active focus]
+
+//! [simple key event end]
+}
+//! [simple key event end]
diff --git a/doc/src/snippets/declarative/focus/widget.qml b/doc/src/snippets/declarative/focus/widget.qml
new file mode 100644
index 0000000..cef34c5
--- /dev/null
+++ b/doc/src/snippets/declarative/focus/widget.qml
@@ -0,0 +1,61 @@
+/****************************************************************************
+**
+** 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 FOO module 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 QtQuick 1.0
+
+//! [window]
+
+//Window code that imports MyWidget
+Rectangle {
+    id: window
+    color: "white"; width: 240; height: 150
+
+    Column {
+        anchors.centerIn: parent; spacing: 15
+
+        MyWidget {
+            focus: true             //set this MyWidget to receive the focus
+            color: "lightblue"
+        }
+        MyWidget {
+            color: "palegreen"
+        }
+    }
+}
+//! [window]