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.)
The Maintain language has the following commands for displaying forms:
This is non-persistent mode. It is the most common mode for Maintain forms. When an end-user submits a non-persistent form, the form re-establishes a connection with the server.
When you display a form with Winform Show_And_Exit, control passes to the form, and any commands after Winform Show_And_Exit are not executed until the form is closed.
When you display a form with Winform Show, control passes to the form, and any commands after Winform Show are not executed until the form is closed.
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.
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.)
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.
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.
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.
Maintain has several commands for closing forms at run time:
Note: You can only issue self.WinClose in the Event Handler editor for a form or one of its controls.
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.
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.
Winform Close closes every form in its chain.
To close a specific form, place the following syntax in your procedure:
Winform Close [form] [;]
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.
Tip: You can generate the self.WinClose syntax in the Event Handler editor by clicking the 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.
The Maintain language contains three commands to manipulate the properties of your form:
Note: If the form is not active, you must issue Winform Show_Inactive form before setting the 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 [;]
Is the name of the form.
Is the name of the 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 [;]
Is required if the form is not the active form.
Is the name of the form.
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.
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.
To close the application, place the following syntax in the Event Handler editor:
Tip: You can generate the self.WinExit syntax in the Event Handler editor by clicking the Close Form button .