GENSCRNX 2.0



INTRODUCTION


GENSCRNX.PRG extends the control of code generated from FoxPro's
screen builder. After Generate... is selected when using the Screen
Builder, GENSCRNX first copies the .SCX database and then updates it
based on comments in the snippets and setup code. Also, GENSCRNX
places the .SPR into a memo field after its created to make possible code
changes and/or replacements after GENSCRN. The ability to define
each object into a global database called FOXSCX.DBF is performed
when a define object directive is placed in an object's comment code.
The FOXSCX.DBF contains the same structure as FoxPro's .SCX files
except has added fields for object name, field, library, and other objects
that it bases from. New screens can be created without snippet code by
simply placing a base object directive in the comment snippet with the
appropriate name. GENSCRNX updates the .SCX before passing it to
GENSCRN. Drivers can be defined in the CONFIG.FP and screen Setup
snippet code. Every driver is called once for each record in the .SCX
before GENSCRN generates code. The driver may update the .SCX
database with no limitations. Objects can be manipulated or replaced by
pure FoxPro code using a driver procedure. GENSCRNX handles the
code replacements to the .SPR. A driver may use pre-made functions
contained in GENSCRNX which handle the .SCX record update for code
replacement, template insertion, and other .SCX update functions. A
DEFINE WINDOW command can be inserted in the .SPR between the
GET/SAY fields in the Screen Layout section.. Multiple drivers may also
be selected for functions such as 3D effects or auto insertion of push
buttons (Next, Previous, Append, Delete, etc.). GENSCRNX is entirely
written in FoxPro and fully compatible with FoxPro 2.0 and FoxPro
2.5/2.6 (all platforms). The FOXSCX library database can be updated
when referenced by FoxPro 2.0 and/or FoxPro 2.5/2.6 for MS-DOS
without any conversion. FoxPro 2.5/2.6 for MS-DOS MS-DOS
applications can be built by referencing objects created with FoxPro 2.0
and vice versa. The FOXSCX.DBF database can contain records for
FoxPro 2.5/2.6 (all platform) while GENSCRNX automatically handles the
record relation between platforms.

Notes:
CONFIG.FP relates to FoxPro 2.0 and FoxPro 2.5/2.6 DOS.
CONFIG.FPW relates to FoxPro 2.5/2.6 Windows.




FEATURES


- Extended control over FoxPro's Screen Builder without changing
GENSCRN. GENSCRNX can be though of as a When and Valid for
GENSCRN.

- Option for compiling the output file when generating from the Screen
Builder.

- Option for displaying the .SPR and .ERR files if an .ERR file is
generated after compiling the output file when generating from the
Screen Builder.

- Ability to store screen objects into a database library.

- Ability to retrieve screen objects from a database library with support of
multiple inheritance (expressions are separated by .AND. while
procedures are appended).

- Option to set Read level settings (OpenFiles, CloseFiles, Modal,
OutFile, etc.) from with the screens setup that override the Generate
dialog checkboxes. This allows settings to be saved with the screen
without using a project.

- Ability to insert records contained in a separate .SCX file at compile
time. All records row and column information is automatically adjusted.
This allows subforms to be inserted without copy and paste. If the
inserted screen is updated, the screen importing it can be re-generated
without change.

- Ability to insert FoxPro code in place of any screen object. This allows
a line or multiple lines of FoxPro code to be generated between GET
commands in the Screen Layout section.

- Ability to block a GET command with any IF/ENDIF statement.

- Ability to specify any SIZE clause and override the SIZE setting
defaulted by the Screen Builder.

- Ability to remove the SIZE clause from any GET command.

- Ability to create .PRG drivers that update the .SCX database at compile
time before GENSCRN is called. This allows external programs to be
created that automatically add, update, or remove code of any screen
snippet. Drivers can make function calls to many of GENSCRNX's built
in function library for parsing or insertion of .SCX information.

- Support for any expression to be evaluated at compile time using
{{}} in any snippet or field. GENSCRNX will evaluate at
compile time and replace {{}} with its result. If was an
external function and the command was placed in the Setup snippet, the
external function could act like a #INCLUDE function by returning multiple
lines of code.
Example:
If the following command was in the Setup snippet and assuming the
current date was 06/01/93:
WAIT '{{DATE()}}' WINDOW NOWAIT
the following code would be placed in the .SPR:
WAIT '06/01/93' WINDOW NOWAIT




INSTALLATION


After unzipping GENSCRNX.ZIP, copy GENSCRNX.PRG to all existing
FoxPro 2.x directories

Change all CONFIG.FP and CONFIG.FPW files to:

_GENSCRN="GENSCRNX.PRG"

MVCOUNT=512

Notes:
If MVCOUNT is already set to a number greater than 512, then do not
change it. If MVCOUNT is set to a number less than 512, then change
the number to 512. If a line containing MVCOUNT does not exist, then
create one as above.




CONFIG.FP/CONFIG.FPW OPTION SETTINGS


_GENSCRNX

Specifies program to generate .SPR file from .SCX database.

Default:
_GENSCRNX="GENSCRN.PRG" in FoxPro start directory

Example:
_GENSCRNX="C:\MYDIR\MYGENSCN.PRG"

Notes:
When _GENSCRN="\GENSCRNX.PRG", then
_GENSCRNX is used to specify which program is used to generate
screen code. If _GENSCRNX is not specified in the
CONFIG.FP/CONFIG.FPW, the default setting is GENSCRN.PRG
located in FoxPro's start-up directory.


_FOXSCX

Specifies database used for object library records.

Default:
_FOXSCX="FOXSCX.DBF" in FoxPro start directory

Example: _FOXSCX="C:\MYDIR\FOXSCX.DBF"

Notes:
It is recommended that all FoxPro 2.x CONFIG.FP/CONFIG.FPW contain
the same _FOXSCX setting.


_SCXDRV1

Specifies global driver program.

Default:
_SCXDRV1=""

_SCXDRV1 to _SCXDRV8

Specifies global driver program. The numbers 1-8 represent various
driver hooks throughout GENSCRNX while the .SCX databases is being
generated.

Example:
_SCXDRV5="C:\3DFOX\3D"


_SPRDRV1

Specifies global driver program.

Default:
_SPRDRV1=""

_SPRDRV1 to _SPRDRV6

Specifies global driver program. The numbers 1-6 represent various
driver hooks throughout GENSCRNX while the .SPR file is being
updated.

Example:
_SPRDRV1="C:\MYDIR\SPRUPD1"


GENSCRNX

Specifies GENSCRNX functions enabled (ON) or disabled (OFF).

Default:
GENSCRNX=ON


COMPSPR

Specifies auto-compilation of .SPR file. A public variable called
_COMPSPR to override the COMPSPR setting.

Default:
COMPSPR=OFF

Important:
This setting is ignored during screen building from projects.


DISPSPR

Specifies auto-display of .SPR and .ERR files if an .ERR file is exists. A
public variable called _DISPSPR to override the DISPSPR setting.

Default:
DISPSPR=OFF


Important:
DISPSPR=ON may cause a file sharing error when SHARE.EXE is
installed.




SETUP SNIPPET DIRECTIVE REFERENCE


#:SECTION 3

Used in Setup snippet (like #SECTION 1 | 2) to insert code after GETs
and before READ in the Screen Layout.


*:AUTORUN [SAVE]

Automatically releases screen after generation and executes generated
file. *:AUTORUN is automatically disabled if either a compiled file is not
properly generated or a compile error was detected via the
COMPSPR=ON. If SAVE is included, .SPR will be executed without
closing the .SCX in the screen builder.


*:COMPSPR

Overrides COMPSPR=OFF in CONFIG.FP/CONFIG.FPW.


New: *:DISPSPR

Overrides DISPSPR=OFF in CONFIG.FP/CONFIG.FPW.


*:SET OPENFILES ON | OFF

Open files.

Example:
*:SET OPENFILES ON


*:SET CLOSEFILES ON | OFF

Close files.


*:SET DEFWINDS ON | OFF

Define windows.


*:SET RELWINDS ON | OFF

Release windows.


*:SET READCYCLE ON | OFF

Read cycle.


*:SET MULTREADS ON | OFF

Multiple READs.


*:SET NOLOCK ON | OFF

READ nolock.


*:SET MODAL ON | OFF

Modal.


*:SET PLATONLY ON | OFF

Current platform objects only. If this setting is ON, GENSCRN will not
generate code for other platform code but GENSCRNX will still process
all platform records. Setting PLATONLY='ON' in the
CONFIG.FP/CONFIG.FPW files will cause GENSCRNX to not pre or
post process other platform records. See ADDITIONAL INFORMATION
section below for controlling this setting using a public variable.


*:SET BORDERGETS ON | OFF

Border for GETs.


*:SET ASSOCWINDS TO

Assoc. windows list. The is appended to Assoc.
windows list from screen or project.

Example:
*:SET ASSOCWINDS TO Calculator,Calendar


*:OUTFILE

Output file name. *:OUTFILE is disabled when building screen from a
project.

Example:
*:OUTFILE TEST.PRG


*:PRG

A Setup snippet directive called *:PRG that is used to automatically
change the .SPR extension to a .PRG extension and also add the
#NOREAD PLAIN directive to the Setup snippet. The *:PRG directive
used in conjunction with screen objects with the *:INSTXT directive will
allow a .PRG file to be created that has no GETs, SAYs, or READ, while
the screen builder Object Order controls the order of the FoxPro source
code generated in the .PRG file. When building a screen from a project,
the *:PRG directive is ignored since the project expects that file specified
in the project to be generated and will abort project generation if the
project specified file is not created..


*:PJXSET

Place in the Setup snippet before the *:PRG directive or any *:SET
directive to force the project information to have priority settings when
building the screen from a project.

Example:
If the following was in the Setup snippet of a screen:

*:SET MODAL ON
*:PJXSET
*:SET READCYCLE OFF

Then if the screen was generated from the Screen Builder, the READ
would contain the clauses MODAL and CYCLE no matter what the check
box settings were set to before selecting . If the screen was
generated from a project, the READ would contain MODAL no matter
what the settings were set to in the project but the CYCLE setting would
be set to whatever the project setting was set to.


*:SCREENSET

Multi-screen set without using project or selecting screens manually from
the Generate dialog.

Example:
To build a screen set using the second and third screen as SCX2.SCX
and SCN3.SCX, place the following in the Setup snippet:

*:SCREENSET SCN2
*:SCREENSET SCN3


*:BRACES

Overrides a CONFIG.FP/FPW setting of BRACES=OFF.


*:NOBRACES

Turns off the auto braces detection for GENSCRNX. By default,
GENSCRNX automatically searches all snippets for any {{}}
expressions to be evaluated. For screens with many objects, this could
result in a few seconds overhead depending on the speed of the
computer being used. Using *:NOBRACES will force GENSCRNX to
only evaluate snippets if *:EVLTXT is in the Comment snippet (or Setup
snippet for the header record). Overrides a CONFIG.FP/FPW setting of
BRACES=ON.


*:IGNOREBRACES

Ignores all {{}} expressions. *:IGNOREBRACES cane only be
declared in the Setup snippet and overrides *:BRACES and
*:NOBRACES.


*:SCNOBJ

Enables the invisible button m.scnobjn above to be generated. Although
it is generated by default, *:SCNOBJ can be used to override a
SCNOBJ=OFF setting in the CONFIG.FP/FPW files.


*:NOSCNOBJ

Disables the invisible button m.scnobjn above to be generated.
*:NOSCNOBJ can be used to override a SCNOBJ=ON setting in the
CONFIG.FP/FPW files. *:NOSCNOBJ is automatic when either the
#NOREAD directive exists in the Setup snippet or no GET objects exist
for the screen.


*:DEFLIB

Defines library name. *:DEFLIB can be used with stand alone screens
only and cannot be used with screens in a screen set. Do not use
*:DEFLIB with screens in a project that contains other screens not using
*:DEFLIB.


*:INCLIB

Includes library in base object search path.


*:BASLIB

Base library objects for field name match.


*:SAVESIZE

Used with *:DEFOBJ in a library object to force the SIZE information to
be retrieved fromt he library when the object is based in a screen.


*:SAVEPICT

Used with *:DEFOBJs to force the PICTURE information to be retrieved
from the library when the object is based in a screen.


*:BASBEFORE

Used with *:DEFOBJ in a library object to force any inherited expressions
or procedures to be inserted before rather than appended after to any
screen surface code.


*:SCXDRV1

Specifies screen driver program.


*:SCXDRV1 to *:SCXDRV8

Specifies screen driver program. The numbers 1-8 represent various
driver hooks throughout GENSCRNX while the .SCX databases is being
generated.


*:SPRDRV1

Specifies screen driver program.


*:SPRDRV1 to *:SPRDRV6

Specifies screen driver program. The numbers 1-6 represent various
driver hooks throughout GENSCRNX while the .SPR file is being
updated.


*:MEMVAR

Replaces all aliases in GET name from alias.variable to m.variable. All
alias.variable names referenced in the When, Valid, Error, Message,
Range Lo, Range High snippets will be replaced with m.variable.


*:NAME

The following example demonstrates how *:NAME affects FoxPro
2.5/2.6's #NAME directive.

#NAME v_show

is changed to

#NAME v_showd && _DOS=.T.
#NAME v_showw && _WINDOWS=.T
#NAME v_showm && _MAC=.T.
#NAME v_showu &&_UNIX=.T.

The above changes will occur before GENSCRN is called.
Then, a function is appended to the Cleanup snippet as follows:

FUNCTION V_SHOW

DO CASE
CASE _DOS
RETURN V_SHOWD()
CASE _WINDOWS
RETURN V_SHOWW()
CASE _MAC
RETURN V_SHOWM()
CASE _UNIX
RETURN V_SHOWU()
ENDCASE
RETURN .F.

FUNCTION V_SHOWM
RETURN .F.

FUNCTION V_SHOWU
RETURN .F.

This will result in the exact same code execution as if a CASE _DOS,
CASE _WINDOWS, etc. was generated in the snippet. The only rule is
that *:NAME uses only the first 9 characters of the snippet name
specified. The 10th character is used for the platform character. Also,
any PARAMETER statement that follows the #NAME in the snippet will
be properly handled in the cross-platform function that is generated. The
only rule here is that the PARAMETER statements must be identical for
all platforms having the same #NAME definition.


*:NOGEN

Prevents GENSCRN from being called so that no .SPR file is generated.
*:NOGEN should be used with templates since templates do not need
code to be generated.


*:NOXGEN

Prevents GENSCRNX from updating .SCX database and .SPR file.



*:GENSCRNX

Used to specify which program is used to generate screen code.
*:GENSCRNX overrides any _GENSCRNX in the CONFIG.FP and
CONFIG.FPW files. If both *:GENSCRNX and _GENSCRNX are
notspecified, the default setting is GENSCRN.PRG located in FoxPro's
start-up directory. *:GENSCRNX can be used to specify a modified
GENSCRN needed for a particular screen rather than changing
_GENSCRN before generating a screen.


*:NOCOMPSPR

Overrides COMPSPR=ON in CONFIG.FP/CONFIG.FPW.


*:NODISPSPR

Overrides DISPSPR=ON in CONFIG.FP/CONFIG.FPW.


*:NOWCLAUSES

Removes a list of clauses from the DEFINE WINDOW command of a
screen. Any list of clauses can be removed (except COLOR) by listing
the name of each clause separated by a space delimiter.

Example:
Add following line in the Setup snippet to remove all FROM, TO, AT,
SIZE, FONT, and STYLE clauses will be removed from the DEFINE
WINDOW command:

*:NOWCLAUSES FROM TO AT SIZE FONT STYLE

To directly add any of the removed clauses, use GENSCRN's
#WCLAUSES directive.

Example:
Add following lines in the Setup snippet to add a custom AT
SIZE :

*:NOWCLAUSES AT SIZE
#WCLAUSES AT 1,1 SIZE 10,30

or

*:NOWCLAUSES AT SIZE
#WCLAUSES AT {{VPOS}},{{HPOS}} SIZE {{HEIGHT}},{{WIDTH}}

Note:
The {{}} evaluates any expression and replace its result as source
code. In the above example, the field names are referencing the .SCX
header record which contains the screen layout window data.

Example:
Add following lines in the Setup snippet to add a custom FONT
STYLE :

*:NOWCLAUSES FONT STYLE
#WCLAUSES FONT m.myfontface STYLE m.myfontstyl


*:DRVOFF

Specified in the Setup snippet to disable any driver setting that is
specified in the CONFIG.FP/CONFIG.FPW. The number of *:DRVOFF
directives specified in the Setup snippet is unlimited and the files included
are retained for all screens in a screen set. If *:DRVOFF is specifed in
the Setup snippet in a screen set, then all screens following in that screen
set will inherit the *:DRVOFF for the specified driver.

Example:
If the 3D.PRG is specified in the CONFIG.FPW as
_SCXDRV5="3D.PRG", for the 3D driver to be executed globally for
every screen, then specifying *:DRVOFF 3D in the Setup snippet would
disable the 3D driver for that screen.


GENSCRNX creates comments in the Setup snippet as that include the
the following information at compile time.

Example:
* This program was preprocessed by GENSCRNX.
*--GENSCRNX 1.7
*--Screen C:\SAMPLE\CUST2.SCX
*--Project C:\SAMPLE\SAMPLE.PJX
*--FOXSCX C:\FOXPRO25\FOXSCX.DBF
*--Platform DOS
*--Time 08/25/93 20:29:46




COMMENT SNIPPET DIRECTIVE REFERENCE


*:DEFOBJ