Events
PinballY's event system is modeled on the event framework used
in Web browsers. There are three main concepts in this framework:
- Event: Abstractly, an event is something that occurs
asynchronously (that is, at any time) and externally to the Javascript
program, such as the user pressing a keyboard key. In more concrete
terms, each time an outside event occurs, the system creates a
Javascript object to represent the event and describe its details.
Each event is represented by a new object, derived from the
Event class. This object uses Javascript
properties to describe the event, such as which key the user pressed.
- Event target: This is a system object that receives
events from the operating system when they occur. Most of the
user interface events in PinballY are sent to the mainWindow
object. All event target objects implement the EventTarget
interface, which provides a set of standard methods you can call to
add and remove your custom event listeners. You don't implement
these objects yourself - they're provided by the system. You
refer to them by name to set up your event listeners.
- Event Listener: This is a Javascript function you write to
carry out a custom response when a particular type of event occurs.
You register a listener function with a specific event target object
to tell the system that you want the listener to be called when a
particular event occurs. For example, you can register a function
that will be called each time the user presses a key. After you
register a listener, the system calls it each time an event of the
desired type occurs. The system passes an Event object to your
listener function as a parameter on each call, to convey the details
of that individual event to the listener.
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.