$labelproperties

Get and set the text of an associated label in a Form.

$labelproperties(Field) = "text=LabelText"

Example: $labelproperties (FULLNAME) = "text=Employee name:"

Parameters

Parameters
Parameter Data Type Description
Field String Name of the field to which the label is attached
LabelText String Text of the label

Return Values

If an error occurs, $procerror contains a negative value that identifies the exact error.

Values of $procerror Commonly Returned Following $labelproperties
Value  Error constant Meaning
-1101 <UPROCERR_FIELD> An incorrect field name was provided; either the field name is not valid syntactically or the field is not available in the component.

Use

Use in Form components.

Description

The $labelproperties function makes it possible to dynamically change an associated label. It does not work with non-associated labels.

The label dimensions as drawn on the form must be large enough to accommodate the assigned name; otherwise, the label is truncated.

Labels are user interface objects, so they can only be addressed when the presentation layer is available. This is after the form has been initially displayed using a show or edit statement. You can then use one of these statements again to refresh the display.

When using $labelproperties after a command that changes the related entity data (such as clear, retrieve or xmlload), precede the $labelproperties command with show to ensure that the label object is available. For example:

clear
show
$labelproperties("FIELD1")="text=%%FIELD1.DUMMY_ENTITY%%%"

Although it can work with any widget type, $labelproperties is especially useful in the grid widget because it enables the associated label of the field shown as the column title to be changed dynamically. In grid widgets, if the label contains a new line character, it is concatenated into one line.

Using $labelproperties

In the following example, the field labels of the ABBREVIATION and FULLNAME fields are set in the exec operation. The show command draws the form, making the label available. After the $labelproperties instructions, the edit command refreshes the display with the new labels.

operation exec
  show
  $labelproperties (ABBREVIATION) = "text=Initials"
  $labelproperties (FULLNAME) = "text=Employee Name"
  edit
end; exec
History
Version Change
9.3.01 Introduced

Related Topics