Tasmanian Traders Class Libraries
Six class libraries were created for Tasmanian Traders. Some of the key decisions in developing Tasmanian Traders concerned the level at which certain functionality should be incorporated:
- The application level
- The form level
- The control level
Tastrade Sample: Application Class Functionality
A generic Application class, Application, was created in Tsgen.vcx with functionality generic to most applications. This class provides the following functionality:
- Saves the Visual FoxPro environment.
- Sets up the environment.
- Restores the original Visual FoxPro environment.
- Runs the main menu.
- Manages application toolbars.
- Manages the user login procedure.
- Manages forms.
A subclass of the Application class, Tastrade, in Main.vcx provides additional functionality specific to Tasmanian Traders:
- Displays the start up screen.
- Runs the initial component.
An object, oApp, is created in Main.prg from the Tastrade class.
The following sections list and describe the Application class functionality.
Save the Visual FoxPro Environment
The Application Class saves the Visual FoxPro environment when the application runs. The Visual FoxPro environment includes SET command settings such as PATH, TALK, CARRY, and so on. In the Init event of the Application class, code adds a new object to Application based on the Environment class in Tsgen.vcx. In the Init event of the Environment class, code stores the existing Visual FoxPro environment settings to properties of the class so that they can be restored later.
Code associated with the Init event also stores the caption of the main Visual FoxPro window to the cOldWindCaption property of the Application class. These stored settings are restored when an object based on the Application class is released.
Another environment factor in Visual FoxPro is the standard toolbars that are active when an application is run. The Application method ReleaseToolbars( ) stores the names of system toolbars as well as information about whether they were open or closed when the application was run.
Code associated with the Init event of the Application class also pushes the current system menu onto the menu stack so that it can be restored later.
Set Up the Environment
Other code in the Init event of the Application class establishes the run-time environment. This code:
- Calls the Set( ) method of the Environment class, which sets the class and procedure libraries, whether deleted records are displayed (CLASSLIB, PROCEDURE, DELETED), and other application-specific environment settings.
- Opens the database for the application.
- Calls the ReleaseToolbars( ) method to release all the system toolbars that were active when the application was run.
- Sets the window title of the main Visual FoxPro window to the value stored in the cMainWindCaption property of the Application class.
Restore the Original Visual FoxPro Environment
When the application quits, code in the Cleanup( ) method of the Application class restores the original caption of the main Visual FoxPro window, closes the database, clears windows, issues CLEAR EVENTS, restores the initial menu, and calls the ShowToolbars( ) method to reopen the Visual FoxPro system toolbars that were displayed before Tastrade.app was run.
When CLEAR EVENTS is issued, program execution continues beyond the READ EVENTS command and code in Main.prg releases oApp. When the Application object is released, the Destroy event of the Environment class occurs because it is a member of the Application class.
In the Destroy event of the Environment object, the Reset( ) method of the Environment object is called to restore the Visual FoxPro environment settings that were in effect when the Environment object was created.
Run the Main Menu and Establish the Event Loop
Additional code in the Application object runs the main menu associated with the application and establishes the event loop. The Do( ) method of the Application class is called in Main.prg as soon as the Application object is created. The Do( ) method runs the main menu program and issues READ EVENTS.
Manage Application Toolbars
The Application object also keeps track of application toolbars. A property at the form level indicates the toolbar to be associated with each form. Because there is only one toolbar in this application, this property setting is the same for all the forms in the application.
Forms in the application call the ShowNavToolbar( ) method of the Application class to display the toolbar. The application knows whether the toolbar already exists and shows it only when necessary, incrementing the nFormInstanceCount property.
The ReleaseNavToolbar( ) method of the application, called in the Destroy event of the forms, decrements the nFormInstanceCount property and removes the toolbar after the last form is released.
Manage the User Login Procedure
Most applications in which security is an issue provide some form of login procedure. To manage this procedure, the Login( ) method of the Application class calls the DoFormRetVal( ) method, passing the class name of the login screen. When the user logs in, a property of the Application class, cUserLevel, stores the user level for that user.
This property is used in the menu cleanup code to remove menu items that shouldn't be visible to a particular user.
Manage Forms
Except for the forms used in reports to set ranges of values for the reports, the forms in Tasmanian Traders are displayed through methods of the Application class. The DoForm( ) method accepts the name of a form and one parameter that can optionally be passed to the form. The DoFormRetVal( ) method accepts the name of a form class and returns a value specified in the form.
Display the Start Up Screen
The subclass of the Application class, Tastrade, in Main.vcx provides additional functionality specific to Tasmanian Traders. The Init event calls the parent class code in the Application class and, if the start up splash screen should be displayed, calls DoFormRetVal("introform" ).
Run the Initial Component when a User Logs In
The subclass of the Application class, Tastrade, in MAIN.vcx provides additional functionality specific to Tasmanian Traders. Code in the Do( ) method overrides the default behavior of the Do( ) method of the Application class. Code in the Do( ) method calls the GetStartupAction( ) method, which returns the component of the application to run after a user logs in. If a default component is specified for a user, code in the Do( ) method runs this initial component.
Tastrade Sample: Form Class Functionality
Tasmanian Traders includes these types of forms:
- Modal forms that return a value (for example, the Login form).
- Data entry forms (for example, the Customer and Order Entry forms).
- Lookup forms (FindCustomer and FindOrder).
- General purpose forms (for example, the About and Introductory forms).
The following list depicts the form classes and their hierarchies in Tasmanian Traders.
| Form Class | Class Library |
|---|---|
| tsFormRetVal | Tsbase.vcx |
IntroForm |
Tsgen.vcx |
Login |
Login.vcx |
LoginPicture |
Login.vcx |
FindCustomer |
Tsgen.vcx |
FindOrder |
Tsgen.vcx |
| tsBaseForm | Tsbase.vcx |
tsMaintForm |
Tsbase.vcx |
tsTextForm |
Tsbase.vcx |
OrderEntry |
Orders.vcx |
About |
About.vcx |
Modal Forms
All forms that return a value are derived at some level from tsFormRetVal in Tsbase.vcx. All the data entry form classes are based on tsBaseForm in Tsbase.vcx.
tsFormRetVal prevents access to other components while active.
Property Settings
| AutoCenter = | .T. |
| BackColor = | Light Gray |
| BorderStyle = | 2-Double wide |
| FontSize = | 8 |
| MaxButton = | .F. |
| MinButton = | .F. |
| WindowType = | 1-Modal |
Custom Properties
| uRetVal: | Holds the form's return value. Can be any data type; the "u" prefix stands for "unknown." uRetVal is .T. by default. |
To create an instance of a subclass, call Application.DoFormRetVal.
Data Entry Forms
Forms for data entry are based on the tsBaseForm class and are closely integrated with the tsToolbar class. tsBaseForm is the parent class of most forms in the Tasmanian Traders application. It provides the following functionality:
- Table navigation
- Management of user access to data
- Interface coordination
Property Settings
| BufferMode = | 2-Optimistic |
Custom Properties
| aerrormsg[3] = | An array of error messages. This allows generic error handling code to be written in the parent class and custom error messages to be defined in each subclass. The following default values are defined in the code associated with the Init event of particular forms: |
| aerrormsg[1] = | "Insert trigger failed!" |
| aerrormsg[2] = | "Update trigger failed!" |
| aerrormsg[3] = | "Delete trigger failed!" |
| cToolBar: | Holds the name of the toolbar to run when the form is run. |
| lAllowEdits: | Whether or not the current record can be edited. |
| lAllowDelete: | Whether or not the current record can be deleted. |
| lAllowNew: | Whether or not the user is allowed to add new records. |
Functionality Associated with Events
| Init: | 1. Restores the previous window position.2. Adds the form's caption to the menu.3. Displays the navigation toolbar.4. Initializes the custom error message array, aerrormsg[ ]. |
| Activate: | 1. Selects the alias specified in the InitialSelectedAlias property of the form's data environment.2. Refreshes the navigation toolbar.3. Refreshes the menu.4. Sets the message of the status bar to the form's Caption property. |
| Error: | Defines generic error handling code for all forms. |
| Destroy: | 1. Removes the form's caption from the menu.2. Saves the position of the window in the Tastrade.ini file. |
| QueryUnload: | Checks whether data has changed, and prompts the user to save changes if necessary. |
| Unload: | Clears the status bar. |
Custom Methods
| First: | Advances the record pointer to the first record. |
| Next: | Advances the record pointer to the next record. |
| Prior: | Advances the record pointer to the previous record. |
| Last: | Advances the record pointer to the last record. |
These four methods all share the following behavior:
- Call the form's custom DataChanged( ) method to check for changes.
- Call the form's custom AskToSave( ) method to prompt the user to save any changes.
Custom Methods
| Save: | Saves the current record. |
| Delete: | Deletes the current record. |
| AddNew: | Adds a new record. |
| Restore: | Restores original field values (cancels changes). |
| AddToMenu: | Adds the form's caption to the Window menu. |
| RemoveFromMenu: | Removes the form's caption from the Window menu. |
| AskToSave: | Prompts user to save changes, not to save changes, or to cancel the last operation. |
| DataChanged: | Returns .T. if any data on the current form has changed. |
| WriteBuffer: | Code to flush the value of the current control to the record buffer. |
| RefreshForm: | Custom refresh routine. |
| SaveWindowPos: | Writes the Top and Left properties of the form to the application's INI file. |
| RestoreWindowPos: | Reads the Top and Left properties of the form from the application's INI file and sets them. |
| WaitMode: | Changes the mouse cursor to an hourglass for all controls on a form. |
Lookup Forms
The FindCustomer and FindOrder forms display the customer and order tables, respectively, in a grid and make it possible for the user to change the index tag. The key value from the selected row is returned to the calling form when the user closes the form.
General Purpose Forms
There are two general purpose forms:
- AboutBox Form
AboutBox in About.vcx accepts parameters in its Init event for caption texts and a logo bitmap. This class uses API functions to retrieve information from either the WIN.INI file for Windows 3.x, or the system registry otherwise, to display information about the user's system. - IntroForm
IntroForm in Tsgen.vcx is the initial splash screen. Code associated with the Click event of chkShowAtStartUp in this class writes a value to the Tastrade.ini file to specify whether the splash screen should be displayed in the future when Tasmanian Traders is run.
Tastrade Sample: Control Class Functionality
Most of the Visual FoxPro base control classes were subclassed to provide additional default functionality or a consistent appearance. Whenever groups of controls were needed in more than one place in Tasmanian Traders, a class was created.
Because the application had to run in a 640 x 480 display, the default font of these controls was set to be 8 point rather than 10 point, to save space on the forms.
The control classes are listed below by library.
Tsbase.vcx Class Library
| Class | Description |
|---|---|
| ts3dShape | The class for shape controls, used mostly for accentuating or enclosing parts of a form. |
| TsComboBox | The class for all combo boxes in the application. |
| TsCommandButton | The class for all command buttons in the application. |
| TsEditBox | The class for all edit boxes in the application. |
| TsGrid | The SumColumn method is used to automatically sum a value in a grid column. This class is added to the List page of the page frame in the tsMaintForm class. |
| TsLabel | The class for all labels in the application. |
| TsListBox | The class used for all list boxes in the application. |
| TsTextBox | The class for all text boxes in the application. |
| OrdTextbox | A subclass of tsTextbox which is used in Order Entry and Order History forms. |
| TsToolBarButton | The class for all command buttons that appear on toolbars in the application. |
Tsgen.vcx Class Library
| Class | Description |
|---|---|
| CustomerInfo | Includes labels and text boxes for the following fields in the customer table. |
| DateRange | A custom control based on the Visual FoxPro Control base class. |
| Splitter | Used in Behind the Scenes to resize the list of features and the description edit box. |
| TsMaintForm | The class for all maintenance forms in the application. |
| TsToolBar | The class for the toolbar in the application. |
See Also
Solutions Samples | Tasmanian Traders Sample | Designing the Tastrade Database | Designing and Creating the Tasmanian Trader Classes | Writing, Testing, and Debugging Tasmanian Traders