1 files changed, 204 insertions, 0 deletions
diff --git a/doc/focus.doc b/doc/focus.doc
new file mode 100644
index 000000000..fe4ed09f6
--- /dev/null
+++ b/doc/focus.doc
@@ -0,0 +1,204 @@
+/****************************************************************************
+**
+** 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.
+
+*/