1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
|
/****************************************************************************
**
** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
** Contact: Nokia Corporation (qt-info@nokia.com)
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:LGPL$
** No Commercial Usage
** This file contains pre-release code and may not be distributed.
** You may use this file in accordance with the terms and conditions
** contained in the Technology Preview License Agreement accompanying
** this package.
**
** GNU Lesser General Public License Usage
** Alternatively, this file may be used under the terms of the GNU Lesser
** General Public License version 2.1 as published by the Free Software
** Foundation and appearing in the file LICENSE.LGPL included in the
** packaging of this file. Please review the following information to
** ensure the GNU Lesser General Public License version 2.1 requirements
** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
**
** In addition, as a special exception, Nokia gives you certain
** additional rights. These rights are described in the Nokia Qt LGPL
** Exception version 1.1, included in the file LGPL_EXCEPTION.txt in this
** package.
**
** If you have questions regarding the use of this file, please contact
** Nokia at qt-info@nokia.com.
**
**
**
**
**
**
**
**
** $QT_END_LICENSE$
**
****************************************************************************/
/****************************************************************************
**
** Documentation of focus handling in Qt.
**
** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
** Contact: Nokia Corporation (qt-info@nokia.com)
**
** This file is part of the Qt GUI Toolkit.
** EDITIONS: FREE, PROFESSIONAL, ENTERPRISE
**
****************************************************************************/
/*!
\page focus.html
\title Keyboard Focus
\ingroup architecture
\ingroup gui-programming
\brief An overview of the keyboard focus management and handling.
\keyword keyboard focus
Qt's widgets handle keyboard focus in the ways that have become
customary in GUIs.
The basic issue is that the user's key strokes can be directed at any
of several windows on the screen, and any of several widgets inside
the intended window. When the user presses a key, they expect it to go
to the right place, and the software must try to meet this
expectation. The system must determine which application the key stroke
is directed at, which window within that application, and which widget
within that window.
\section1 Focus Motion
The customs which have evolved for directing keyboard focus to a
particular widget are these:
\list 1
\o The user presses \key Tab (or \key Shift+Tab).
\o The user clicks a widget.
\o The user presses a keyboard shortcut.
\o The user uses the mouse wheel.
\o The user moves the focus to a window, and the application must
determine which widget within the window should get the focus.
\endlist
Each of these motion mechanisms is different, and different types of
widgets receive focus in only some of them. We'll cover each of them
in turn.
\section2 Tab or Shift+Tab
Pressing \key Tab is by far the most common way to move focus
using the keyboard. (Sometimes in data-entry applications Enter
does the same as \key{Tab}; this can easily be achieved in Qt by
implementing an \l{Events and Event Filters}{event filter}.)
Pressing \key Tab, in all window systems in common use today,
moves the keyboard focus to the next widget in a circular
per-window list. \key Tab moves focus along the circular list in
one direction, \key Shift+Tab in the other. The order in which
\key Tab presses move from widget to widget is called the tab order.
You can customize the tab order using QWidget::setTabOrder(). (If
you don't, \key Tab generally moves focus in the order of widget
construction.) \l{Qt Designer} provides a means of visually
changing the tab order.
Since pressing \key Tab is so common, most widgets that can have focus
should support tab focus. The major exception is widgets that are
rarely used, and where there is some keyboard accelerator or error
handler that moves the focus.
For example, in a data entry dialog, there might be a field that
is only necessary in one per cent of all cases. In such a dialog,
\key Tab could skip this field, and the dialog could use one of
these mechanisms:
\list 1
\o If the program can determine whether the field is needed, it can
move focus there when the user finishes entry and presses \gui OK, or when
the user presses Enter after finishing the other fields. Alternately,
include the field in the tab order but disable it. Enable it if it
becomes appropriate in view of what the user has set in the other
fields.
\o The label for the field can include a keyboard shortcut that moves
focus to this field.
\endlist
Another exception to \key Tab support is text-entry widgets that
must support the insertion of tabs; almost all text editors fall
into this class. Qt treats \key Ctrl+Tab as \key Tab and \key
Ctrl+Shift+Tab as \key Shift+Tab, and such widgets can
reimplement QWidget::event() and handle Tab before calling
QWidget::event() to get normal processing of all other keys.
However, since some systems use \key Ctrl+Tab for other purposes,
and many users aren't aware of \key Ctrl+Tab anyway, this isn't a
complete solution.
\section2 The User Clicks a Widget
This is perhaps even more common than pressing \key Tab on
computers with a mouse or other pointing device.
Clicking to move the focus is slightly more powerful than \key
Tab. While it moves the focus \e to a widget, for editor widgets
it also moves the text cursor (the widget's internal focus) to
the spot where the mouse is clicked.
Since it is so common and people are used to it, it's a good idea to
support it for most widgets. However, there is also an important
reason to avoid it: you may not want to remove focus from the widget
where it was.
For example, in a word processor, when the user clicks the 'B' (bold)
tool button, what should happen to the keyboard focus? Should it
remain where it was, almost certainly in the editing widget, or should
it move to the 'B' button?
We advise supporting click-to-focus for widgets that support text
entry, and to avoid it for most widgets where a mouse click has a
different effect. (For buttons, we also recommend adding a keyboard
shortcut: QAbstractButton and its subclasses make this very easy.)
In Qt, only the QWidget::setFocusPolicy() function affects
click-to-focus.
\section2 The User Presses a Keyboard Shortcut
It's not unusual for keyboard shortcuts to move the focus. This
can happen implicitly by opening modal dialogs, but also
explicitly using focus accelerators such as those provided by
QLabel::setBuddy(), QGroupBox, and QTabBar.
We advise supporting shortcut focus for all widgets that the user
may want to jump to. For example, a tab dialog can have keyboard
shortcuts for each of its pages, so the user can press e.g. \key
Alt+P to step to the \underline{P}rinting page. It is easy to
overdo this: there are only a few keys, and it's also important
to provide keyboard shortcuts for commands. \key Alt+P is also
used for Paste, Play, Print, and Print Here in the \l{Standard
Accelerator Keys} list, for example.
\section2 The User Rotates the Mouse Wheel
On Microsoft Windows, mouse wheel usage is always handled by the
widget that has keyboard focus. On Mac OS X and X11, it's handled by
the widget that gets other mouse events.
The way Qt handles this platform difference is by letting widgets move
the keyboard focus when the wheel is used. With the right focus policy
on each widget, applications can work idiomatically correctly on
Windows, Mac OS X, and X11.
\section2 The User Moves the Focus to This Window
In this situation the application must determine which widget within
the window should receive the focus.
This can be simple: If the focus has been in this window before,
then the last widget to have focus should regain it. Qt does this
automatically.
If focus has never been in this window before and you know where
focus should start out, call QWidget::setFocus() on the widget
which should receive focus before you call QWidget::show() it. If
you don't, Qt will pick a suitable widget.
*/
|
