Environment (ENV) Class Library for Visual Foxpro 3.0

Fehler! Formatvorlage nicht definiert.Fehler! Formatvorlage nicht definiert.1

Environment (ENV) Class Library

for Microsoft Visual FoxPro 3.0

Another TRUE Public Domain Enhancement for Visual FoxPro

Tom Rettig’s Utility Extensions (TRUE) are developed by Rettig Micro Corporation; designed, implemented, and documented by Tom Rettig; and tested and quality assured by Tom Rombouts.

The author and copyright holder release all rights in TRUE programs, structures, and documentation to the public domain subject to the Warranty Disclaimer below. Although they are in the public domain, we maintain and upgrade them regularly because they are relied upon in commercial software products from our company and many others.

Other TRUE class libraries include Program To Visual (PrgToVcx) that converts program class libraries like this one to visual class libraries in VCX files, Extended Database Container (EDC) that extends VFP’s database container and lets you define properties for any logical view, and Info that gathers various FoxPro information. We hope you find TRUE useful and welcome any comments you may have.

Rettig Micro Corporation (RMC)

2532 Lincoln Boulevard, Suite 110

Marina del Rey, CA 90291-5978

Fax: 310-821-1162

CompuServe: 75066,352 in the Microsoft FOXUSER forum’s 3rd-Party section or CIS MAIL

Telephone: 310-301-0911

Product Information: 800-742-7843

TRUE Warranty Disclaimer: No Warranty!

THE AUTHOR RELEASES TO THE PUBLIC DOMAIN ALL CLAIMS TO ANY RIGHTS IN THIS PROGRAM AND DOCUMENTATION, AND FREELY PROVIDES THEM “AS IS” WITHOUT WARRANTY OF ANY KIND, EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT SHALL THE AUTHOR, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THIS PROGRAM AND DOCUMENTATION, BE LIABLE FOR ANY COMMERCIAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM INCLUDING, BUT NOT LIMITED TO, LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR LOSSES SUSTAINED BY THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS, EVEN IF YOU OR OTHER PARTIES HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

Commercial Product Information

If you have serious application needs, you will find our commercial software very helpful and we would be delighted to send you our product information. Since 1991, Rettig Micro Corporation has developed and published Tom Rettig's Office (TRO), a suite of rapid application development (RAD) tools for FoxPro plus an integrated business application including accounting and full source code. TRO's pre-written programs, menus, forms, and reports implement a generic, reusable “foundation” for FoxPro on top of which you easily build all kinds of applications in record time. TRO for Visual FoxPro is a rich collection of class libraries, builders, wizards, and projects, fully object oriented, and takes maximum advantage of new VFP features to get your application up and running faster than any other tool on the market, guaranteed! TRO for FoxPro 2.6 is a complete cross-platform solution running under Microsoft Windows, MS-DOS, Macintosh, and UNIX as a single code base written in 100% pure FoxPro using the FoxPro design tools and unmodified templates. Visual or cross-platform, TRO is the most reliable, robust, and fully-featured FoxPro development environment money can buy with megabytes of functionality ready to use right out of the box. Contact us today for complete product literature and discover why thousands of developers worldwide, including the largest corporate and government organizations, trust their applications to TRO.

Technical Support

Technical support is not officially provided because all TRUE software is free. However, the author is very interested in hearing about bugs, usability problems, or enhancement requests you may have and will try to be helpful within reasonable limits. All TRUE support is handled in writing via CompuServe, fax, or postal mail. TRUE support is not available by telephone.

Acknowledgments

The author appreciates acknowledgment in commercial products and publications that use or learn from TRUE software. The author acknowledges the following people for their contributions.

• Dave Fulton and Bill Gates for the vision and the tenacity to make it reality.
• Janet Walker, Glenn Hart, and Tod Neilson for keeping the vision alive and the community together.
• Eric Rudder and Morris Sim for the VFP design. Erik Svenson for the database design and extensibility.
• The entire VFP development team for the implementation.
• Susan Graham and all the beta sysops for the hard work, long hours, and patience while we learned.
• Richard McAniff and all the program and product managers for the goal to make VFP the very best.
• Dawn Trudeau for making the vision salable.
• Tom Kemm and David Kalman for teaching and promoting relational database design in FoxPro before it became fashionable.
• George Goley, Alan Schwartz, Y. Alan Griver, Mike Feltman, Doug Hennig, and all other 3rd-party data dictionary developers for doing it at least once from scratch.
• Ken Levy for contributing code and ideas to make PrgToVcx work with VFP’s Class Browser, and the suggestion for EDC to write directly to the DBC.
• Andy Neil for ideas about EDC’s registry.
• Drew Speedie for a beta forum Tip Of The Day that inspired EnvLib.
• Lisa Slater Nicholls for ENV saving properties and system memory variables, and for creating resource files.

About Tom Rettig

Tom Rettig is President and Software Architect of Rettig Micro Corporation. He worked on the design and implementation of dBASEIII as a member of Ashton-Tate's development team, independently wrote the original Clipper Extend Library, and released two award-winning software products, Tom Rettig’s Library and Tom Rettig’s Help. Since 1990, his products, including Tom Rettig’s Office are exclusively for FoxPro and Visual FoxPro.

An Xbase evangelist since 1981, Tom is internationally recognized as an authority on the language and its various dialects and implementations. He presents at computer shows and user groups, contributes to magazines and the public domain, has written several books, is active on Microsoft’s FoxPro forums, participates in FoxPro pre-release programs, and has presented at every Microsoft FoxPro DevCon.

Fehler! Formatvorlage nicht definiert.Fehler! Formatvorlage nicht definiert.1

Table of Contents

Environment (ENV) Class Library

for Microsoft Visual FoxPro 3.01

Another TRUE Public Domain Enhancement for Visual FoxPro1

TRUE Warranty Disclaimer: No Warranty!1

Commercial Product Information1

Technical Support2

Acknowledgments2

About Tom Rettig2

Table of Contents3

User’s Guide7

Getting Started7

Advanced Features8

Your Contributions are Important!8

Developer’s Guide9

New in This Release9

Cross Platform9

Default Values9

Documentation9

Enhancements9

Errors9

Files10

Requirements10

Technical Reference11

How ENV Works11

Named Constants: True.h11

Naming Conventions11

Constant Scope11

Constant Type11

General11

Objects11

Language Reference12

Abstract Classes12

On Class12

SaveArea Class12

SaveUsedArea Class12

Set Class12

SetOnOff Class13

SetOnOffTwo Class13

SetTwo Class13

ON Classes13

OnError Class13

OnKey Class13

OnKeyLabel Class14

OnShutdown Class14

Property Classes14

SaveProperty Class14

SetProperty Class14

SET Classes15

SetAlternate Class15

SetAnsi Class15

SetAutoSave Class15

SetBell Class15

SetBlockSize Class16

SetBrStatus Class16

SetCarry Class16

SetCentury Class16

SetClassLib Class16

SetClear Class17

SetClock Class17

SetCollate Class17

SetColor Class17

SetCompatible Class17

SetConfirm Class18

SetConsole Class18

SetCpCompile Class18

SetCpDialog Class18

SetCurrency Class18

SetCursor Class19

SetDatabase Class19

SetDataSession Class19

SetDate Class19

SetDebug Class20

SetDecimals Class20

SetDefault Class20

SetDeleted Class20

SetDelimiters Class20

SetDevelopment Class21

SetDisplay Class21

SetDoHistory Class21

SetEcho Class21

SetEscape Class21

SetExact Class22

SetExclusive Class22

SetFdow Class22

SetFixed Class22

SetFullPath Class22

SetFweek Class23

SetHeadings Class23

SetHelp Class23

SetHelpFilter Class23

SetHours Class23

SetIntensity Class24

SetKeyComp Class24

SetLibrary Class24

SetLock Class24

SetLogErrors Class25

SetMargin Class25

SetMacKey Class25

SetMark Class25

SetMemoWidth Class25

SetMessage Class26

SetMultiLocks Class26

SetNear Class26

SetNotify Class26

SetNull Class26

SetOdometer Class27

SetOleObject Class27

SetOptimize Class27

SetPalette Class27

SetPath Class27

SetPoint Class28

SetPrinter Class28

SetProcedure Class28

SetReadBorder Class28

SetRefresh Class28

SetReprocess Class28

SetResource Class28

SetResourceCreate Class28

SetSafety Class28

SetSeconds Class28

SetSeparator Class28

SetSpace Class28

SetStatus Class28

SetStatusBar Class28

SetStep Class28

SetSysFormats Class28

SetSysMenu Class28

SetTalk Class28

SetTopic Class28

SetTrBetween Class28

SetTypeAhead Class28

SetUdfParms Class28

SetUnique Class28

SetVfpDefaults Class28

SetView Class28

SetWindowOfMemo Class28

System Variable Classes28

SetSysVar Class28

Table Classes28

SaveAllTables Class28

SaveBuffering Class28

SaveFilter Class28

SaveOrder Class28

SaveRecno Class28

SaveRelation Class28

SaveSelect Class28

SaveTable Class28

SetBuffering Class28

SetFilter Class28

SetOrder Class28

SetRelation Class28

SetSelect Class28

Timer Classes28

MessageTimer Class28

Exposed Properties28

Exposed Methods28

GetDefault() Method28

GetDefaultTwo() Method28

GetDescending() Method28

GetLabel() Method28

GetNew() Method28

GetNewTwo() Method28

GetOld() Method28

GetOldTwo() Method28

GetSelect() Method28

Revert() Method28

SetIntervalDefault() Method28

SetMessage() Method28

Update() Method28

Protected Properties28

Protected Events28

Destroy() Event Procedure28

Init() Event Procedure28

Protected Methods28

CreateResource() Function28

Fehler! Formatvorlage nicht definiert.Fehler! Formatvorlage nicht definiert.1

User’s Guide

You use ENV whenever you want to save something, change it, and restore it. Most often, we need to do this with VFP’s SET and ON commands and open table settings. Additionally, we may need to do it with system memory variables or an object’s exposed properties. ENV’s object oriented design lets you do what you need in most cases with just one line of code. Once you get used to it, you’ll never want to go back to the old way.

* Old way.

PROCEDURE Foo

LOCAL llSetExact

llSetExact = SET("EXACT")== “ON"

SET EXACT OFF

<code here>

IF llSetExact

SET EXACT ON & or worse, use a macro

ENDIF

ENDPROC

* New way.

PROCEDURE Foo

LOCAL loSetExact

loSetExact = CREATEOBJECT("SetExact", "Off")

<code here>

ENDPROC

ENV classes save the current setting and set the new one in their Init events. The saved setting is restored in their Destroy event, so this happens automatically when the procedure returns and its object variable goes out of scope. To reset within the procedure, you can simply RELEASE or store .NULL. to the object variable.

RELEASE loSetExact

loSetExact = .NULL.

Each ENV SET class takes the same syntax as follows.

cValue1 [, cValue2] [, lNoReset]

In addition to saving and restoring SET, ON, and open Table environment, ENV has classes to handle an object’s exposed properties and Visual FoxPro’s system memory variables.

loSaveProp = CREATEOBJECT("SaveProperty", _SCREEN)

loSetProp = CREATEOBJECT("SetProperty", _SCREEN, "Caption", "Some Name")

loSetVar = CREATEOBJECT("SetSysVar", "_LMARGIN", 15)

Getting Started

We use all the VFP naming conventions as documented in VFP’s Windows Help file in the Technical Reference under Programming. In addition, we add a few of our own conventions that are defined in our Technical Reference under Naming Conventions. You’ll understand this material more easily if you look up any conventions that you don’t know.

The ENV class definitions are stored in EnvLib.prg and Env.vcx. They contain the exact same information. The .PRG file is the programmatic definition and the .VCX file is the visual definition. You only need one or the other to instantiate an object from the ENV class. Both of the definition files require the named constant file, True.h, at compile time. Env.vcx is not shipped with EnvLib.prg. Use TRUE’s PrgToVcx to convert EnvLib.prg to a visual class library.

* Using program class.

SET PROCEDURE TO EnvLib.prg ADDITIVE

oEnv = CREATEOBJECT("SetMemoWidth", "100")

...

RELEASE PROCEDURE EnvLib

* Using visual class.

SET CLASSLIB TO Env.vcx ADDITIVE

oEdc = CREATEOBJECT("SetAlternate”, “ON”, “AltFile.txt")

...

RELEASE CLASSLIB EnvLib

All ENV Set and On classes know their VFP defaults. To set a setting to the VFP default, pass .NULL. in the value argument.

oEnv = CREATEOBJECT("SetDecimals", .NULL.)

To set a setting and not have it reset, pass the optional lNoReset argument a logical true. This also prevents the object from being created because there is nothing left for the Destroy event to do, so no variable is needed to hold the object reference.

=CREATEOBJECT("SetDecimals", .NULL., .T.)

Some ENV Set classes take two settings and an additional argument for the second value. Both are optional.

oEnv = CREATEOBJECT("SetAlternate", "ON", "AltFile.txt")

oEnv = CREATEOBJECT("SetAlternate", "OFF")

oEnv = CREATEOBJECT("SetAlternate", , "NewFile.txt")

To set system memory variables, use the SetSysVar Class.

To save or set an object’s exposed properties, use the SaveProperty Class and SetProperty Class.

Advanced Features

You can do even more with advanced ENV classes.

To set all the VFP defaults, use SetVfpDefaults Class.

oDefaults = CREATEOBJECT("VfpDefaultSet")

To set all the VFP defaults and not have them reset, pass the optional lNoReset argument a logical true.

=CREATEOBJECT("VfpDefaultSet", .T.)

See Default Values in the Developer's Guide for more information on default values.

In addition to VfpDefaultSet, there are currently two other subclasses that treat groups of settings, SaveTable Class and SaveAllTables Class. SaveAllTables restores all dependencies first so relations and filters are not restored until all tables are reopened and their order is restored. Order is restored after all tables are opened in case they have key references to other tables.

To set a resource file and optionally create it if it doesn’t exist, use the SetResourceCreate Class.

To set a status bar message that times out, use the MessageTimer Class. Can you think of any other environmental places where this timer feature would be useful?

Your Contributions are Important!

We designed ENV to grow for its users and you can play an important part in that growth by sending us your contributions in the following three categories.

1. Techniques, tips, and tricks using ENV you’ve found useful that we can add to this documentation
2. ENV feature extensions that you’d like to see in a future release

All contributions in category number 1 must include either the TRUE Warranty Disclaimer: No Warranty! wording from page 1 or the following words, “This contribution is made to the public domain and ENV according to the published TRUE Warranty Disclaimer.”

All contributions must be in writing and sent to us via Email, fax, or snail mail to the following address. We will contact you for additional details and confirmation if we decide to publish it, and you will receive full credit for it.

ENV Contributions

Rettig Micro Corporation (RMC)

2532 Lincoln Boulevard, Suite 110

Marina del Rey, CA 90291-5978

Fax: 310-821-1162

CompuServe: 75066,352 in the Microsoft FOXUSER forum’s 3rd-Party section or CIS MAIL

Developer’s Guide

New in This Release

• System memory variable classes.
• Object property classes.
• Timer classes.

Cross Platform

Additional capability will be added as necessary when VFP is ported to other platforms.

• Path specs containing spaces have not been tested.

Default Values

Some default values make certain assumptions that can produce unexpected results in some environments. For example, the SetResource Class default assumes that a FoxUser.dbf file exists and will trigger an error if it does not. In this case, you can use the SetResourceCreate Class instead. In other cases, you might want to subclass our functions to contain different default values as in the following example.

DEFINE CLASS MySetExact AS SetExact

uDefault = "ON"

ENDDEFINE

Documentation

Documentation is provided in a Microsoft Word 6.0 file. This can be easily printed, translated, and/or written to a Rich Text Format (RTF) file for compilation into a Windows help file. Windows help formatting is under construction!

This document prints 27 pages.

This document uses Word bookmarks and REF fields extensively. If the document is changed, you should update all fields before printing or saving as RTF. To update all fields, Select All from the Edit menu and then press F9.

This document uses the True.dot template file.

Caution! This help file uses forward and backward quote marks “ ” in text including syntax. If you cut and paste any text with these marks into a program, you will get a syntax error unless you change these to straight quote marks " ".

Enhancements

These enhancements are either planned or under consideration for implementation in a future upgrade.

• Add all Visual FoxPro settings that need to be saved and restored.

Errors

No special error handling is employed. Any ENV error will trigger whatever ON ERROR routine or Error event is in effect at the time.

Files

These files make up this class library.

You may modify, subclass, and distribute any or all files in any form you like.

Only two files are required, True.h plus one of the class definition files, EnvLib.prg or the visual class library that you make with TRUE's PrgToVcx. You may distribute the source files if you wish, but you do not have to if they are compiled into your application.

Requirements

1. Visual FoxPro for Windows, version 3.0 or greater.
2. Compiling EnvLib.prg or Env.vcx requires the named constant file, True.h.

Technical Reference

How ENV Works

ENV classes save the current setting and set the new one in their Init events. The saved setting is restored in their Destroy event, so this happens automatically when the procedure returns and its object variable goes out of scope.

Each setting has its own class, and each class has a property that stores the setting’s default value. These are initially set up to be VFP’s defaults, and can be easily changed by subclassing.

ENV avoids using macro substitution whenever possible.

Named Constants: True.h

True.h includes FoxPro.h, plus it defines these groups of named constants.

• ENV control codes
• Constants used by other TRUE software

Naming Conventions

We use VFP naming conventions for everything. In addition, we add the following conventions.

Constant Scope

Constants are scoped to the precompiler at design time and do not have a run-time scope.

Constant Type

We use VFP variable naming conventions for our constant data type. In addition, we add the following for literal string constants.