In this section:
How to: Reference: |
The Winform command controls the forms that appear on the screen. Winforms are used to edit and display data. They act as an application's user interface, whereas a procedure controls the application's logic and use of data.
The Winform command performs three tasks:
The syntax of the Winform command for displaying and controlling forms is
Winform command formname [;]
where command is one of the following:
Makes the specified form active: it displays the form and transfers control to it, enabling an application user to manipulate the controls (of the form), such as buttons and fields. If other forms are currently displayed on the screen, the specified form is displayed on top.
Can be used for clarity. It is functionally identical to Show.
Displaysthe specified form without making it active. Because the form is inactive, control passes to the following command, not to the form. You can use this to change the initial properties of a form, and of the form's controls, dynamically at run time before the form is displayed.
Repopulates the form's data values as if control had returned to the form from a trigger, but without making the form active.
Closes all forms. The form environment remains active.
Closes the chain of forms from the currently active form back up to the specified form. If you do not specify a form, the command closes only the currently active form.
The close operation does the following:
Closes all Winforms. Terminates the Winform environment. Directs TYPE messages to the screen.
The syntax of the Winform command for changing a form control property is:
Winform Set formname[.controlname].property TO value [;]
The syntax of the Winform command for querying a form control property is
Winform Get formname[.controlname].property INTO variable [;]
where:
Is the name of the form.
Is the name of the form control whose property you wish to set or get. Omit the control name if you are changing a property for an entire form, otherwise you must specify it.
Except where noted otherwise in Dynamically Changing Winform Control Properties, properties can be set for all types of controls.
Is any valid property. Properties are described in Dynamically Changing Winform Control Properties.
Is a value that is valid for the specified property. Properties and their values are described in Dynamically Changing Winform Control Properties.
Is any scalar variable (a user-defined field or a stack cell) to which you will assign the value of the specified property of the specified form or control.
Terminates the command. Although the semicolon is optional, including it to allow for flexible syntax and better processing is recommended. For more information about the semicolon, see Terminating a Command's Syntax.
When a Winform command is encountered that contains the Show option, control is passed to the named Winform. Control does not return to the procedure until the user exits the Winform. While the Winform is active, controls within the Winform can call Maintain functions (controls are also known as Winform objects, and functions are also known as cases). This is accomplished by the use of triggers that specify what happens when the associated event occurs.
The following is an example of a triggered Maintain function. Two Winforms are hidden, a background Winform is displayed, and the main Winform is made active. The background Winform is just a background graphic, so there is no need to activate it:
Winform Hide Addr; Winform Hide Info; Winform Show_Inactive Back; Winform Show_Active Main;
The next example uses the Winform command after a MATCH in a triggered function. If there is a match on Emp_ID, two Winform commands are performed. Empinput, the Winform used to enter the employee’s ID number, is hidden and EmpInfo, the Winform that displays information for the employee whose ID was found, is activated. If the MATCH is unsuccessful, the procedure displays the NotFound Winform which informs the application user that the employee ID was not found. It does not hide the Empinput Winform because the application’s user should be able to see the unsuccessful employee ID in case the error was caused by a typing mistake:
CASE Findemp MATCH Emp_ID; ON MATCH BEGIN Winform Hide Empinput; Winform Show EmpInfo; ENDBEGIN ON NOMATCH Winform Show Notfound; ENDCASE
A trigger action can be a case (also known as a function) or a system action (such as Exit).
When a trigger that specifies a function is called, the function is performed. The Winform remains visible to the end user but does not accept keyboard activity. When the function or functions finish processing, the Winform again becomes available to end user activity.
A trigger can display another Winform. This is done by specifying a Winform command within the triggered Maintain function. In this situation, if the Winform in the function is made active by the Show or Show_Active option, the Winform that triggers the function continues to be displayed but is no longer active. When the second Winform is exited, control returns to the function that called it. When that function is exited, control returns to the Winform from which the trigger was called, and at that time the calling Winform becomes active again. The following are the steps in a generic example:
In this example, if Winform B has a trigger that issues a Winform Show A command, a warning message is displayed because Show cannot be specified for a Winform that is already displayed to the user.
If a form displays a variable that has not been assigned a value, the form will display the default value. A variable's default is determined by its data type and whether it was defined with the MISSING attribute:
Data Type |
Default value without the MISSING attribute |
Default value with the MISSING attribute |
---|---|---|
Character/Alphanumeric |
space |
null |
Numeric |
zero |
null |
Date and time |
space |
null |
A null value is displayed as a period (.) by default; you can specify a different character using the SET NODATA command.
You can change many properties of forms and controls at run time using the Winform Set command, and can determine the current state of those properties using the Winform Get command. Controls are also known as Winform objects. You can use these commands with all Winform controls. For some properties, such as a grid’s current column, you call a function instead of using Winform Set and Get.
If you want to change a form's properties at run time before the form is displayed, you can first issue the Winform Show_Inactive command, then issue commands to set form and control properties, and finally issue a Winform Show command. If you wish to change a form's properties in response to user activity in the form, you can trigger a function containing Winform Set commands and function calls from those user events. You cannot dynamically set a form's properties before it has been opened with either a Winform Show or Winform Show_Inactive.
For example, you could develop a data entry function that determines whether a user has entered data into a field; if the user has not, you could use the Winform Set command to change the field's color and give it focus, effectively drawing the user's attention to it and making it the target of any keyboard activity.
You can set and query the following properties:
Colors |
Numeric Values |
---|---|
BLACK | 1 |
BLUE | 2 |
GREEN | 3 |
TURQ | 4 |
RED | 5 |
PINK | 6 |
YELLOW | 7 |
WHITE | 8 |
For each control, you can change the foreground color or the background color, but not both at the same time: when you set one, the other is automatically set to black.
For example, the following command changes the Sales entry field in the SalesSummary Winform to red:
Winform Set SalesSummary.Sales.BACKGROUND_COLOR TO RED;
[COMPUTE] formname.gridname.ChangeColBcolor(ColumnNumber, ColorNumber); [COMPUTE] formname.gridname.ChangeColFcolor(ColumnNumber, ColorNumber);
where:
Is an optional keyword. It is required if the preceding command can take an optional semicolon terminator, but was coded without one. In all other situations the COMPUTE keyword is unnecessary.
Is the name of the Winform that contains the grid.
Is the name of the grid.
Is the column number in the grid.
Is the number associated with the color you want in the grid column. Colors and numbers are listed in the previous table.
For example, the following command hides the Salary entry field in the EmployeeReview Winform:
WINFORM SET EmployeeReview.Salary.VISIBLE TO NO;
If you wish to dynamically hide an entry field’s prompt, you must issue a separate Winform Set command that includes the STATIC keyword. The syntax is
Winform Set formname.fieldnamesSTATIC.VISIBLE TO NO;
For example, the following command hides the Salary entry field’s prompt in the EmployeeReview Winform:
Winform Set EmployeeReview.SalarySTATIC.VISIBLE TO NO;
When a control is protected, an application user cannot tab to it or use it. You cannot unprotect control types that, by definition, cannot be tabbed to or manipulated, such as text.
For example, the following command protects the CustomerNameList list box in the CustomerForm Winform:
Winform Set CustomerForm.CustomerNameList.PROTECTED TO YES;
When a control is protected using the Protected property, it cannot be made available for user control by setting PROTECTED to NO. If you protect a control by selecting its Protected check box, the Winform Set PROTECTED TO NO command cannot affect or eliminate the control’s protection.
The syntax for calling this function is
[COMPUTE] formname.gridname.SetStackMode(ADDOFF);
where:
Is an optional keyword. It is required if the preceding command can take an optional semicolon terminator, but was coded without one. In all other situations the COMPUTE keyword is unnecessary.
Is the name of the Winform that contains the grid.
Is the name of the grid.
Prevents the user from placing the cursor below the last line of the grid that contains data.
For grids, the row indicated by the current value of FocIndex receives focus. You cannot give focus to control types that you cannot tab to, such as text.
For example, the following command makes the NextButton push button in the CustomerForm Winform the active control:
Winform Set CustomerForm.NextButton.FOCUS TO HERE;
The following command assigns the name of the control that is currently active (that is, that currently has focus) to the variable ControlHasFocus:
Winform Get CustomerForm.FOCUS INTO ControlHasFocus;
For example, the following command bolds the text in the JobTitleList list box in the EmployeeReview Winform:
Winform Set EmployeeReview.JobTitleList.BOLD_FONT TO YES;
For example, the following command underlines the text in the SubmitButton button in the EmployeeReview Winform:
Winform Set EmployeeReview.SubmitButton.UNDERLINE_FONT TO YES;
For example, the following command makes the text in the HeadingText banner blink at the top of the EmployeeReview Winform:
Winform Set EmployeeReview.HeadingText.BLINK_FONT TO YES;
RowNumber = ContactListForm.Grid1.CurStkRowNum;
Maintain automatically sets the FocIndex system variable to the value of the CurStkRowNum variable when the user leaves the grid and clicks on another control on the Winform. The syntax for this variable is
formname.gridname.CurStkRowNum
where:
Is the name of the Winform.
Is the name of the grid.
ColNumber = ContactListForm.Grid1.CurStkColNum;
The syntax for this variable is
formname.gridname.CurStkColNum
where:
Is the name of the Winform.
Is the name of the grid.
The syntax for this variable is
formname.gridname.CurGrdRowNum
where:
Is the name of the Winform.
Is the name of the grid.
The syntax for this variable is
formname.gridname.CurGrdColNum
where:
Is the name of the Winform.
Is the name of the grid.
Information Builders |