The Form Specification File

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 data that is displayed.
• 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 formfield. 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 icon, 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. See the documentation for Form specification files and Form item attributes in the Genero Business Development Language User Guide for additional information about form items.

Styles from a Presentation Styles file can be applied to the form and form items.

A basic form specification consists of the following sections:

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.

Interactive form items, such as COMBOBOX, CHECKBOX, and RADIOGROUP, can be used instead of simple form fields to represent the values in the underlying formfield. Special width calculations are done for some of these form items, such as COMBOBOX, BUTTONEDIT, and DATEEDIT. If the default width generated by the form compiler does not fit, the - dash symbol can be used to define the real width of the item.

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

Company [f01            ]

The TABLES section (optional)

If a database table or database view is referenced elsewhere in the form specification file, in the ATTRIBUTES

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.

Form Fields

<item-type> <item-tag> = <item-name>, <attribute-list> ;

• The item-type defines the kind of graphical object which must be used to display the form element.
• The item-tag identifies the form item in the display area.
• The item-name provides the name of the form item.
• The optional attribute-list defines the aspect and behavior of the form item.

Examples

EDIT f01 = customer.cust_num,REQUIRED;
COMBOBOX f03 = customer.state;
CHECKBOX f04 = formonly.propcheck;

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 defined as FORMONLY are discussed in chapter 11) 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.

Form field and form item definitions can optionally include an attribute-list to specify the appearance and behavior of the item. For example, you can define acceptable input values, on-screen comments, and default values for fields; you can insure that a value is entered in the field during the input of a new row (REQUIRED); columns in a table can be specified as sortable or non-sortable; numbers and dates can be formatted for display; data entry patterns can be defined and input data can be upshifted or downshifted.

A form field can be an EDIT, BUTTONEDIT, CHECKBOX, COMBOBOX, DATEEDIT, IMAGE, LABEL, PROGRESSBAR, RADIOGROUP, or TEXTEDIT.

Other form items

<item-type> <item-tag>: <item-name> , <attribute-list> ;

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