HandleEvents -- handle display events (V6.0)
int error = HandleEvents(lua_State *L, ULONG flags, struct hwTagList *t);
This function must handle all display events that have come in. Hollywood will call this function many times per second so that your application stays responsive. As this is called so very often, you may want to implement a throttle here so that you only poll for events 50 times per second or so. Otherwise, HandleEvents() has the potential to slow down your script's execution significantly if polling for events is too expensive and you do not implement a throttle. Be sure to benchmark raw performance of scripts with your display adapter and compare them to the performance of Hollywood's inbuilt display handler to see if your adapter needs optimizing.

The following flags may be passed in the second parameter:

This flag is set if HandleEvents() has been called from the Lua line hook.

If this flag is set, then HandleEvents() has been called from a modal loop that Hollywood is currently running. A modal loop is a temporary event loop set up by functions that block the script execution until certain events happen, e.g. WaitLeftMouse() or InKeyStr().

This flag is set if HandleEvents() has been called as a result of the script calling Hollywood's CheckEvent() command.

This flag is set if HandleEvents() has been called because WaitEvents() has triggered.

Your HandleEvents() function should always call hw_MasterServer() with the HWMSFLAGS_DRAWVIDEOS flag set so that Hollywood can update any videos that are currently playing. If you don't do that, video playback won't work correctly.

The third parameter is a tag list which is currently always NULL. This might change in the future, though.

HandleEvents() must return an error code or 0 for success. A special return value is ERR_USERABORT. If your HandleEvents() returns ERR_USERABORT, Hollywood will quit. Thus, it is suggested that you return ERR_USERABORT if the user has clicked your display's close widget, pressed the escape key, etc. Note that you should not return ERR_USERABORT in case the HWDISPSATAG_USERCLOSE attribute has been set to True using SetDisplayAttributes(). See SetDisplayAttributes for details.

Please note that this function must handle events on all displays that have currently been opened by OpenDisplay(). Additionally, it could also happen that no display is open at all and your HandleEvents() function is called. Be prepared to deal with these cases.

All standard window events like sizing a window, moving a window, key presses and mouse events, etc. should be forwarded to Hollywood using hw_PostEventEx() so that Hollywood is able to notify any handlers that might listen to these events.

pointer to the lua_State
combination of flags (see above)
tag list containing additional parameters (see above)
error code or 0 for success; returning ERR_USERABORT tells Hollywood to quit

Show TOC