summaryrefslogtreecommitdiffstats
path: root/doc/html/focus.html
diff options
context:
space:
mode:
Diffstat (limited to 'doc/html/focus.html')
-rw-r--r--doc/html/focus.html167
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&nbsp;Classes</font></a>
+ | <a href="mainclasses.html">
+<font color="#004faf">Main&nbsp;Classes</font></a>
+ | <a href="annotated.html">
+<font color="#004faf">Annotated</font></a>
+ | <a href="groups.html">
+<font color="#004faf">Grouped&nbsp;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 &copy; 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>