Many of PinballY's program functions are accessible as "commands". A command is an operation that can be triggered by the user via an action in the UI, usually by selecting an item from a menu. Commands can sometimes be triggered directly by pressing a button, but most buttons are mapped to navigation controls that only operate the menus rather than triggering commands directly. Commands are also sometimes used for internal event sequencing, such as handling the events involved in starting or exiting a game.
The concept of commands is important in the Javascript context in two ways. The first is that each time a user action (such as a button press or a menu selection) triggers a command, a Javascript Command Event is fired. This notifies your scripting code that a command is being executed, lets it know which one, and gives it a chance to intervene. Your event handler can cancel the command, carry out some additional operation along with the command, or perform some other action instead of the command. The second way that commands are important to Javascript is that you can intentionally trigger a command from a script, as though the user had selected the command from a menu. You do this by calling mainWindow.doCommand().
Each available command action is identified by an integer command code. This might seem a little primitive or opaque, but we do it this way because it's the Windows convention for associating commands with window menus. PinballY uses normal window menus in addition to its own graphical menu system, so we chose a command representation that's compatible with the native Windows APIs.
To make your Javascript code more readable, the system pre-defines named symbols for the command codes, so that you can refer to the commands by name in your code rather than by number. All of the command codes are defined as properties of the global command object, so you refer to each one as command.commandName.
You can also do the reverse lookup. That is, given a numeric command ID, you can find its name - the name of the property for that ID in the command object - via command.name(id). That will give you a string with the corresponding command property name.
The system reserves a range of identifiers for user-defined commands: command.UserFirst to command.UserLast. The system doesn't use any of these internally, so you can safely use any value in this range to identify your own commands, such as when creating custom menus.
The best way to define your own command IDs is to use the command.allocate() function to dynamically allocate an ID for each command. This assigns a new ID, and records it as in use within the command object, to guarantee that each call to command.allocate() yields a different ID. IDs are assigned starting with command.UserLast and with each new ID one less than the previous one.
The number of available user-defined IDs is finite, so you should allocate an ID for each unique command you need during startup, and then use those assigned numbers throughout the session.
The advantage of using command.allocate() to assign IDs, rather than defining IDs on an ad hoc basis in your code, is that it helps ensure that different modules written by different people can be safely mixed together on one system. As long as each module assigns any commands it needs via this function, each module will get its own separate commands, so there will be no conflict about the meaning of a given user command ID.
Don't save command IDs in external files or settings, since there's no guarantee that the ID numbers will be the same from one session to the next.
The pre-defined system command names are listed below.
command.AboutBox: Display the program's About Box, as a graphic overlay in the main playfield window.
command.AddFavorite: Add the current game to the Favorites list.
command.AdjustCaptureDelay: Displays the dialog to adjust the media capture startup delay time. This is normally only shown in the course of the capture setup procedure.
command.AdjustAudioVolume: Displays the audio volume adjustment dialog, which sets the per-game audio attenuation level for background videos and table audio tracks.
command.BatchCaptureAll: Activates "step 2" of the batch capture setup workflow, specifying that all games are to be included in the batch.
command.BatchCaptureFilter: Activates "step 2" of the batch capture setup workflow, specifying that games selected by the current filter are to be included in the batch.
command.BatchCaptureGo: Executes the batch capture, using the settings entered during the setup workflow process.
command.BatchCaptureMarked: Activates "step 2" of the batch capture setup workflow, specifying that the batch should consist of the games manually marked for capture. Step 2 displays a menu letting the user select the media types to include in the capture.
command.BatchCaptureStep1: Initiates the batch capture setup workflow. This is the command that the user selects from the game setup menu to initiate a batch capture. The batch capture setup process consists of a workflow that steps the user through a series of menus to select options for the capture. The immediate effect of this command is to display the first menu in that workflow, so this command doesn't actually initiate a batch capture, but rather starts the UI workflow to set up the options.
command.BatchCaptureStep3: Activates "step 3" of the batch capture setup workflow. Step 3 displays a menu letting user select the treatment of existing files (replace or keep) for each media type to be included in the capture.
command.BatchCaptureStep4: Activates "step 4" of the batch capture setup workflow. Step 4 displays a summary of the items to be captured, and presents menu options to view the full capture details and to launch the capture.
command.BatchCaptureView: Displays a detailed list of the games and media items selected for the batch capture. This is offered as a menu option on the last step of the batch capture setup workflow, to let the user view the detailed work list before launching the capture.
command.CaptureFirst ... command.CaptureLast: These commands are used during the capture setup workflow to refer to the individual media types in the capture. Activating the command advances the selection state of the associated media type: for example, it might change the selection state of "Playfield Image" from "Capture" to "Skip". The media type associated with each index in this range isn't fixed; it's determined by the set of media types the user selects during earlier steps in the capture workflow. And the range of selection options is likewise variable at run-time, as it depends on which media subtype is involved (video, image, audio), whether or not there are existing files of the type, and whether this is a single or batch capture.
command.CaptureGo: Launches a single-game media capture. In the user interface, this command is offered from the final menu of the capture setup workflow.
command.CaptureLayoutSkip: When you start a capture, PinballY shows a message explaining how the PinballY window layout determines the screen capture area, and shows a menu with options to proceed or cancel. This command is used for an additional item lets the user "Skip this message from now on". Selecting this command toggles a config variable (Capture.SkipLayoutMessage).
command.CaptureLayoutOk: Acknowledges the message shown at the start of a capture about how the PinballY window layout determines the screen recording area.
command.CaptureMediaSetup: Displays the capture media setup menu. This starts the single-game media capture workflow; it's offered as an option in the UI from the game setup menu. This command doesn't actually launch a media capture operation, but rather begins the UI workflow to set up a capture. The immediate effect of the command is to display the capture setup menu.
command.ClearCredits: Zeroes the coin credit counters.
command.ConfirmDeleteGameInfo: This command appears in the UI as an option on the "Confirm Delete Game Information" menu, to let the user confirm that they really want to delete the game data. This command carries out the deletion of the current game's information in the XML table database file.
command.DeleteGameInfo: This command displays the "Confirm Delete Game Information" menu, which asks the user to confirm that they wish to delete the current game's XML data from the table database. This command doesn't actually perform the deletion; it just shows the menu to prompt the user for confirmation. If the user does confirm the operation through that menu, the menu will trigger a ConfirmDeleteGameInfo command to actually carry out the deletion.
command.DeleteMediaFile: Deletes the currently selected media file for the current game. The file must be selected first via the media viewer dialog.
command.EditCategories: Displays the category editor dialog, allowing the user to add, remove, and rename category tags.
command.EditGameInfo: Displays the game information editor dialog, allowing the user to create or modify the XML table database information (title, year, manufacturer, system, etc) for the current game.
command.EnableVideos: Toggles the global "enable videos" setting.
command.FilterByAdded: Displays a menu showing options for all of the filters that select for when a game was added to the database.
command.FilterByCategory: Displays a menu showing options for all of the filters that select games by category.
command.FilterByEra: Displays a menu showing options for all of the filters that select games by release date.
command.FilterByManufacturer: Displays a menu showing options for all of the filters that select games by manufacturer.
command.FilterByRating: Displays a menu showing options for all of the filters that select games by "star" ratings.
command.FilterByRecency: Displays a menu showing options for all of the filters that select a game by how recently they were played.
command.FilterBySystem: Displays a menu showing options for all of the filters that select a game by simulator system.
command.FilterFirst ... command.FilterLast: The commands in this range select individual filters. The menus shown by the "Filter By Xxx" commands all consist of commands in this range, to select specific filters. The system assigns a unique command ID in this range to each filter during startup. The ID assigned to a given filter can vary from session to session, because the overall collection of filters depends on the game database. For example, there's one filter per manufacturer found in the database, so the number of manufacturer filters depends on how many unique manufacturers are in the user's database, and can even change during the session if the user adds games with new manufacturers through the game information editor.
command.FindMediaGo: Launches a media search operation for the current game, which opens an external browser window and navigates to a Google search page with a pre-built search term designed to find HyperPin Media Pack files for the current game, using the game's metadata to fill in the search details. In the UI, this command is accessed from the Media Search menu, which is displayed via the ShowFindMediaMenu command.
command.Flyer: Displays the current game's flyer graphics, if available, as an overlay in the main window.
command.GameInfo: Displays an overlay in the main window with details on the current game.
command.Help: Displays the PinballY help file, by opening an external Web browser window and navigating to the table of contents page. The help files are local HTML files within the PinballY folder, so this simply navigates to a file:/// URL selecting the main h elp file.
command.HideGame: Toggles the "hidden" status for the current game. A hidden game is excluded by all filters except for the special "hidden games" filter, so hiding a game allows a user to exclude a non-playable game (e.g., an old version, a backup copy, etc) from the normal UI without actually deleting any of the files involved.
command.HideWindow: Hides the current foreground window. The window's Javascript object still exists, but the on-screen window is hidden and can't receive any keyboard or other input events. From the user's perspective, the window is effectively closed. This command has no effect on the playfield window, since that window holds the main UI.
command.HighScores: Displays an overlay showing the high score information for the current game, if available.
command.Instructions: Displays an overlay showing the instruction card for the current game, if available. The overlay appears as a popup in the main window, backglass window, or topper window, according to the option settings.
command.KillGame: If a game is running, this attempts to terminate the game and make PinballY the foreground application.
command.MarkForBatchCapture: Toggles the current game's "marked for batch capture" status. One of the options in the batch capture process for selecting which games to include is to include games marked with this status, so this gives the user a way to construct an ad hoc set of games to include in a capture.
command.MediaDropFirst ... command.MediaDropLast: The commands in this range represent the individual entries in a set of media files involved in a drag-and-drop operation, where the user has dragged files from the Windows desktop and dropped them onto a PinballY window for the purposes of installing the files as media for the current games. Each file in the drop set is assigned a unique ID within this range, with the first file assigned the ID MediaDropFirst, and each additional file getting the next higher ID. These commands are used in "step 2" of the media drop workflow, which displays an option for the disposition (add, skip, replace) for each file in the group of files dropped. The effect of each of these commands when executed is to toggle to the next disposition for the item.
command.MediaDropGo: Executes the current media drop operation, installing the dropped files according to the selections made in the media drop menu workflow. In the UI, this is offered as a command in the final step of the workflow, to confirm that the file installation should proceed.
command.MediaDropPhase2: Initiates "step 2" of the media drop workflow, which displays a menu showing the items to be dropped, allowing the user to select a disposition (add, skip, replace) for each item. The available dispositions depend upon whether or not the game already has an existing file of the same type. Each file in the drop set is assigned a command ID in the range MediaDropFirst to MediaDropLast, and each of these commands is used to let the user select which disposition to use for each file. Note that "step 2" is normally initiated by "step 1", which is triggered not by a regular menu command but by a mouse drag-and-drop operation.
command.MenuPageDown: If a menu is being displayed, and the menu has a section of items that's divided into multiple pages (because there are too many items in the section to show all at once), this advances to the next group of items in the menu.
command.MenuPageUp: If a multi-page menu is being displayed, this moves to the prior page of items in the menu.
command.MenuReturn: Cancel the current menu and return to the previous UI mode. This is the command associated with the "Cancel" or "Return" items that appear in most menus. The Exit button also triggers this command when a menu is showing, unless the menu is designated as an Exit Menu and the option to treat the Exit button as the Select button in an Exit menu is set.
command.MirrorWindowHorz: Mirrors the current foreground window's graphics contents left-to-right. This produces a display as though you were viewing the window in a mirror held up to one side of the window. The window's caption bar and frame controls aren't affected by this, since the Windows desktop UI isn't capable of applying these sorts of transformations to window frames. Mirroring can be useful if you have physical display setup where you're viewing one of your monitors as a reflection in a mirror, which is sometimes the case in video game cabinets.
command.MirrorWindowVert: Mirrors the current foreground window's graphics contents to-to-bottom. This produces a display as though you were viewing the window in a mirror held up to the top or bottom edge of the window. The window's caption bar and frame controls aren't affected by this, since the Windows desktop UI isn't capable of applying these sorts of transformations to window frames. Mirroring can be useful if you have a physical display setup where you're viewing one of your monitors as a reflection in a mirror, which is sometimes the case in video game cabinets.
command.MuteAttractMode: Toggles the "mute attract mode" option setting, which controls whether or not sound effects are muted when attract mode is active.
command.MuteButtons: Toggles the "mute buttons" setting, which controls whether or not button sound effects are played.
command.MuteTableAudio: Toggles the "mute table audio" setting, which controls whether or not table audio files are played.
command.MuteVideos: Toggles the "mute videos" setting, which controls whether or not the audio portion of a table's video file is played.
command.Options: Displays the Options dialog.
command.PauseGame: If a game is running, this attempts to bring the main PinballY window to the foreground. Despite the name, this doesn't attempt to send the game any explicit commands to pause, since none of the popular game systems have anything like that. Instead, it depends upon the game recognizing loss of window activation as meaning it should pause, which the popular systems happen to do.
command.PinscapeNightMode: If a Pinscape unit has been detected, this sends a "toggle night mode" command to the device.
command.PickSysFirst ... command.PickSysLast: These commands are used in the "Pick a system" menu, which is displayed if the user tries to launch a game that doesn't have an XML database entry, and whose file type is associated with more than one system. The program can't infer which game system to use in this case, so it asks the user by displaying a menu. Each matching system is assigned a unique command ID from this range; executing one of these command IDs has the effect of launching the game using the assigned system.
command.PlayGame: Launch the current game.
command.PowerOff: This command is triggered when the user selects "Shutdown" from the Exit menu. It doesn't actually shut down the system; it just shows the shutdown confirmation menu, which asks the user to confirm the action before proceeding.
command.PowerOffConfirm: This command is triggered when the user selects the "Yes, I really want to shut down the system now" option from the shutdown confirmation menu. This command proceeds by asking Windows to power off the system. Assuming that Windows allows the shutdown request, this will have the side effect of terminating the program shortly after the power-off command.
command.Quit: Exits the program.
command.RateGame: Displays the Rate Game dialog, allowing the user to enter a "star" rating for the current game interactively.
command.RemoveFavorite: Removes the current game from the Favorites list.
command.RestartAsAdmin: Re-launches the program under the Admin Host program. This is normally used when a game launch fails because it requires admin privileges, and the user selects this option to restart the session using the Admin Host.
command.ResumeGame: If a game is running, attempts to make the game the foreground application, which should return keyboard focus to the game and make it resume normal play.
command.RealDmdAutoEnable: Sets the Real DMD status to "Automatic", which means that the program will enable the DMD if the DMD DLL can be loaded.
command.RealDmdDisable: Disables PinballY's Real DMD usage, which prevents PinballY from attempting to load the DMD DLL or access the device.
command.RealDmdEnable: Enables PinballY's DMD usage. This tells PinballY that a DMD device is definitely present, so PinballY attempts to load the DMD DLL and connect to the device at startup. The difference between "Enabled" and "Automatic" is that PinballY will display an error message in "Enabled" mode if the DMD can't be accessed, since you've asserted that the device is definitely present and that you definitely want PinballY to use it; whereas there's no error in "Automatic" mode, since that mode means that you want PinballY to determine whether or not a DMD is present, and it's not an error condition if the answer is "no".
command.RealDmdMirrorHorz: Set the Real DMD display format to horizontal mirroring.
command.RealDmdMirrorVert: Set the Real DMD display format to vertical mirroring.
command.RotateWindowCCW: Rotates the current foreground window's graphics contents counter-clockwise (CCW) by 90 degrees. This only rotates the contents of the window, since the Windows desktop UI isn't capable of rotating window frames, so the on-screen boundaries of the window aren't affected.
command.RotateWindowCW: Rotates the current foreground window's graphics contents clockwise (CW) by 90 degrees. This only rotates the contents of the window, since the Windows desktop UI isn't capable of rotating window frames, so the on-screen boundaries of the window aren't affected.
command.SaveCategories: This commits changes made in the Set Categories menu.
command.SetCategories: Displays the Set Categories menu, which lets the user toggle category tags for the current game.
command.ShowExitMenu: Shows the Exit menu. This menu is normally shown when the user presses the "Exit" button when no other menu is showing.
command.ShowFindMediaMenu: Displays the "Media Search" menu, which describes the media search process and gives the user options to proceed or cancel. If the user proceeds, a FindMediaGo command is triggered.
command.ShowGameSetupMenu: Shows the Game Setup menu for the current game, which has options for editing the game's details, capturing media, etc.
command.ShowMainMenu: Shows the main menu. This menu is normally shown when the user presses the "Select" button (on a pin cab, usually assigned to the Start button) when no other menu or popup is showing.
command.ShowMediaFiles: Display the Media Files dialog, which lists all of the media files for the current game, shows the folder search locations, and lets the user delete files and open the folders in the Windows desktop.
command.ShowOperatorMenu: Displays the "Operator Menu", which has options for game setup and system settings.
command.SWFErrorDisable: Disables .swf instruction card images in the configuration settings, and then reloads settings and media. This is an option on the menu displayed when an attempt to load an .swf file fails, to give the user options for how to handle such errors in the future.
command.SWFErrorSuppress: Disables errors related to loading .swf files for the remainder of the current program session. This is an option on the .swf load error menu.
Shows the help page about how PinballY uses .swf files and how to install Flash Player. This is an option on the .swf load error menu.
command.ToggleFrameCounter: Toggles the performance statistics display (which includes a video frame update rate counter and CPU usage stats) on or off in the current foreground window.
command.ToggleFullScreen: Toggles the current foreground window between full screen mode and regular windowed mode.
command.ToggleWindowBorders: Toggles visibility of the window border decorations (the caption bar and sizing borders) for the current foreground window.
command.UserFilterGroupFirst ... command.UserFilterGroupLast: This range of commands is reserved for user filter groups. These commands are automatically assigned when you create a custom filter and you assign it a new group name.
command.UserFirst ... command.UserLast: This is a range of commands reserved for user-written Javascript commands, mainly for use in custom menus. The system doesn't generate any of these commands itself, and the default processing is to simply ignore them. This lets you assign these commands to your own custom menu items and write your own handlers to carry them out.
command.ViewBackglass: Show the backglass window if it's currently hidden, and bring it to the foreground.
command.ViewDMD: Show the DMD score area window if it's currently hidden, and bring it to the foreground.
command.ViewInstCard: Show the instruction card window if it's currently hidden, and bring it to the foreground.
command.ViewPlayfield: Bring the playfield window (the main UI window) to the foreground.
command.ViewTopper: Show the topper window if it's currently hidden, and bring it to the foreground.
command.allocate(name): Allocates a new command from the UserFirst...UserLast range for use as a custom command code. Returns the new command code. If name is given, it will be assigned as the name for the new code within the command object: for example, if you call command.allocate("MyNewFilter"), command.MyNewFilter will be set to the newly assigned command ID.
command.name(id): Returns a string with the name for the given command ID (an integer value, one of the command.Name properties). For the "ranged" commands (FilterFirst to FilterLast, CaptureFirst to CaptureLast, etc), a command in the middle of the range will be represented with a name like "FilterFirst+3", indicating the numeric offset from the start of the range.
command.nameAndIndex(id): Returns an object with properties { name: string, index: integer } giving the command's name and, if applicable, the index of the command within its range. For most commands, the name is set to the same string that command.name() would return for the same ID, and index is undefined. For the "ranged" commands, name is set to the first command of the range (e.g., "FilterFirst"), and index is set to the ID's offset from the first command in the range. This provides an easier way to handle ranged commands, since the name is the same for every command in the range, and the index within the range is separated out as a simple integer value.