From d796c9dd933ab96ec83b9a634feedd5d32e1ba3f Mon Sep 17 00:00:00 2001 From: Timothy Pearson Date: Tue, 8 Nov 2011 12:31:36 -0600 Subject: Test conversion to TQt3 from Qt3 8c6fc1f8e35fd264dd01c582ca5e7549b32ab731 --- doc/html/focus.html | 167 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 167 insertions(+) create mode 100644 doc/html/focus.html (limited to 'doc/html/focus.html') diff --git a/doc/html/focus.html b/doc/html/focus.html new file mode 100644 index 000000000..f9456559c --- /dev/null +++ b/doc/html/focus.html @@ -0,0 +1,167 @@ + + + + + +Keyboard Focus Overview + + + + + + + +

Keyboard Focus Overview

+ + + +

TQt's widgets handle keyboard focus in the ways that have become +customary in GUIs. +

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. +

Focus motion +

The customs which have evolved for directing keyboard focus to a +particular widget are these: +

The user presses Tab (or Shift+Tab) (or sometimes Enter). +
The user clicks a widget. +
The user presses a keyboard shortcut. +
The user uses the mouse wheel. +
The user moves the focus to a window, and the application must +determine which widget within the window should get the focus. +

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. +

Tab or Shift+Tab. +

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. +

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. +

In TQt, this list is kept in the TQFocusData class. There is one +TQFocusData object per window, and widgets automatically append +themselves to the end of it when TQWidget::setFocusPolicy() is +called with an appropriate TQWidget::FocusPolicy. You can customize +the tab order using TQWidget::setTabOrder(). (If you don't, Tab +generally moves focus in the order of widget construction.) TQt Designer provides a means of visually +changing the tab order. +

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. +

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: +

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. +
The label for the field can include a keyboard shortcut that moves +focus to this field. +

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 TQWidget::event() and +handle Tab before calling TQWidget::event() 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. +

The user clicks a widget. +

This is perhaps even more common than pressing Tab on computers with a +mouse or other pointing device. +

Clicking to move the focus is slightly more powerful than Tab. While +it moves the focus 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: TQButton and its subclasses make this very easy.) +

In TQt, only the TQWidget::setFocusPolicy() function affects +click-to-focus. +

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 TQLabel::setBuddy(), TQGroupBox and TQTabBar. +

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 +Printing 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 standard list of shortcuts, for +example. +

The user uses 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 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. +

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. TQt does this +automatically. +

If focus has never been in this window before and you know where focus +should start out, call TQWidget::setFocus() on the widget which +should receive focus before you TQWidget::show() it. If you don't, +TQt will pick a suitable widget. +

+ +

Trademarks +

TQt 3.3.8

+ -- cgit v1.2.1