This document covers the following topics:
To manipulate dialog elements, Natural provides you with handle attribute operands. You use handle attribute operands wherever an operand may be specified in a Natural statement. This is the most important programming technique in event-handler code.
Important:
You must have defined a handle.
Note:
ActiveX controls are manipulated in a slightly different way than
the standard way described below. This is described in
Working with ActiveX
Controls.
Handle attribute operands may be specified as follows:
| handle.name - attribute.name [(index-specification)] |
The handle-name is the handle of the
dialog-element-type as defined in the
HANDLE definition of the DEFINE DATA statement.
The attribute-name is the name of an attribute which has to be valid for the dialog-element-type of the handle.
Examples:
1 #PB-1 HANDLE OF PUSHBUTTON /* #PB-1 is a handle-name of the
/* dialog-element-type PUSHBUTTON
RESET #PB-1.STRING... /* #PB-1.STRING is the handle attribute operand
/* where STRING is a valid attribute-name of the
/* dialog-element-type PUSHBUTTON
1 #RB-1(1:5) HANDLE OF RADIOBUTTON /* #RB-1 is an array of five RADIOBUTTONs
IF #RB-1.CHECKED(3) = CHECKED /* If the third radio-button control is
THEN... /* checked ...
In most applications, it will be necessary
to set an attribute value before creating the dialog element,
to modify the value after creating the dialog element, and
to query an attribute value.
In some cases, it may be necessary to modify and query some attributes during processing, for example to query the checked/not checked state of a radio-button control or to disable (= modify) a menu item.
You can do that, for example, in the ASSIGN,
MOVE or
CALLNAT
statements.
Examples:
1 #PB-1 HANDLE OF PUSHBUTTON /* #PB-1 is a handle-name of the
... /* dialog-element-type PUSHBUTTON
#PB-1.STRING:= 'MY BUTTON' /* Set or modify the value of the STRING
/* attribute to 'MY BUTTON'
#TEXT:= #PB-1.STRING /* Query the value of the STRING attribute
/* and assign the value to #TEXT
CALLNAT 'SUBPGM1' #PB-1.STRING /* Query the value of the STRING attribute
/* and pass it on to the subprogram
When you use the handle-name variable only on the left side of the statements, as in the first of the three examples above, the attribute value is set or modified, that is, it is assigned the value of the specified operand.
When you use the handle-name variable on the right side of the statements, as in the second example, the attribute value is queried, that is, the value is assigned to the operand.
Once a handle has been defined (either explicitly in specified Natural code, or implicitly with the dialog editor), it can be used with most Natural statements. However, only a specific set of attributes can be queried, set or modified for a particular dialog element. To find out which values an attribute can have, see the section Attributes in the Dialog Component Reference.
Although an exact data type is specified for the values of most attributes, it is sufficient to supply move-compatible values to a handle attribute operand. The rules are the same as those for Natural variables.
All alphanumeric attributes are stored in Unicode form internally and are thus locale-independent.
However, in order to allow attribute values to be used as Natural statement operands, it is necessary for the data to be transferred through a temporary internal data field that is accessible to the Natural Run-time. This internal field has the format and length as is documented for the corresponding attribute, which (for historical, technical and compatibility reasons) is format A for alphanumeric attributes by default and cannot be changed. The upshot of this is that alphanumeric attribute accesses will fail by default if the value being transferred contains characters that cannot be represented in the active code page. For example:
#PB-1.STRING := U'оши́бка' /* --> NAT3413 ERROR in non-Cyrillic locales
The solution to this problem is to inform Natural that the temporary internal data field should be created with format U rather than with format A. This is done by appending a "-U" suffix to the name of any alphanumeric attribute. For example:
#PB-1.STRING-U := U'оши́бка' /* works in all locales
It is important to note that only the use of the "-U"
suffix only has an effect on the format of the temporary internal data field,
not on the stored attribute. For example, there is only one
STRING attribute,
regardless of whether it is addressed via the STRING or STRING-U notation. The
same storage location is used in both cases.
As a general rule, if alphanumeric attribute values are being set or retrieved that contain at least one character that is not representable in the current code page, then the attribute name should be suffixed with a "-U".
Handle attribute operands must not be used in the following statements:
AT BREAK,
FIND,
HISTOGRAM,
INPUT,
READ,
READ WORK FILE.
User-defined variables can be used instead.
If you assign numeric operands to alphanumeric attributes, the values of these attributes will be in a non-displayable format. The Natural arithmetic assignment rules apply.
If you need a displayable format, you can use
MOVE EDITED.
Examples:
#PB-1.STRING:= -12.34 /* Non-displayable format MOVE EDITED #I4 (EM = -Z(9)9) TO #PB-1.STRING /* Displayable format
The following edit masks may be used for the various format/length definitions of numeric operands:
| Format/Length | Edit Mask |
|---|---|
| I1 | -ZZ9 |
| I2 | -Z(5)9 |
| I4 | -Z(9)9 |
| Nn.m/Pn.m | -Z(n).9(m) |