1 /****************************************************************************
3 ** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
4 ** All rights reserved.
5 ** Contact: Nokia Corporation (qt-info@nokia.com)
7 ** This file is part of the documentation of the Qt Toolkit.
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
17 ** Alternatively, this file may be used in accordance with the terms
18 ** and conditions contained in a signed written agreement between you
26 ****************************************************************************/
31 \brief Keyboard focus management and handling.
32 \ingroup frameworks-technologies
34 \keyword keyboard focus
36 Qt's widgets handle keyboard focus in the ways that have become
39 The basic issue is that the user's key strokes can be directed at any
40 of several windows on the screen, and any of several widgets inside
41 the intended window. When the user presses a key, they expect it to go
42 to the right place, and the software must try to meet this
43 expectation. The system must determine which application the key stroke
44 is directed at, which window within that application, and which widget
47 \section1 Focus Motion
49 The customs which have evolved for directing keyboard focus to a
50 particular widget are these:
54 \o The user presses \key Tab (or \key Shift+Tab).
55 \o The user clicks a widget.
56 \o The user presses a keyboard shortcut.
57 \o The user uses the mouse wheel.
58 \o The user moves the focus to a window, and the application must
59 determine which widget within the window should get the focus.
62 Each of these motion mechanisms is different, and different types of
63 widgets receive focus in only some of them. We'll cover each of them
66 \section2 Tab or Shift+Tab
68 Pressing \key Tab is by far the most common way to move focus
69 using the keyboard. (Sometimes in data-entry applications Enter
70 does the same as \key{Tab}; this can easily be achieved in Qt by
71 implementing an \l{The Event System}{event filter}.)
73 Pressing \key Tab, in all window systems in common use today,
74 moves the keyboard focus to the next widget in a circular
75 per-window list. \key Tab moves focus along the circular list in
76 one direction, \key Shift+Tab in the other. The order in which
77 \key Tab presses move from widget to widget is called the tab order.
79 You can customize the tab order using QWidget::setTabOrder(). (If
80 you don't, \key Tab generally moves focus in the order of widget
81 construction.) \l{Qt Designer} provides a means of visually
82 changing the tab order.
84 Since pressing \key Tab is so common, most widgets that can have focus
85 should support tab focus. The major exception is widgets that are
86 rarely used, and where there is some keyboard accelerator or error
87 handler that moves the focus.
89 For example, in a data entry dialog, there might be a field that
90 is only necessary in one per cent of all cases. In such a dialog,
91 \key Tab could skip this field, and the dialog could use one of
96 \o If the program can determine whether the field is needed, it can
97 move focus there when the user finishes entry and presses \gui OK, or when
98 the user presses Enter after finishing the other fields. Alternately,
99 include the field in the tab order but disable it. Enable it if it
100 becomes appropriate in view of what the user has set in the other
103 \o The label for the field can include a keyboard shortcut that moves
108 Another exception to \key Tab support is text-entry widgets that
109 must support the insertion of tabs; almost all text editors fall
110 into this class. Qt treats \key Ctrl+Tab as \key Tab and \key
111 Ctrl+Shift+Tab as \key Shift+Tab, and such widgets can
112 reimplement QWidget::event() and handle Tab before calling
113 QWidget::event() to get normal processing of all other keys.
114 However, since some systems use \key Ctrl+Tab for other purposes,
115 and many users aren't aware of \key Ctrl+Tab anyway, this isn't a
118 \section2 The User Clicks a Widget
120 This is perhaps even more common than pressing \key Tab on
121 computers with a mouse or other pointing device.
123 Clicking to move the focus is slightly more powerful than \key
124 Tab. While it moves the focus \e to a widget, for editor widgets
125 it also moves the text cursor (the widget's internal focus) to
126 the spot where the mouse is clicked.
128 Since it is so common and people are used to it, it's a good idea to
129 support it for most widgets. However, there is also an important
130 reason to avoid it: you may not want to remove focus from the widget
133 For example, in a word processor, when the user clicks the 'B' (bold)
134 tool button, what should happen to the keyboard focus? Should it
135 remain where it was, almost certainly in the editing widget, or should
136 it move to the 'B' button?
138 We advise supporting click-to-focus for widgets that support text
139 entry, and to avoid it for most widgets where a mouse click has a
140 different effect. (For buttons, we also recommend adding a keyboard
141 shortcut: QAbstractButton and its subclasses make this very easy.)
143 In Qt, only the QWidget::setFocusPolicy() function affects
146 \section2 The User Presses a Keyboard Shortcut
148 It's not unusual for keyboard shortcuts to move the focus. This
149 can happen implicitly by opening modal dialogs, but also
150 explicitly using focus accelerators such as those provided by
151 QLabel::setBuddy(), QGroupBox, and QTabBar.
153 We advise supporting shortcut focus for all widgets that the user
154 may want to jump to. For example, a tab dialog can have keyboard
155 shortcuts for each of its pages, so the user can press e.g. \key
156 Alt+P to step to the \underline{P}rinting page. It is easy to
157 overdo this: there are only a few keys, and it's also important
158 to provide keyboard shortcuts for commands. \key Alt+P is also
159 used for Paste, Play, Print, and Print Here in the \l{Standard
160 Accelerator Keys} list, for example.
162 \section2 The User Rotates the Mouse Wheel
164 On Microsoft Windows, mouse wheel usage is always handled by the
165 widget that has keyboard focus. On Mac OS X and X11, it's handled by
166 the widget that gets other mouse events.
168 The way Qt handles this platform difference is by letting widgets move
169 the keyboard focus when the wheel is used. With the right focus policy
170 on each widget, applications can work idiomatically correctly on
171 Windows, Mac OS X, and X11.
173 \section2 The User Moves the Focus to This Window
175 In this situation the application must determine which widget within
176 the window should receive the focus.
178 This can be simple: If the focus has been in this window before,
179 then the last widget to have focus should regain it. Qt does this
182 If focus has never been in this window before and you know where
183 focus should start out, call QWidget::setFocus() on the widget
184 which should receive focus before you call QWidget::show() it. If
185 you don't, Qt will pick a suitable widget.