Focus and Active Windows

To the user, it appears that when they click in a window, any text they enter interacts with that window, perhaps showing up in a text entry area in the window. By keeping track of the focus and the active windows, you may monitor and specify which component should receive text input.

The "focus" is the single component that will receive text input from the keyboard. To find out (or change) which component is the focus, use the system module's keyboard component focus property:

DIM f AS component
f = system:keyboard.focus

Each window component (each Form, Dialog, and Floater) has a focus property. This property keeps track of the focus within that window. When that window becomes the active window, its focus will become the system focus. If you want a Text/Entry component to receive text directed to a window, make it the window's focus. (You may do this using the Builder by entering the Text/Entry component's name in the Focus area of the window's Properties Box, the "Specific" area.)

To differentiate between the focus and a component which is a window's focus, we sometimes call the focus "the s ystem focus." Windows are most likely to become the active window when they first appear or when the user clicks them.

Windows find out when they start and stop being active windows by receiving _activeChanged() events. Handling this event is an opportunity to update the window's focus.

The situation is complicated by the fact that there may be more than one active window. There may be an active form, an active non-modal window, and an active modal window. Whichever of these most recently became active is the true active window.

Tool Windows

There is a type of dialog window that never becomes the active window: the Tool type. This type is useful for allowing the user to interact with a dialog without changing the focus. The tools palette in a graphic building application is an example of this.

Example

Suppose ComicDialog has two children, ComicTitle (an Entry) and ComicDesc (a Text). Each time the users interacts with ComicDialog, they will change its focus property.

If they click in ComicTitle, it becomes the focus; if they click in ComicDesc, ComicDesc becomes the focus.

The following code would ensure that ComicTitle was the default focus when the ComicDialog window becomes active:

SUB ComicDialog_activeChanged(self AS dialog, gain AS integer)
REM This event occurs whenever this window becomes the active
REM non-modal window or stops being the active non-modal
REM window.
REM
REM When it becomes the active window, make the ComicTitle
REM Entry the default focus.
IF gain THEN
self.focus = ComicTitle
END IF
END SUB