ACTIVATE DIALOG

7.8.5, PLBCMP GUI Only

The ACTIVATE DIALOG statement makes a DIALOG visible and allows the user to interact with it. A required execution label must be provided to process information if the user selects the DIALOG. The instruction uses the following format:

[label]

ACTIVATE

{dialog}[,{routine},{result}]

Where:

label

Optional. A Program Execution Label.

dialog

Required. The name of a previously created DIALOG object variable or pointer to a DIALOG object.

routine

Optional. A Program Execution Label called when a mouse click occurs within the DIALOG.

result

Optional. A previously defined Numeric Variable in number of the selected dialog object is placed.

Flags Affected: NONE

Note the following:

The DIALOG object requires the {routine} and {result} arguments.
If the {result} operand is specified, it is set to indicate the number of the object that was selected. Objects are numbered in the order of their creation.
If the {result} operand is too small to contain the value, the OVER flag is set upon entry to the {routine}. This flag setting does not occur at the time of the ACTIVATE butat the time the {routine} is called.
The {routine} is called when a DIALOG object is selected.
The {routine} is called as if a CALL instruction was performed. It is only called when an EVENTCHECK or EVENTWAIT is executed.
When the {routine} is complete, a RETURN instruction continues execution at the instruction following the EVENTWAIT or EVENTCHECK. Otherwise, a NORETURN instruction should be executed to clear the return address from the call stack.
If the DIALOG specified by an ACTIVATE instruction is already active, the old {routine} and {result} operands are replaced with the new {routine} and {result} operands.
When a modal DIALOG is activated, all other processing is suspended until a DEACTIVATE or DESTROY instruction is performed on the DIALOG object and a subsequent RETURN instruction is executed for the modal DIALOG {routine}. A modal DIALOG {routine} should always be ended by using the RETURN instruction. The {routine} for one modal DIALOG may activate another modal DIALOG. Ten (10) modal DIALOGs may be nested in this manner. An O109 error occurs if more than ten modal DIALOGs are nested. In addition, an O110 error occurs if the modal DIALOGs are not terminated in the reverse order to the order of activation. Also note that a KEYIN instruction terminates immediately as if an <enter> key was performed when a modal DIALOG is active.
When a modal DIALOG is activated, all other processing is suspended until a DEACTIVATE instruction is performed on the DIALOG object. A modal DIALOG {routine} that is not going to DEACTIVATE the DIALOG should always be ended by using the RETURN instruction.
A modeless DIALOG does not suspend processing. If the user attempts to close a modeless DIALOG, the result operand is set to 999.
A DIALOG must be CREATEd before it is activated. If this is not done, a runtime error of O105 is generated.
If insufficient memory is available to perform the operation, a runtime error O106 is generated.
If a FILEPI instruction is active, it is terminated.