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.
- Techniques, tips, and tricks using ENV you’ve found useful that we can add to this documentation
- 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.
File / DescriptionEnvLib.prg / Program class definitions
Env.vcx / Use TRUE's PrgToVcx to convert EdcLib.prg to a visual class library
True.h / Named constant definitions (required by all TRUE libraries)
Env.doc / Documentation in Word 6.0 format
True.dot / Word 6.0 template file used by all TRUE documentation
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
- Visual FoxPro for Windows, version 3.0 or greater.
- 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.
Description / Prefix / ExampleConstant (#DEFINE) / c / ccERR_PROMPT
Constant Type
We use VFP variable naming conventions for our constant data type. In addition, we add the following for literal string constants.