| EV_captureEvents | Function (ROM Call 0xC6)

events.h

EVENT_HANDLER EV_captureEvents (EVENT_HANDLER NewHandler);

Sets the event message handler (i.e. installs an event driven application).

EV_captureEvents sets a new event message handler to the routine pointed to by NewHandler, overriding any current handler. NewHandler is the pointer of type EVENT_HANDLER, which is the pointer to a void function (i.e. procedure) which accepts one parameter of EVENT type. If NewHandler is NULL, EV_captureEvents restores the standard event handler (which depends on the current application like "Home Screen", "Graph", etc.). EV_captureEvents returns the pointer to the previous installed event handler.
Any event handler is, in fact, an event driven application. All built-in flash applications like "Home screen", "Graph", "Text editor", "Geometry" etc. and all add-in flash applications are event driven applications. Also, "About" and "Catalog" dialogs and "Error message" dialogs are also event driven applications (maybe the word "applets" is better for them). The whole idea of event driving is as follows: instead of having an application which has an internal "main loop" in which all processing are performed, an event driven application accepts a message (or event), checks the type of the event (a keypress is, for example, one type of the event), process it, then exits immediately after processing the event. So, the user needs to make a loop in which necessary events are collected and dispatched (using EV_sendEvent) to the application. The main advantage of such an approach is in the fact that the main loop is under the control of the user, even if the application itself may be written by somebody else. So, the user can decide in the loop what events will be sent to an application etc. This would not be possible if the "main loop" is the part of the application itself. For example, if the user makes a loop in which events are dispatched to two or more applications, it is easy to estabilish a kind of multitasking. Note that each modern operating system (for example Windows or UNIX) is based on such event dispatching/handling mechanism!
To understand more about event driven applications, you need to read about all other functions in this header file (especially EV_eventLoop, EV_sendEvent and EV_defaultHandler may be very useful in user programs). Probably the most frequent usage of these functions in user programs will be to access the text editor application (see textedit.h header file), which is event driven. In this header file, there is also a good example about using some event functions.
Note: If you want to "hook" on the existing event handler instead to complete overriding the current handler, it is better to use EV_hook.

Used by: ABT_dialog, EV_defaultHandler, cmd_input, cmd_inputstr, cmd_prompt, Dialog, ERD_dialog, GD_Text, fgetchar, gets, getsn, EV_quit, GT_Trace