The Form Specification File

You can specify the layout of a form in a form specification file, which is compiled separately from your program.

Overview

Form specification files created in Genero Studio's Form Designer have a file extension of .4fd. Text-based form specification files have a file extension of .per. The structure of the form is independent of the use of the form. For example, one function can use a form to display a database row, another can let the user enter a new database row, and still another can let the user enter criteria for selecting database rows.

A Form can contain the following types of items:
  • Container - groups other form items. Every form item must be in a container. GRID is the basic container, frequently used to display a single row of database data. TABLE containers can provide record-list presentation in columns and rows. Other containers, such as a FOLDER or GROUP, provide additional options for organizing the form layout.
  • FormField - defines an area where the user can view and edit data. The data is stored in variables defined in the .4gl source code file. The EDIT formfield provides a simple line-edit field. Other form items, such as a COMBOBOX or RADIOGROUP, provide a user-friendly interface to the data stored in the underlying form field. The data type of a formfield can be defined by a database table column, or it can be FORMONLY - defined specifically in the form.
  • Action view - allows the user to trigger actions specified in the .4gl file. An Action view can be a BUTTON, TOOLBAR item, or TOPMENU option, for example.
  • Other - items that enhance the display or provide read-only information (an IMAGE or LABEL, for example).

Each form and form item has attributes that control its appearance and behavior. Go to the documentation for Form specification files and Form item attributes in the Genero Business Development Language User Guide for additional information about form items.

Decoration attributes from a Presentation Styles file can be applied to the form and form items, such as backgroup colors for example.

The SCHEMA section (optional)

This specifies the database schema file to be used when the form is compiled. It is required if any form items are defined as data types based on a column of a database table.

SCHEMA custdemo

The ACTION DEFAULTS, TOPMENU, and TOOLBAR sections (optional)

These sections are provided to allow you to define the decoration for action views (action defaults), as well as to define topmenus and toolbars for the form. In this case, the definitions are specific to the form. If your definitions are in external XML files instead, they can be applied to any form.

This is discussed in chapter 5.

The LAYOUT section

This section defines the appearance of a form using a layout tree.

Of containers, which can hold other containers or can define a screen area. Some of the available containers are GRID, VBOX, HBOX, GROUP, FOLDER, and PAGE.

The simplest layout tree could have only a GRID container defining the dimensions and the position of the logical elements of a screen:

LAYOUT
GRID
{
    grid-area
}
END 
END

The END keyword is mandatory to define the end of a container block.

The grid-area is delimited by { } curly braces. Within this area, you can specify the position of form items or interactive objects such as BUTTON, COMBOBOX, CHECKBOX, RADIOGROUP, PROGRESSBAR, and so on.

Simple form fields, delimited by square brackets ( [ ] ), are form items used to display data and take input. Generally, the number of characters in the space between the brackets defines the width of the region to be used by the item. For example, in the grid-area, the following field could be defined:

[f01            ]

This form field has an item tag of f01, which will be used to link the field to its definition in the ATTRIBUTES section of the form specification.

Text in the grid-area that is outside brackets is display-only text, as in the word Company:

Company [f01            ]
However, in order to internationalize (localize) your application messages, best practice is to define an item tag for labels, and specify the text in the ATTRIBUTES section:
[l01     |f01          ]
...
ATTRIBUTES
...
LABEL l01: l_company, TEXT=%"label.company";

The TABLES section (optional)

If a database table or database view is referenced elsewhere in the form specification file, in the ATTRIBUTES, the schema must be declared at the top the form definition file, and the SQL table must be declared in the TABLES section:

SCHEMA custdemo
...
TABLES
  customer 
END

A default screen record is automatically created for the form fields associated with each table listed in this section.

The ATTRIBUTES section

The ATTRIBUTES section defines properties of the items used in the form:

ATTRIBUTES
EDIT f01 = customer.cust_num, NOENTRY;
COMBOBOX f03 = customer.state, ITEMS=("IL","IA", "WI");
CHECKBOX f04 = formonly.propcheck, TEXT="Checked",
    VALUECHECK="Y", VALUEUNCHECKED="N";

The most commonly used item-type, EDIT, defines a simple line edit box for data input or display. This example uses an EDIT item-type for the form field f01. The COMBOBOX and CHECKBOX item types present the data contained in the form fields f03 and f04 in a user-friendly way.

The item-name must specify a database column as the name of the display field, or must be FORMONLY. Fields are associated with database columns only during the compilation of the form specification file, to identify the data type for the form field based on the database schema. After the form compiler identifies the data types, the association between fields and database columns is broken, and the item-name is associated with the screen record.

Static form items such as BUTTON and LABEL are not bound to a form field, and are defined with a : colon instead of an = equal sign:
BUTTON btn1: print, TEXT = "Print Report";
LABEL lab1: label1, TEXT = "Customer";

The INSTRUCTIONS section (optional)

The INSTRUCTIONS section is used to define explicit screen records or screen arrays. This is discussed in Chapter 7