Dynamically Manipulating Forms at Run Time

In this section:

Using the Winform command in the Maintain language, you can open, close, reset, and perform other operations on your forms at run time.

If you are developing with forms, you must understand the flow of control for forms in a WebFOCUS Maintain application. (Keep in mind that Maintain procedures do not execute linearly. The only code that is guaranteed to be executed is in and before the Top function.)


Top of page

x
Displaying Forms at Run Time

How to:

The Maintain language has the following commands for displaying forms:

To display an initial form, somewhere in the Top Case of the starting procedure, you must issue the Winform Show command that displays this form (or Top Case should call another function or procedure that executes this command).

The rest of the forms in the procedure are displayed only if the end user does something to display the forms, such as clicking a button. Clicking a button is known as an event to a WebFOCUS Maintain developer, and you use the Event Handler editor to define what happens when an event occurs. For more information, see Defining Events and Event Handlers.

As each form is opened in a WebFOCUS Maintain application, it is stacked on top of the previous form. This means that all your forms remain open until you issue a command to close them or exit the application.

Note: When you close a form, you close every form in its chain, and WebFOCUS Maintain ignores any code after the closing statement.

When WebFOCUS Maintain encounters the Winform Show[_Active] command, it passes control to the named form. Control does not return to the procedure until the user exits the form.



x
Syntax: How to Make a Form Active

To make a form active so that an end user can use it, place the following syntax in your procedure:

Winform Show[_Active] formname [;]

Control is transferred to the form.

You can generate this syntax by dragging the form from the Project Explorer into the Procedure Editor or the Event Handler editor. (The form must be part of the procedure you are editing.)



x
Syntax: How to Display a Non-Persistent Form

To display a non-persistent form, place the following syntax in your procedure:

Winform Show_And_Exit formname [;]

The form is displayed, but does not maintain a persistent connection with the server.



x
Syntax: How to Display a Form Without Making it Active

To display a form without making it active, place the following syntax in your procedure:

Winform Show_Inactive formname [;]

Control passes to the next command in the procedure, but not to the form.


Top of page

x
The Active Form

When a form is active, end users can fire events in the form, such as clicking a button or typing into a field. These events invoke event handlers, such as Maintain functions, JavaScriptâ„¢ functions, VBScript functions, or web links.

When an event that is handled by a function is fired, the function is performed. Control returns to the server until the function is done, then the application displays a new browser page.


Top of page

x
The Non-Persistent Form

The code that differentiates between a persistent and non-persistent form is the code you use to display your form. If you use the default code for Maintain, Winform Show, you create a persistent form. If you use the code that is embedded in the comment text at the top of each new form, Winform Show_And _Exit, you create a non-persistent form.

Forms in Maintain applications that were built in WebFOCUS Maintain Release 4.2 Version 1 or earlier are, by default, persistent. When a user accesses a persistent form, an agent from your server is accessed and sends the appropriate information to the browser. After the user has the form, the WebFOCUS Server agent waits for further instructions while the user makes choices on the form. That agent is dedicated to that user until the user closes the application. This method is appropriate if your application requires navigation from form to form.

With a non-persistent form, when the user accesses a non-persistent form, your server sends the appropriate information to the user, then disconnects the connection. The WebFOCUS Server agent is no longer dedicated to that user, and is available for another user to access. This method is appropriate for single form applications or for the last form in an application that uses multiple forms.


Top of page

x
Closing Forms at Run Time

How to:

Maintain has several commands for closing forms at run time:

When you close a form, control returns to the command directly after the command that initially displayed the form, as shown in the diagram below. No additional commands should be placed immediately following the Winform Close command.

Form image

Suppose you have four forms: Form1, Form2, Form3 and Form4. Form1 opens Form2, Form2 opens Form3, and Form3 opens Form4. If you close Form2 while you are in Form4, WebFOCUS Maintain closes Form2, Form3, and Form4, and returns to Form1, as shown in the following diagram.

Form image

Winform Close closes every form in its chain.



x
Syntax: How to Close a Form

To close a specific form, place the following syntax in your procedure:

Winform Close [form] [;]

or

self.WinClose();

These commands close the specified form and the chain of forms that may have been opened from this one. It returns control to the point just following the Winform Show command that displayed the form.

Note:

Tip: You can generate the self.WinClose syntax in the Event Handler editor by clicking the Close Form button Close Form button.

Caution: Closing a form returns control of the application to the command directly after the Winform Show form command that initially displayed the form. No additional commands should be placed immediately following the Winform Close command.



x
Syntax: How to Close All Forms

To close all forms, place the following syntax in your procedure:

Winform Close_All [;]

Top of page

x
Manipulating Form Properties

How to:

The Maintain language contains three commands to manipulate the properties of your form:



x
Syntax: How to Determine the Value of a Form Property

To determine the value of a form property and assign it to a variable, use the following syntax

Winform Get form.property INTO variable [;]

where:

form

Is the name of the form.

property

Is the name of the property.



x
Syntax: How to Set the Value of a Form Property

To set the value of a form property (except for colors), use the following syntax

[Winform Show_Inactive form;]
Winform Set form.property TO setting [;]

where:

Winform Show_Inactive

Is required if the form is not the active form.

form

Is the name of the form.

property

Is the name of the property.

You cannot set the values of all properties. To see which properties you can set, see Form and Control Properties Reference.

Tip: You can generate this syntax by selecting the property in the property sheet and dragging it to the Procedure Editor or the Event Handler editor. Note that you cannot drag properties that you cannot set at run time.

For information on how to set color properties, see Defining Colors for Your Form and Controls.



x
Syntax: How to Reset a Form

To reset a form and its controls to their original properties, place the following syntax in your procedure:

Winform Resetformname [;]

All selectable controls, such as list boxes, check boxes, and radio buttons, return to their default selections.


Top of page

x
Exiting Your Application at Run Time

How to:

The Maintain language has two commands for exiting an application:

For more information on the Winform Show_And_Exit form command, see How to Display a Non-Persistent Form.



x
Syntax: How to Close the Application

To close the application, place the following syntax in the Event Handler editor:

self.WinExit();

Note:

Tip: You can generate the self.WinExit syntax in the Event Handler editor by clicking the Close Form button Close Form button.


WebFOCUS