1// Copyright (C) 2016 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
6 \title Keyboard Focus in Widgets
7 \brief Keyboard focus management and handling.
8 \ingroup frameworks-technologies
10 \keyword keyboard focus
12 Qt's widgets handle keyboard focus in ways that have become
15 The basic issue is that the user's key strokes can be directed at any
16 of several windows on the screen, and any of several widgets inside
17 the intended window. When the user presses a key, they expect it to go
18 to the right place, and the software must try to meet this
19 expectation. The system must determine which application the key stroke
20 is directed at, which window within that application, and which widget
23 \section1 Focus Motion
25 The customs that have evolved for directing keyboard focus to a
26 particular widget are these:
30 \li The user presses \uicontrol Tab (or \uicontrol Shift+Tab).
31 \li The user clicks a widget.
32 \li The user presses a keyboard shortcut.
33 \li The user uses the mouse wheel.
34 \li The user moves the focus to a window, and the application must
35 determine which widget within the window should get the focus.
38 Each of these motion mechanisms is different, and different types of
39 widgets receive focus in only some of them. We'll cover each of them
42 \section2 Tab or Shift+Tab
44 Pressing \uicontrol Tab is by far the most common way to move focus
45 using the keyboard. (Sometimes in data-entry applications Enter
46 does the same as \uicontrol{Tab}; this can easily be achieved in Qt by
47 implementing an \l{The Event System}{event filter}.)
49 Pressing \uicontrol Tab, in all window systems in common use today,
50 moves the keyboard focus to the next widget in a circular
51 per-window list. \uicontrol Tab moves focus along the circular list in
52 one direction, \uicontrol Shift+Tab in the other. The order in which
53 \uicontrol Tab presses move from widget to widget is called the tab order.
55 You can customize the tab order using QWidget::setTabOrder(). (If
56 you don't, \uicontrol Tab generally moves focus in the order of widget
57 construction.) \QD provides a means of visually
58 changing the tab order.
60 Since pressing \uicontrol Tab is so common, most widgets that can have focus
61 should support tab focus. The major exception is widgets that are
62 rarely used, and where there is some keyboard accelerator or error
63 handler that moves the focus.
65 For example, in a data entry dialog, there might be a field that
66 is only necessary in one percent of all cases. In such a dialog,
67 \uicontrol Tab could skip this field, and the dialog could use one of
72 \li If the program can determine whether the field is needed, it can
73 move focus there when the user finishes entry and presses \uicontrol OK, or when
74 the user presses Enter after finishing the other fields. Alternately,
75 include the field in the tab order but disable it. Enable it if it
76 becomes appropriate in view of what the user has set in the other
79 \li The label for the field can include a keyboard shortcut that moves
84 Another exception to \uicontrol Tab support is text-entry widgets that
85 must support the insertion of tabs; almost all text editors fall
86 into this class. Qt treats \uicontrol Ctrl+Tab as \uicontrol Tab and \uicontrol
87 Ctrl+Shift+Tab as \uicontrol Shift+Tab, and such widgets can
88 reimplement QWidget::event() and handle Tab before calling
89 QWidget::event() to get normal processing of all other keys.
90 However, since some systems use \uicontrol Ctrl+Tab for other purposes,
91 and many users aren't aware of \uicontrol Ctrl+Tab anyway, this isn't a
94 \section2 The User Clicks a Widget
96 This is perhaps even more common than pressing \uicontrol Tab on
97 computers with a mouse or other pointing device.
99 Clicking to move the focus is slightly more powerful than \uicontrol
100 Tab. While it moves the focus \e to a widget, for editor widgets
101 it also moves the text cursor (the widget's internal focus) to
102 the spot where the mouse is clicked.
104 Since it is so common and people are used to it, it's a good idea to
105 support it for most widgets. However, there is also an important
106 reason to avoid it: you may not want to remove focus from the widget
109 For example, in a word processor, when the user clicks the 'B' (bold)
110 tool button, what should happen to the keyboard focus? Should it
111 remain where it was, almost certainly in the editing widget, or should
112 it move to the 'B' button?
114 We advise supporting click-to-focus for widgets that support text
115 entry, and to avoid it for most widgets where a mouse click has a
116 different effect. (For buttons, we also recommend adding a keyboard
117 shortcut: QAbstractButton and its subclasses make this very easy.)
119 In Qt, only the QWidget::setFocusPolicy() function affects
122 \section2 The User Presses a Keyboard Shortcut
124 It's not unusual for keyboard shortcuts to move the focus. This
125 can happen implicitly by opening modal dialogs, but also
126 explicitly using focus accelerators such as those provided by
127 QLabel::setBuddy(), QGroupBox, and QTabBar.
129 Your application can support shortcut focus for all widgets that the user
130 may want to jump to. For example, a tab dialog can have keyboard
131 shortcuts for each of its pages, so the user can press e.g. \uicontrol
132 Alt+P to step to the \underline{P}rinting page. Keep in mind that it's easy
133 to overdo this, as there are only a few keys, and also important to provide
134 keyboard shortcuts for commands. Refer to the design guidelines for the
135 platform you target, for example Microsoft's \l
136 {https://learn.microsoft.com/en-us/previous-versions/windows/desktop/dnacc/guidelines-for-keyboard-user-interface-design}
137 {guidelines for keyboard user interface design} or Apple's \l
138 {https://developer.apple.com/design/human-interface-guidelines/inputs/focus-and-selection/}
139 {focus and selection} guidelines.
141 \section2 The User Rotates the Mouse Wheel
143 On Microsoft Windows, mouse wheel usage is always handled by the
144 widget that has keyboard focus. On \macos and X11, it's handled by
145 the widget that gets other mouse events.
147 The way Qt handles this platform difference is by letting widgets move
148 the keyboard focus when the wheel is used. With the right focus policy
149 on each widget, applications can work idiomatically correctly on
150 Windows, \macos, and X11.
152 \section2 The User Moves the Focus to This Window
154 In this situation the application must determine which widget within
155 the window should receive the focus.
157 This can be simple: If the focus has been in this window before,
158 then the last widget to have focus should regain it. Qt does this
161 If focus has never been in this window before and you know where
162 focus should start out, call QWidget::setFocus() on the widget
163 which should receive focus before you call QWidget::show() it. If
164 you don't, Qt will pick a suitable widget.
1.10.0