+---------------------------------+
|              READ               |
+---------------------------------+
READ
        [CYCLE]
        [ACTIVATE <expL1>]
        [DEACTIVATE <expL2>]
        [MODAL]
        [WITH window title list]
        [SHOW <expL3>]
        [VALID <expL4 | expN1>]
        [WHEN <expL5>]
        [OBJECT <expN2>]
        [TIMEOUT <expN3>]
        [SAVE]
        [NOMOUSE]
        [LOCK | NOLOCK]
        [COLOR <color pair list>
        | COLOR SCHEME <expN4>]

-----------------------------------
Activates objects created with @ ... GET and @ ... EDIT commands.
-----------------------------------

READ activates GET objects.  GET objects are GET fields, Text Editing
Regions, Push Buttons, Radio Buttons, Popups, Check Boxes, and Lists.
All GET objects created since the last READ or CLEAR GETS was issued are
activated.

Positioning
-----------

When the READ is issued, you may press Enter, Tab, or Down arrow to move
forward from object to object.  Press Shift+Tab or the Up arrow to move
backward from object to object. Movement from object to object takes
place in the order the GETs were issued.

If you have a mouse, you can select an object by clicking on the object.
If you are not familiar with mouse operation, please refer to the FoxPro
Getting Started manual.

Entering Data
-------------

When you move into a GET field or text editing region you may enter text
or edit existing text.  Standard FoxPro text editing features are
available in a GET field or text editing region -- text may be cut,
copied and pasted.

Exiting the READ
----------------

READ can be exited in several ways.  Moving forward past the last GET
object or backward past the first object exits READ (if CYCLE isn't
included with READ).  Pressing Escape, Ctrl+W or choosing a control that
was defined to terminate the READ also exits the READ.

Multi-Window READ
-----------------

A READ may span multiple windows.  GET objects may be placed in
different windows and activated with a single READ.  When you move from
object to object, the objects are traversed in the order the GETs were
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.  The SHOW GETS command contains
an example of multi-window reads.

Nested READS
------------

Nested READs can be created by issuing GETs and a READ in a routine
called while in READ.  READs may be nested to a depth of five levels.
RDLEVEL() returns the current READ level. The section on RDLEVEL()
contains an example of nested READS.

Event Execution Order
---------------------

The following list shows the order in which READ events and clauses are
executed when the READ is first issued:

        . READ level WHEN clause is executed

        . First GET's window is activated

        . READ level ACTIVATE is executed

        . READ level SHOW is executed

        . GET level WHEN is executed for first GET

        The following list shows the order in which READ clauses are called
when a new window is activated:

        . VALID for the field being exited is executed

        . READ level DEACTIVATE is executed

        . Window of field being exited is deactivated

        . New GET field's window is activated

        . READ level ACTIVATE is executed

        . WHEN clause for the new field is executed

Clauses
-------

CYCLE
        If CYCLE is included, READ is not terminated when you move forward past
the last GET object or backward past the first GET object.  If you are
positioned on the last GET object and press Tab, Enter or the Down
arrow, you will be repositioned on the first GET object.  If you are
positioned on the first GET object and press Shift+Tab or the Up arrow,
you will be repositioned on the last GET object.  If CYCLE is included,
a terminating button, Escape, Ctrl+W, CLEAR READ or the TIMEOUT clause
will all terminate the READ.

ACTIVATE <expL1>
        The ACTIVATE clause is executed when READ is issued and whenever the
current READ window changes.  ACTIVATE may be viewed as a window level
WHEN clause.  The logical expression <expL1> is typically a user-defined
function.  WOUTPUT() can be used in the user-defined function to
determine which window was made current.  The user-defined function can
disable GET objects in other windows, hide windows, display a message
and so on.

DEACTIVATE <expL2>
        The DEACTIVATE clause is executed whenever you attempt to bring any
other window forward (that is, whenever WONTOP() changes).  DEACTIVATE
may be viewed as a window level VALID clause.

        The logical expression <expL2> is typically a user-defined function.
The user-defined function can be used to validate the contents of fields
in a window before allowing you to bring forward another window.  If the
user-defined function returns a logical false value (.F.), the READ is
not terminated.  If the user-defined function returns true (.T.), the
READ is terminated.

MODAL
        Including the MODAL keyword in READ prevents ALL windows from being
activated with the exception of windows that are involved in the READ.
If windows not involved in the READ are defined when a MODAL READ is
issued, they cannot be activated or accessed.

WITH <window title list>
        Windows that typically are not involved in a READ can participate in
the READ by including the WITH clause.  Browse windows, memo and text
editing windows, FoxPro system windows and so on can participate in a
READ by including their titles in the <window title list>.

        Including the WITH clause implicitly creates a MODAL READ.  Only the
windows included in the window title list can actively participate in
the READ.

        . To make a Browse window accessible, include the Browse window title
(by default, the database alias) in the window list.