Running a Form

Article
10/23/2006

You can run a form directly from the interface or in program code.

Running a Form Interactively

There are several ways to run the form you've designed.

If you're working in the Form Designer, you can test the form by clicking the Run button on the Form Designer toolbar. To reopen the form in the Form Designer, close the form or choose the Modify Form button on the toolbar.

You can also run a form from a project or programmatically.

To run a form

In the Project Manager, select the select the name of the form under the Documents tab and choose Run.

-or-
Type DO FORM in the Command window.

-or-
From the Form menu, choose Run Form. You can also choose the Run button on the Standard toolbar.

You can also run the form by choosing Do from the Program menu, choosing Form in the List Files of Type box, selecting the form, and choosing Do.

Tip When running a form, you can quickly switch to Design mode by clicking the Modify Form button on the Standard toolbar.

Running a Form from a Program

To programmatically run a form, include the DO FORM command in the code associated with an event, in method code, or in a program or procedure.

Naming the Form Object

By default, when you use the DO FORM command, the name of the form object is the same as the name of the .scx file. For example, the following line of code runs Customer.scx. Visual FoxPro automatically creates an object variable for the form named customer:

DO FORM Customer

To name a form object

Use the NAME clause of the DO FORM command.

For example, the following commands run a form, creating two form object variable names:

DO FORM Customer NAME frmCust1
DO FORM Customer NAME frmCust2

Manipulating the Form Object

If you issue the DO FORM command from the Command window, the form object is associated with a public variable. You can access the form object through the variable name. For example, the following commands, issued in the Command window, open a form named Customer and change its caption.

DO FORM Customer
Customer.Caption = "Hello"

If you then issue the following command in the Command window, O is displayed in the active output window, indicating that Customer is an object:

? TYPE("Customer")

If you issue the DO FORM command in a program, the form object is scoped to the program. If the program or procedure completes, the object is gone, but the form remains visible. For example, you could run the following program:

*formtest.prg
DO FORM Customer

After you run the program, the form remains visible and all of the controls on the form are active, but TYPE("Customer") returns U indicating that Customer is an undefined variable. The following command, issued in the Command window, would generate an error:

Customer.Caption = "Hello"

You can, however, access the form by using the ActiveForm, Forms, and FormCount properties of the application object.

Scoping the Form to the Form Object Variable

The LINKED keyword of the DO FORM command allows you to link the form to the form object. If you include the LINKED keyword, when the variable associated with the form object goes out of scope, the form is released.

For example, the following command creates a form linked to the object variable frmCust2:

DO FORM Customer NAME frmCust2 LINKED

When frmCust2 is released, the form is closed.

Closing an Active Form

To allow users to close the active form by clicking the close button or by choosing Close from the form's Control menu, set the Closable property of the form.

To allow a user to close the active form

In the Properties window, set the Closable property to true (.T.).

-or-
Use the RELEASE command.

For example, you can close and release the frmCustomer form by issuing the following command in a program or in the Command window:

RELEASE frmCustomer

You can also allow a user to close and release a form by including the following command in the Click event code for a control, such as a command button with a caption of "Quit":

THISFORM.Release

You can also use the RELEASE command in the code associated with an object on the form, but any code you've included in the Release method will not be executed.

Caution When you release a form, you release from memory the object variable created for the form. There is a single variable for a form set, so you can't release forms in a form set without releasing the form set. If you want to release the form set, you can use RELEASE THISFORMSET. If you want to remove a form from the screen so that a user can no longer see it or interact with it, you can use THISFORM.Hide.