http://www.microsoft.com/TechNet/dbdev/foxpro/technote/fx201.htm (PC Press Internet CD, 03/1996)
| Updated: March 15,1996 |  Go To TechNet Home Page |
Alden Anderson Inc. offers consulting services and technical assistance to organizations with existing automation staff. Clients include The Boeing Company, Walt Disney Company, Microsoft Corporation, Sun Bank, USAR TRANSCOM, Citicorp of America, Legent Corporation, US Army FORSCOM, and Environment Control.
Introduction
Microsoft® Visual FoxPro™ database forms are converted in a "Read" compatibility mode. It is important to grasp how this mode functions in order to understand what changes should be made to converted forms to enable them to operate in a fully event-driven model. This session covers all aspects of the "Read Compatibility" mode and how to make changes to forms so that they can take full advantage of the Visual FoxPro event model.
Visual FoxPro's "Read Compatibility" Mode
Overview
Several features have been included in Visual FoxPro to provide full support for screens created using Microsoft FoxPro® 2.x. These features include properties and events on the FormSet, Form and controls, special variable scoping in the FormSet Load and Form Load events, the use of Pageframes and Pages for read levels, and the availability of @ ... GET, @ ... EDIT, @ ... SAY, @ ... TO, and READ commands.
The "Read" FormSet
When a FoxPro 2.x screen is converted to Visual FoxPro form, a FormSet will always be created to contain the form. If the screen is converted from a screen set, one FormSet will be created to contain all of the forms in the screen set.
FormSet WindowType Property
The FormSet WindowType property is what identifies its contained Form(s) as operating in "read" mode. Valid values for the FormSet WindowType property are 0 (Modeless), 1 (Modal), 2 (Read), and 3 (Read Modal). For "read" mode Forms, the property must be set to 2 or 3.
If the FormSet WindowType property is set to 2, the FormSet behaves as if it were activated by the READ command. If the FormSet WindowType property is set to 3, the FormSet behaves as if it were activated by the READ MODAL command. Program execution stops at the Show method or the DO FORM command. When the FormSet is deactivated, execution continues.
The WindowType setting of a FormSet overrides the individual WindowType settings of the Form objects it contains. For example, if the WindowType property for a FormSet is set to 2, all the Form objects contained in it are read (modeless), regardless of their individual WindowType property settings.
Parameter Passing to FormSets with WindowType = 2 or 3
Visual FoxPro will pass parameters to FormSets with WindowType = 2 or 3 to the FormSet Load event. When the FormSet WindowType = 0 or 1 the parameters are passed to the FormSet Init event.
Other FormSet Properties and Events
Once the WindowType of a FormSet is set to 2 or 3, several properties and events become available for use by the program. These properties and events are included for backward compatibility and do nothing when the FormSet WindowType is not 2 or 3.
FormSet Properties
Visual FoxPro FoxPro 2.x Functionality FormSet Equivalent Property
ReadCycle READ CYCLE Specifies whether the focus moves to
the first object in a FormSet when
the focus moves beyond the last
object in a FormSet.
ReadLock READ LOCK Specifies whether all records that
are referenced on any of the Forms
in the FormSet are locked.
ReadMouse READ NOMOUSE Specifies whether you can move
between controls using the mouse on
the Forms contained in a given
FormSet.
ReadSave READ SAVE Specifies whether the READ command
can be used to re-activate an
object.
ReadTimeout READ TIMEOUT Specifies how long the FormSet
remains active with no user input.
FormSet Events
Visual FoxPro FoxPro 2.x Functionality FormSet Event Equivalent
Load #SECTION 1 Setup Occurs just before the FormSet is
Code created.
ReadActivate READ ACTIVATE Occurs when a new Form in the
FormSet is made active.
ReadDeactivate READ DEACTIVATE Occurs when a new Form in the
FormSet is deactivated.
ReadShow READ SHOW Occurs when a SHOW GETS command is
issued on the active FormSet and
when a FormSet is activated.
ReadValid READ VALID Occurs just before a FormSet is
deactivated.
ReadWhen READ WHEN Occurs when a FormSet is activated.
FormSet Variable Scoping
Variables created in the FormSet Load of a FormSet with WindowType = 2 or 3 are scoped to the FormSet and visible to the entire FormSet, its Forms and controls. Variables created in other FormSet events (or methods) will only be visible as specified (i.e., PRIVATE, PUBLIC, or LOCAL).
The "Read" Form
Form Properties and Events
Window settings used in FoxPro 2.x are mapped to Visual FoxPro Form properties.
Form Properties
Visual FoxPro Form FoxPro 2.x Equivalent Functionality Property
Name Screen Name Specifies the name of
the form.
Top Vertical Position Determines the
distance between the
top edge of the Form
and the main Visual
FoxPro window.
Left Horizontal Position Specifies the distance
between the left edge
of the Form and the
main Visual FoxPro
window.
Height Height Specifies the vertical
dimension of the Form.
Width Width Specifies the width of
the Form.
Caption Title Specifies the text
displayed in the
Form's title bar.
FontName Font (FontFace) Specifies the name of
the font used to
display text.
FontBold Font Style Bold Specifies that text is
bold.
FontItalic Font Style Italic Specifies that the
text it italic.
FontSize Font Size Specifies the size of
the font.
Movable Window Attribute Moveable Specifies whether the
(Float) Form can be moved at
run time by the user.
Closable Window Attribute Close Specifies whether the
Form can be closed by
double-clicking the
Control-menu box or
choosing Close from
the Control menu.
HalfHeightCaption Window Attribute Half Ht Specifies whether the
Title Bar caption of a Form is
half the normal
height.
MinButton Window Attribute Minimize Specifies whether a
Form has a Minimize
button.
BorderStyle Border Specifies the border
style of the Form.
AutoCenter Center Specifies whether the
Form is automatically
centered in the main
Visual FoxPro window
the first time it is
displayed.
Icon Window Icon Specifies the icon
displayed for a Form
at run time when the
Form is minimized.
Form Events
Visual FoxPro Form FoxPro 2.x Equivalent Functionality Event
Load #SECTION 2 Setup Code Occurs just before the Form
is created.
Unload Cleanup Code Occurs when the Form is
released.
Form Variable Scoping
Variables created in the Form Load event are scoped to the Form and visible to the FormSet, its Forms and controls when a FormSet with WindowType = 2 or 3 exists. Variables created in other Form events (or methods) will only be visible as specified (i.e. PRIVATE, PUBLIC or LOCAL).
"Read" Mode and Controls
"Read" Mode Usage of PageFrames and Pages
Whenever the FormSet WindowType = 2 or 3, there must be a PageFrame containing at least one Page control on each Form in the FormSet. Each Page in the PageFrame represents one read level. Therefore, if there is one read level on the form, there should be one Page in the PageFrame, if there are two read levels, there should be two Pages in the PageFrame, and so on. The controls contained within each Page are the controls that will participate in the read level specified by the Page. Page1 is read level 1, Page2 is read level 2, and so on.
When a program issues any @ ... GETs, Visual FoxPro will create a PageFrame, if one does not already exist, and a new Page to handle the new read level. The @ ... GETs will be controls contained within the newly created Page. When the READ statement is issued, the Page and its contained controls will become active. Once the READ terminates, the Page created for the read level will be destroyed, along with the controls created by the @ ... GETs. If the PageFrame was created for the Page (i.e. the Page was Page1), it will also be destroyed.
Control Properties and Events
@ ... SAYs, @ ... GETs, @ ... EDITs, @ ... TOs and their FoxPro 2.x settings are mapped to Visual FoxPro controls. @ ... snippet code from FoxPro 2.x is mapped to the corresponding control event code in Visual FoxPro.
Control Properties (Core Set)
Visual FoxPro FoxPro 2.x Functionality Control Property Equivalent
Top Vertical Position Specifies the top-most edge of
the control.
Left Horizontal Position Specifies the distance between
the left edge of a the control
and the left edge of its
container object.
Height Height Specifies the vertical dimension
of the control.
Width Width Specifies the width of the
control.
Format, Picture Format: Mimics the behavior of
InputMask the FUNCTION clause for the @ ...
GET and @ ... EDIT commands.
InputMask: Specifies the
data-entry rule for each
character entered in the control.
FontName FontFace Specifies the name of the font
used to display text.
FontBold, FontStyle Specify that text is either Bold
FontItalic or Italic.
FontSize FontSize Specifies the font size for text
displayed with an object.
Caption Label Expression Specifies the text displayed in
(Expr) an object's caption.
BackColor FillColor Specifies the background color
used to display text and graphics
in an object.
ForeColor PenColor Specifies the foreground color
used to display text and graphics
in an object.
BackStyle Mode Specifies whether the background
of an object is transparent or
opaque.
Alignment Text Alignment Specifies the alignment of text
associated with a control.
Name Name Specifies the name of the
control.
ControlSource Name Specifies the source of data to
which an object is bound.
Enabled .not. Disabled Specifies whether an object can
respond to user-generated events.
TerminateRead Terminate READ on Specifies whether or not the READ
Selection command is terminated when a
control receives the focus.
Value Initial Value Specifies the current state
(value) of a control.
SpinnerHighValue Maximum (Tag2) Specifies the highest value that
can be entered into a Spinner
control by clicking on the up
arrow.
SpinnerLowValue Minimum (Tag) Specifies the lowest value that
can be entered into a Spinner
control by clicking on the down
arrow.
BorderWidth Pen Size Specifies the width of a
control's border.
DrawStyle Pen Pattern Specifies the line style to use
when drawing with graphics
methods.
FillStyle Fill Pattern Specifies the pattern used to
fill Shapes and figures created
with the Circle and Box graphics
methods.
Stretch Scale Picture Specifies how an image is sized
to fit inside an Image control.
Style Picture Check Box Specifies the style of a control.
Note Option buttons are converted to Option Groups, Command buttons are converted to Command Groups.
Control Events
Visual FoxPro FoxPro 2.x Functionality Control Event Equivalent
When When Occurs before a control
receives the focus.
Valid Valid Occurs before a control loses
the focus.
Message Message Displays a message in the
status bar at the bottom of
the screen.
Error Error Occurs when there is a
run-time error in a method.
RangeHigh RangeHi TextBox, Spinner low range,
ListBox, ComboBox 1st Element
RangeLow RangeLo TextBox, Spinner high range,
ListBox, ComboBox # of
Elements
Event Firing Sequence
When the FormSet WindowType = 2 or 3, the order of events is as follows:
FormSet Load
Form Load
Controls Init (Inside to Outside)
Form Init
FormSet Init
FormSet ReadWhen
FormSet ReadActivate
FormSet ReadShow
FormSet Show
Form Show
FormSet Activate
Form Activate
(when event of first control)
Control Valid event
. . .
Form Deactivate
FormSet Deactivate
FormSet ReadDeactivate
FormSet ReadValid
Controls Destroy (Outside to Inside)
FormSet Destroy
Form Destroy
Form Unload
FormSet Unload
Moving from "Read Compatibility" Mode into the Event Model
Overview
The GOOD NEWS is that Visual FoxPro's converter does so much work! Most form and control properties have already been set!
There are, however, some changes that should be made to FormSets, Forms and code to allow applications to run fully in the event model.
Remove/Change the FormSet and Form
If there is only one Form in the FormSet, the FormSet should probably be removed (leaving the form, of course). But before doing this, all code in the FormSet events must be moved to the appropriate places in the Form events, otherwise the code will be removed along with the FormSet.
If there is more than one Form in the FormSet, the FormSet cannot be removed.
Change the FormSet WindowType Property and Move Event Code
If the FormSet will not be removed, several changes should be made to it. First, the WindowType property should be changed from 2 (read) or 3 (read modal) to 0 (modeless) or 1 (modal). This change will require the code in the FormSet ReadWhen, ReadActivate, ReadShow, ReadDeactivate, and ReadValid code to be moved to other events because they will not fire when the FormSet WindowType property is 0 or 1. The code in ReadWhen, ReadActivate, and ReadShow should be moved to the FormSet Show and Activate events, with care being given to make sure that sequence that the code will execute is correct. Note that the event firing sequence in FoxPro 2.x is When, Active and then Show, while the event firing sequence in Visual FoxPro is Show and then Activate.
If the FormSet will be removed, The FormSet Read... events should be moved to the Form Show and Activate events, with the same care given to the sequence that the code will execute (as described above). Additionally, the FormSet Load code should be moved to the Form Load event.
Parameters are passed to the FormSet Load event when the FormSet WindowType = 2 or 3 and to the FormSet Init when the FormSet WindowType = 0 or 1. All parameter handling code will need to be moved to the Init event of the FormSet if the FormSet is not removed or to the Init of the Form if the FormSet is removed.
Create FormSet or Form Properties for Variables created in FormSet Load
When the FormSet WindowType property is not 2 or 3 or the FormSet is removed, no special scoping of variables created in the FormSet Load or Form Load occurs. Properties should be added to the FormSet for each variable needing to be scoped to the FormSet. If the FormSet is removed, these properties should be added to the Form instead. Properties also should be added to the Form for variables needing to be scoped to the Form.
Remove the PageFrame and Page
For each Form in the FormSet, the PageFrame and Page should be removed. Before deleting them, however, make sure that all controls contained within the Page are copied to the clipboard (select all controls contained within the Page and press Ctrl-C or select Copy from the Edit menu. Note that you will need to make the Page the current object in the property sheet before you will be able to select the controls contained within it. Once all the controls have been copied to the clipboard, re-select the PageFrame and press the delete key. This should delete the PageFrame and Page from the Form (if the PageFrame remains, press the delete key one more time to make sure it is removed). Make the Form the current object in the property sheet and press Ctrl-V or select Paste from the Edit menu. This will place the controls that were copied to the clipboard back on the Form. The controls may need to be moved.
Change Code
CLEAR READ
Any occurrences of CLEAR READ will need to be changed to RELEASE ThisFormSet or RELEASE ThisForm (depending on whether the FormSet remains).
SHOW GETS
Any occurrences of SHOW GETS will need to be changed to ThisFormSet Refresh or ThisForm Refresh (depending on whether the FormSet remains).
Change Foundation READ to READ EVENTS
We are no longer in "Read" mode. Change to READ EVENTS.
CLEAR READ
Any occurrences of CLEAR READ should be changed to CLEAR EVENTS.
Get Rid of the .SPR?
Procedures and Functions in the .spr can be turned into methods for the various objects that they pertain to. If all of them are changed to methods, the .spr file can be disposed of. Make sure all program statements that call the form with the statement DO x.spr are changed to DO FORM x (passing parameters, if necessary).
What Else?
At this point, your Form should run in the event model. Other things to consider include analyzing your program to see where the use of classes may be beneficial and how to take full advantage of the Data Environment and Sessions.
© 1995 Microsoft Corporation.
THESE MATERIALS ARE PROVIDED "AS-IS," FOR INFORMATIONAL
PURPOSES ONLY.
NEITHER MICROSOFT NOR ITS SUPPLIERS MAKES ANY WARRANTY, EXPRESS
OR IMPLIED WITH RESPECT TO THE CONTENT OF THESE MATERIALS OR THE
ACCURACY OF ANY INFORMATION CONTAINED HEREIN, INCLUDING, WITHOUT
LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS
FOR A PARTICULAR PURPOSE. BECAUSE SOME STATES/JURISDICTIONS DO
NOT ALLOW EXCLUSIONS OF IMPLIED WARRANTIES, THE ABOVE LIMITATION
MAY NOT APPLY TO YOU.
NEITHER MICROSOFT NOR ITS SUPPLIERS SHALL HAVE ANY LIABILITY FOR
ANY DAMAGES WHATSOEVER INCLUDING CONSEQUENTIAL INCIDENTAL, DIRECT,
INDIRECT, SPECIAL, AND LOSS PROFITS. BECAUSE SOME STATES/JURISDICTIONS
DO NOT ALLOW THE EXCLUSION OF CONSEQUENTIAL OR INCIDENTAL DAMAGES
THE ABOVE LIMITATION MAY NOT APPLY TO YOU. IN ANY EVENT, MICROSOFT'S
AND ITS SUPPLIERS' ENTIRE LIABILITY IN ANY MANNER ARISING OUT
OF THESE MATERIALS, WHETHER BY TORT, CONTRACT, OR OTHERWISE SHALL
NOT EXCEED THE SUGGESTED RETAIL PRICE OF THESE MATERIALS.
 |
Click Here to Search TechNet Web Contents | TechNet CD Overview | |
Microsoft TechNet Credit Card Order Form At this time we can only support electronic orders in the US and Canada. International ordering information. |
| Go To TechNet Home Page |
©1996 Microsoft Corporation |  Go To Microsoft Home Page |