--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/src/widgets-and-layouts/focus.qdoc Wed Mar 31 11:06:36 2010 +0300
@@ -0,0 +1,200 @@
+/****************************************************************************
+**
+** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** No Commercial Usage
+** This file contains pre-release code and may not be distributed.
+** You may use this file in accordance with the terms and conditions
+** contained in the Technology Preview License Agreement accompanying
+** this package.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 2.1 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL included in the
+** packaging of this file. Please review the following information to
+** ensure the GNU Lesser General Public License version 2.1 requirements
+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** In addition, as a special exception, Nokia gives you certain additional
+** rights. These rights are described in the Nokia Qt LGPL Exception
+** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
+**
+** If you have questions regarding the use of this file, please contact
+** Nokia at qt-info@nokia.com.
+**
+**
+**
+**
+**
+**
+**
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+ \page focus.html
+ \title Keyboard Focus
+ \brief Keyboard focus management and handling.
+ \ingroup frameworks-technologies
+
+ \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 key strokes 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 key stroke
+ 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
+
+ \o The user presses \key Tab (or \key Shift+Tab).
+ \o The user clicks a widget.
+ \o The user presses a keyboard shortcut.
+ \o The user uses the mouse wheel.
+ \o 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 \key Tab is by far the most common way to move focus
+ using the keyboard. (Sometimes in data-entry applications Enter
+ does the same as \key{Tab}; this can easily be achieved in Qt by
+ implementing an \l{Events and Event Filters}{event filter}.)
+
+ Pressing \key Tab, in all window systems in common use today,
+ moves the keyboard focus to the next widget in a circular
+ per-window list. \key Tab moves focus along the circular list in
+ one direction, \key Shift+Tab in the other. The order in which
+ \key Tab presses move from widget to widget is called the tab order.
+
+ You can customize the tab order using QWidget::setTabOrder(). (If
+ you don't, \key Tab generally moves focus in the order of widget
+ construction.) \l{Qt Designer} provides a means of visually
+ changing the tab order.
+
+ Since pressing \key 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,
+ \key Tab could skip this field, and the dialog could use one of
+ these mechanisms:
+
+ \list 1
+
+ \o If the program can determine whether the field is needed, it can
+ move focus there when the user finishes entry and presses \gui 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.
+
+ \o The label for the field can include a keyboard shortcut that moves
+ focus to this field.
+
+ \endlist
+
+ Another exception to \key Tab support is text-entry widgets that
+ must support the insertion of tabs; almost all text editors fall
+ into this class. Qt treats \key Ctrl+Tab as \key Tab and \key
+ Ctrl+Shift+Tab as \key Shift+Tab, and such widgets can
+ reimplement QWidget::event() and handle Tab before calling
+ QWidget::event() to get normal processing of all other keys.
+ However, since some systems use \key Ctrl+Tab for other purposes,
+ and many users aren't aware of \key Ctrl+Tab anyway, this isn't a
+ complete solution.
+
+ \section2 The User Clicks a Widget
+
+ This is perhaps even more common than pressing \key Tab on
+ computers with a mouse or other pointing device.
+
+ Clicking to move the focus is slightly more powerful than \key
+ 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: QAbstractButton and its subclasses make this very easy.)
+
+ In Qt, only the 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
+ QLabel::setBuddy(), QGroupBox, and 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. \key
+ Alt+P to step to the \underline{P}rinting page. It is easy to
+ overdo this: there are only a few keys, and it's also important
+ to provide keyboard shortcuts for commands. \key Alt+P is also
+ used for Paste, Play, Print, and Print Here in the \l{Standard
+ Accelerator Keys} list, for example.
+
+ \section2 The User Rotates 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 QWidget::setFocus() on the widget
+ which should receive focus before you call QWidget::show() it. If
+ you don't, Qt will pick a suitable widget.
+*/