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