diff options
Diffstat (limited to 'doc/src/widgets-and-layouts/focus.qdoc')
| -rw-r--r-- | doc/src/widgets-and-layouts/focus.qdoc | 186 |
1 files changed, 186 insertions, 0 deletions
diff --git a/doc/src/widgets-and-layouts/focus.qdoc b/doc/src/widgets-and-layouts/focus.qdoc new file mode 100644 index 0000000000..446b374901 --- /dev/null +++ b/doc/src/widgets-and-layouts/focus.qdoc @@ -0,0 +1,186 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 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. +** +** 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{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 + + \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. +*/ |