# EventTarget Interface

The EventTarget interface is implemented by each object that generates Javascript events. Here are the event targets and their associated events:

- mainWindow
- gameList

You call EventTarget methods by addressing the specific object that the events are associated with. For example, to add a "keydown" event listener to the main playfield window, you'd write:

mainWindow.on("keydown", ev => { /* event handler code... */ });

## Methods

eventTarget.addEventListener(event, listener, options): Adds an event listener. event is a string giving the name of the event (e.g., "keydown"). listener is a function to call when this event occurs; the function takes a single parameter, an Event object that describes the event. options is an object with the following members:

- capture: A boolean indicating whether the listener should be added to the "capture" stage or the "bubble" stage of processing for the event. This isn't currently used, as no PinballY events distinguish these phases.
- data: Any value. This will be passed to the event listener in event.data (the "data" property of the Event object parameter) each time this listener is invoked. This can be used to store context information for the event listener.
- once: A boolean. If true, the listener is automatically removed (as though by calling removeEventListener()) the first time it's called. Use this to create a listener that only handles the first event it receives.

The options parameter can be omitted, in which case default options are used. For the sake of those familiar with the analogous Web browser method, options can also be passed as a boolean (true/false), in which case it specifies the value of the "capture" property.

eventTarget.dispatchEvent(event): Calls the registered event listeners for the given event. The event argument is passed as the parameter to each listener invoked, with the event-specific properties (target, data) set appropriately for each call. Returns true if the event's default system processing should proceed, false if not. Returning false usually means that event.preventDefault() was called in the course of processing the event.

eventTarget.off(events, listener): Removes event listeners previously registered with on() or addEventListener(). As with on(), events is a string listing one or more event names, separated by spaces. And as with on(), namespaces can be specified in the event names with ".namespace" suffixes ("keydown.MyPlugin", for example). The listener argument is optional; if provided, only listeners originally added using the same function will be removed, otherwise all listeners matching the event name and namespace values will be removed.

When namespaces are specified, any namespace match from the original on() call will match. You don't have to match the whole list specified in on(). For example, if an event listener was registered as target.on("keydown.MyPlugin.Main", func), any of these calls will remove it:

- target.off("keydown.MyPlugin")
- target.off("keydown.Main")
- target.off("keydown.MyPlugin.Main")
- target.off("keydown.Main.MyPlugin")

eventTarget.on(events, data, listener): Adds an event listener. events is a string listing one or more events, separated by spaces (for example, "keydown keyup"). data is optional; if provided, it can be any type of value, and specifies a value that will be passed to the listener each time it's invoked in the "data" property of the event object, which is passed to the listener as its single function parameter. listener is a function to call each time the event fires.

The event name list can include "namespace" qualifiers for the events. A namespace is any arbitrary string appended after a "." to an event name, as in "keydown.MyPlugin". You can specify multiple namespaces on a single event this way: "keydown.MyPlugin.Main". The purpose of a namespace is to help identify the event in calls to off(). That method lets you specify namespaces the same way in the event(s) to be removed. Namespaces are especially useful to create shared code modules that can be mixed and matched with other modules, since it makes it easier to manage your own module's listeners without affecting code from other unrelated modules.

eventTarget.one(events, data, listener): This works exactly like on(), but registers a one-time-only listener that will be removed the first time it fires. If this registers listeners for multiple events, each event's listener will be set up as a separate once-only handler. For example, if events is "keydown keyup", two listeners are registered, and each listener will be called once before it's removed.

eventTarget.removeEventListener(type, listener, options): Removes an event listener that matches the type, function, and capture setting used in a prior call to addEventListener() or on(). As in the Web browser analog of this method, the only options value used to match the listener is the "capture" property.