Reference » Window classes » MWindow » appendTabStop

Elgrint::MWindow::appendTabStop(MWindow&) method

Declaration (see MWindow.h):

void appendTabStop(MWindow& wnd);

Description

Inserts wnd to the end of the tab-stop chain, which starts with this.

Parameters:

Name Type Description
wnd MWindow&

The window which becomes the previous tab-stop of this (added at the end of the chain).

Details

Many apps let the user shift the focus between several most often used windows using the Tab key, as if these windows (called "tab-stops") were links in a closed chain. This is a common user interface principle, which can make the interface significantly more efficient, especially if the user relies heavily on the keyboard.

On the developer's side, this principle could be implemented simply by catching the Tab key in a mainframe window via KeysEntered message, and calling setFocus to shift the focus to the next link in the chain. However, such implementation would be inconvenient and inefficient, since it would require either an overblown multi-level if statement, or the use of MMap (and window pointers, because MWindow objects cannot be used in collections) to select the next tab-stop. And supporting the shift in the opposite direction (using Shift+Tab) would require duplicating this implementation. Also, MEditBox, the most common tab-stop candidate, does not propagate the Tab key, because it is needed for typing tab characters, so the mainframe would not receive these events automatically. Plus, there are a few additional complications, such as handling the disabled tab-stops.

To make things easier for the developers, Elgrint implements this tab-stop switching mechanism internally, with convenience and efficiency. The mechanism is composed of the appendTabStop, operator>>(MWindow&,MWindow&), getNextTabStop and getPrevTabStop functions, as well as the default OnKeysEntered handler, which performs the actual focus switch. The switching can be customized by overloading OnKeysEntered. For example, MDialogBox allows the focus shift using the Left/Right arrow keys in addition to Tab/Shift+Tab).

But unless a customization is required, the typical usage would be to define the chain via operator>>(MWindow&,MWindow&), which is a simple convenience wrapper of appendTabStop (see Example). This definition is usually made during the program's initialization, but in principle can be done at any time. After wnd is appended at the end of the chain that starts form this (or, equivalently, just before this, because the chain is circular), every time the user presses the Tab key in wnd, the focus goes to this window, and pressing Shift+Tab in this window shifts the focus to wnd. The size of the chain is limited only by the number of window, and there can be many such chains throughout the app. If wnd already belongs to some other chain (or even the same one), then appendTabStop removes wnd from its chain and adds it to the end of the chain of wnd. Thus, every window can belong to one chain at most. To remove the window from any chain, just make a 1-link chain from that window by adding it to itself, e.g. wnd.appendTabStop(wnd).

As mentioned previously, all tab-stop chains are circularly closed. However, this does not mean that pressing Tab in succession will eventually return the focus to the same window where it started, because when a window receives the focus, it can pass it anywhere else. Also, pressing Tab or Shift+Tab in a window that is not part of any chain can still shift the focus to some other window. See getNextTabStop, getPrevTabStop, and MWindow::OnKeysEntered for additional details. See also operator>>(MWindow&,MWindow&).

Remarks

Example

Let us know

Please Contact us to report any errors on this page, or to suggest any improvements.

Miranor Home | About Miranor | About Elgrint | Create account | Login | Account settings | Contact Us | Privacy Policy | Site map

© Copyright 2014 by Miranor. All rights reserved. By using this site you agree to the Terms of Use.

Page last updated on August 10th, 2014.