LABEL item type

Defines a simple text area to display a read-only value.

LABEL item basics

The LABEL form item defines a read-only text area.

Defining a LABEL

A LABEL form item can be defined as a form field image or as a static label. Use a form field label when the text changes often during program execution (for example, to display text from the database). Use a static label if the text remains the same during program execution.

Front-ends support different presentation and behavior options, which can be controlled by a STYLE attribute. For more details, see Common style attributes and Label style attributes.

Form field LABEL item

Use a form field label item to display values that change often during program execution, for example if the text is stored in the database.

The label text is defined by the value of the field.

The value can be changed by the program using the DISPLAY BY NAME / DISPLAY TO instruction, or just by changing the value of the program variable bound to the label field when using the UNBUFFERED mode in an interactive instruction.

When defining the LABEL item in the form, use a field name to identify the element in programs:

-- Grid-based layout (ATTRIBUTES item definition)
LABEL f001 = cars.description;

-- Stack-based layout (STACK item)
LABEL cars.description;

Static LABEL item

Use a static label item to display text that does not change during program execution.

This kind of item is not affected by instructions such as CLEAR FORM or the DISPLAY TO instruction.

-- Grid-based layout (ATTRIBUTES item definition)
LABEL lab1: label1, TEXT="Name:";

-- Stack-based layout (STACK item)
LABEL : label1, TEXT="Name:";
Consider using localized strings to ease application internationalization:
LABEL ...
   TEXT = %"label.customer.name";

Static labels display only character text values, and therefore do not follow any justification rule as form field labels.

Multi-line text in LABELs

In order to display label text on several lines, the text must contain \n line-feed characters:
LABEL lab1: label1,
      TEXT="First line.\nSecond line.";

Where to use a LABEL

A LABEL form item can be defined in two different ways:
  1. With an item tag and a LABEL item definition in a grid-layout container (GRID, SCROLLGRID and TABLE).
  2. As a LABEL stack item in a STACK container.

Defining the widget size

The size of a LABEL widget can be controlled in grid-based or stack-based layout by using the SIZEPOLICY attribute.

By default (SIZEPOLICY=INITIAL), labels adapt their width to the initial text displayed by the element.

With static labels, the initial text is usually defined in the form file, or with a localized string, and the size does not need to adapt once the label is displayed.

When using form field labels, the same default rule applies. However, if the initial text displayed in the form field is NULL or smaller than other texts that will be displayed, the size of the label element will not adapt after the initial text is displayed; the label stays at the size of the initial displayed text.

Important: When using a form field label, make sure that the size of the label will be large enough to display all possible values. To control the label size, use the SIZEPOLICY=DYNAMIC attribute, or use SIZEPOLICY=FIXED and define the form item with a sufficient size in the LAYOUT section.