When passed ALL_EVENTS, DoOneEvent processes events as they arise and puts the application to sleep when no further events are outstanding. DoOneEvent first looks for a window or I/O event and, if found, calls the handler and returns. If there is no window or I/O event, it looks for a single timer event, invokes the callback, and returns. If no window, I/O, or timer event is ready, all pending idle callbacks are executed, if any. In all cases, DoOneEvent returns 1.

When passed DONT_WAIT, DoOneEvent works as described, except that, if there are no events to process, it returns immediately with a value of 0, indicating it didn't find any work to do.

It's actually rather difficult to find a use for DoOneEvent. One example is the bouncing ball widget demonstration, although it might have been better written using timer callbacks. But it is simulating a simulation, and simulations typically want to run as fast as possible, so we can't fault the implementation.

Even games don't usually require DoOneEvent. Here are two scenarios in which you might use it. Example one probably never reaches the MainLoop statement. It runs as fast as possible, consuming all available CPU time, and depends on update to process events.

&run;
MainLoop;

sub run {
    while (1) {
        &dogame;
        $mw->update;
    }
}

Example two establishes a repeating timer event, then enters MainLoop to process events. The game progresses at a more or less stately speed, with an update occurring every 50 milliseconds. Unlike example one, this example does not consume all available CPU time.

$mw->repeat(50 => \&run);
MainLoop;

sub run {
    &dogame;
    $mw->update;
}