Back to Contents

Form Specification File Attributes

Summary:

• Attributes Summary

See also: Form Specification Files.

Attributes Summary

ACCELERATOR Attribute

Purpose:

The ACCELERATOR attribute defines the primary accelerator key of an action default item.

Syntax:

Notes:

1. key defines the accelerator key as described in Accelerators

ACCELERATOR2 Attribute

Purpose:

The ACCELERATOR2 attribute defines the secondary accelerator key of an action default item.

Syntax:

Notes:

1. key defines the accelerator key as described in Accelerators

ACCELERATOR3 Attribute

Purpose:

The ACCELERATOR3 attribute defines the third accelerator key of an action default item.

Syntax:

Notes:

1. key defines the accelerator key as described in Accelerators

ACCELERATOR4 Attribute

Purpose:

The ACCELERATOR4 attribute defines the fourth accelerator key of an action default item.

Syntax:

Notes:

1. key defines the accelerator key as described in Accelerators

ACTION Attribute

Purpose:

The ACTION attribute defines the name of the action to be sent to the program when the user activates the form item.

Syntax:

Notes:

1. action-name is an identifier that defines the name of the action to be sent.

Tips:

1. Try to use abstract action names instead of key identifiers.

Example:

01 BUTTONEDIT f001 = customer.state, ACTION = print;

AUTOSCALE Attribute

Purpose:

The AUTOSCALE attribute causes the form element contents to automatically scale to the size given to the item.

Syntax:

Notes:

1. For images, this attribute forces the image to be stretched to fit in the area reserved for the image.

AUTONEXT Attribute

Purpose:

The AUTONEXT attribute causes the cursor to automatically advance during input to the next field when the current field is full.

Syntax:

Notes:

1. If data values entered in the field do not meet the requirements of other field attributes like INCLUDE or PICTURE, the cursor does not automatically move to the next field but remains in the current field, and an error message displays.

Tips:

1. AUTONEXT is particularly useful with character fields in which the input data is of a standard length, such as numeric postal codes or the abbreviations in the state table. It is also useful if a character field has a length of 1 because only one keystroke is required to enter data and move to the next field.

CENTURY Attribute

Purpose:

The CENTURY attribute specifies how to expand abbreviated one- and two-digit year specifications in a DATE and DATETIME field. Expansion is based on this setting (and on the year value from the system clock at runtime).

Syntax:

Notes:

1. The CENTURY attribute can specify any of four algorithms to expand abbreviated years into four-digit year values that end with the same digits (or digit) that the user has entered.
2. CENTURY supports the same settings as the DBCENTURY environment variable, but with a scope that is restricted to a single field.
3. If the CENTURY and DBCENTURY settings are different, CENTURY takes precedence.

Warnings:

1. Unlike DBCENTURY, the CENTURY attribute is not case sensitive. However, we recommend that you use uppercase letters in the attribute.

CLASS Attribute

Purpose:

The CLASS attribute is used to define the behavior of a field.

Syntax:

Notes:

1. identifier is a predefined keyword defining the class of the field.

Supported field classes:

Warnings:

1. The attribute is supported for backward compatibility.

COLOR Attribute

Purpose:

The COLOR attribute defines the foreground color of the text displayed by a form element.

Syntax:

Notes:

1. color-name can be: BLACK, BLUE, CYAN, GREEN, MAGENTA, RED, WHITE, and YELLOW.
2. For backward compatibility, color-name can be combined with an intensity keyword: REVERSE, LEFT, BLINK, and UNDERLINE.

Example:

01 EDIT f001 = customer.name, COLOR = RED;

COLOR WHERE Attribute

Purpose:

The COLOR WHERE attribute defines a condition to set the foreground color dynamically.

Syntax:

Notes:

1. color-name can be: BLACK, BLUE, CYAN, GREEN, MAGENTA, RED, WHITE, and YELLOW.
2. color-name can also be an intensity keyword: REVERSE, LEFT, BLINK, and UNDERLINE.
3. boolexpr defines a Boolean expression with a restricted syntax.
4. The Boolean expression is automatically evaluated at runtime to check when the color attribute must be set.

Warnings:

1. The condition in COLOR WHERE can only reference the field for which the attribute is set.
2. The COLOR WHERE attribute may not be supported in all situations; it is not supported in TABLE columns.

Example:

01 EDIT f001 = item.price, COLOR = RED WHERE f001>100;

CONFIG Attribute

Purpose:

The CONFIG attribute is used with the WIDGET attribute to define the behavior and decoration of the field.

Syntax:

Notes:

1. The CONFIG attribute can only be used with the WIDGET attribute. It is ignored if WIDGET is not used.
2. parameter is the value of a configuration parameter.
3. Configuration parameters are separated by blanks.
4. If a configuration parameter holds blank characters, you must use {} curly braces to delimit the parameter value.
5. See the WIDGET attribute for more details about configuration.

COMMENT Attribute

Purpose:

The COMMENT attribute defines text that can be shown when the element becomes current.

Syntax:

Notes:

1. string is the text to be displayed.
2. string can be a localized string.
3. The screen location where the message is displayed depends on external configuration. It can be displayed in the COMMENT LINE, or in the STATUSBAR when using a graphical user interface.

Tips:

1. The most common use of the COMMENT attribute is to give information or instructions to the user. This is particularly appropriate when the field accepts only a limited set of values.

Warnings:

1. If the OPEN WINDOW statement specifies COMMENT LINE OFF, any output to the comment area is hidden even if the window displays a form that includes fields that include the COMMENT attribute.

Example:

01 EDIT f001 = customer.name, COMMENT = "The customer name";

DEFAULT Attribute

Purpose:

The DEFAULT attribute assigns a default value to a field during data entry.

Syntax:

Notes:

1. value can be any literal expression supported by the form compiler.
2. value can be TODAY to specify the current system date as default.
3. value can be CURRENT to specify the current system datetime as default.
4. Default values have no effect when you execute the INPUT statement using the WITHOUT DEFAULTS option. In this case, the runtime system displays the values in the program variables list on the screen. The situation is the same for the INPUT ARRAY statement, except that the default values are displayed when the user inserts a new row.
5. If the field is FORMONLY, you must also specify a data type when you assign the DEFAULT attribute to a field.
6. If both the DEFAULT attribute and the REQUIRED attribute are assigned to the same field, the REQUIRED attribute is ignored.
7. If you do not use the WITHOUT NULL INPUT option in the DATABASE section, all fields default to null values unless you have specified a DEFAULT attribute.

Warnings:

1. DATETIME and INTERVAL literals are not supported.

Example:

01 EDIT f001 = order.orderdate, DEFAULT = TODAY;

DEFAULTVIEW Attribute

Purpose:

DEFAULTVIEW is an Action Default attribute defining whether the default view (button) must be displayed for an action.

Syntax:

Notes:

1. AUTO means that the view must be displayed if no explicit action view is used for that action. This is the default.
2. YES  indicates that a default action view must always be displayed for this action.
3. NO indicates that no default action view must be displayed for this action.

DISPLAY LIKE Attribute

Purpose:

The DISPLAY LIKE attribute takes column attributes defined in the database schema files and applies them to a field.

Syntax:

Notes:

1. table is the optional table name to qualify the column.
2. column is the name of the column to be used to retrieve display attributes.
3. Specifying this attribute is equivalent to listing all the attributes that are assigned to table.column in the database schema file generated from the syscolatt table.
4. Display attributes are automatically taken from the schema file if the field is linked to table.column in the field name specification.

Warnings:

1. The DISPLAY LIKE clause is evaluated at compile time, not at runtime. If the database schema file changes, you might need to recompile a program that uses the LIKE clause. Even if all of the fields in the form are FORMONLY, this attribute requires the form compiler to access the database schema file that contains the description of table.

Example:

01 EDIT f001 = FORMONLY.fullname, DISPLAY LIKE customer.custname;

HIDDEN Attribute

Purpose:

The HIDDEN attribute indicates that the element should not be displayed.

Syntax:

Notes:

1. HIDDEN sets the underlying item attribute to 1.
2. HIDDEN=USER sets the underlying item attribute to 2.

Warnings:

1. When you set a hidden attribute for a form field, the model node gets the hidden attribute, not the view node.

Usage:

By default, all elements are visible. You can use the HIDDEN attribute to hide an element, such as a form field or a groupbox. The runtime system handles hidden form fields. If you write an INPUT statement using a hidden field, the field is ignored (as if it was declared as NOENTRY). Programs may change the visibility of form fields dynamically with the ui.Form built-in class.

When you use the HIDDEN keyword only, the underlying item attribute is set to 1. The value 1 indicates that the element is hidden to the user without the possibility of showing the element, for example with the context menu of table headers. In this hidden mode, the UNHIDABLE attribute is ignored by the front end.

When you use HIDDEN=USER, the underlying item attribute is set to 2. The value 2 indicates that the element is hidden by default, but the user can show/hide the element as needed. For example, the user can change a hidden column back to visible.

Example:

01 EDIT f001 = FORMONLY.field1, HIDDEN;
02 EDIT col1 = FORMONLY.column1, HIDDEN=USER;

HEIGHT Attribute

Purpose:

The HEIGHT attribute defines an explicit height for a form element.

Syntax:

Notes:

1. integer defines the height of the element.

Usage:

By default, the size of an element is defined in characters and automatically computed by the form compiler according to the size of the form element in the layout.

For items like images, the default height is defined by the number of lines of the item tag (as a vertical character height). You can overwrite this default by specifying the HEIGHT attribute. You typically give a number of pixels. 

For tables, the default height is defined by the number of lines used in the table layout. You can overwrite this default by specifying the HEIGHT attribute.

If you don't specify any unit, the size unit defaults to CHARACTERS, which defines the number of grid cells.

See also: WIDTH.

Example:

01 IMAGE img1 : image1, WIDTH = 200 PIXELS, HEIGHT = 120 PIXELS;

BUTTONTEXTHIDDEN Attribute

Purpose:

The BUTTONTEXTHIDDEN attribute indicates that the labels of the buttons of this element should not be displayed.

Syntax:

Usage:

Use in a TOOLBAR definition to hide the labels of buttons.

DOUBLECLICK Attribute

Purpose:

The DOUBLECLICK attribute defines the action to be sent when the user double-clicks on a TABLE row.

Syntax:

Usage:

This attribute is typically used in a TABLE container, to define the action to be sent when the user double-clicks on a row. By default, if the TABLE is driven by a DISPLAY ARRAY, a double-click fires the accept action. When using an INPUT ARRAY, double-click selects the whole text if the current widget is editable. If DOUBLECLICK is defined when using an INPUT ARRAY, the action can only be sent when the user double-clicks on a non-editable widget like a LABEL.

DOWNSHIFT Attribute

Purpose:

Assign the DOWNSHIFT attribute to a character field when you want the runtime system to convert uppercase letters entered by the user to lowercase letters, both on the screen and in the corresponding program variable.

Syntax:

Notes:

1. Because uppercase and lowercase letters have different values, storing character strings in one or the other format can simplify sorting and querying a database.
2. Characters entered by the user are converted in INPUT, INPUT ARRAY and CONSTRUCT instructions.
3. When using single byte runners, the conversion of ASCII characters >127 is controlled by the LC_CTYPE environment variable.
4. The results of conversions between uppercase and lowercase letters are based on the locale settings (LANG).

FORMAT Attribute

Purpose:

You can use the FORMAT attribute with numeric and date time fields to control the format of output displays.

Syntax:

Notes:

1. format-string is a string of characters that specifies a data display format.
2. You must enclose format-string within quotation marks ( " ).
3. Use the PICTURE attribute to format data entered in the field by the user.
4. When using FORMAT the data is right-aligned in the field.
5. If format-string is smaller than the field width, you get a compile-time warning, but the form is usable.
6. When this attribute is not used, environment variable settings define the default format.

Warnings:

1. To follow abstract user interface programming and support internationalization, it is not recommended that you use this attribute.

Numeric formats:

For DECIMAL, SMALLFLOAT, and FLOAT data types, format-string consists of pound signs (#) that represent digits and a decimal point. For example, "###.##" produces three places to the left of the decimal point and exactly two to the right.

If the numeric value is too large to fit in the number of characters defined by the format, an overflow text is displayed (****).

If the actual number displayed requires fewer characters than format-string specifies, numbers are right-aligned and padded on the left with blanks.

If necessary to satisfy the format-string specification, the number values are rounded before display.

Date formats:

For DATE data types, the runtime system recognizes these symbols as special in format-string:

The form compiler interprets any other characters as literals and displays them wherever you place them within format-string.

These format-string examples and their corresponding display formats for DATE fields display the twenty-third day of September 1999:

Example:

01 EDIT f001 = order.thedate, FORMAT = "mm/dd/yyyy";

FONTPITCH Attribute

Purpose:

This attribute defines the character font type as fixed or variable when the default font is used.

Syntax:

Notes:

1. When using FIXED, you force the characters to have a fixed size.
2. When using VARIABLE, you allow the characters to have a variable size.

Usage:

By default, most front ends use variable width character fonts, but in some cases you might need to use a fixed font.

It is recommended that you use a STYLE defining a fixed font instead of this attribute.

GRIDCHILDRENINPARENT Attribute

Purpose:

This attribute is used for a container to align its children to the parent container.

Syntax:

Usage:

By default, child elements of a container are aligned locally inside the container layout cells. With this attribute, you can force children to be aligned according to the layout cells of the parent container of the container to which you assign this attribute.

This is useful, for example, when you want to align fields across groups defined with Layout Tags inside a GRID:

01 LAYOUT
02   GRID
03   {
04    <G g1                             >
05     Field1 [f1                      ]
06     Field2 [f2                      ]
07     Field3 [f3                      ]
08 
09    <G g2                             >
10     F4     [f4                  ]
11     F5     [f5                  ]
12 
13   }
14   END
15 END
16 ATTRIBUTES
17 GROUP g1 : GRIDCHILDRENINPARENT;
18 GROUP g2 : GRIDCHILDRENINPARENT;
19 EDIT f1 = FORMONLY.field1;
20 EDIT f2 = FORMONLY.field2;
21 EDIT f3 = FORMONLY.field3;
22 EDIT f4 = FORMONLY.field4;
23 EDIT f5 = FORMONLY.field5;
24 END

INCLUDE Attribute

Purpose:

The INCLUDE attribute specifies acceptable values for a field and causes the runtime system to check the data before accepting an input value.

Syntax:

Notes:

1. literal can be any literal expression supported by the form compiler.
2. If the field is FORMONLY, you must also specify a data type when you assign the INCLUDE attribute to a field.

Warnings:

1. DATETIME and INTERVAL literals are not supported.

Example:

01 EDIT f001 = compute.rate, INCLUDE = ( 1 TO 100, 200, NULL);
02 EDIT f002 = customer.state, INCLUDE = ( "AL" TO "GA", "IA" TO "WY" );

INVISIBLE Attribute

Purpose:

The INVISIBLE attribute prevents user-entered data from being echoed on the screen during an interactive statement.

Syntax:

Notes:

1. Characters that the user enters in a field with this attribute are not displayed during data entry. Depending on the front end type, the typed characters are displayed using the blank, star, underscore or dot characters.

Warnings:

1. This attribute does not prevent display instructions like DISPLAY, DISPLAY ARRAY from explicitly displaying data in the field.

IMAGE Attribute

Purpose:

The IMAGE attribute defines the image file to be associated with the form item.

Syntax:

Notes:

1. name can be a simple file name, a path, or URL to an image server.

Usage:

This attribute is used to define the image file containing the icon to be displayed in a button or the picture of an image form item.

The name can be a simple file name, a complete or relative path, or an URL (Uniform Resource Locator) path to an image server.

While you can give a complete path with the file extension, it is recommended that you use a simple name or a relative path without the file extension, so that the system can automatically search for the image file using the specific extension (bmp, gif, ...).

If the image specification is a simple file name, the file is first sought in the pictures directory on the client workstation. If the file is not found, the front-end automatically sends an image request to the runtime system, in order to search for an image on the application server. The runtime system searches for server-side images by using the FGLIMAGEPATH environment variable.

To simplify deployment, you should use server-side images to centralize all images on the application server.

Example:

01 BUTTONEDIT f001 = FORMONLY.field01, IMAGE = "zoom";

KEY Attribute

Purpose:

The KEY attribute is used to define the labels of keys when the field is made current.

Syntax:

Notes:

1. keyname is the name of a key ( like F10, "Control-z" ).
2. Note that the keyname has to be specified in quotes if you want to use Control / Shift / Alt key modifiers.
3. label is the text to be displayed in the button corresponding to the key.
4. See also the KEYS section to define key labels for the whole form.

Warning: This attributes is supported for backward compatibility.

Example:

01 EDIT f001 = customer.city, KEY F10 = "City list";
02 EDIT f002 = customer.state, KEY "Control-z" = "Open Zoom";

MINHEIGHT Attribute

Purpose:

The MINHEIGHT attribute defines the minimum height of a form.

Syntax:

Notes:

1. integer defines the minimum height of the element, as a number of grid cells.

Usage:

The MINHEIGHT attribute is used to define a minimum height of the form/window. It must be specified in the attributes of the LAYOUT section.

The unit defaults to a number of grid cells. This is the equivalent of the CHARACTERS in the HEIGHT attribute specification.

See also: MINWIDTH.

Example:

01 LAYOUT ( MINWIDTH=60, MINHEIGHT=50 )
02 GRID
03 ...

MINWIDTH Attribute

Purpose:

The MINWIDTH attribute defines the minimum width of a form.

Syntax:

Notes:

1. integer defines the minimum width of the element, as a number of grid cells.

Usage:

The MINWIDTH attribute is used to define a minimum width of the form/window. It must be specified in the attributes of the LAYOUT section.

The unit defaults to a number of grid cells. This is the equivalent of the CHARACTERS in the WIDTH attribute specification.

See also: MINHEIGHT.

Example:

01 LAYOUT ( MINWIDTH=60, MINHEIGHT=50 )
02 GRID
03 ...

NOT NULL Attribute

Purpose:

The NOT NULL attribute sets that the field does not accept NULL values.

Syntax:

Notes:

1. NOT NULL keywords can also be used in the type definition of FORMONLY fields.

Usage:

This attribute requires that the field contains a value. If the field contains a default value, the NOT NULL attribute satisfied. To insist on data entry from the user, combine NOT NULL with the REQUIRED attribute in the field definition, or make sure the corresponding column is defined as REQUIRED in the database schema file.

See also REQUIRED attribute.

Example:

01 EDIT f001 = customer.city, NOT NULL;

NOENTRY Attribute

Purpose:

The NOENTRY attribute prevents data entry in the field during an INPUT or INPUT ARRAY statement.

Syntax:

Notes:

1. The NOENTRY attribute does not prevent data entry into a field during a CONSTRUCT statement.

Example:

01 EDIT f001 = order.totamount, NOENTRY;

ORIENTATION Attribute

Purpose:

The ORIENTATION attribute defines whether an element displays vertically or horizontally.

Syntax:

Example:

01 RADIOGROUP f001 = customer.status, ORIENTATION=HORIZONTAL;

PICTURE Attribute

Purpose:

The PICTURE attribute specifies a character pattern for data entry in a text field, and prevents entry of values that conflict with the specified pattern.

Syntax:

Notes:

1. format-string defines the data input pattern of the field.
2. format-string can be any combination of characters, where the characters "A", "#" and "X" have a special meaning.
3. The character "A" specifies any letter (alpha-numeric) character at a given position.
4. The character "#" specifies any digit character at a given position.
5. The character "X" specifies any character at a given position.
6. Any character different from "A", "X" and "#" is treated as a literal. Such characters automatically appear in the field and do not have to be entered by the user.
7. The PICTURE attribute does not require data entry into the entire field. It only requires that whatever characters are entered conform to format-string.
8. When PICTURE specifies input formats for DATETIME or INTERVAL fields, the form compiler does not check the syntax of format-string, but your form will work if the syntax is correct. Any error in format-string, however, such as an incorrect field separator, produces a runtime error.

Example:

01 EDIT f001 = carinfo.number, PICTURE = "AA####-AA(X)";

PROGRAM Attribute TUI Only!

Purpose:

The PROGRAM attribute can specify an external application program to work with screen fields of data type TEXT or BYTE.

Syntax:

Notes:

1. editor is the name of the program that must be used to edit the special field data.
2. You can assign the PROGRAM attribute to a TEXT or BYTE field to call an external program to work with the BYTE or TEXT values.
3. Users can invoke the external program by pressing the exclamation point ( ! ) key while the screen cursor is in the field.
4. The external program then takes over control of the screen. When the user exits from the external program, the form is redisplayed with any display attributes besides PROGRAM in effect.
5. When no PROGRAM attribute is used, the DBEDIT environment variable defines the default editor.

Warning: This attribute works in TUI mode only.

QUERYEDITABLE Attribute

Purpose:

The QUERYEDITABLE attribute makes a combobox field editable during a CONSTRUCT statement.

Syntax:

Notes:

1. The QUERYEDITABLE attribute is effective only during a CONSTRUCT statement..
2. This attribute is useful when the display values match the real values in the ITEMS attribute.

REQUIRED Attribute

Purpose:

The REQUIRED attribute forces the user to enter data in the field during an INPUT or INPUT ARRAY statement.

Syntax:

Notes:

1. The REQUIRED attribute is effective only when the field name appears in the list of screen fields of an INPUT or INPUT ARRAY statement.
2. If both the REQUIRED and DEFAULT attributes are assigned to the same field, the runtime system assumes that the default value satisfies the REQUIRED attribute.

Warnings:

1. If the dialog instruction uses the WITHOUT DEFAULTS clause, the current value of the variable linked to the REQUIRED field is considered as a default value; the runtime system assumes that the field satisfies the REQUIRED attribute, even if the variable value is NULL. 

Usage:

This attribute requires only that the user enter a printable character in the field. If the user subsequently erases the entry during the same input, the runtime system considers the REQUIRED attribute satisfied. To insist on a non-null entry, combine REQUIRED with the NOT NULL attribute in the field definition or make sure the corresponding column is defined as NOT NULL in the database schema file.

See also NOT NULL attribute.

REVERSE Attribute

Purpose:

On character terminals, the REVERSE attribute displays any value in the field in reverse video (dark characters in a bright field).

Syntax:

Notes:

1. With character based terminals, the REVERSE video escape sequences must be defined in the TERMINFO or TERMCAP databases.

SAMPLE Attribute

Purpose:

The SAMPLE attribute defines the text to be used to compute the width of a form field.

Syntax:

Notes:

1. text is the sample string that will be used to compute the width of the field.

Warnings:

1. By default the physical width of the fields is:
   if the width is smaller than 6 chars, the pixel width of the character 'M', multiplied by the number of characters the field is designed for,
   if the width is bigger than 6 chars, the pixel width of 6 characters 'M' plus the pixel width of the character '0' , multiplied by the number of characters the field is designed for minus 6.
   The default sample looks like "MMMMMM0000"...

Usage:

By default, form fields are rendered by the client with a size determined by the current font and the number of characters used in the layout grid. The field width is computed so that the largest value can fit in the widget.

Sometimes the default computed width is too wide for the typical values displayed in the field. For example, numeric fields usually need less space as alphanumeric fields. If the values are always smaller, you can use the SAMPLE attribute to provide a hint for the front end to compute the best width for that form field.

You can define a default sample for all fields used in the form, by specifying a DEFAULT SAMPLE option in the INSTRUCTIONS section.

See also: DEFAULT SAMPLE.

Example:

01 EDIT cid = customer.custid, SAMPLE="0000";
02 EDIT ccode = customer.ucode, SAMPLE="MMMMMM";
03 DATEEDIT be01 = customer.created, SAMPLE="00-00-0000";

SCROLL Attribute

Purpose:

The SCROLL attribute can be used to enable horizontal scrolling in a character field.

Syntax:

Warnings:

1. Applies only to fields with character data input.

Usage:

By default, the maximum data input length is defined by the width of the item-tag of the field. For example, if you define an CHAR field in the form with a length of 3 characters, users can only enter a maximum of 3 characters, even if the program variable used for input is a CHAR(20).

If you want to let the user input more characters than the width of the item-tag of the field, use the SCROLL attribute.

See also: Field Input Length.

STRETCH Attribute

Purpose:

The STRETCH attribute specifies how a widget must resize when the parent container is resized.

Syntax:

STRETCH = { NONE | X | Y | BOTH }

Usage:

This attribute is typically used with form items that can be resized like IMAGE or TEXTEDIT fields. By default such form items have a fixed width and height, but in some cases you may want to force the widget to resize vertically, horizontally, or in both directions.

Example:

01 IMAGE i01 = FORMONLY.image01, STRETCH=BOTH;

STEP Attribute

Purpose:

The STEP attribute specifies how a value is increased or decreased in one step (by a mouse click or key up/down).

Syntax:

STEP = integer

Usage:

This attribute is typically used with form items allowing the user to change the current integer value by a mouse click like SLIDER, SPINEDIT.

Example:

01 SLIDER s01 = FORMONLY.slider, STEP=10;

TEXT Attribute

Purpose:

The TEXT attribute defines the label associated with a form item, such as the text of a checkbox item.

Syntax:

Notes:

1. string defines the label to be associated with the form item.
2. string can be a localized string.

Example:

01 CHECKBOX cb01 = FORMONLY.checkbox01, TEXT="OK", VALUECHECKED='y', VALUEUNCHECKED='n';

TITLE Attribute

Purpose:

The TITLE attribute defines the title of a form item. Use may be restricted to form fields that make up the columns of a table container; see the documentation for the relevant form item.

Syntax:

Notes:

1. string defines the title to be associated with the form item.
2. string can be a localized string.

Example:

01 EDIT col1 = FORMONLY.column1, TITLE="Num";

VALUEMIN Attribute

Purpose:

The VALUEMIN attribute defines a lower limit of values displayed in widgets (such as progress bars).

Syntax:

Notes:

1. integer is a integer literal.

Usage:

This attribute is typically used in PROGRESSBAR fields, to define the lower limit.

VALUEMAX Attribute

Purpose:

The VALUEMAX attribute defines a upper limit of values displayed in widgets (such as progress bars).

Syntax:

Notes:

1. integer is an integer literal.

Usage:

This attribute is typically used in PROGRESSBAR fields, to define the upper limit.

VALUECHECKED Attribute

Purpose:

The VALUECHECKED attribute defines the value associated with a checkbox item when it is checked.

Syntax:

Notes:

1. value is a numeric or string literal, or one of the following keywords: NULL, TRUE, FALSE.

Usage:

This attribute is used in conjunction with the VALUEUNCHECKED attribute to define the values corresponding to the states of a CHECKBOX. See CHECKBOX definition for more details.

Example:

01 CHECKBOX cb01 = FORMONLY.checkbox01, TEXT="OK", VALUECHECKED=TRUE, VALUEUNCHECKED=FALSE;

VALUEUNCHECKED Attribute

Purpose:

The VALUEUNCHECKED attribute defines the value associated with a checkbox item when it is not checked.

Syntax:

Notes:

1. value is a numeric or string literal, or one of the following keywords: NULL, TRUE, FALSE.

Usage:

This attribute is used in conjunction with the VALUECHECKED attribute to define the values corresponding to the states of a CHECKBOX. See CHECKBOX definition for more details.

Example:

01 CHECKBOX cb01 = FORMONLY.checkbox01, TEXT="OK", VALUECHECKED="Y", VALUEUNCHECKED="N";

UNSORTABLE Attribute

Purpose:

Indicates that the element cannot be selected by the user for sorting.

Syntax:

Notes:

1. Makes sense only for a field that is used for the definition of a column in a TABLE container.

Usage:

By default, a TABLE container allows the user to sort the columns by a left-click on the column header. Use this attribute to prevent a sort on a specific column.

Example:

01 EDIT c01 = item.comment, UNSORTABLE;

UNSORTABLECOLUMNS Attribute

Purpose:

Indicates that the columns of the table cannot be selected by the user for sorting.

Syntax:

Usage

Same effect as UNSORTABLE, but at the TABLE level, so that none of the table columns can be used for sort.

Example:

01 TABLE t1 ( UNSORTABLECOLUMNS )

UNSIZABLE Attribute

Purpose:

Indicates that the element cannot be resized by the user.

Syntax:

Notes:

1. Makes sense only for a field that is used for the definition of a column in a TABLE container.

Usage:

By default, a TABLE container allows the user to resize the columns by a drag-click on the column header. Use this attribute to prevent a resize on a specific column.

Example:

01 EDIT c01 = item.comment, UNSIZABLE;

UNSIZABLECOLUMNS Attribute

Purpose:

Indicates that the columns of the table cannot be resized by the user.

Syntax:

Usage

Same effect as UNSIZABLE, but at the TABLE level, to make all columns not resizable.

Example:

01 TABLE t1 ( UNSIZABLECOLUMNS )

UNHIDABLE Attribute

Purpose:

Indicates that the element cannot be hidden or shown by the user with the context menu.

Syntax:

Notes:

1. Makes sense only for a field that is used for the definition of a column in a TABLE container.

Usage:

By default, a TABLE container allows the user to hide the columns by a right-click on the column header. Use this attribute to prevent the user from hiding a specific column.

Example:

01 EDIT c01 = item.comment, UNHIDABLE;

UNHIDABLECOLUMNS Attribute

Purpose:

Indicates that the columns of the table cannot be hidden or shown by the user with the context menu.

Syntax:

Usage

Same effect as UNHIDABLE, but at the TABLE level, to make all columns not hidable.

Example:

01 TABLE t1 ( UNHIDABLECOLUMNS )

UNMOVABLE Attribute

Purpose:

The UNMOVABLE attribute prevents the user from moving a defined column of a table.

Syntax:

Usage:

By default, a TABLE container allows the user to move the columns by dragging and dropping the column header. Use this attribute to prevent the user from changing the order of a specific column. Typically, UNMOVABLE is used on at least two columns to prevent the user from changing the order of the input on these columns.

UNMOVABLECOLUMNS Attribute

Purpose:

The UNMOVABLECOLUMNS attribute prevents the user from moving columns of a table.

Syntax:

Usage:

By default, a TABLE container allows the user to move the columns by dragging and dropping the column header. Use this attribute to prevent the user from changing the order of columns.

UPSHIFT Attribute

Purpose:

Assign the UPSHIFT attribute to a character field when you want the runtime system to convert lowercase letters entered by the user to uppercase letters, both on the screen and in the corresponding program variable.

Syntax:

Notes:

1. Because uppercase and lowercase letters have different values, storing character strings in one or the other format can simplify sorting and querying a database.
2. Characters entered by the user are converted in INPUT, INPUT ARRAY and CONSTRUCT instructions.
3. With single byte runners the conversion of ASCII characters >127 is controlled by the locale settings (the LC_CTYPE environment variable).
4. The results of conversions between uppercase and lowercase letters are based on the locale settings (LANG).

Example:

01 EDIT f001 = FORMONLY.thetitle, UPSHIFT;

VALIDATE Attribute

Purpose:

VALIDATE is an Action Defaults attribute defining the data validation level for a given action.

Syntax:

Notes:

1. NO indicates that no data validation must occur for this action. However, current input buffer contains the text modified by the user before triggering the action.

VALIDATE LIKE Attribute

Purpose:

The VALIDATE LIKE attribute instructs the runtime system to validate the data entered in the field by using the validation rules defined in the database schema file for the column associated with the field.

Syntax:

Notes:

1. table is the optional table name to qualify the column.
2. column is the name of the column used to search for validation rules.
3. Specifying this attribute is equivalent to listing all the attributes that are assigned to table.column in the database schema file generated from the syscolval table.
4. Validation rules are taken automatically from the schema file if the field is linked to table.column in the field name specification.

Warnings:

1. The VALIDATE LIKE clause is evaluated at compile time, not at runtime. If the database schema file changes, you might need to recompile a program that uses the LIKE clause. Even if all of the fields in the form are FORMONLY, this attribute requires the form compiler to access the database schema file that contains the description of table.

Example:

01 EDIT f001 = FORMONLY.fullname, VALIDATE LIKE customer.custname;

INITIALIZER Attribute

Purpose:

The INITIALIZER attribute allows you to specify an initialization function that will be automatically called by the runtime system to set up the form item.

Syntax:

Notes:

1. function is an identifier defining the program function to be called.

Usage:

The initialization function must exist in the program using the form file and must be defined with a ui.ComboBox parameter.

ITEMS Attribute

Purpose:

The ITEMS attribute defines a list of possible values that can be used by the form item.

Syntax:

where single-value-list is:

( value [,...] )

where double-value-list is:

( ( value, label-value ) [,...] )

Notes:

1. single-value-list is a comma-separated list of single values.
2. double-value-list is a comma-separated list of (a, b) values pairs within parentheses.
3. value is a numeric or string literal, or one of the following keywords: NULL, TRUE, FALSE.
4. label-value is a numeric literal, a string literal, or a localized string.

Warnings:

1. It is only possible to use localized strings  for item labels (i.e. not for key values).

Usage:

The list must be delimited by parentheses, and each element of the list can be a simple literal value or a pair of literal values delimited by parentheses.

The following example defines a list of simple values:

ITEMS = ("Paris", "London", "New York")

The next example defines a list of pairs:

ITEMS = ((1,"Paris"),(2,"London"),(3,"New York"))

This attribute can be used, for example, to define the list of a COMBOBOX form item:

01 COMBOBOX cb01 = FORMONLY.combobox01, ITEMS = ((1,"Paris"),(2,"London"),(3,"New York"));

In this case, the first value of a pair (1,2,3) defines the data values of the form field and the second value of a pair ("Paris", "London", "New York") defines the value to be displayed in the selection list.

When used in a RADIOGROUP form item, this attribute defines the list of radio buttons:

01 RADIOGROUP rg01 = FORMONLY.radiogroup01, ITEMS = ((1,"Paris"),(2,"London"),(3,"New York"));

In this case, the first value of a pair (1,2,3) defines the data values of the form field and the second value of a pair ("Paris", "London", "New York") defines the value to be displayed as the radio button label.

Localization

You can specify item labels with Localized Strings, but this is only possible when you specify a key and a label:

ITEMS = ((1,%"item1"),(2,%"item2"),(3,%"item3"))

Using NULL items

It is allowed to define a NULL value for an item (note that an empty string is equivalent to NULL):

ITEMS = ((NULL,"Enter bug status"),(1,"Open"),(2,"Resolved"))

In this case, the behavior of the field depends from the item type used. For more details, see field type specific notes for COMBOBOX and RADIOGROUP.

JUSTIFY Attribute

Purpose:

The JUSTIFY attribute defines text justification.

Syntax:

Usage:

Default text justification depends on the dialog type, the field data type and the FORMAT attribute. For example, a numeric field value is right aligned, while a string field is left aligned. The type of dialog also defines the default justification. In a CONSTRUCT, all input fields are left aligned, for search criteria input.

With the JUSTIFY attribute, you define the display text justification of a field, as LEFT, CENTER or RIGHT. This attribute is ignored for input; only the default text justification rule applies when a field has the focus.

The JUSTIFY attribute can only be used for widgets displaying a value as text, like a LABEL, EDIT or BUTTONEDIT.

Example:

01 LABEL t01 : TEXT="Hello!", JUSTIFY=RIGHT;
02 EDIT f01 = order.value, JUSTIFY=CENTER;

SCROLLBARS Attribute

Purpose:

The SCROLLBARS attribute can be used to specify scrollbars for a form item.

Syntax:

Usage:

This attribute defines scrollbars for the form item, such as a TEXTEDIT.

Example:

01 TEXTEDIT f001 = customer.fname, SCROLLBARS=BOTH;

SIZEPOLICY Attribute

Purpose:

The SIZEPOLICY attribute is a sizing directive to display form elements.

Syntax:

Usage:

This attribute defines the initial size of some form elements. The default value of SIZEPOLICY is INITIAL.

When the SIZEPOLICY is FIXED, the form elements size is exactly the one defined in the Form Specification File. The width of the element is computed from the defined width and the font used.

For some elements such as COMBOBOX or RADIOGROUP, you may want the size of the widget to fit exactly to its content: When SIZEPOLICY is DYNAMIC, the width of the element grows and shrinks according to the width of the wider item.

When a form element is created from a database (for instance populating a COMBOBOX item list), the width of each element is not known when designing the form. When SIZEPOLICY is INITIAL, the width is computed to display the element correctly the first time it appears on the screen. Once it is displayed, its width is frozen. This behavior is also very useful when using Internationalization.

When SIZEPOLICY is INITIAL, the client behaves differently depending on the form element type:

• Buttons: The width defined in the form is a minimum width. If the text is bigger, the size grows. 
• ComboBoxes: The width defined in the form is a minimum width. If one of the items in the value list is bigger, the size grows in order for the combobox to display the largest item fully .
• Labels, Checkboxes and Radio Groups: The width defined in the form is ignored. The fields are sized according to their text.
• Images are using AUTOSCALE and STRETCH attributes in combination of SIZEPOLICY .
• Other items (mostly Edits, or widget without items like ProgressBar) are not sensitive to this attribute

The following table shows the effect of the SIZEPOLICY attribute according to the type of form item; INITIAL corresponds to the first content, while DYNAMIC corresponds to the content at anytime:

Example:

01 COMBOBOX f001 = customer.city, ITEMS=((1,"Paris"),(2,"Madrid"),(3,"London")), SIZEPOLICY=DYNAMIC;

SPACING Attribute

Purpose:

The SPACING attribute is a spacing directive to display form elements.

Syntax:

Usage:

This attribute defines the global distance between two neighboring form elements. By default, forms are displayed with NORMAL spacing. In NORMAL mode, the front end displays form elements consistent with the desktop spacing, which is, for example, 6 and 10 pixels on Microsoft Windows platforms. Some overcrowded forms may need to be displayed with less space between elements, to let them fit to the screen. In this case you can use the COMPACT mode.

Example:

01 LAYOUT ( SPACING=COMPACT )

SPLITTER Attribute

Purpose:

The SPLITTER attribute forces the container to use a splitter widget between each child element.

Syntax:

Usage:

This attribute indicates that the container (typically, a VBOX or HBOX) must have a splitter between each child element held by the container. If a container is defined with a splitter and if the children are stretchable (like TABLE or TEXTEDIT), users can resize the child elements inside the container.

Example:

01 VBOX ( SPLITTER )

STYLE Attribute

Purpose:

The STYLE attribute specifies a presentation style for a form element.

Syntax:

Notes:

1. string is a user-defined style.

Usage:

This attribute specifies a presentation style to be applied to a form element. The presentation style can define decoration attributes such as a background color, a font type, and so on.

TAG Attribute

Purpose:

The TAG attribute can be used to identify the form item with a specific string.

Syntax:

Notes:

1. tag-string is free text.

Usage:

This attribute is used to identify form items with a specific string. It can be queried in the program to perform specific processing.

You are free to use this attribute as you need. For example, you can define a numeric identifier for each field in the form in order to show context help, or group fields for specific input verification.

If you need to handle multiple data, you can format the text, for example, by using a pipe separator.

Example:

01 EDIT f001 = customer.fname, TAG = "name";
02 EDIT f002 = customer.lname, TAG = "name|optional";

TABINDEX Attribute

Purpose:

The TABINDEX attribute defines the tab order for a form item.

Syntax:

Notes:

1. integer defines the order of the item in the tab sequence.
2. If integer is zero, the item will be excluded from the tagging list. 

Usage:

This attribute can be used to define the order in which the form items are selected as the user "tabs" from field to field when the program is using the form field order option.

It can also be used to define which field must get the focus when a folder page is selected.

By default, form items get a tab index according to the order in which they appear in the LAYOUT section.

Tip: TABINDEX can be set to zero in order to exclude the item from the tabbing list. The item can still get the focus with the mouse.

Example:

01 EDIT f001 = customer.fname, TABINDEX = 1;
02 EDIT f002 = customer.lname, TABINDEX = 2;
03 EDIT f003 = customer.comment, TABINDEX = 0; -- Exclude from tabbing list

VERIFY Attribute

Purpose:

The VERIFY attribute requires users to enter data in the field twice to reduce the probability of erroneous data entry.

Syntax:

Notes:

1. Because some data is critical, this attribute supplies an additional step in data entry to ensure the integrity of your data. After the user enters a value into a VERIFY field and presses RETURN, the runtime system erases the field and requests reentry of the value. The user must enter exactly the same data each time, character for character: 15000 is not exactly the same as 15000.00.
2. The VERIFY attribute takes effect while INPUT or INPUT ARRAY statements are executing. It has no effect on CONSTRUCT statements.

VERSION Attribute

Purpose:

The VERSION attribute is used to specify a user version string for an element.

Syntax:

Notes:

1. string is a user-defined version string.

Warnings:

1. Use the TIMESTAMP only during development.

Usage:

This attribute specifies a version string to distinguish different versions of a form element. You can specify an explicit version string or use the TIMESTAMP keyword to force the form compiler to write a timestamp string into the 42f file.

Typical usage is to specify a version of the form to indicate if the form content has changed. This attribute is used by the front-end to distinguish different form versions and to avoid reloading window/form settings into a new version of a form.

Example:

01 LAYOUT ( TEXT="Orders", VERSION = "1.23" )

OPTIONS Attribute

Purpose:

The OPTION attribute specifies widget options for the field.

Syntax:

Notes:

1. option can be one of: -nolist (to indicate that the column should appear as an independent field).

Warnings:

1. This attributes is supported for backward compatibility.

WANTTABS Attribute

Purpose:

The WANTTABS attribute forces a text field to insert TAB characters in the text when the user presses the TAB key.

Syntax:

Usage:

By default, text fields  like TEXTEDIT do not insert a TAB character in the text when the user presses the TAB key, since the TAB key is used to move to the next field. You can force the field to consume TAB keys with this attribute.  

WANTNORETURNS Attribute

Purpose:

The WANTNORETURNS attribute forces a text field to reject NewLine characters when the user presses the RETURN key.

Syntax:

Usage:

By default, text fields like TEXTEDIT insert a NewLine (ASCII 10) character in the text when the user presses the RETURN key. As the RETURN key is used to validate the dialog, you can force the field to reject RETURN keys with this attribute.

WANTFIXEDPAGESIZE Attribute

Purpose:

The WANTFIXEDPAGESIZE attribute gives a fixed height to a TABLE container.

Syntax:

Usage:

By default, the height of a TABLE container is resizable. Use this attribute to freeze the number of rows to the number of screen lines defined by the form file.

WIDTH Attribute

Purpose:

The WIDTH attribute defines an explicit width of a form element.

Syntax:

Notes:

1. integer defines the width of the element.

Usage:

By default, the size of an element is defined in characters and automatically computed by the form compiler according to the size of the form element in the layout.

For items like images, the default width is defined by the number of horizontal characters used in the item tag. You can overwrite this default by specifying the WIDTH attribute. You typically give a number of pixels. 

For tables, the default width is defined by the columns used in the table layout. You can overwrite this default by specifying the WIDTH attribute. You typically give a number of columns. This allows you to use tables with a large number of columns, but a small initial width.

If you don't specify any unit, the size unit defaults to CHARACTERS, which defines the number of grid cells.

See also: HEIGHT.

Example:

01 TABLE t1 ( WIDTH = 5 COLUMNS )

WIDGET Attribute

Purpose:

The WIDGET attribute specifies the type of graphical widget to be used for the field.

Syntax:

Notes:

1. identifier defines the type of widget, it can be one of the keywords listed in the table below.
2. The WIDGET attribute is used with CONFIG to parameter the field widget.

Warnings:

1. This attribute is supported for backward compatibility.
   • Instead of WIDGET="IMAGE", you should now use a IMAGE form item.
   • Instead of WIDGET="CANVAS", you should now use a CANVAS form item.
   • Instead of WIDGET="CHECK", you should now use a CHECKBOX form item.
   • Instead of WIDGET="COMBO", you should now use a COMBOBOX form item.
   • Instead of WIDGET="BMP", you should now use a BUTTON form item.
   • Instead of WIDGET="FIELD_BMP", you should now use a BUTTONEDIT form item.
   • Instead of WIDGET="RADIO", you should now use a RADIOGROUP form item.
2. The identifier widget type is case sensitive, only uppercase letters are recognized. 
3. When you use the WIDGET attribute, the form cannot be properly displayed on character based terminals, it should only be displayed on graphical front ends.

Supported widgets:

Controlling V3 widgets activation:

The following list of widgets can be enabled or disabled from programs with a DISPLAY TO instruction:

• Text buttons (WIDGET="BUTTON") 
• Image buttons (WIDGET="BMP")
• Checkboxes of class "KEY" (WIDGET="CHECK", CLASS="KEY")
• Radio buttons of class "KEY" (WIDGET="RADIO", CLASS="KEY")

If you display an exclamation mark in such fields, the button is enabled, but if you display a star (*), it is disabled:

01 DISPLAY "*" TO button1 # disables the button
02 DISPLAY "!" TO button1 # enables the button

Changing the text of V3 buttons:

Text buttons (WIDGET="BUTTON") can be changed from programs with the DISPLAY TO instruction:

01 DISPLAY "Click me" TO button1 # Sets text and enables the button

Changing the image of V3 buttons:

Image buttons (WIDGET="BMP") can be changed from programs with the DISPLAY TO instruction:

01 DISPLAY "smiley.bmp" TO button1 # Sets image and enables the button

Warning: Image files are not centralized on the machine where the program is executed; image files must be present on the Workstation. See front end specific documentation for more details. 

Changing the text of V3 labels:

The text if label fields (WIDGET="LABEL") can be changed from programs with the DISPLAY TO instruction:

01 DISPLAY "Firstname" TO l_firstname # Sets text of the label field

Using V3 canvas areas:

The fields declared with the WIDGET="Canvas" attribute can be used by the program as drawing areas. Canvas fields must be defined in the LAYOUT section. A set of drawing functions are provided to fill CANVAS fields with graphical elements.

WINDOWSTYLE Attribute

Purpose:

The WINDOWSTYLE attribute defines the style to be used by the parent window of a form.

Syntax:

Notes:

1. string is a user defined style.

Usage:

The WINDOWSTYLE attribute can be used to specify the style of the parent window that will hold the form. This attribute is specific to the LAYOUT element. Do not confuse with the STYLE attribute, which is used to specify decoration style of the form elements.

When a form is loaded by the OPEN WINDOW or DISPLAY FORM instructions, the runtime system automatically assigns the WINDOWSTYLE to the 'style' attribute of the parent window element.

See also: STYLE, Windows and Forms.

Example:

01 LAYOUT ( STYLE="BigFont", WINDOWSTYLE="dialog" )

WORDWRAP Attribute

Purpose:

The WORDWRAP attribute enables a multiple-line editor in TUI mode.

Syntax:

Usage:

• During input and display, the runtime system treats all segments that have that field tag as segments of a single field.
• The multi-line editor can wrap long character strings to the next line of a multiple-segment field for data entry, data editing, and data display.
• The COMPRESS option prevents blanks produced by the editor from being included in the program variable. COMPRESS is applied by default and can cause truncation to occur if the sum of intentional characters exceeds the field or column size. Because of editing blanks in the WORDWRAP field, the stored value might not correspond exactly to its multiple-line display.
• Specifying NONCOMPRESS after the WORDWRAP keyword causes any editor blanks to be saved when the string value is saved in a database column, in a variable, or in a file.

• The WORDWRAP attribute is ignored, because text input and display is managed by the text editor widget.
• The text data is NOT automatically modified by the editor by adding blanks to put words on the next line.

Warnings:

1. This attribute is provided for backward compatibility with character-based forms; you should use a TEXTEDIT form item instead in graphical forms.
2. Using WORDWRAP fields with character-based terminals results in quite different behavior than with graphical front ends. With character-based terminals, the text input and display is modified by the multi-line editor. This editor can automatically modify the text data by adding blanks to put words to the next line, in order to make the text fit into the form field. In GUI mode, the text input and display is managed by a multi-line edit control.

The maximum number of bytes a user can enter is the width of the form-field multiplied by the height of the form-field. Blank characters may be intentional blanks or fill blanks. Intentional blanks are initially stored in the target variable where entered by the user. Fill blanks are inserted at the end of a line by the editor when a new-line or a  word-alignment forces a line-break. It is not possible to set the cursor at a fill blank. Intentional blanks are always displayed (even on the beginning of a line; the word-wrapping method used in reports with PRINT WORDWRAP works differently).

When entering characters with Japanese locales, special characters are prohibited from being the first or the last character on a line. If the last character is prohibited from ending a line, this character is wrapped down to the next line. If the first character is prohibited from beginning a line, the preceding character will also wrap down to the next line. This method is called kinsoku. The test for prohibited characters will be done only once for the first and the last character on each line.

Word-wrapping is disabled on the last row of a WORDWRAP field. The last word on the last row may by truncated. The WORDWRAP COMPRESS attribute instructs the editor to remove fill blanks before assigning the field-buffer to the target variable. The WORDWRAP NONCOMPRESS attribute instructs the editor to store fill blanks to the target variable. The WORDWRAP and WORDWRAP NONCOMPRESS attributes are equivalent.