x

The Winform command performs three tasks:

• Displaying and controlling forms.
• Setting form and form control properties (controls are sometimes referred to as Winform objects).
• Querying form and form control properties.

The syntax of the Winform command for displaying and controlling forms is

Winform command formname [;]

where command is one of the following:

Show

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.

Show_Active

Can be used for clarity. It is functionally identical to Show.

Show_Inactive

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.

Refresh

Repopulates the form's data values as if control had returned to the form from a trigger, but without making the form active.

Close_All

Closes all forms. The form environment remains active.

Close

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:

• Passes control directly to the beginning of the chain, to the point just following the Winform Show command that called the specified form.
• Removes closed popup forms from the screen. Closed non-popup Winforms remain on the screen until hidden by a Winform Hide command or the end of the current Maintain procedure.

Stop

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:

formname

Is the name of the form.

controlname

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.

property

Is any valid property. Properties are described in Dynamically Changing Winform Control Properties.

value

Is a value that is valid for the specified property. Properties and their values are described in Dynamically Changing Winform Control Properties.

variable

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.

x

• NEXT retrieves sets of data from a data source into a stack; you can then display the stack's data in a form.
• TYPE displays messages on the screen or writes them to a file.

x

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:

1. Winform A is active, and the user invokes a trigger.
2. The trigger calls a function.
3. The function displays Winform B and makes B active. Winform A is no longer active.
4. Once Winform B is exited, the rest of the function is performed.
5. When the function is exited, Winform A becomes active again.

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.

x

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.

x

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:

• Color: controls in general. You can change the foreground and background colors of a Winform control, or of the entire Winform, by setting the FOREGROUND_COLOR and BACKGROUND_COLOR properties respectively. You can set these properties to a color’s name or to its corresponding numeric value; the Winform Get command retrieves the numeric value. The following colors are available:

  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;

• Color: grid columns. You can change the background and foreground colors of a grid column using the ChangeColBcolor and ChangeColFcolor functions respectively. The syntax for calling these functions is

  [COMPUTE] formname.gridname.ChangeColBcolor(ColumnNumber, ColorNumber);
  [COMPUTE] formname.gridname.ChangeColFcolor(ColumnNumber, ColorNumber);

  where:

  COMPUTE

  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.

  formname

  Is the name of the Winform that contains the grid.

  gridname

  Is the name of the grid.

  ColumnNumber

  Is the column number in the grid.

  ColorNumber

  Is the number associated with the color you want in the grid column. Colors and numbers are listed in the previous table.

• Visibility: general. You can display and hide a control by setting its VISIBLE property to YES or NO respectively. The corresponding values retrieved by Winform Get are 1 and 0.

  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;

• User control: general. You can protect and unprotect a control from being used by setting PROTECTED to YES and NO respectively. The corresponding values retrieved by Winform Get are 1 and 0.

  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.

• User control: adding grid columns. You can prevent a user from adding rows to a grid using the SetStackMode function. The user is still able to scroll through the stack and update and delete data in the stack’s existing rows. (If you also wish to prevent users from changing existing data, you can protect the stack in the Winform Painter.)

  The syntax for calling this function is

  [COMPUTE] formname.gridname.SetStackMode(ADDOFF);

  where:

  COMPUTE

  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.

  formname

  Is the name of the Winform that contains the grid.

  gridname

  Is the name of the grid.

  ADDOFF

  Prevents the user from placing the cursor below the last line of the grid that contains data.

• Input focus. You can specify which control is active—that is, which control is the focus of user activity such as pressing a function key—by setting its FOCUS property. The control to receive focus is always set to the value HERE. The Winform Get command retrieves the name of the control that currently has focus.

  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;

• Bold font for a control’s text. You can make a control’s text bold, or not bold, by setting its BOLD_FONT property to YES or NO respectively. The corresponding values retrieved by Winform Get are 1 and 0.

  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;

• Underline font for a control’s text. You can make a control’s text underlined, or not underlined, by setting its UNDERLINE_FONT property to YES or NO respectively. The corresponding values retrieved by Winform Get are 1 and 0.

  For example, the following command underlines the text in the SubmitButton button in the EmployeeReview Winform:

  Winform Set EmployeeReview.SubmitButton.UNDERLINE_FONT TO YES;

• Blinking font for a control’s text. You can make a control’s text blink, or not blink, by setting its BLINK_FONT property to YES or NO respectively. The corresponding values retrieved by Winform Get are 1 and 0.

  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;

• Current grid column and row. You can determine and set which grid column and row are current (that is, active) using several variables defined for grids. These enable you to refer to the current grid column and row either by counting from the first column or row in the grid (that is, an absolute reference), or by counting from the first column or row currently visible in a grid, which enables you to take into account how the grid has been scrolled (that is, a relative referenceærelative to the first currently visible column).
• CurStkRowNum. The CurStkRowNum variable always contains the value of the current row number in the grid, and is set automatically by Maintain. This system variable is helpful for determining the current row number. For example, the following command assigns the current row number of Grid1 to the variable RowNumber:

  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:

  formname

  Is the name of the Winform.

  gridname

  Is the name of the grid.

• CurStkColNum. The CurStkColNum variable always contains the value of the current column number in the grid, and is set automatically by Maintain. This variable is helpful for determining the current column number. For example, the following command assigns Grid1’s current column number to the variable ColNumber:

  ColNumber = ContactListForm.Grid1.CurStkColNum;

  The syntax for this variable is

  formname.gridname.CurStkColNum

  where:

  formname

  Is the name of the Winform.

  gridname

  Is the name of the grid.

• CurGrdRowNum. The CurGrdRowNum variable contains the number of the current grid row, relative to the first row that is visible in the grid, and is set automatically by Maintain. This variable is different from CurStkRowNum if you scroll the grid. For example, if you scroll down a grid, your current row number may be 12, but the relative row number may be 3.

  The syntax for this variable is

  formname.gridname.CurGrdRowNum

  where:

  formname

  Is the name of the Winform.

  gridname

  Is the name of the grid.

• CurGrdColNum. The CurGrdColNum variable contains the number of the current grid column, relative the first column that is visible in the grid, and is set automatically by Maintain. This variable is different from CurStkColNum if you scroll the grid left or right.

  The syntax for this variable is

  formname.gridname.CurGrdColNum

  where:

  formname

  Is the name of the Winform.

  gridname

  Is the name of the grid.