← Back to branch summary

~oif-team/ubuntu/natty/qt4-x11/xi2.1

« back to all changes in this revision

Viewing changes to doc/src/focus.qdoc

  • Committer: Bazaar Package Importer
  • Author(s): Alessandro Ghersi
  • Date: 2009-11-02 18:30:08 UTC
  • mfrom: (1.2.2 upstream)
  • mto: (15.2.5 experimental)
  • mto: This revision was merged to the branch mainline in revision 88.
  • Revision ID: james.westby@ubuntu.com-20091102183008-b6a4gcs128mvfb3m
Tags: upstream-4.6.0~beta1
Import upstream version 4.6.0~beta1

Show diffs side-by-side

added added

removed removed

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