The FxuInstance class is meant to provide all internal components of the FoxUnit application with common and consistent information as well as functionality (e.g. the FoxUnit class factory). Information is delivered through properties, functionality comes
as a set of methods.
The most common way of use is to instantiate an object of this class in FXU.PRG and then pass it to the other objects created there (e.g. instances of the FoxUnit main form or the test broker). The main motivation to introduce this class was to avoid the need
of changing environment settings from inside FoxUnit, especially SET PATH and SET PROCEDURE, but also SET UDFPARMS. The common functionality provided here isn't all new. Before, it was provided through functions in FXU.PRG and FxuNewObject.prg. The bad thing
about functions in PRGs is that the location of the file might need to be known and managed before you call them (depends on whether the file is in the program cache or not). However, the VFP compiled program cache cannot be managed reliably (see documentation
of CLEAR PROGRAM in the VFP help) and even CLEAR ALL cannot help out, despite the fact that doing a CLEAR ALL while running tests might not be the best choice at all. So having a FxuInstance object in place makes the need of managing PRG files and changing
any environment setting obsolete while still having the full feature set available.
The following functions have become obsolete through the introduction of the FxuInstance class:
| FXU.PRG/ManageFxuClassFactory() | Has been moved to the FxuInstance.ManageFxuClassFactory() method. It has been made sure that every line of code where this function was used before now has an FxuInstance object available and uses the FxuInstance.ManageFxuClassFactory() method. |
| FXU.PRG/GetTestsDir() | The logic provided here has been included in the getter of the FxuInstance.DataPath property. It has been made sure that every line of code where this function was used before now has an FxuInstance object available and uses the FxuInstance.DataPath property. |
| FXU.PRG/CheckPath() | Functionality has been moved to the FxuInstance.Init() event. All code lines calling this function have been removed. |
| FxuNewObject.prg | All code has been adapted in the FxuClassFactory.FxuNewObject() method. |
GetFoxUnitPath() is a new method which creates a single place where the FoxUnit Path can be evaluated immediately on startup of FoxUnit. It is called by the multiple functions that instantiate FxuInstance objects and which all are placed in FXU.PRG as well.
GetFoxUnitPath() is not meant to be called from outside FXU.PRG.
The FxuInstance class is not maintained by the FoxUnit class factory because it actuallyis the FoxUnit class factory now.
Initialization
Some information needs to be passed to the Init() event to get stored in the object and therefore made available to all components using it:
| tcVersion | The version information of the FoxUnit application. This parameter is mandatory and must not be empty. It can be passed using the C_Version constant in FXU.PRG directly. The value provided in this parameter is stored in the Version property. |
|---|---|
| tcFoxUnitPath | The FoxUnit Path used throughout the instance. It can be evaluated using FXU.PRG/GetFoxUnitPath(). The tcFoxUnitPath parameter is mandatory and will be checked during initialization. If the path provided in tcFoxUnitPath doesn't exist, the object won't be created. If it is not in the VFP search path configuration, a message will be shown (if ASSERTS is set to ON), but the object will not be prevented from being created. If the checks are ok, the value will be stored and can be retrieved through the FoxUnitPath property. |
| toProject | A reference to a VisualFoxPro.IFoxProject object. This parameter is optional. If supplied, the reference will be stored in the Project property for later use. The behavior of certain methods and property getters depends on whether there is an object reference in the Project property or not. |
Properties
| FoxUnitPath | Read-only, must be initialized during Init() event. Returns the FoxUnit Path. |
| DataPath | Read-only. Returns the FoxUnit Data Path. If a reference to a project exists in the Project property, the FoxUnit Data Path will point to the subdirectory Tests of the project's home directory. Otherwise it will point to the subdirectory Tests of the currently active project's home directory. |
| Version | Read-only, must be initialized during Init() event. Returns the version of the currently running instance of FoxUnit. |
| Project | Read-only, optional, can be initialized during Init() event. Is .NULL. by default. |
| UserId | Read-only. Returns the user name of the currently logged on user (retrieved from SYS(0)). For performance reasons, the user id is evaluated only once on the first access to this properties' value, and then cached for subsequent access operations. |
| DataSessionId | Read-write. Sets or returns the data session id all data related operations performed in FxuInstance should work in. This is essential when using private data sessions in forms like frmfoxunit, e.g. if the class factory instantiates classes that open tables that are expected to be 'seen' by the form that requested the object creation. This problem didn't exist before because the class factory was located in a PRG (for more information on this common trap see this post in Ricks blog: http://rickschummer.com/blog/2007/08/understanding-session-object-behavior.html). |
Methods
| ManageFxuClassFactory() | Creates / updates the FoxUnit class factory table and returns a logical expression indicating success. Automatically called during Init() event. |
| FxuNewObject() | Creates and returns an object by class id, or .NULL. on failure. |
| IsInPathConfig() | Checks if the path specified in parameter tcPath is included in the VFP search path configuration (SET PATH) and returns a logical expression indicating if this is the case. This method does not check if the path exists. |
| WriteDebug() | Writes the information passed in parameters tcLocation and tcMessage to the debug output window. [Subject to be extended in the future to write to default debugger using OutputDebugString()-API when running as COM-Server-DLL - VS UnitTests attach debugger and can collect info separately from tests. |