PRIMARY() | Hackers Guide to Visual FoxPro 7.0

Do Form

This command runs a form or formset from its SCX file.

Usage

DO FORM FormName | ?       [ NAME oName ] [ LINKED ]      [ WITH ParameterList ] [ TO uResult ]      [ NOREAD ] [ NOSHOW ]

When you run a form or formset, FoxPro automatically creates an object variable to give you access to it. By default, the variable's name is the name of the form or formset (the file name up to, but not including, the SCX extension). The NAME clause lets you specify the name instead. The variable can even be an array element. In fact, many application frameworks store references to active forms in an array that's a property of an application object. Whether you supply the name or use the default, you can access the form's PEMs using the reference.

But there's a catch. The variable created is an additional reference to the form, supplementing an internal reference of some sort. When you release the variable (or it goes out of scope), the form still exists—unless you include the LINKED keyword. LINKED says the form's existence is tied to the variable itself. When the variable is destroyed, the form should be, too.

WITH passes parameters to the form. For forms you create with Visual FoxPro, parameters are passed to the Init method, even though it's not the first to execute. Forms converted from FoxPro 2.x receive parameters in the Load method instead. The parameters are scoped to the method that receives them, so you either need to process them there or store them in a custom property of the form or formset.

One of our favorite tricks in FoxPro 2.x was to turn a screen into a function and have it return a value. Visual FoxPro forms aren't quite as versatile in this way. You can't call them as functions. But, if you make the form modal, it can return a value. You set this up by RETURNing the desired value in the Unload method of the form or formset. The value you return gets put in the variable listed in the TO clause. One warning: You can't directly return the value of a property from a control because the controls get destroyed before Unload. If you want to return a property value, you have to save it to a form property before you start shutting things down.

The NOREAD clause is supposed to replace the #NOREAD generator directive of FoxPro 2.x. That directive told the screen-generator program to create code to paint the screen, but not to include the READ that activated the controls. In our tests, DO FORM whatever NOREAD (where whatever is a converted FoxPro 2.x screen) errors out because the variables for the controls don't get created at the right time. With the NOREAD clause, events fire in a really weird order.

NOSHOW lets you create a form without making it visible. You can then do some manipulation of the form object before you show it to the user. To make a NOSHOW form visible, call its Show method or set its Visible property to .T. There's a small difference between the two methods of making it visible. When you call the Show method, the form gets focus; setting Visible to .T. displays it, but doesn't give it the focus.

The original release of VFP 7 has a subtle but nasty error. If you run a form within an executable, then close the form, the process retains a hold on that form until the executable is finished. That means, among other things, that you can't delete the form from within the EXE. Not something we do every day, but now and then, weird situations like this do come up. Fortunately, the problem is fixed in Service Pack 1.

Example

DO FORM MyForm NAME oApp.aActiveForms[nFormCnt]