event-loop

Arguments: &key window exit-test

Enters a loop that processes all messages that are sent to any windows that are created in the thread that is calling event-loop. When an application creates a new thread that will create windows, the preset-function that is passed to process-run-function should call event-loop before it exits, both to cause that thread's messages to be handled and also to prevent the thread from exiting until it should. The arguments determine when event-loop will return, which then allows the thread to exit.

window may be nil or a window. If a window, then event-loop will check that the window is still open after processing each message, and return when the window has been closed. Typically a "main window" for the thread is passed to event-loop.

exit-test may be nil or a function name or function object. If non-nil, then event-loop will call the exit-test function once after it has processed each message, and return if the function returns true. For efficient event-handling, an exit-test if used should execute quickly. The function should take one argument, which is the value of the window argument to event-loop. An exit-test may be used along with a null window argument (in which case the argument to the exit-test function will be nil), but it is probably most often useful to pass a main-window as well when an exit-test is used.

Note: It is not necessary to call event-loop when using the project system to create an application with a single windowing thread, because it is called automatically for the thread created by the Run | Run Project command in the IDE and by the corresponding initial thread of the generated standalone application (as long as the project's on-initialization function returns a window). It is also not necessary to call event-loop when creating windows by evaluating forms in IDE listeners or editors, since the threads used for evaluation by these IDE windows are already in event-handling loops.

event-loop basically calls process-single-event in a loop until an exit requirement is met. So if event-loop does not meet an application's needs, it may work to use a custom loop that calls process-single-event itself. But event-loop performs some additional internal management and is recommended over custom process-single-event loops. In particular, event-loop ensures that multiple threads that call it will all exit cleanly when lisp exits; otherwise multiple windowing threads may hang on exit unless the :no-unwind argument is passed to exit. In a standalone application that does its own event handling (rather than returning a window from its on-initialization function), calling event-loop also ensures that the Enable Debugging of Runtime Errors option behaves as documented (see the Build tab of the Project Manager).

See also About using multiple windowing threads in a Common Graphics application in cgide.htm. And see inside-event-loop and exit-event-loop.

The new (in release 7.0) function initialize-cg allows using Common Graphics in a Lisp that does not include the IDE, or in a standalone application that was not created from an IDE project. Also new are exit-cg and *cg-is-initialized*.

The macro in-cg-process may be used to handle the creation of a Common Graphics process and the call to event-loop for a body of Common Graphics code.

See also the variable *event-loop-processes*.

Copyright (c) 1998-2019, Franz Inc. Oakland, CA., USA. All rights reserved.
This page was not revised from the 8.2 page.
Created 2012.5.30.