UnderlayEvent

This event type is fired when the program is about to change the underlay - the image layer displayed at the bottom of the screen, under the wheel icons. PinballY checks for a change of underlay image every time a new game is selected in the wheel UI, since the underlay image for a game depends on its system.

The event target for this event type is the mainWindow object.

The UnderlayEvent class has only one subtype:

underlaychange: Fires when the system is about to change the underlay as a result of changing the selected game.
There are a couple of subtleties to this event. First, it only fires when the system initiates an underlay change, as part of changing the selected game in the wheel UI. The event doesn't fire for Javascript-initiated changes. Second, it only fires when the underlay is actually about to change, so it doesn't necessarily fire on every new game selection - only those when the underlay for the game is different from the one currently displayed. The underlay is considered different if it's a different image file, or if any of the display options for the current underlay were overridden from the configuration defaults.

As with most event types, an UnderlayEvent fires before the system carries out its normal handling for the command. This allows you to block the underlay change entirely by calling preventDefault() on the event object in your handler. For example, if you simply want to prevent system-triggered underlay changes across the board (which you might wish to do if you're creating your own custom way of selecting the underlay to use on each game change), you could do this:

mainWindow.on("underlaychange", ev => { ev.preventDefault(); });

You can also change the image file that the system loads, if you allow the event to proceed. The filename property of the event object (passed as a parameter to your event handler) contains the full filename (with directory path and extension) of the image file that the system intends to load, as a string. You can change the property to a new string with a different filename, in which case the system will load that file instead. For example, this adds an alternating "-blue" or "-red" suffix to the name of the file that the system was planning to load.

let suffix = ["-blue$1", "-red$1"]; mainWindow.on("underlaychange", ev => { ev.filename = ev.filename.replace(/(\.\w+)$/, suffix[0]); suffix.push(suffix.shift()); });

Properties

filename: A string giving the full Windows file name (with directory path and extension) of the new underlay file that the system has selected for the game. If you change the value of this property, the system will load the file you specify in the new value instead of the file it originally planned to load.
If the system passes an empty string as the filename, it means that it's planning to remove any prior underlay image, effectively displaying no underlay. By the same token, you can set the filename to an empty string to remove the previous underlay image.
game: A GameInfo object representing the newly selected game that triggered the underlay change.
options: An object containing overrides for the layout options from the configuration. This is simply set to an empty object when the event initially fires. Event handlers can populate this with properties to override the default settings in the configuration, for the underlay display height, bottom offset, and so on. For a list of the properties you can set, see mainWindow.setUnderlay(). The properties for this object are the same as the properties for the options parameter to setUnderlay().