mailbox-wait-for-event

mailbox-wait-for-event Function

Summary

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

Package

Signature

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

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 result 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.

If wait-function is non-nil, then is it called as a Process Wait function (see 19.6.2 Generic Process Wait functions) with the mailbox mailbox as its argument while waiting for an event. If the call returns true before any events arrive, then mailbox-wait-for-event will return nil.

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.