FunctionPackage: cgToCDocOverviewCGDocRelNotesFAQIndexPermutedIndex
Allegro CL version 8.1
Unrevised from 8.0 to 8.1. Minimal update since 8.1 release.
8.0 version


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-2009, Franz Inc. Oakland, CA., USA. All rights reserved.
Documentation for Allegro CL version 8.1. This page was not revised from the 8.0 page.
Created 2009.7.29.

Allegro CL version 8.1
Unrevised from 8.0 to 8.1. Minimal update since 8.1 release.
8.0 version