path: root/src/widgets/doc/src/widgets-and-layouts/focus.qdoc
diff options
Diffstat (limited to 'src/widgets/doc/src/widgets-and-layouts/focus.qdoc')
1 files changed, 186 insertions, 0 deletions
diff --git a/src/widgets/doc/src/widgets-and-layouts/focus.qdoc b/src/widgets/doc/src/widgets-and-layouts/focus.qdoc
new file mode 100644
index 0000000000..60f05948b4
--- /dev/null
+++ b/src/widgets/doc/src/widgets-and-layouts/focus.qdoc
@@ -0,0 +1,186 @@
+** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
+** Contact:
+** This file is part of the documentation of the Qt Toolkit.
+** GNU Free Documentation License
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of
+** this file.
+** Other Usage
+** Alternatively, this file may be used in accordance with the terms
+** and conditions contained in a signed written agreement between you
+** and Nokia.
+ \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
+ \li The user presses \key Tab (or \key Shift+Tab).
+ \li The user clicks a widget.
+ \li The user presses a keyboard shortcut.
+ \li The user uses the mouse wheel.
+ \li 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{The Event System}{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
+ \li 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.
+ \li 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.