doc/src/widgets/widgets-and-layouts/focus.qdoc

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
   4 ** All rights reserved.
   5 ** Contact: Nokia Corporation (qt-info@nokia.com)
   6 **
   7 ** This file is part of the documentation of the Qt Toolkit.
   8 **
   9 ** $QT_BEGIN_LICENSE:FDL$
  10 ** GNU Free Documentation License
  11 ** Alternatively, this file may be used under the terms of the GNU Free
  12 ** Documentation License version 1.3 as published by the Free Software
  13 ** Foundation and appearing in the file included in the packaging of
  14 ** this file.
  15 **
  16 ** Other Usage
  17 ** Alternatively, this file may be used in accordance with the terms
  18 ** and conditions contained in a signed written agreement between you
  19 ** and Nokia.
  20 **
  21 **
  22 **
  23 **
  24 ** $QT_END_LICENSE$
  25 **
  26 ****************************************************************************/
  27
  28 /*!
  29     \page focus.html
  30     \title Keyboard Focus
  31     \brief Keyboard focus management and handling.
  32     \ingroup frameworks-technologies
  33
  34     \keyword keyboard focus
  35
  36     Qt's widgets handle keyboard focus in the ways that have become
  37     customary in GUIs.
  38
  39     The basic issue is that the user's key strokes can be directed at any
  40     of several windows on the screen, and any of several widgets inside
  41     the intended window. When the user presses a key, they expect it to go
  42     to the right place, and the software must try to meet this
  43     expectation. The system must determine which application the key stroke
  44     is directed at, which window within that application, and which widget
  45     within that window.
  46
  47     \section1 Focus Motion
  48
  49     The customs which have evolved for directing keyboard focus to a
  50     particular widget are these:
  51
  52     \list 1
  53
  54     \o The user presses \key Tab (or \key Shift+Tab).
  55     \o The user clicks a widget.
  56     \o The user presses a keyboard shortcut.
  57     \o The user uses the mouse wheel.
  58     \o The user moves the focus to a window, and the application must
  59        determine which widget within the window should get the focus.
  60     \endlist
  61
  62     Each of these motion mechanisms is different, and different types of
  63     widgets receive focus in only some of them. We'll cover each of them
  64     in turn.
  65
  66     \section2 Tab or Shift+Tab
  67
  68     Pressing \key Tab is by far the most common way to move focus
  69     using the keyboard. (Sometimes in data-entry applications Enter
  70     does the same as \key{Tab}; this can easily be achieved in Qt by
  71     implementing an \l{The Event System}{event filter}.)
  72
  73     Pressing \key Tab, in all window systems in common use today,
  74     moves the keyboard focus to the next widget in a circular
  75     per-window list. \key Tab moves focus along the circular list in
  76     one direction, \key Shift+Tab in the other. The order in which
  77     \key Tab presses move from widget to widget is called the tab order.
  78
  79     You can customize the tab order using QWidget::setTabOrder(). (If
  80     you don't, \key Tab generally moves focus in the order of widget
  81     construction.) \l{Qt Designer} provides a means of visually
  82     changing the tab order.
  83
  84     Since pressing \key Tab is so common, most widgets that can have focus
  85     should support tab focus. The major exception is widgets that are
  86     rarely used, and where there is some keyboard accelerator or error
  87     handler that moves the focus.
  88
  89     For example, in a data entry dialog, there might be a field that
  90     is only necessary in one per cent of all cases. In such a dialog,
  91     \key Tab could skip this field, and the dialog could use one of
  92     these mechanisms:
  93
  94     \list 1
  95
  96     \o If the program can determine whether the field is needed, it can
  97     move focus there when the user finishes entry and presses \gui OK, or when
  98     the user presses Enter after finishing the other fields. Alternately,
  99     include the field in the tab order but disable it. Enable it if it
 100     becomes appropriate in view of what the user has set in the other
 101     fields.
 102
 103     \o The label for the field can include a keyboard shortcut that moves
 104     focus to this field.
 105
 106     \endlist
 107
 108     Another exception to \key Tab support is text-entry widgets that
 109     must support the insertion of tabs; almost all text editors fall
 110     into this class. Qt treats \key Ctrl+Tab as \key Tab and \key
 111     Ctrl+Shift+Tab as \key Shift+Tab, and such widgets can
 112     reimplement QWidget::event() and handle Tab before calling
 113     QWidget::event() to get normal processing of all other keys.
 114     However, since some systems use \key Ctrl+Tab for other purposes,
 115     and many users aren't aware of \key Ctrl+Tab anyway, this isn't a
 116     complete solution.
 117
 118     \section2 The User Clicks a Widget
 119
 120     This is perhaps even more common than pressing \key Tab on
 121     computers with a mouse or other pointing device.
 122
 123     Clicking to move the focus is slightly more powerful than \key
 124     Tab. While it moves the focus \e to a widget, for editor widgets
 125     it also moves the text cursor (the widget's internal focus) to
 126     the spot where the mouse is clicked.
 127
 128     Since it is so common and people are used to it, it's a good idea to
 129     support it for most widgets. However, there is also an important
 130     reason to avoid it: you may not want to remove focus from the widget
 131     where it was.
 132
 133     For example, in a word processor, when the user clicks the 'B' (bold)
 134     tool button, what should happen to the keyboard focus? Should it
 135     remain where it was, almost certainly in the editing widget, or should
 136     it move to the 'B' button?
 137
 138     We advise supporting click-to-focus for widgets that support text
 139     entry, and to avoid it for most widgets where a mouse click has a
 140     different effect. (For buttons, we also recommend adding a keyboard
 141     shortcut: QAbstractButton and its subclasses make this very easy.)
 142
 143     In Qt, only the QWidget::setFocusPolicy() function affects
 144     click-to-focus.
 145
 146     \section2 The User Presses a Keyboard Shortcut
 147
 148     It's not unusual for keyboard shortcuts to move the focus. This
 149     can happen implicitly by opening modal dialogs, but also
 150     explicitly using focus accelerators such as those provided by
 151     QLabel::setBuddy(), QGroupBox, and QTabBar.
 152
 153     We advise supporting shortcut focus for all widgets that the user
 154     may want to jump to. For example, a tab dialog can have keyboard
 155     shortcuts for each of its pages, so the user can press e.g. \key
 156     Alt+P to step to the \underline{P}rinting page. It is easy to
 157     overdo this: there are only a few keys, and it's also important
 158     to provide keyboard shortcuts for commands. \key Alt+P is also
 159     used for Paste, Play, Print, and Print Here in the \l{Standard
 160     Accelerator Keys} list, for example.
 161
 162     \section2 The User Rotates the Mouse Wheel
 163
 164     On Microsoft Windows, mouse wheel usage is always handled by the
 165     widget that has keyboard focus. On Mac OS X and X11, it's handled by
 166     the widget that gets other mouse events.
 167
 168     The way Qt handles this platform difference is by letting widgets move
 169     the keyboard focus when the wheel is used. With the right focus policy
 170     on each widget, applications can work idiomatically correctly on
 171     Windows, Mac OS X, and X11.
 172
 173     \section2 The User Moves the Focus to This Window
 174
 175     In this situation the application must determine which widget within
 176     the window should receive the focus.
 177
 178     This can be simple: If the focus has been in this window before,
 179     then the last widget to have focus should regain it. Qt does this
 180     automatically.
 181
 182     If focus has never been in this window before and you know where
 183     focus should start out, call QWidget::setFocus() on the widget
 184     which should receive focus before you call QWidget::show() it. If
 185     you don't, Qt will pick a suitable widget.
 186 */