path: root/doc/focus.doc

/****************************************************************************
**
** Documentation of focus handling in Qt
**
** Copyright (C) 1992-2008 Trolltech ASA.  All rights reserved.
**
** This file is part of the Qt 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 Qt Foundation.
**
** Please review the following information to ensure GNU General
** Public Licensing retquirements 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 QFocusData class. There is one
QFocusData object per window, and widgets automatically append
themselves to the end of it when \l QWidget::setFocusPolicy() is
called with an appropriate \l QWidget::FocusPolicy. You can customize
the tab order using \l QWidget::setTabOrder(). (If you don't, Tab
generally moves focus in the order of widget construction.) \link
designer-manual.book Qt 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. Qt treats Control+Tab as Tab and Control+Shift+Tab as
Shift+Tab, and such widgets can reimplement \l QWidget::event() and
handle Tab before calling QWidget::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 QButton and its subclasses make this very easy.)

In Qt, only the \l QWidget::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 QLabel::setBuddy(), \l
QGroupBox and \l QTabBar.

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 Qt 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. Qt does this
automatically.

If focus has never been in this window before and you know where focus
should start out, call \l QWidget::setFocus() on the widget which
should receive focus before you \l QWidget::show() it. If you don't,
Qt will pick a suitable widget.

*/