Events

PinballY's event system is modeled on the event framework used in Web browsers. There are three main concepts in this framework:

In terms of practical usage, you usually have to perform two tasks to set up custom event handling.

First, you write a listener function for each event you're interested in. This is simply a Javascript function that takes a single "event" parameter. When invoked, the "event" parameter will be filled in with an Event object describing the details of the event that occurred, such as which keyboard key was pressed.

function myKeyListener(ev) { logfile.log("The " + ev.key + " key was pressed!"); }

Note: unlike some older browsers, there's no "global" event object that you can refer to. The event details are always passed to each listener via the event object parameter.

Second, you register the listener with the appropriate target object for that event type. For example, you register keyboard event listeners with the mainWindow object:

mainWindow.on("keydown", myKeyListener);

You normally register your event listeners somewhere in the "outer" code in main.js, meaning code that's not contained in any function or class block. All of the "outer" code in the main file is executed when the system initially loads the script, so putting your registration calls there will ensure that the listeners are set up as soon as the code is loaded.

Event registration is completely dynamic, so you can also add and remove listeners at any time. You might want to listen for certain events only when the system is in certain modes, for example, so you might have event handlers that are registered and removed by other event handlers.

Event types

For a list of the specific event types, see Event Types.