<!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 > TQt'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 TQt, this list is kept in the < a href = "ntqfocusdata.html" > TQFocusData< / a > class. There is one
< a href = "ntqfocusdata.html" > TQFocusData< / a > object per window, and widgets automatically append
themselves to the end of it when < a href = "tqwidget.html#setFocusPolicy" > TQWidget::setFocusPolicy< / a > () is
called with an appropriate < a href = "tqwidget.html#FocusPolicy-enum" > TQWidget::FocusPolicy< / a > . You can customize
the tab order using < a href = "tqwidget.html#setTabOrder" > TQWidget::setTabOrder< / a > (). (If you don't, Tab
generally moves focus in the order of widget construction.) < a href = "designer-manual.html" > TQt 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. TQt treats Control+Tab as Tab and Control+Shift+Tab as
Shift+Tab, and such widgets can reimplement < a href = "tqwidget.html#event" > TQWidget::event< / a > () and
handle Tab before calling < a href = "tqwidget.html#event" > TQWidget::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 = "tqbutton.html" > TQButton< / a > and its subclasses make this very easy.)
< p > In TQt, only the < a href = "tqwidget.html#setFocusPolicy" > TQWidget::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 = "tqlabel.html#setBuddy" > TQLabel::setBuddy< / a > (), < a href = "tqgroupbox.html" > TQGroupBox< / a > and < a href = "tqtabbar.html" > TQTabBar< / 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 TQt 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. TQt does this
automatically.
< p > If focus has never been in this window before and you know where focus
should start out, call < a href = "tqwidget.html#setFocus" > TQWidget::setFocus< / a > () on the widget which
should receive focus before you < a href = "tqwidget.html#show" > TQWidget::show< / a > () it. If you don't,
TQt 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 > TQt 3.3.8< / div >
< / table > < / div > < / address > < / body >
< / html >
