Back to Contents

Using Windows and Forms

Summary:

• Windows and Forms Concepts
• Opening a Window (OPEN WINDOW)
  • Window Dimensions
  • Open With Form
  • Window Styles
  • Window Title
  • OPEN WINDOW attributes
• Windows closed by the user
• Closing a Window (CLOSE WINDOW)
• Selecting a Window (CURRENT WINDOW IS)
• Opening a Form (OPEN FORM)
• Displaying a Form (DISPLAY FORM)
• Closing a Form (CLOSE FORM)
• Clearing a Window (CLEAR WINDOW) Console Only!
• Clearing the screen (CLEAR SCREEN) Console Only!
• Displaying text by position (DISPLAY AT) Console Only!

See also: Presentation Styles, Window class, Form class, Flow Control, Forms, Input Array, Display Array, Record Input, Construct.

Windows and Forms Concepts

Programs manipulate "Window" and "Form" objects to define display areas for interactive instructions like INPUT ARRAY, DISPLAY ARRAY, INPUT and CONSTRUCT. When an interactive instruction takes control, it uses the Form associated with the current window.

Windows

Windows are created from programs; they define a display context for sub-elements like forms, ring menus, message and error lines. A window can contain only one form at a time.

When using a character terminal, windows are displayed as fixed-size boxes, at a given line and column position, with a given width and height. When using a graphical front end, windows are displayed as independent resizable windows by default. This behavior is needed to create real graphical applications, but it breaks the old-mode layout implementations.

When the runtime system starts a program, it creates a default window named SCREEN. This default window can be used as another window (it can hold a Ring Menu and a Form), but it can also be closed, with CLOSE WINDOW SCREEN.

A program creates a window with the OPEN WINDOW instruction, which also defines the window identifier. The program destroys a Window with the CLOSE WINDOW instruction. One or more windows can be displayed concurrently, but there can be only one current Window. You can use the CURRENT WINDOW instruction to make a specific window current.

When opening a window, the window style is used to specify the type and the decoration of the window.

You can also use the ui.Window class to manipulate windows as objects.

Forms

Forms define the layout and presentation of areas used by the program to display or input data. Typically, Forms are loaded by programs from external files with the 42f extension, the compiled version of Form Specification Files.

Forms files are identified by the file name, but you can also specify a form version with the VERSION attribute. The form version attribute is typically used to indicate that the form content has changed. The front-end is then able to distinguish different form versions and avoid saved settings to be reloaded on new form versions.

A program can load a Form file with the OPEN FORM instruction, then display the Form with DISPLAY FORM into the current window, and release resources with CLOSE FORM. However, it is recommended that you dedicate a window for each form. Programs typically create the window and load the form in a unique instruction: OPEN WINDOW WITH FORM.

When a Form is displayed, it is attached to the current window and a ui.Form object is created internally. You can get this object with the ui.Window.getForm() method. The ui.Form built-in class is provided to handle form elements. You can, for example, hide some parts of a form.

The Form that is used by interactive instructions like INPUT is defined by the current window.

Windows in MDI mode

Windows can be displayed in an MDI container application; see Dynamic User Interface for more details.

OPEN WINDOW

Purpose:

Creates and displays a new Window.

Syntax:

Notes:

1. identifier is the name of the window; it is always converted to lowercase by the compiler.
2. The AT clause is optional.
3. line is the integer defining the top position of the window.
   The first line in the screen is 1, while the relative line number inside the window is zero.
4. column is the integer defining the position of the left margin.
   The first column in the screen is 1, while the relative column number inside the window is zero.
5. height defines the number of lines of the window in character units; includes the borders in character mode.
6. width defines the number of lines of the window in character units; includes the borders in character mode.
7. form-file is a string literal or variable defining the form specification file to be used, without the file extension.
8. window-attributes defines the window attributes. See below for more details.

Tips:

1. For graphical applications, use this instruction without the AT clause, and with the WITH FORM clause.

Warnings:

1. The compiler converts the window identifier to lowercase for internal storage. When using functions or methods taking the window identifier as a string parameter, the window name is case-sensitive. Therefore, we recommend that you always specify the window identifier in lowercase letters. 

Usage:

An OPEN WINDOW statement can have the following effects:

• Declares a name (the identifier) for the window.
• Indicates which form has to be used in that window.
• Specifies the display attributes of the window.
• When using character mode, specifies the position and dimensions of the window, in character units.

The window identifier must follow the rules for identifiers and be unique among all windows defined in the program. Its scope is the entire program. You can use this identifier to reference the same Window in other modules with other statements (for example, CURRENT WINDOW and CLOSE WINDOW).

The runtime system maintains a stack of all open windows. If you execute OPEN WINDOW to open a new window, it is added to the window stack and becomes the current window. Other statements that can modify the window stack are CURRENT WINDOW and CLOSE WINDOW.

Window Dimensions

When using graphical mode, the WITH lines ROWS, characters COLUMNS clause is ignored, because the size of the window is automatically calculated according to its contents.

When using character mode, the WITH lines ROWS, characters COLUMNS clause specifies explicit vertical and horizontal dimensions for the window. The expression at the left of the ROWS keyword specifies the height of the window, in character unit lines. This must be an integer between 1 and max, where max is the maximum number of lines that the screen can display. The integer expression after the comma at the left of the COLUMNS keyword specifies the width of the window, in character unit columns. This must return a whole number between 1 and length, where length is the number of characters that your monitor can display on one line. In addition to the lines needed for a form, allow room for the Comment line, the Menu line, the Menu comment line and the Error line. The runtime system issues a runtime error if the window does not include sufficient lines to display both the form and these additional reserved lines. The minimum number of lines required to display a form in a window is the number of lines in the form, plus an additional line below the form for prompts, messages, and comments.

Open With Form

As an alternative to specifying explicit dimensions, the WITH FORM clause can specify a quoted string or a character variable that specifies the name of a file that contains the compiled screen form. The runtime system expects the compiled version of the form, but the file name should not include the .42f file extension. A window is automatically opened and sized to the screen layout of the form. When using character mode, the width of the window is from the left-most character on the screen form (including leading blank spaces) to the right-most character on the screen form (truncating trailing blank spaces). The length of the window is calculated as (form line) + (form length).

It is recommended that you use the WITH FORM clause, especially in the standard graphical mode, because the window is created in accordance with the form. If you use this clause, you do not need the OPEN FORM, DISPLAY FORM, or CLOSE FORM statement to open and close the form. The CLOSE WINDOW statement closes the window and the form.

Window Styles

By default windows are displayed as normal application windows, but you can use the window style to show a window at the top of all other windows, as a "modal window".

The window style defines the type of the window (normal, modal) and its decoration, via a Presentation Style. The Presentation Style specifies a set of attributes in an external file (.4st).

The STYLE attribute can be used in the OPEN WINDOW instruction to define the default style for a Window, It is better, however, to specify the window style in the form file, with the WINDOWSTYLE attribute of the LAYOUT section. This avoids decoration-specific code in the programs.

Warnings:

1. If you open and display a second form in an existing window, the window style of the second form is not applied.

The following standard window styles are defined in the default presentation style file (FGLDIR/lib/default.4st):

Warnings:

1. It is not recommended that you change the default settings of window styles in the 4st file.
2. If you want to define your own style, you must copy the default styles in your own file.
3. It is not possible to change the presentation attributes of windows in the AUI tree.

For more details about the attributes you can set for Windows, see Presentation Styles.

Window Title

The TEXT attribute in the ATTRIBUTES clause defines the default title of the window. If the window is opened with a form (WITH FORM) that defines a TEXT attribute in the LAYOUT section, the default is ignored. Subsequent OPEN FORM instructions may change the window title if the form defines a new title in the LAYOUT section.

It is recommended that you specify the window title in the form file, not with the TEXT attribute of the OPEN WINDOW instruction.

If you want to set a window title dynamically, you can use the Window built-in class.

OPEN WINDOW attributes

The following table shows the window-attributes supported by the OPEN WINDOW statement:

The following list describes the default line positions in character mode:

• First line: Prompt line (output from PROMPT statement) and Menu line (command value from MENU statement).
• Second line: Message line (output from MESSAGE statement; also the descriptions of MENU options).
• Third line: Form line (output from DISPLAY FORM statement).
• Last line: Error line (output from ERROR statement); also comment line in any window except SCREEN.

Example:

01 MAIN
02    OPEN WINDOW w1 WITH FORM "customer"
03    MENU "Test"
04       COMMAND KEY(INTERRUPT) "exit" EXIT MENU
05    END MENU
06    CLOSE WINDOW w1
07 END MAIN

CLOSE WINDOW

Purpose:

Closes and destroys a window. 

Syntax:

Notes:

1. identifier is the name of the window.
2. If the OPEN WINDOW statement includes the WITH FORM clause, it closes both the form and the window.
3. Closing a window has no effect on variables that were set while the window was open.
4. Closing the current window makes the next window on the stack the new current window. If you close any other window, the runtime system deletes it from the stack, leaving the current window unchanged.

Tips:

1. You can close the default screen window with the CLOSE WINDOW SCREEN instruction.

Warnings:

1. If the window is currently being used for input, CLOSE WINDOW generates a runtime error.

Example:

01 MAIN
02    OPEN WINDOW w1 WITH FORM "customer"
03    MENU "Test"
04       COMMAND KEY(INTERRUPT) "exit" EXIT MENU
05    END MENU
06    CLOSE WINDOW w1
07 END MAIN

Windows closed by the user

In typical graphical applications, windows can be closed by the user, for example on Microsoft Windows by pressing ALT+F4 or by clicking the cross button in the upper-left corner of the window.

A Predefined Action is dedicated to this specific event: When the user closes a graphical window, the program gets a 'close' action.

By default, when the program is in a MENU instruction, the 'close' action is converted to an INTERRUPT key press (the key that cancels a dialog). This means that a COMMAND KEY(INTERRUPT) block is invoked if it is defined in the MENU statement. If there is no COMMAND KEY(INTERRUPT), nothing happens. 

When the program is in an INPUT, INPUT ARRAY, CONSTRUCT or DISPLAY ARRAY, the 'close' action acts by default the same as the 'cancel' predefined action. So when the user clicks the X cross button, the dialog stops and int_flag is set to 1.

To prevent / overwrite the default behavior, you can overwrite the 'close' action as in the following example:

01 MAIN
02    OPEN WINDOW w1 WITH FORM "customer"
03    MENU "Test"
04       ON ACTION quit
05         DISPLAY "quit ..."
06         EXIT MENU
07       ON ACTION close
08         DISPLAY "close ..."
09         EXIT MENU
10    END MENU
11    CLOSE WINDOW w1
12 END MAIN

CURRENT WINDOW

Purpose:

Make a specified window the current window.

Syntax:

Notes:

1. identifier is the name of the window or the SCREEN keyword.

Usage:

Programs with multiple windows might need to switch to a different open window so that input and output occur in the appropriate window. To make a window the current window, use the CURRENT WINDOW statement.

When a program starts, the screen is the current window. Its name is SCREEN. To make this the current window, specify the keyword SCREEN instead of a window identifier.

If the window contains a form, that form becomes the current form when a CURRENT WINDOW statement specifies the name of that window. The CONSTRUCT, DISPLAY ARRAY, INPUT, INPUT ARRAY, and MENU statements use only the current window for input and output. If the user displays another form (for example, through an ON KEY clause) in one of these statements, the window containing the new form becomes the current window. When the CONSTRUCT, DISPLAY ARRAY, INPUT, INPUT ARRAY, or MENU statement resumes, its original window becomes the current window.

Example:

01 MAIN
02    OPEN WINDOW w1 WITH FORM "customer"
03    OPEN WINDOW w2 WITH FORM "custlist"
04    MENU "Test"
05       COMMAND "Win1"
06          CURRENT WINDOW IS w1
07       COMMAND "Win2"
08          CURRENT WINDOW IS w2
09       COMMAND KEY(INTERRUPT) "exit"
10          EXIT MENU
11    END MENU
12    CLOSE WINDOW w1
13    CLOSE WINDOW w2
14 END MAIN

CLEAR WINDOW Console Only!

Purpose:

Clears the contents of a window in character mode.

Syntax:

Notes:

1. identifier is the name of the window, or the SCREEN keyword.

Warnings:

1. This instruction is provided for backward compatibility; it is only supported to clear windows created in character mode.

OPEN FORM

Purpose:

Declares a compiled form in the program.

Syntax:

Notes:

1. identifier is the name of the window object.
2. The scope of reference of identifier is the entire program.
3. file-name is a string literal or variable defining the name of the compiled Form Specification File.
4. Form files are found by using the directory paths defined in the DBPATH environment variable.

Tips:

1. When the window is dedicated to the form, use the OPEN WINDOW WITH FORM instruction to create the window and the form object in one statement.
2. It is not recommended that you provide a path for file-name; You should use the DBPATH environment variable instead.

Usage:

In order to use a 42f compiled version of a Form Specification File, the programs must declare the form with the OPEN FORM instruction and then display the form in the current window by using the DISPLAY FORM instruction. Both operations can be automatically performed by opening a window that directly uses the form, using the WITH FORM clause:

01 OPEN WINDOW w1 WITH FORM "customer"

If you execute an OPEN FORM with the name of an open form, the runtime system first closes the existing form before opening the new form.

In character mode, the form is displayed in the current window at the position defined by the FORM LINE attribute, which can be specified in the ATTRIBUTE clause of OPEN WINDOW or as the default with the OPTIONS instruction. 

After the form is loaded, you can activate the form by executing a CONSTRUCT, DISPLAY ARRAY, INPUT, or INPUT ARRAY statement. When the runtime system executes the OPEN FORM instruction, it allocates resources and loads the form into memory. To release the allocated resources when the form is no longer needed,  the program must execute the CLOSE FORM instruction. This is a memory-management feature to recover memory from forms that the program no longer displays on the screen. If the form was loaded with a window by using the WITH FORM clause, it is automatically closed when the window is closed with a CLOSE WINDOW instruction.

The quoted string that follows the FROM keyword must specify the name of the file that contains the compiled screen form. This filename can include a pathname, but this is not recommended.

The form identifier does not need to match the name of the Form Specification File, but it must be unique among form names in the program. Its scope of reference is the entire program.

Example:

01 MAIN
02    OPEN WINDOW w1 WITH 11 ROWS, 63 COLUMNS
03    OPEN FORM f1 FROM "customer"
04    DISPLAY FORM f1
05    CALL input_customer()
06    CLOSE FORM f1
07    OPEN FORM f2 FROM "custlist"
08    DISPLAY FORM f2
09    CALL input_custlist()
10    CLOSE FORM f2
11    CLOSE WINDOW w1
12 END MAIN

DISPLAY FORM

Purpose:

Displays and associates a form with the current window.

Syntax:

Notes:

1. identifier is the name of the form.
2. window-attributes defines the display attributes of the form. See below for more details.

Usage:

The following table shows the display-attributes supported by the DISPLAY FORM statement:

The runtime system applies any other display attributes that you specify in the ATTRIBUTE clause to any fields that have not been assigned attributes by the ATTRIBUTES section of the Form Specification File, or by the database schema files, or by the OPTIONS statement. If the form is displayed in a window, color attributes from the DISPLAY FORM statement supersede any from the OPEN WINDOW statement. If subsequent CONSTRUCT, DISPLAY, or DISPLAY ARRAY statements that include an ATTRIBUTE clause reference the form, however, their attributes take precedence over those specified in the DISPLAY FORM instruction.

CLOSE FORM

Purpose:

Closes a form.

Syntax:

Notes:

1. identifier is the name of the form.
2. Releases the memory allocated to the form.

Tips:

1. A form associated with a window by the OPEN WINDOW WITH FORM instruction is automatically closed when the program closes the window with a CLOSE WINDOW instruction.

CLEAR SCREEN Console Only!

Purpose:

Clears the complete application screen in character mode.

Syntax:

Notes:

1. Clears the complete screen.

Warnings:

1. The CLEAR SCREEN instruction is provided for backward compatibility.

DISPLAY AT Console Only!

Purpose:

Displays text at a given position in character mode in the current window.

Syntax:

Notes:

1. text is any expression to be evaluated and displayed at the given position in the current window.
2. line is an integer literal or variable defining the line position in the current window.
3. column is an integer literal or variable defining the column position on the screen.
4. display-attributes defines the display attributes for the text. See below for more details.

Warnings:

1. The DISPLAY AT instruction is provided for backward compatibility and can only be used in character mode. To display data at a given place in a graphical form, use form fields and the DISPLAY TO instruction.

Usage:

The following table shows the display-attributes supported by the DISPLAY AT statement: