mainWindow Object

mainWindow is a pre-defined PinballY object representing the main user interface window (the "playfield" window). This window is the event target for most UI-related events, and in many ways it serves as the Javascript object that represents the overall PinballY application.

Class inheritance structure

This object is an instance of the common window base class, so it has all of the behavior defined in that class, in addition to its own methods and properties (see below).

Basic Window Object

Event target

mainWindow is an event target object, so you can use the standard event methods (on(), off(), addEventListener(), etc) to add and remove event listeners. See EventTarget.

mainWindow serves as the event target for the following event types:

Drawing layer ordering

The system displays graphics in several layers in the main window. If you use custom drawing layers, you can interleave your graphics with the system's graphics by using the Z index when creating a layer. Here's the order of the layers, from back to front:

Methods and properties

The mainWindow object provides the common window methods and properties. It also provides the additional items listed below.

mainWindow.createMediaWindow(desc): Creates a new media window. This lets you add custom media display windows of your own alongside the standard backglass window, DMD window, topper window, and instruction card window. Custom media windows act just like the built-in windows, the only difference being that you can specify exactly what kind of media to show in a custom window. Custom media windows also have full support for drawing layers, just like the built-in windows, so you can further specialize these windows with your own custom-programmed graphics.

For an example of how to use this method, see Custom Media Window in the Worked Examples section.

The desc argument is an object, with a collection of properties describing the new window. All of the properties are optional, but in most cases you'll want to at least specify the title and configuration file prefix.

The return value of the method is the newly created window object, which has methods and properties described in CustomWindow.

The descriptor desc doesn't contain any window position, size, or visibility information. That's intentional. A custom media window is a first-class window with all of the standard functionality that comes with the built-in media windows, so one of the things that the system will do automatically with this window is to save and restore its layout information. When you create the window, its layout information will be restored from the settings file, so that the window appears at the same location where the user left it at the end of the last session. Of course, there's no saved information to be restored when you create a window for the first time, so the window is simply shown at a default position. If you want to override the saved location every time you create the window in a new session, you can use the optionSettings object to update the window's settings variables just before you open the window. Recall that the window's variables all start with the configVarPrefix string you specify when creating the window.

mainWindow.doButtonCommand(command, down, repeatCount): Simulates a key press, or more precisely, simulates a processed key event that corresponds to CommandButtonEvent. This carries out the effect of a named button command, specified by the string command. The valid command names are the values listed for the .command property of the CommandButtonEvent object. down is a boolean indicating if this simulates a key press (true) or a key-up event (false) representing the user releasing the key.

repeatCount is an integer indicating if the simulated event represents an initial key press or an auto-repeated key press (that is, repeated key events generated when the key is being held down). 0 represents an initial key/button press (not yet auto-repeated), 1 represents the first auto-repeat, 2 is the second auto-repeat, and so on. repeatCount is only meaningful when down is true, for obvious reasons.

Because the simulated key press is coming from Javascript already, it doesn't generate any of the usual Javascript events for actual key presses; it just carries out the effect of the key command.

mainWindow.doCommand(id): Executes the command specified by id, which is one of the integer command codes in the Commands set. This function carries out a menu-level command, as opposed to a button-level command; for the latter, use doButtonCommand().

mainWindow.DOFPulse(name): Pulses the named DOF event. This turns the effect "on" (by setting its "brightness" level in DOF to the maximum value of 255), then turns the effect back off (by setting the DOF brightness value to 0) after a brief interval. This is the normal way in DOF to trigger the lighting or tactile effects associated with an "event". In a simulated pinball game, a DOF event would represent a specific, momentary action in the game, such as "the ball hit the Extra Ball target". In a PinballY context you might use this to represent a discrete user action, such as "pressed the left flipper button" or "navigated to a new game".

You can connect events fired with this method to actions in your DOF Config Tool configuration by using the same event name in the Config Tool, adding the $ prefix in the Config Tool rule. For example, if you write mainWindow.DOFPulse("MyEvent") in Javascript, the corresponding rule in the DOF Config Tool syntax would refer to the event as $MyEvent, because the Config Tool uses the $ prefix to refer to named events. See DOF Events for more.

mainWindow.DOFSet(name, value): Sets the given named DOF event to the given value, from 0 (off) to 255 (full "brightness"). The setting stays in effect until you change it with another call to DOFEffect() using the same name and a different value.

You can connect events fired with this method to actions in your DOF Config Tool configuration by using the same event name in the Config Tool, adding the $ prefix in the Config Tool rule. For example, if you write mainWindow.DOFSet("MyEvent", 255) in Javascript, the corresponding rule in the DOF Config Tool syntax would refer to the event as $MyEvent, because the Config Tool uses the $ prefix to refer to named events. See DOF Events for more.

Be careful about timing. DOF effects require a little time padding between consecutive changes to a given effect's value, because DOF operates on its own "clock", and only checks for updates periodically. If you update the same named event twice in a row too quickly, DOF might not notice the change and might not trigger the desired hardware effects. For cases where you want to represent a momentary action in the UI, such as "user pressed left flipper button", it's almost always better to use DOFPulse(), since that automatically paces the ON-OFF sequence at a speed that DOF can handle.

This function doesn't coordinate at all with PinballY's own DOF event generation, so it's easiest to use this for your own custom events, using unique names that aren't part of PinballY's own named DOF event set (see DOF Events). You can use any names you want for named DOF events, so you're free to invent as many new events as you like representing whatever actions you like. You can also use this to update PinballY's own named events, but since PinballY updates those events itself, this could cause unpredictable interactions.

mainWindow.enableJoystickAxisEvents(options): Enables or disables JoystickAxisEvent (joystick axis change events) for a given set of control axes on a given joystick. By default, PinballY doesn't generate joystick axis change events at all; these events can occur at fairly high frequency, so filtering them out by default avoids the performance impact of sending them to Javascript scripts that aren't using them. This method lets you tell PinballY that you are using them and that it should generate the Javascript calls after all.

options is an object that describes which joystick axes on which joystick are to be enabled or disabled. It has the following properties:

mainWindow.endAttractMode(): Exits "Attract Mode" if it's currently active. There's no effect if the program isn't already in attract mode. The attractmodeend event isn't fired when you use this method.

mainWindow.getActiveWindow(): Returns the window object (mainWindow, backglassWindow, etc) corresponding to the current active window in the application. This is the active window at the operating system level, which means that it's in the foreground and has keyboard focus. If the application is currently in the background, none of the windows are active, so this returns null.

mainWindow.getJoystickInfo(id): Retrieves a joystick descriptor object with information about a particular joystick device, or descriptors for all of the joystick devices in the system. If id is specified, the method returns a single JoystickInfo object, for the joystick identified as follows:

If id is omitted, the method returns an array of JoystickInfo objects, one for each joystick in the system. The array in this case is in order of logical unit number, so the element at index [0] is the descriptor for unit number 0, and so on.

See JoystickInfo for details on the returned descriptor objects.

The devices in the joystick array are "logical" joystick units, meaning that they might or might not be physically present in the system. PinballY creates a logical unit for each joystick mentioned in the settings file under a joystick button mapping. If you plugged in a joystick at one point, and then assigned some buttons from that joystick to commands in the PinballY settings, PinballY will create a logical joystick to represent that unit even if the device isn't physically plugged in to the system during a later session. That allows the button mappings to become active again as soon as you plug the device back in.

mainWindow.getKeyCommand(descriptor): Returns an array of the button commands assigned to the given key or joystick button. descriptor is an object describing the key or button to look up. This can be in one of the following formats:

{ type: "key", vkey: integer }; // look up by virtual key (vkey) from key event { type: "key", code: string }; // look up by key code from key event { type: "joystick", unit: integer, button: integer }; // joystick button

This is the same information provided to your event listener in a KeyEvent or JoystickButtonEvent object, so it's easy to look up the command information in one of those handlers.

The command names in the returned array are the same names used in the .command property of the CommandButtonEvent object. An array is returned because it's possible for a user to assign multiple commands to the same keyboard key or joystick button. Pressing a key with multiple commands assigned carries out each of the commands in sequence.

mainWindow.getUIMode(): Returns an object describing the current UI state. Here's a quick summary of the object's contents:

{ mode: "wheel", // see list game: (object), // GameInfo object for currently selected game in wheel menuID: "main", // see list; present only in "menu" mode popupID: "about box", // see list; present only in "popup" mode runMode: "running", // or "starting", "exiting"; present only when a game is running capture: "single" // or "batch"; present only when running a game in media capture mode }

The main state is given by the property .mode, which has one of the values listed below. Depending on the mode, other properties of the object might be present to provide additional information.

The .game property identifies the game that's currently selected in the wheel, if any. This is present regardless of which UI mode is in effect. This is a GameInfo object, which has properties that access the game's details. The .game property will be omitted (so it'll read as undefined) if no game is selected, which can only happen when the wheel is completely empty. The wheel can be empty when the program can't find any installed games, or when a filter is selected that doesn't match any games.

mainWindow.launchOverlay: This read-only property contains an object representing the launch overlay, which displays graphics showing the status during game launches. This lets you customize the graphics shown during the launch process. launchOverlay has two properties, giving you access to the two drawing layers of the launch overlay:

Each of those objects in turn has methods that let you show graphics in its layer. The foreground layer (mainWindow.launchOverlay.fg) is, as the name suggests, the front layer; the background layer (bg) is immediately behind it in the drawing order. These are the topmost layers overall, so they're draw in front of the wheel UI and the playfield background. If you draw an opaque background into either window, it'll cover up everything else in the UI.

The reason we have two layers for this one overlay is that it lets the system (or your Javascript code) draw some fixed graphics in the background layer, and then update the message in the foreground layer at each stage of the process, without having to redraw the background. This is more efficient than redrawing the whole background on every update, and it's also nice if you want to show a video, since videos can't be directly combined in one layer with other graphics. You can use the background layer for a video that plays throughout the loading process, for example, while status messages are drawn on top of the video via the foreground layer.

The launch overlay is only displayed during game launches. Accessing it at other times will have no effect. In most cases, you'd use this object in listeners for the LaunchOverlayEvent group of events.

The fg and bg objects are DrawingLayer objects. You can draw graphics into them the same way you would with a drawing layer that you created explicitly in your scripting code via createDrawingLayer(). However, since PinballY itself creates and manages the fg and bg objects, there are a few differences to be aware of:

mainWindow.message(message, style): Shows a message using a graphical popup box in the main window. Unlike the global alert() function, this doesn't pause the script until the user acknowledges the message; it simply shows or queues the message and returns immediately. This is a good option for showing error messages or status updates, since it doesn't interrupt the flow of the user interface with a modal dialog. If style is provided, it's a string value specifying the visual style of the popup message. This can be "info", "warning", or "error", to show the message with green, orange, or red trim (respectively), to visually signal the nature of the message. The regular "info" style is used if style is omitted.

mainWindow.playGame(game, options): Launches a game. game is a GameInfo object for the game to be launched. options is an object with properties specifying option settings; this whole argument can be omitted, in which case defaults are used for all options. If you do include the object argument, you only have to specify the properties for options you want to override; any missing properties will use the corresponding defaults. Here are the possible options properties:

mainWindow.setUnderlay(filename, options): Display a new underlay in the main window's wheel UI. This loads the image file specified by filename and displays it as the new underlay. Use an empty string ("") to remove the underlay image.

options, if present, is an object specifying additional layout details for the underlay. This lets you override the normal layout parameters for an individual underlay file, in case you want to customize the size or position of each underlay file separately. If the options object is omitted entirely, all of the layout parameters use the settings from the configuration. If you do provide an options object, you don't have to include all of the properties listed below - just the ones you want to override. Any properties not included in your options object use the defaults, taken from the configuration. Any values you specify in the options object override the settings for duration of this underlay display (so the overrides remain in effect even if the user edits the option settings or resizes the window). The options only last for the duration of this single underlay display; they aren't persistently attached to the file or anything crazy like that. The following properties can be specified:

See also UnderlayEvent, which describes the event fired when the system is about to initiate its own change to the underlay because of a new game selection in the wheel UI.

mainWindow.setWheelAutoRepeatRate(interval): Sets the "instantaneous" auto-repeat rate for the current game wheel navigation command. The repeat interval is specified in milliseconds. This method has no effect unless a wheel navigation command (Next, Previous, Next Page, Previous Page) is currently in progress. If a command is in effect, this method sets the auto-repeat rate for the current command. The new rate overrides the repeat rate set in the options, and it remains in effect from now until the command ends, or until another call to setWheelAutoRepeatRate(). It doesn't affect future commands, since those start over at the repeat rate set in the options. This can be useful for modifying the repeat rate when the command is coming from an alternative input device such as a joystick; see Joystick Game Switcher for an example of how to use it.

mainWindow.showMenu(id, items, options): Displays a custom menu in the main window, in the same style as the main menu, exit menu, etc. See Menus for more details. The menuopen event isn't fired when you use this method.

mainWindow.showPopup(desc): Displays a custom popup dialog in the main window, in the style of the standard system popups (e.g., game information, high scores, ratings entry). See Custom Popups for more details.

mainWindow.showWheel(show): Shows or hides the game wheel display. If show is true, the function shows the wheel; if show is false, the wheel is hidden. The system hides the wheel itself at certain times, such as when "attract mode" is active and the options are set to hide the wheel in attract mode; in these cases, showing the wheel through this function will have no immediate effect.

mainWindow.startAttractMode(): Enters "Attract Mode", the screen saver mode that normally kicks in automatically when there hasn't been any keyboard or mouse input for some amount of time (the exact amount of time is configurable in the settings). This function lets you explicitly enter Attract Mode from Javascript code, so that you can create your own custom conditions for triggering the mode, separately from the system's normal handling. For example, you could use this to enter attract mode when a certain key is pressed, or from a custom menu selection. The attractmodestart event isn't fired when you use this method.

mainWindow.statusLines: An object containing references to the StatusLine objects representing the on-screen status line displays. The object has the following properties: