Function

Summary

Waits for an event in a "windowing friendly" way.

Package

mp

Signature

mailbox-wait-for-event mailbox &key wait-reason wait-function process-other-messages-p no-hang-p stop-at-user-operation-p => event

Arguments

mailbox

A mailbox.

wait-reason

A string or nil .

wait-function

A function designator.

process-other-messages-p

A generalized boolean.

no-hang-p

A generalized boolean.

stop-at-user-operation-p

A generalized boolean.

Values

result

An event or nil .

Description

The function mailbox-wait-for-event waits for an event in a mailbox in a "windowing friendly" way. It reads an event from the mailbox mailbox . If there is no event in the mailbox, it waits for an event (unless no-hang-p is true).

The value event is any object that was put in the mailbox, or nil if the mailbox is empty, possibly after waiting.

mailbox-wait-for-event is the appropriate way to wait for an event in a mailbox in an application with a graphical user interface, because it interacts correctly with the windowing system. Most importantly, on Microsoft Windows, when process-other-messages-p is true it processes Windows messages while it is waiting. The default value of process-other-messages-p is t .

wait-function is the wait function to be used, which is called with the mailbox mailbox as its argument. If wait-function is not supplied, a function that returns t when the mailbox is not empty is used is used internally.

wait-reason is used as the wait reason if it needs to wait. The default value of wait-reason is "Waiting for an event".

process-other-messages-p controls processing of other messages. On Microsoft Windows this means Windows messages. On other platforms it has no effect.

no-hang-p controls whether mailbox-wait-for-event should really wait. If no-hang-p is true and there is no event, it returns immediately except on Microsoft Windows, where it may first process all Windows messages (depending on the value of process-other-messages-p ). The default value of no-hang-p is nil .

stop-at-user-operation-p on Microsoft Windows causes mailbox-wait-for-event to return if it received a user operation message (meaning keyboard or mouse input). It has no effect on other platforms. The default value of stop-at-user-operation-p is nil .

If mailbox-wait-for-event is called when not Lisp is not multiprocessing, it returns immediately. The return value is an event or nil .

See also

mailbox-read
mailbox-send
make-mailbox
process-wait-for-event