Name
CheckEvent -- check for event without blocking (V1.9)
Synopsis
info = CheckEvent()
Function
This function checks if there is an event in the queue. If there is, CheckEvent() will remove it from the queue and run its callback function. If there is no event in the queue, CheckEvent() will return immediately.

CheckEvent() returns a table that contains information about whether or not it has executed a callback. The following fields will be initialized in that table:

Action:
Contains the name of the event that caused the callback execution (e.g. OnMouseDown). If CheckEvent() returns without having ran a callback, this field will be set to an empty string.

ID:
Contains the identifier of the object that caused the callback execution (e.g. a display identifier). ID can also be zero in case an event was caused that has no ID associated.

Triggered:
Will be set to True if CheckEvent() has executed a callback.

NResults:
Contains the number of values that the user callback returned (e.g. 1). This will be 0 if the user callback did not return any values or if no user callback was ran at all.

Results:
If NResults is greater than 0, this table will contain all values that the user callback returned. Otherwise this table will not be present at all. You can easily use this table to pass additional information from your callbacks back to the main scope of the program.

CheckEvent() is similar to the popular WaitEvent() command with the difference that WaitEvent() blocks the script execution until an event arrives whereas CheckEvent() immediately exits if there is no event. By using this command you can do something while waiting for an event which would not be possible with WaitEvent().

Note that CheckEvent() only handles a single event from the event queue. If you'd like to handle all events that are currently in the event queue, you have to use CheckEvents() instead. See CheckEvents for details.

Please note that generally you should use CheckEvent() only if you really need it. Using WaitEvent() is normally a much better idea than CheckEvent().

Inputs
none

Results
info
table containing information about whether and event occurred or not, and the return value(s) of the user callback in case it has been called

Show TOC