We suggest that you encompass in a single READ all the windows that you
intend to interact with.  FoxPro can coordinate windows containing GET
objects (@...GETs, check boxes, radio buttons, popups, etc.) with other
windows not usually associated with a READ -- Browse windows, memo and
text editing windows, FoxPro system windows and so on.  By default, all
interactive windows (Browse windows, desk accessories and windows opened
with MODIFY FILE, MODIFY REPORT, etc.) can participate in a READ.

Coordinating Windows with a Single READ
---------------------------------------

To programmatically coordinate windows containing GET objects with a
single READ:

1.      Create the windows that will contain the GET objects.

2.      Activate one of the windows and issue the GET commands that create
the GET objects for that window.

3.      Activate another window and issue the GET commands that create the
GET objects for the window.

4.      Continue in this fashion for the remaining windows.

5.      Issue READ.

The screen set program code generated by GENSCRN provides a good example
of how this is accomplished.

The windows will now be coordinated with a single READ.  Each of the GET
objects will appear in their respective windows, and you can move
between the GET objects in each of the windows.  When you move from
object to object, the objects are traversed in the order the GETs are
issued, regardless of the object's window.  A window is activated and
becomes the current output window when the current object is in the
window.

When you press Tab, Enter or Down Arrow on the last GET object in a
window, you are positioned on the first GET object in the next window.
When you press Shift+Tab or Up Arrow on the first GET object in a
window, you are positioned on the last GET object in the previous
window.  You can move between different GET objects in different windows
by clicking the mouse on the GET objects.

Access to other windows during a single READ can be controlled with the
new READ MODAL clause.  Including the MODAL keyword in READ prevents
interaction with windows that are not encompassed in READ's coordinated
set of windows.  When MODAL is included with READ, you cannot close,
zoom, minimize, or move windows not involved in the READ.  Clicking the
mouse on a window not involved in the READ will sound a beep if BELL is
SET ON.

By default, all interactive windows (Browse windows, desk accessories
and windows opened with MODIFY FILE, MODIFY REPORT, etc.) can
participate in a READ.

You can explicitly indicate other windows that will participate in the
READ by including their names in WITH clause.  If you have included the
WITH clause to specify other windows involved in the READ, the READ is
automatically made MODAL.  The windows included in the WITH clause can
include FoxPro system windows (Browse windows, desk accessories and text
and memo editing windows).

READ ACTIVATE and DEACTIVATE
----------------------------

When a window involved in the READ is brought forward, the action taken
can be controlled by READ's ACTIVATE and DEACTIVATE clauses.  A window
can be brought forward by clicking on the window with the mouse, by
cycling to the window with Ctrl+F1, or by choosing a control or menu
option that activates the window.

When a window containing @...GETs is foremost and you attempt to bring
any other window forward, the new window is brought forward then the
READ DEACTIVATE clause is executed.

The value returned by the READ DEACTIVATE clause answers the question
"Shall the READ be terminated?"  If the READ DEACTIVATE clause returns a
logical true value (.T.), the READ is terminated.  If a logical false
(.F.) is returned, the READ is not terminated.

When the DEACTIVATE clause is executed, WONTOP() returns the name of the
new window brought forward and WLAST(), a function new to FoxPro 2.0,
returns the name of the window that was formerly frontmost.  The window
functions (WONTOP(), WOUTPUT() ... ) have been modified in FoxPro 2.0 so
that when you include the name of a window that does not exist in these
functions, a logical false (.F.) is returned.  Formerly an error was
generated.

If your DEACTIVATE clause lets the new window remain forward and the new
window contains @...GETs, the READ ACTIVATE clause is executed.

. HOT TIP .
        When a window is brought forward, you can return the window to its
former position by issuing the command

        ACTIVATE WINDOW (WLAST())

        in the READ DEACTIVATE clause.  Note how WLAST() is used above in a
name expression.

The function WREAD() has been added to FoxPro 2.0 to facilitate
manipulation of windows participating in a READ.  WREAD() lets you
determine if a specific window is participating in the current READ.

Coordinating Multiple READs / Foundation READs
----------------------------------------------

The Single READ with Multiple Windows section above recommends an
approach to handling multiple windows with a single READ.  The single
READ approach should suffice for most applications.

However, a Foundation READ may be necessary in some applications.  A
Foundation READ is a READ without @...GETs.  A Foundation READ is used
to coordinate multiple READs into a single interactive session.

. WARNING .
        Foundation READs can be complex to program. Be sure you are thoroughly
familiar with the single READ approach before you attempt to use
Foundation READs.

A Foundation READ typically incorporates code in its VALID clause
routine that activates and controls the child READs.  Child READs are
sometimes called nested READs.

A Foundation READ normally has a VALID clause.  The VALID clause is
triggered by any event that would otherwise terminate the READ.  Here
are the events that will terminate a Foundation READ:

-       Any mouse click or keystroke that is not a menu selection or does not
execute an ON KEY LABEL command.  During a Foundation READ, the FoxPro
system menu is accessible.

        Selecting an item from a menu or executing an ON KEY LABEL command does
not terminate a Foundation READ.  If a menu is activated but a selection
is not made from the menu, the Foundation READ is not terminated.

-       A child READ is terminated.  However, the Foundation READ is not
terminated if a grandchild READ is terminated.

The value returned by the READ VALID clause answers the question "Shall
the Foundation READ be terminated?"  If the READ VALID clause returns a
logical true value (.T.), the Foundation READ is terminated; if it
returns false (.F.), the Foundation READ remains active.

READKEY() has been enhanced in FoxPro 2.0 to facilitate the management
of child READs.  By including a numeric argument in READKEY(), you can
determine how the last READ was terminated.  For example, the value can
indicate that the last READ was terminated by closing a window, by a
CLEAR READ, by a READ VALID or READ DEACTIVATE clause returning .T. and
so on.

Here are the values returned by READKEY() with the reason why the READ
was terminated:

Value           Reason
--------------------------------

 1              None of the following
 2              CLEAR READ issued
 3              Terminating control chosen
 4              READ window closed
 5              DEACTIVATE clause returned .T.
 6              READ timed out