diff options
Diffstat (limited to 'doc/src/focus.qdoc')
| -rw-r--r-- | doc/src/focus.qdoc | 213 |
1 files changed, 0 insertions, 213 deletions
diff --git a/doc/src/focus.qdoc b/doc/src/focus.qdoc deleted file mode 100644 index 459a9d850..000000000 --- a/doc/src/focus.qdoc +++ /dev/null @@ -1,213 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). -** 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 either Technology Preview License Agreement or the -** Beta Release License Agreement. -** -** 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.0, included in the file LGPL_EXCEPTION.txt in this -** package. -** -** GNU General Public License Usage -** Alternatively, this file may be used under the terms of the GNU -** General Public License version 3.0 as published by the Free Software -** Foundation and appearing in the file LICENSE.GPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU General Public License version 3.0 requirements will be -** met: http://www.gnu.org/copyleft/gpl.html. -** -** If you are unsure which license is appropriate for your use, please -** contact the sales department at http://qt.nokia.com/contact. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/**************************************************************************** -** -** Documentation of focus handling in Qt. -** -** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). -** Contact: Nokia Corporation (qt-info@nokia.com) -** -** This file is part of the Qt GUI Toolkit. -** EDITIONS: FREE, PROFESSIONAL, ENTERPRISE -** -****************************************************************************/ - -/*! - \page focus.html - \title Keyboard Focus - \ingroup architecture - \ingroup gui-programming - \brief An overview of the keyboard focus management and handling. - - \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. -*/ |