Back to Contents

Using Windows and Forms

Summary:

• Windows and Forms Concepts
  • Windows
  • Forms
  • Windows in MDI mode
  • Traditional text mode
• Opening a Window (OPEN WINDOW)
  • Window Position and Dimensions
  • Open With Form
  • Window Styles
  • Window Titles
  • Window Icons
  • OPEN WINDOW attributes
• 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)
• Clearing the screen (CLEAR SCREEN)
• Displaying text by position (DISPLAY AT)

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, DIALOG, 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 a Genero program starts, 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. You can display the main form of your program in the SCREEN window, by using OPEN FORM + DISPLAY FORM.

A program creates a new 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. This is however not typical and is not recommended, since the last created window becomes the current window. When the last created window is closed, the previous window in the window stack becomes the current window.

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 being reloaded for 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. For temporary popup windows (typical record list where the user can select a row), you must dedicate a new window for the form. This can be done wit 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 MDI Windows for more details.

Traditional text mode

To simplify migration from Informix 4GL or Four Js BDS, you can run GUI application in traditional text mode, displaying windows as simple boxes. For more details, see Compatibility with traditional text mode.

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. 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.
3. 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.
4. form-file is a string literal or variable defining the form specification file to be used, without the file extension.
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. window-attributes defines the window attributes. See below for more details.

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.

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

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).

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

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 Position and Dimensions

When using the Genero GUI mode (without traditional rendering mode), the AT line, column clause is optional and if used, the WITH lines ROWS, characters COLUMNS clause is ignored, because the size of the window is automatically calculated according to its contents.

When using the TUI mode, the the AT line, column clause defines the position of the top-left corner of the window on the terminal screen and 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 GUI 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, but it is better 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.

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

It is recommended that you NOT change the default settings of windows styles in the default.4st file. If you create your own style file, copy the default styles into your file.

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

Window Titles

The TEXT attribute in the ATTRIBUTE 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/DISPLAY FORM instructions may change the window title if the new form defines a different 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.

Window Icons

If the window is opened with a form (WITH FORM) that defines an IMAGE attribute in the LAYOUT section, the window will use this image as icon. Subsequent OPEN FORM/DISPLAY FORM instructions may change the window icon if the new form defines a different image in the LAYOUT section.

If you want to set a window icon 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.

Usage:

Closing a window has no effect on variables that were set while the window was open.

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.

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

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

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

CURRENT WINDOW

Purpose:

Makes a specified window the current window.

Syntax:

Notes:

1. identifier is the name of the window.

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. All interactive instruction such as CONSTRUCT, INPUT 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 an interactive instruction resumes, its original window becomes the current window.

Example:

01 MAIN
02   OPEN WINDOW w1 WITH FORM "customer"
03   ...
04   OPEN WINDOW w2 WITH FORM "custlist"
05   ...
06   CURRENT WINDOW IS w1
07   ...
08   CURRENT WINDOW IS w2
09   ...
10   CLOSE WINDOW w1
11   CLOSE WINDOW w2
12 END MAIN

CLEAR WINDOW

Purpose:

Clears the contents of a window in character mode.

Syntax:

Notes:

1. identifier is the name of the window.

Usage:

This instruction is typically used in TUI based applications.

The CLEAR WINDOW instruction clears the content of the specified window that was declared in an OPEN WINDOW. If the window was created with borders, these are left untouched (only the content of the window is cleared).

If you specify CLEAR WINDOW SCREEN, the root screen will be cleared, except areas occupied by an existing window. CLEAR WINDOW SCREEN will not change the current window setting.

OPEN FORM

Purpose:

Declares a compiled form in the program.

Syntax:

Notes:

1. identifier is the name of the window object.
2. file-name is a string literal or variable defining the name of the compiled Form Specification File.

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. OPEN FORM / DISPLAY FORM are typically used at the beginning of programs to display the main form in the default SCREEN window:

01 OPEN FORM f FROM "customer"
02 DISPLAY FORM f

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.

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.

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

After the form is loaded, you can activate the form by executing a CONSTRUCT, DISPLAY ARRAY, INPUT, INPUT ARRAY, or DIALOG 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 FORM f1 FROM "customer"
03   DISPLAY FORM f1
04   CALL input_customer()
05   CLOSE FORM f1
06   OPEN FORM f2 FROM "custlist"
07   DISPLAY FORM f2
08   CALL input_custlist()
09   CLOSE FORM f2
10 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 DISPLAY FORM instruction creates a form element in the current window, from a form resource loaded by the OPEN FORM instruction.

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 the resources allocated by OPEN FORM.

Syntax:

Notes:

1. identifier is the name of the form.

Usage:

The CLOSE FORM instruction releases the memory allocated to the form.

CLEAR SCREEN

Purpose:

Clears the complete application screen in character mode.

Syntax:

Usage:

The CLEAR SCREEN instruction is typically used in TUI mode to clear the complete screen and make the root screen window the current window on the stack. The whole screen will be cleared, including prompt, error and message lines (the menu line is not cleared).

DISPLAY AT

Purpose:

Displays text at a given line/column position 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.

Usage:

The DISPLAY AT instruction evaluates and displays a string expression at a given line and column in the current window. This instruction is typically used in text-based applications to display static text on the screen such as messages or decoration lines with - (dash) or _ (underscore) characters.

The DISPLAY AT instruction should only be used in TUI mode. To display data at a given place in a graphical form, use form fields and the DISPLAY BY NAME or DISPLAY TO instruction.

Note that when using DISPLAY AT in GUI mode, the text will only be displayed if the current window contains no form or contains a form defined with the SCREEN layout.

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