# 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.

## 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:

## Methods and properties

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

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.doButtonCommand(command, down, repeat): 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. repeat is a boolean indicating if this should represent an auto-repeat event. repeat 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.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.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.

- "wheel": in the normal game wheel UI, awaiting a command
- "menu": a menu is being displayed (this refers to the graphical menu that PinballY displays as an overlay in the playfield window, not a standard Windows menu). In this case, the .menuID property of the mode object will contain a string identifying which particular menu is being displayed. See system menus for a list of the built-in menus and their identifiers.
- "popup": a popup box is being displayed. The .popupID property of the mode object is a string specifying the type of popup. See system popups for a list of the system popup types.
- "running": a running game is in progress. Note that "menu" mode can supersede this, since the user can still bring up menus while a game is running. You can determine for sure whether or not a game is running by checking for the presence of another property, .runMode, which will be present if and only if a game is running. If present, .runMode will be set to the string "starting" (the game has been launched but hasn't opened its UI window yet), "running" (the game is in progress), or "exiting" (PinballY has closed the game and is waiting for the process to exit). In addition, if the game is running for the purposes of media capture, the property .capture will be present, and will be set to the string "single" for a single-game capture or "batch" for a batch capture.
- "attract": attract mode/screen saver mode (meaning that there hasn't been any user input for the period of time configured in the settings to activate attract mode)

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.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.playButtonSound(name): Plays a button sound effect. These are the same system sound effects played when the user presses various buttons. Does nothing if button sounds are muted in the user's option settings. The available effect names are:

- AddCredit: played when a coin is inserted and a full credit is added
- CoinIn: played when a coin is inserted and a fractional credit is added
- Deselect: played when closing a menu or popup
- Next: played when switching to the next game, menu item, or popup page
- Prev: played when switching to the previous game, menu item, or popup page
- Select: played when showing a menu or selecting a menu item

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:

- command: An integer giving the command code that the game is nominally launched under. The default is command.PlayGame, which is also the command that the system itself uses to launch games for normal play (as opposed to media capture). The command you specify here has no effect on how PinballY itself handles the launch process, but it's reported to your event handlers as the command code in all of the LaunchEvent events reported that fire during the launch, so you can use it as the basis of any custom handling you want to perform during the launch.
- system: A GameSysInfo object specifying which system to use to launch the game. The default is the system associated with the game in the game database, or the system associated with the table directory where the game file is located. If it's not possible for PinballY to uniquely determine the system from one of those sources, you must specify this option to tell the program which system to use. Note that PinballY doesn't try to second-guess your choice of system here; it'll let you run any game file with any system. But for obvious reasons, the launched program will probably show an error, crash, or otherwise fail to work properly if you try to launch it with a game file designed for a different system.

mainWindow.showMenu(id, items, options): Display 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): Display 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.startAttractMode(): Enters "Attract Mode", the screen saver mode that normally kicks in automatically after a period without any user input (the exact amount of time is configurable in the settings). This function lets you create your own conditions for entering attract mode. The attractmodestart event isn't fired when you use this method.