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