Introduction

Getting Started

Programming Guides

API Reference

Additional Resources

Get_Wakeup

Functions

void Get_Wakeup (double time)
 Performs all the work needed to have your program go to sleep for a specified interval or until a user event occurs. More...
 

Detailed Description

Function Documentation

void Get_Wakeup ( double  time)

Performs all the work needed to have your program go to sleep for a specified interval or until a user event occurs.

Parameters
time- The time from the present, in seconds, at which Get_Wakeup() should return.

DETAILS

Get_Wakeup() is a utility routine that combines a common sequence of input routines. The sequence does the work necessary to start a wakeup running. The sequence waits for the wakeup to expire, then deletes the wakeup from the system again.

In pseudo- C, Get_Wakeup() corresponds to the following:

    if (time > 0.0) {
        Enable_Wakeup_Events (time) 
        do Await_Event (&type) 
        until (strcmp (type, "wakeup") == 0) 
        Disable_Wakeup_Events (time) 
                } 
Your program can then continue. Get_Wakeup() is unusual among Get routines in that it does not return any value.

Get_Wakeup() is not an elegant routine to use in an interactive application—there's usually a better method available.

For example, if you have an error message that you want to display, let the user read for a while, then take away again, put an "acknowledge" button next to the message and wait for a button push. That way the user could take time to read the message and would also have an opportunity to push some other button and proceed to a new activity. (Of course, if the message routine does receive an unexpected event, it should requeue it and return.) With judicious use of event-enables and Await Event, you could even do both—put up a message until a lengthy timer expires or a button is pushed, whichever comes first.

On the other hand, Get_Wakeup() might be useful in non-interactive programs—for example, to space out the frames in a non-interruptible animation sequence. (If you want a sequence to be interruptible, again you'll need to enable both kinds of events, call Await Event() at each frame, and react appropriately.)

NOTES

The Update that occurs implicitly in Await_Event() might cause user input to be turned off. This happens if you use Get_Selection(), Get_String(), etc., to gather user input. The remedy for this is an extra "enable event", as described in the Get routine manual pages.

Get_Wakeup() does not verify that the wakeup event received is actually the one requested.

RESTRICTIONS

See also
Enable_Wakeup_Events, Show_Wakeup, Await_Event, Requeue_Event.