You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
205 lines
8.1 KiB
205 lines
8.1 KiB
/****************************************************************************
|
|
**
|
|
** Documentation of focus handling in Qt
|
|
**
|
|
** Copyright (C) 1992-2008 Trolltech ASA. All rights reserved.
|
|
**
|
|
** This file is part of the TQt GUI Toolkit.
|
|
**
|
|
** This file may be used under the terms of the GNU General
|
|
** Public License versions 2.0 or 3.0 as published by the Free
|
|
** Software Foundation and appearing in the files LICENSE.GPL2
|
|
** and LICENSE.GPL3 included in the packaging of this file.
|
|
** Alternatively you may (at your option) use any later version
|
|
** of the GNU General Public License if such license has been
|
|
** publicly approved by Trolltech ASA (or its successors, if any)
|
|
** and the KDE Free TQt Foundation.
|
|
**
|
|
** Please review the following information to ensure GNU General
|
|
** Public Licensing requirements will be met:
|
|
** http://trolltech.com/products/qt/licenses/licensing/opensource/.
|
|
** If you are unsure which license is appropriate for your use, please
|
|
** review the following information:
|
|
** http://trolltech.com/products/qt/licenses/licensing/licensingoverview
|
|
** or contact the sales department at sales@trolltech.com.
|
|
**
|
|
** This file may be used under the terms of the Q Public License as
|
|
** defined by Trolltech ASA and appearing in the file LICENSE.QPL
|
|
** included in the packaging of this file. Licensees holding valid Qt
|
|
** Commercial licenses may use this file in accordance with the Qt
|
|
** Commercial License Agreement provided with the Software.
|
|
**
|
|
** This file is provided "AS IS" with NO WARRANTY OF ANY KIND,
|
|
** INCLUDING THE WARRANTIES OF DESIGN, MERCHANTABILITY AND FITNESS FOR
|
|
** A PARTICULAR PURPOSE. Trolltech reserves all rights not granted
|
|
** herein.
|
|
**
|
|
**********************************************************************/
|
|
|
|
/*!
|
|
\page focus.html
|
|
|
|
\title Keyboard Focus Overview
|
|
|
|
\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 keystrokes 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 keystroke
|
|
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
|
|
|
|
\i The user presses Tab (or Shift+Tab) (or sometimes Enter).
|
|
|
|
\i The user clicks a widget.
|
|
|
|
\i The user presses a keyboard shortcut.
|
|
|
|
\i The user uses the mouse wheel.
|
|
|
|
\i 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 Tab is by far the most common way to move focus using the
|
|
keyboard. Sometimes in data-entry applications Enter does the same as
|
|
Tab. We will ignore that for the moment.
|
|
|
|
Pressing Tab, in all window systems in common use today, moves the
|
|
keyboard focus to the next widget in a circular per-window list. Tab
|
|
moves focus along the circular list in one direction, Shift+Tab in the
|
|
other. The order in which Tab presses move from widget to widget is
|
|
called the tab order.
|
|
|
|
In Qt, this list is kept in the \l TQFocusData class. There is one
|
|
TQFocusData object per window, and widgets automatically append
|
|
themselves to the end of it when \l TQWidget::setFocusPolicy() is
|
|
called with an appropriate \l TQWidget::FocusPolicy. You can customize
|
|
the tab order using \l TQWidget::setTabOrder(). (If you don't, Tab
|
|
generally moves focus in the order of widget construction.) \link
|
|
designer-manual.book TQt Designer\endlink provides a means of visually
|
|
changing the tab order.
|
|
|
|
Since pressing 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, Tab
|
|
could skip this field, and the dialog could use one of these
|
|
mechanisms:
|
|
|
|
\list 1
|
|
|
|
\i If the program can determine whether the field is needed, it can
|
|
move focus there when the user finishes entry and presses 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.
|
|
|
|
\i The label for the field can include a keyboard shortcut that moves
|
|
focus to this field.
|
|
|
|
\endlist
|
|
|
|
Another exception to Tab support is text-entry widgets that must
|
|
support the insertion of tabs; almost all text editors fall into this
|
|
class. TQt treats Control+Tab as Tab and Control+Shift+Tab as
|
|
Shift+Tab, and such widgets can reimplement \l TQWidget::event() and
|
|
handle Tab before calling TQWidget::event() to get normal processing of
|
|
all other keys. However, since some systems use Control+Tab for other
|
|
purposes, and many users aren't aware of Control+Tab anyway, this
|
|
isn't a complete solution.
|
|
|
|
\section2 The user clicks a widget.
|
|
|
|
This is perhaps even more common than pressing Tab on computers with a
|
|
mouse or other pointing device.
|
|
|
|
Clicking to move the focus is slightly more powerful than 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: \l TQButton and its subclasses make this very easy.)
|
|
|
|
In Qt, only the \l TQWidget::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 \l TQLabel::setBuddy(), \l
|
|
TQGroupBox and \l TQTabBar.
|
|
|
|
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. Alt+P to step to the
|
|
<u>P</u>rinting page. But don't overdo this: there are only a few
|
|
keys, and it's also important to provide keyboard shortcuts for
|
|
commands. Alt+P is also used for Paste, Play, Print and Print Here in
|
|
the \link accelerators.html standard list of shortcuts\endlink, for
|
|
example.
|
|
|
|
\section2 The user uses 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 TQt 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. TQt does this
|
|
automatically.
|
|
|
|
If focus has never been in this window before and you know where focus
|
|
should start out, call \l TQWidget::setFocus() on the widget which
|
|
should receive focus before you \l TQWidget::show() it. If you don't,
|
|
Qt will pick a suitable widget.
|
|
|
|
*/
|