diff options
Diffstat (limited to 'doc/html/focus.html')
| -rw-r--r-- | doc/html/focus.html | 167 |
1 files changed, 167 insertions, 0 deletions
diff --git a/doc/html/focus.html b/doc/html/focus.html new file mode 100644 index 0000000..0124b20 --- /dev/null +++ b/doc/html/focus.html @@ -0,0 +1,167 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> +<!-- /home/espenr/tmp/qt-3.3.8-espenr-2499/qt-x11-free-3.3.8/doc/focus.doc:36 --> +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>Keyboard Focus Overview</title> +<style type="text/css"><!-- +fn { margin-left: 1cm; text-indent: -1cm; } +a:link { color: #004faf; text-decoration: none } +a:visited { color: #672967; text-decoration: none } +body { background: #ffffff; color: black; } +--></style> +</head> +<body> + +<table border="0" cellpadding="0" cellspacing="0" width="100%"> +<tr bgcolor="#E5E5E5"> +<td valign=center> + <a href="index.html"> +<font color="#004faf">Home</font></a> + | <a href="classes.html"> +<font color="#004faf">All Classes</font></a> + | <a href="mainclasses.html"> +<font color="#004faf">Main Classes</font></a> + | <a href="annotated.html"> +<font color="#004faf">Annotated</font></a> + | <a href="groups.html"> +<font color="#004faf">Grouped Classes</font></a> + | <a href="functions.html"> +<font color="#004faf">Functions</font></a> +</td> +<td align="right" valign="center"><img src="logo32.png" align="right" width="64" height="32" border="0"></td></tr></table><h1 align=center>Keyboard Focus Overview</h1> + + + +<p> <!-- index keyboard focus --><a name="keyboard-focus"></a> +<p> Qt's widgets handle keyboard focus in the ways that have become +customary in GUIs. +<p> The basic issue is that the user's keystrokes 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 keystroke +is directed at, which window within that application, and which widget +within that window. +<p> <h2> Focus motion +</h2> +<a name="1"></a><p> The customs which have evolved for directing keyboard focus to a +particular widget are these: +<ol type=1> +<p> <li> The user presses Tab (or Shift+Tab) (or sometimes Enter). +<p> <li> The user clicks a widget. +<p> <li> The user presses a keyboard shortcut. +<p> <li> The user uses the mouse wheel. +<p> <li> The user moves the focus to a window, and the application must +determine which widget within the window should get the focus. +<p> </ol> +<p> 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. +<p> <h3> Tab or Shift+Tab. +</h3> +<a name="1-1"></a><p> Pressing Tab is by far the most common way to move focus using the +keyboard. Sometimes in data-entry applications Enter does the same as +Tab. We will ignore that for the moment. +<p> Pressing Tab, in all window systems in common use today, moves the +keyboard focus to the next widget in a circular per-window list. Tab +moves focus along the circular list in one direction, Shift+Tab in the +other. The order in which Tab presses move from widget to widget is +called the tab order. +<p> In Qt, this list is kept in the <a href="qfocusdata.html">QFocusData</a> class. There is one +<a href="qfocusdata.html">QFocusData</a> object per window, and widgets automatically append +themselves to the end of it when <a href="qwidget.html#setFocusPolicy">QWidget::setFocusPolicy</a>() is +called with an appropriate <a href="qwidget.html#FocusPolicy-enum">QWidget::FocusPolicy</a>. You can customize +the tab order using <a href="qwidget.html#setTabOrder">QWidget::setTabOrder</a>(). (If you don't, Tab +generally moves focus in the order of widget construction.) <a href="designer-manual.html">Qt Designer</a> provides a means of visually +changing the tab order. +<p> Since pressing 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. +<p> 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, Tab +could skip this field, and the dialog could use one of these +mechanisms: +<p> <ol type=1> +<p> <li> If the program can determine whether the field is needed, it can +move focus there when the user finishes entry and presses 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. +<p> <li> The label for the field can include a keyboard shortcut that moves +focus to this field. +<p> </ol> +<p> Another exception to Tab support is text-entry widgets that must +support the insertion of tabs; almost all text editors fall into this +class. Qt treats Control+Tab as Tab and Control+Shift+Tab as +Shift+Tab, and such widgets can reimplement <a href="qwidget.html#event">QWidget::event</a>() and +handle Tab before calling <a href="qwidget.html#event">QWidget::event</a>() to get normal processing of +all other keys. However, since some systems use Control+Tab for other +purposes, and many users aren't aware of Control+Tab anyway, this +isn't a complete solution. +<p> <h3> The user clicks a widget. +</h3> +<a name="1-2"></a><p> This is perhaps even more common than pressing Tab on computers with a +mouse or other pointing device. +<p> Clicking to move the focus is slightly more powerful than Tab. While +it moves the focus <em>to</em> a widget, for editor widgets it also moves +the text cursor (the widget's internal focus) to the spot where the +mouse is clicked. +<p> 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. +<p> 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? +<p> 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: <a href="qbutton.html">QButton</a> and its subclasses make this very easy.) +<p> In Qt, only the <a href="qwidget.html#setFocusPolicy">QWidget::setFocusPolicy</a>() function affects +click-to-focus. +<p> <h3> The user presses a keyboard shortcut. +</h3> +<a name="1-3"></a><p> 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 <a href="qlabel.html#setBuddy">QLabel::setBuddy</a>(), <a href="qgroupbox.html">QGroupBox</a> and <a href="qtabbar.html">QTabBar</a>. +<p> 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. Alt+P to step to the +<u>P</u>rinting page. But don't overdo this: there are only a few +keys, and it's also important to provide keyboard shortcuts for +commands. Alt+P is also used for Paste, Play, Print and Print Here in +the <a href="accelerators.html">standard list of shortcuts</a>, for +example. +<p> <h3> The user uses the mouse wheel. +</h3> +<a name="1-4"></a><p> 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. +<p> 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. +<p> <h3> The user moves the focus to this window. +</h3> +<a name="1-5"></a><p> In this situation the application must determine which widget within +the window should receive the focus. +<p> 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. +<p> If focus has never been in this window before and you know where focus +should start out, call <a href="qwidget.html#setFocus">QWidget::setFocus</a>() on the widget which +should receive focus before you <a href="qwidget.html#show">QWidget::show</a>() it. If you don't, +Qt will pick a suitable widget. +<p> +<!-- eof --> +<p><address><hr><div align=center> +<table width=100% cellspacing=0 border=0><tr> +<td>Copyright © 2007 +<a href="troll.html">Trolltech</a><td align=center><a href="trademarks.html">Trademarks</a> +<td align=right><div align=right>Qt 3.3.8</div> +</table></div></address></body> +</html> |