doc/src/declarative/focus.qdoc

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
   4 ** All rights reserved.
   5 ** Contact: http://www.qt-project.org/
   6 **
   7 ** This file is part of the documentation of the Qt Toolkit.
   8 **
   9 ** $QT_BEGIN_LICENSE:FDL$
  10 ** GNU Free Documentation License
  11 ** Alternatively, this file may be used under the terms of the GNU Free
  12 ** Documentation License version 1.3 as published by the Free Software
  13 ** Foundation and appearing in the file included in the packaging of
  14 ** this file.
  15 **
  16 ** Other Usage
  17 ** Alternatively, this file may be used in accordance with the terms
  18 ** and conditions contained in a signed written agreement between you
  19 ** and Nokia.
  20 **
  21 **
  22 **
  23 **
  24 ** $QT_END_LICENSE$
  25 **
  26 ****************************************************************************/
  27
  28 /*!
  29 \target qmlfocus
  30 \page qdeclarativefocus.html
  31 \inqmlmodule QtQuick 2
  32 \ingroup qml-features
  33 \contentspage QML Features
  34 \previouspage {QML Text Handling and Validators}{Text Handling and Validators}
  35 \nextpage {QML Signal and Handler Event System}{Signal and Handler Event System}
  36
  37 \title Keyboard Focus in QML
  38
  39 When a key is pressed or released, a key event is generated and delivered to the
  40 focused QML \l Item. To facilitate the construction of reusable components
  41 and to address some of the cases unique to fluid user interfaces, the QML items add aged
  42 \i scope based extension to Qt's traditional keyboard focus model.
  43
  44 \tableofcontents
  45
  46 \section1 Key Handling Overview
  47
  48 When the user presses or releases a key, the following occurs:
  49 \list 1
  50 \o Qt receives the key action and generates a key event.
  51 \o If the Qt widget containing the \l QDeclarativeView has focus, the key event
  52 is delivered to it. Otherwise, regular Qt key handling continues.
  53 \o The key event is delivered by the scene to the QML \l Item with
  54 \i {active focus}. If no Item has active focus, the key event is
  55 \l {QEvent::ignore()}{ignored} and regular Qt key handling continues.
  56 \o If the QML Item with active focus accepts the key event, propagation
  57 stops. Otherwise the event is "bubbled up", by recursively passing it to each
  58 Item's parent until either the event is accepted, or the root Item is reached.
  59
  60 If the \c {Rectangle} element in the following example has active focus and the \c A key is pressed,
  61 it will bubble up to its parent. However, pressing the \c B key will bubble up to the root
  62 item and thus subsequently be ignored.
  63
  64 \snippet doc/src/snippets/declarative/focus/rectangle.qml simple key event
  65 \snippet doc/src/snippets/declarative/focus/rectangle.qml simple key event end
  66
  67 \o If the root \l Item is reached, the key event is \l {QEvent::ignore()}{ignored} and regular Qt key handling continues.
  68
  69 \endlist
  70
  71 See also the \l {Keys}{Keys attached property} and \l {KeyNavigation}{KeyNavigation attached property}.
  72
  73 \section1 Querying the Active Focus Item
  74
  75 Whether or not an \l Item has active focus can be queried through the
  76 property \c {Item::activeFocus} property. For example, here we have a \l Text
  77 element whose text is determined by whether or not it has active focus.
  78
  79 \snippet doc/src/snippets/declarative/focus/rectangle.qml active focus
  80
  81 \section1 Acquiring Focus and Focus Scopes
  82
  83 An \l Item requests focus by setting the \c focus property to \c true.
  84
  85 For very simple cases simply setting the \c focus property is sometimes
  86 sufficient. If we run the following example with the \l {QML Viewer}, we see that
  87 the \c {keyHandler} element has active focus and pressing the \c A, \c B,
  88 or \c C keys modifies the text appropriately.
  89
  90 \snippet doc/src/snippets/declarative/focus/basicwidget.qml focus true
  91
  92 \image declarative-qmlfocus1.png
  93
  94 However, were the above example to be used as a reusable or imported component,
  95 this simple use of the \c focus property is no longer sufficient.
  96
  97 To demonstrate, we create two instances of our previously defined component and
  98 set the first one to have focus. The intention is that when the \c A, \c B, or
  99 \c C keys are pressed, the first of the two components receives the event and
 100 responds accordingly.
 101
 102 The code that imports and creates two MyWidget instances:
 103 \snippet doc/src/snippets/declarative/focus/widget.qml window
 104
 105 The MyWidget code:
 106 \snippet doc/src/snippets/declarative/focus/MyWidget.qml mywidget
 107
 108 We would like to have the first MyWidget object to have the focus by setting its
 109 \c focus property to \c true. However, by running the code, we can confirm that
 110 the second widget receives the focus.
 111
 112 \image declarative-qmlfocus2.png
 113
 114 Looking at both \c MyWidget and \c window code, the problem is evident - there
 115 are three elements that set the \c focus property set to \c true. The two
 116 MyWidget sets the \c focus to \c true and the \c window component also sets the
 117 focus. Ultimately, only one element can have keyboard focus, and the system has
 118 to decide which element receives the focus. When the second MyWidget is created,
 119 it receives the focus because it is the last element to set its \c focus
 120 property to \c true.
 121
 122 This problem is due to visibility. The \c MyWidget component would like to have
 123 the focus, but it cannot control the focus when it is imported or reused.
 124 Likewise, the \c window component does not have the ability to know if its
 125 imported components are requesting the focus.
 126
 127 To solve this problem, the QML introduces a concept known as a \i {focus scope}.
 128 For existing Qt users, a focus scope is like an automatic focus proxy.
 129 A focus scope is created by declaring the \l FocusScope element.
 130
 131 In the next example, a \l FocusScope element is added to the component, and the
 132 visual result shown.
 133
 134 \snippet doc/src/snippets/declarative/focus/myfocusscopewidget.qml widget in focusscope
 135
 136 \image declarative-qmlfocus3.png
 137
 138
 139 Conceptually \i {focus scopes} are quite simple.
 140 \list
 141 \o Within each focus scope one element may have \c {Item::focus} set to
 142 \c true. If more than one \l Item has the \c focus property set, the
 143 last element to set the \c focus will have the focus and the others are unset,
 144 similar to when there are no focus scopes.
 145 \o When a focus scope receives active focus, the contained element with
 146 \c focus set (if any) also gets the active focus. If this element is
 147 also a \l FocusScope, the proxying behavior continues. Both the
 148 focus scope and the sub-focused item will have \c activeFocus property set.
 149 \endlist
 150
 151 Note that, since the FocusScope element is not a visual element, the properties
 152 of its children need to be exposed to the parent item of the FocusScope. Layouts
 153 and positioning elements will use these visual and styling properties to create
 154 the layout. In our example, the \c Column element cannot display the two widgets
 155 properly because the FocusScope lacks visual properties of its own. The MyWidget
 156 component directly binds to the \c rectangle properties to allow the \c Column
 157 element to create the layout containing the children of the FocusScope.
 158
 159 So far, the example has the second component statically selected. It is trivial
 160 now to extend this component to make it clickable, and add it to the original
 161 application. We still set one of the widgets as focused by default.
 162 Now, clicking either MyClickableWidget gives it focus and the other widget
 163 loses the focus.
 164
 165 The code that imports and creates two MyClickableWidget instances:
 166 \snippet doc/src/snippets/declarative/focus/clickablewidget.qml clickable window
 167
 168 The MyClickableWidget code:
 169 \snippet doc/src/snippets/declarative/focus/MyClickableWidget.qml clickable in focusscope
 170
 171 \image declarative-qmlfocus4.png
 172
 173 When a QML \l Item explicitly relinquishes focus (by setting its
 174 \c focus property to \c false while it has active focus), the
 175 system does not automatically select another element to receive focus. That is,
 176 it is possible for there to be no currently active focus.
 177
 178 See the \l{declarative/keyinteraction/focus}{Keyboard Focus example} for a
 179 demonstration of moving keyboard focus between multiple areas using FocusScope
 180 elements.
 181
 182 \section1 Advanced uses of Focus Scopes
 183
 184 Focus scopes allow focus to allocation to be easily partitioned. Several
 185 QML items use it to this effect.
 186
 187 \l ListView, for example, is itself a focus scope. Generally this isn't
 188 noticeable as \l ListView doesn't usually have manually added visual children.
 189 By being a focus scope, \l ListView can focus the current list item without
 190 worrying about how that will effect the rest of the application. This allows the
 191 current item delegate to react to key presses.
 192
 193 This contrived example shows how this works. Pressing the \c Return key will
 194 print the name of the current list item.
 195
 196 \snippet doc/src/snippets/declarative/focus/advancedFocus.qml FocusScope delegate
 197
 198 \image declarative-qmlfocus5.png
 199
 200 While the example is simple, there are a lot going on behind the scenes. Whenever
 201 the current item changes, the \l ListView sets the delegate's \c {Item::focus}
 202 property. As the \l ListView is a focus scope, this doesn't affect the
 203 rest of the application. However, if the \l ListView itself has
 204 active focus this causes the delegate itself to receive active focus.
 205 In this example, the root element of the delegate is also a focus scope,
 206 which in turn gives active focus to the \c {Text} element that actually performs
 207 the work of handling the \c {Return} key.
 208
 209 All of the QML view classes, such as \l PathView and \l GridView, behave
 210 in a similar manner to allow key handling in their respective delegates.
 211 */