This document covers the following topics:
Dialog elements are uniquely identified by a handle. A handle is a
binary value that is returned when a dialog element is created. A handle must
be defined in a DEFINE
DATA statement of the dialog.
by creating a dialog or a dialog element with the dialog editor; in this case, the handle definition is generated;
by explicitly entering the definition in a global, local, or parameter data area of the dialog;
by explicitly entering the definition in a subprogram or a subroutine.
Note:
Handles of ActiveX controls are defined in a slightly different way
than the standard handle definition described below. This is described in
Working with ActiveX
Controls.
A handle is defined inside a DEFINE DATA statement in the
following way:
level
handle-name
[(array-defintion)] HANDLE
OF dialog-element-type
|
Handles may be defined on any level.
Handle-name is the name to be assigned to the handle; the naming conventions for user-defined variables apply.
Dialog-element-type is the type of dialog
element. Its possible values are the values of the
TYPE attribute. It may
not be redefined and not be contained in a redefinition of a group.
Examples:
1 #SAVEAS-MENUITEM HANDLE OF MENUITEM 1 #OK-BUTTON (1:10) HANDLE OF PUSHBUTTON
When you have defined a handle, you can use the handle-name with handle attribute operands in those Natural statements where an operand may be specified. With handle attribute operands, you can, for example, dynamically query, set, or modify attribute values for the defined dialog-element-type. This is the most important programming technique in the dialog editor. For details, see the section How To Manipulate Dialog Elements.
If there is a dialog element handle of the same name in two different
dialogs, the PARENT attribute
ensures that Natural knows the difference between the two handles (two
different PARENT values). Handles may be passed
as parameters or may be assigned from one handle variable to another.
In addition to the handle types referring to one dialog element, the
generic handle type HANDLE OF GUI is available. In event-handler
code, you can use HANDLE OF GUI to refer to the handle of any type
of dialog element.
This can be useful, for example, if you are querying an attribute value in all dialog elements on one level: you go through the dialog elements one after the other; in the course of this query, it is not clear which type of dialog element is going to be queried next. Then a GUI handle makes it possible to query the next dialog element regardless of its type. This saves a lot of coding, because otherwise, you would have to query the attribute's value of each dialog element separately.
Example:
... 1 #CONTROL HANDLE OF GUI ... #CONTROL := #DLG$WINDOW.FIRST-CHILD REPEAT UNTIL #CONTROL = NULL-HANDLE ... #CONTROL := #CONTROL.SUCCESSOR END-REPEAT
The HANDLE constant NULL-HANDLE may be used to
query, set or modify a NULL value of a HANDLE. Such a
NULL value means that the dialog element is nonexistent (even if
it has been created explicitly).
Example:
DEFINE DATA PARAMETER 1 #PUSH HANDLE OF PUSHBUTTON END-DEFINE ... IF #PUSH = NULL-HANDLE ...
The HANDLE constant NULL-HANDLE represents the
NULL value of a HANDLE variable or of an attribute
with format HANDLE. For handle variables, the value indicates that
the expression handle.attribute refers to the global
attribute list. For attributes, this value indicates that no value is currently
set.
