This document covers the following topics:
Enumerates the client keys currently in use by a dialog or dialog element.
The action only returns a single key at a time, and must therefore be called repeatedly in order to retrieve the entire key list. The key that is returned is the "next" key, based on an internal enumeration cursor, which is originally reset (implying that the "first" key is returned) and which is implicitly advanced to the "next" key on each successive call to this action. By omitting the optional client key parameter, the internal enumeration cursor may be explicitly reset at any time.
If there are no further keys left to enumerate, an empty (i.e., all blank) client key value is returned.
If the client key/client value pair to which the internal enumeration cursor currently refers is deleted, the enumeration cursor is implicitly set to the "previous" key, if any, or is reset otherwise, such that the result of a subsequent call to this action is unaffected. It is thus possible to delete the keys whilst enumerating them (see example below).
Note that the words "first", "next" and "previous" relate to the internal client key sequence, which is implementation-defined, and thus may change in future Natural versions. A Natural application must not depend on this enumeration sequence!
For more information, please refer to the article Storing and Retrieving Client Data for a Dialog Element.
| Name/Data Type | Explanation |
|---|---|
| HANDLE OF GUI | Input
Handle of dialog or dialog element, for which the keys are to be enumerated. |
| Client key (A253) | Output (optional parameter)
If specified, this parameter retrieves the next key (if any) in use by the specified dialog or dialog element. If this parameter is omitted, the internal enumeration cursor is reset, implying that the next key returned by this action will be the "first" key. |
| Response (I4) | Output
Natural error (if applicable). |
DEFINE DATA LOCAL01
#CLIENT-KEY (A253)
...
END-DEFINE
*
/*reset enumeration cursor
PROCESS GUI ACTION ENUM-CLIENT-KEYS WITH #DLG$WINDOW GIVING *ERROR
/* Enumerate and delete the keys in use by the dialog
REPEAT
PROCESS GUI ACTION ENUM-CLIENT-KEYS WITH #DLG$WINDOW #CLIENT-KEY
GIVING *ERROR
IF #CLIENT-KEY <> ' '
/* Delete the key and associated value
PROCESS GUI ACTION SET-CLIENT-VALUE WITH #DLG$WINDOW #CLIENT-KEY
GIVING *ERROR
END-IF
WHILE #CLIENT-KEY <> ' '
END-REPEAT