|Takes the event currently being examined and pushes it back onto the queue of pending events. More...|
Takes the event currently being examined and pushes it back onto the queue of pending events.
You may find it is a nuisance for each low-level routine in your program to be aware of, and ready for, all the different kinds of events and selections the user might initiate. A traditional way of dealing with this problem is for the low-level routines to ignore any button-pushes, etc., that they don't understand. The user experiences this as menu buttons that have "gone dead".
A better policy is to assign events to be dealt with as either "higher-level" or "lower-level" in your program. There is a clean way of implementing this. When a low level routine encounters something it wasn't expecting, it should unwind what it was doing, push the odd event back onto the event queue, and return to its caller. The caller then resumes its own cycle of acquiring events by calling Await_Event() or one of the Get routines. The "odd" event becomes current once again, and—hopefully—the new (higher level) routine knows what to do with it. The bottom line is that the high-level routine doesn't have to know why the low-level routine returned—it can simply go on looking for high-level events.
The essential piece is "pushing the odd event back onto the event queue". This is the function provided by Requeue_Event() .
The event requeued is put on the front, not the back, of the event queue, and will be the next event to be dequeued.
Requeue_Event() is the HOOPS equivalent of the C language ungetc routine.
After Requeue has returned, and before the next call to Await or Get, there is no longer a "current event", and routines that operate on the current event—Requeue itself, for example—will complain if called. As a corollary of this, Requeue is able to push, at most, one event back onto the event queue.