The Sample Applications
-----------------------

Included with FoxPro are three sample applications, INV.APP, EX1.APP and
EX2.APP.  These sample applications illustrate the enhancements made to
READ and how these enhancements can be used to create an event-driven
interface.

The applications are built from three projects, INV.PJX, EX1.PJX and
EX2.PJX.  The projects contain all the files (programs, screen sets,
menus, databases, etc.) used by the applications.  To examine the files
included in a project, open the project with MODIFY PROJECT, or with the
Open File dialog.

INV: A Single READ with Multiple Windows
----------------------------------------

The sample application INV.APP demonstrates the use of a single READ
with multiple windows.  A user-defined window containing @...GETs, two
Browse windows and the CONTROL2 screen set control panel are coordinated
with a single READ.

EX1: A Foundation Read with Multiple Applications
-------------------------------------------------

EX1.APP, a more complex application, demonstrates coordination of four
READs, each of which use the control panel built from the CONTROL3.SCX
screen set.  A Foundation READ coordinates the four READs. EX1.APP has
been designed so you can utilize any FoxPro desk accessories or windows
(Help, Filer, Calculator, Calendar/Diary, editing windows, etc.) in
conjunction with the application windows.

Applications are launched from the Application menu.  You can switch
from one application to another just by clicking on the application
window.  Execution of the entire system can be terminated by choosing
the Quit option in the File menu.

EX1 Quiz
--------

Before you attempt to write your own multi-READ event driven code, we
recommend you carefully study EX1 and be certain you can answer the
following questions about its operation.  The answers are provided at
the end of this section.

1.      What would happen if the menu handling routine always immediately
launched the requested application, regardless of the current READ level
(returned by RDLEVEL())?

2.      Why is it necessary to specify the IN EX1.MPR clause in the menu
command in the Application menu?

3.      Where is the code that handles the situation where an application
window is closed manually either by clicking the mouse on its close box,
or by selecting Close from the File menu popup?

4.      What's the largest number of READs that are ever active at any one
time while EX1.APP is executing?

5.      What insures that the control panel vanishes when the last remaining
application window is closed?

6.      If you bring, say, the Calculator up on top of an application window,
is the application READ still active?  The Foundation READ?

7.      When you're executing EX1.APP and neither an application window nor
the control panel is visible, and you're using, say, the Filer, is there
any READ active?

8.      When you're running in an application window and you click in
another, how is control transferred from the first application to the
new one?  What event triggers the transfer?

If you can answer all the above questions, you're ready to proceed to
the next example.

EX2: A Foundation Read with Multiple Applications
-------------------------------------------------

This application is similar to EX1, but replaces the single invoice
editing screen with the INV.APP application that, besides editing the
invoice file, includes the CONTROL2 control panel and two Browse windows
coordinated as part of the READ.

Study EX2 carefully and you'll see that the changes required to handle
this more complex situation are rather simple.  If you can answer the
eight questions about EX1, you should have no difficulty with EX2.  And
by now, you should have a general idea how to proceed in your own
applications.

EX1 Quiz Answers
----------------

1.      You would add one READ level each time you selected an application
from the menu and, therefore, would get "Too many READs in effect" in
short order.  FoxPro supports a maximum of five READ levels.

2.      Because the procedure MENUHIT is contained within EX1.MPR.  EX1.MPR
is not a part of EX1.PRG; the IN EX1.MPR clause must be included to tell
EX1.PRG where to look for the MENUHIT procedure.

3.      It's found in the STOPREAD procedure which is evaluated each time an
application window is DEACTIVATEd.  The window name is passed to
STOPREAD.  If the window isn't visible, (i.e., closed either manually or
by clicking on its close box) the control panel is displayed.  .T. is
returned by STOPREAD if the window is involved in the READ, otherwise
.F. is returned (a FoxPro system window was closed).

4.      There are at most three READs active:  the Foundation READ, one of
the application READs, and a READ MODAL associated with either BROWSER
or FINDER.

5.      The procedure named EFFACE, which is called in the cleanup code for
each application screen, insures that when the last application window
is closed the control panel is released.

        EFFACE is called when either the Quit button has been pressed, or a
READ window has been manually closed by clicking the mouse on the close
box or by selecting the Close option from the File menu popup.

        EFFACE looks through all the windows that are open, from back to front.
If it finds any of the user application windows (which require the
control panel) it simply exits.  Otherwise, it concludes you're finished
with the control panel and releases it.

6.      The application READ is terminated because its DEACTIVATE clause
returned .T., but the Foundation READ remains active.

7.      The Foundation READ is still active.

8.      The first application's DEACTIVATE clause returns .T., thereby
terminating that application's READ.  Termination of the application's
READ triggers the Foundation READ's VALID clause routine.

        This routine, called MYHANDLER, uses WONTOP() to return the name of the
application window where the mouse was clicked, and the screen program
(.SPR) for that window is executed.

+---------------------------------+
|             Examples            |
+---------------------------------+
**** OBJECT clause example

STORE 1 TO radio
STORE SPACE(10) TO name
CLEAR
@ 2,2 SAY 'Enter a name: ' GET name
@ 4,2 GET radio PICTURE '@*R Apples;Oranges;Lemons'
READ CYCLE OBJECT 3

-----------------------------------

See Also:  @ ... SAY/GET, CLEAR, RDLEVEL(), .  READ with Multiple
Windows, READKEY(), SET CONFIRM, VARREAD(), USER-DEFINED FUNCTIONS
(UDFs), SYS(2016) SHOW GETS WINDOW, WREAD()

-----------------------------------