WaitFor Method

Usually, when you use the SendUserEvent method, OpenROAD queues the user event and then continues executing the current event block. The WaitFor method lets you prevent the rest of the current event block from being executed until you tell it to stop waiting.

When you invoke the WaitFor method, you specify the name of a user event that the event block must wait for. When the current frame receives that user event, control returns to the statement immediately following the WaitFor call.

The syntax of the WaitFor method is:

You can use the WaitFor method for the current frame only with the CurFrame reference variable. The method returns an Event object that contains the eventname, messageobject, messageinteger, messagefloat, and message varchar parameters sent with the SendUserEvent call that completes the method. (When the SendUserEvent call completes a WaitFor call, the SendUserEvent focusbehavior parameter is ignored in the receiving frame.)

WaitFor makes the executing frame ignore any other events, both from the user and other SendUserEvent methods. Window-level events, such as button clicks, are disabled. User events are delivered to the frame after it receives the user event that it is waiting for.

Important! Do not use the WaitFor method when you are sending the user event from the current frame to itself. The user event is never delivered to the frame and the event block is never continued. This results in the frame remaining in an unending wait state.

The most common use of the WaitFor method is immediately following a SendUserEvent method to wait for acknowledgment that the user event was processed. This is especially useful when coordination of frames is important.

The following sample frame script uses the WaitFor method to wait until all child frames have closed themselves before executing the return statement to close itself:

on click close_button,
on windowclose =
begin
    /* If there are any detail frames open,
    ** tell them to clean up themselves. */
    i = 1;
    while i <= vlist.LastRow() do
        if vlist[i].details_frame is not null then
        vlist[i].details_frame.SendUserEvent
            (eventname ='Cleanup',
            focusbehavior = FT_SETVALUE);
        CurFrame.WaitFor(eventname = 'Done');

    /* If there are any detail frames for
    ** new videos, tell them to clean up. */
    i = 1;
    while i <= new_details_frames.LastRow() do
        new_details_frames[i].SendUserEvent
            (eventname ='Cleanup',
            focusbehavior = FT_SETVALUE);
        CurFrame.WaitFor(eventname = 'Done');
        i = i + 1;
    endwhile;

    return;
end;

Be sure to use the SendUserEvent method to send the user event back to the frame that contains the WaitFor call. The following example sends the Done user event back to the parent frame:

The PurgeUserEvent method lets you remove user events from the event queue. If you trigger a series of related user events and one of the events fails for some reason, you can use this method to remove the remaining user events from the event queue.

In addition, when you use the resume statement to prevent the user from leaving a field that contains invalid data, OpenROAD does not remove the user events from the event queue (although it does remove the other frame events for the current frame). Use the PurgeUserEvent method to remove them if necessary. The PurgeUserEvent method removes one or all the user events from the event queue.

The syntax of this method is:

The PurgeUserEvent method removes the specified user event from the event queue. If you do not specify the eventname parameter, it removes all user events for the specified frame. The method returns the number of events removed from the queue.

You can use this method for any running version of a frame. To specify the FrameExec variable for the running version of the frame, use any of the methods described in SendUserEvent Method (see SendUserEvent Method).