Version 6.3.13 for Windows
 —  Programming Guide  —

How To Manipulate Dialog Elements

This document covers the following topics:


Introduction

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 ...

Top of page

Querying, Setting and Modifying Attribute Values

In most applications, it will be necessary

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.

Top of page

Querying and Modifying Unicode Attribute Values

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".

Top of page

Restrictions

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.

Top of page

Numeric/Alphanumeric Assignment

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)

Top of page