# CommandButtonEvent

This Event subclass is similar to KeyEvent and JoystickEvent, but represents a notional "command" button, which is what a physical key press turns into after being translated into the PinballY command that's assigned to the physical key that was actually pressed. This event lets you work in terms of the assigned meaning of a key rather than in terms of the physical key. Since PinballY lets users reassign commands to whichever keys they want, the physical key pressed is often irrelevant to a program function; the assigned command is often all that matters.

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

When the user presses a physical key, it goes through several steps of processing. These steps generate Javascript events that you can monitor:

- A "keydown" or "joystickbuttondown" event is generated for the physical key. (The "bg" equivalent is used instead if the program is running in the background.) This gives you a chance to take action according to the actual physical key pressed, regardless of which command it's assigned to, or whether it's assigned to a command at all.
- PinballY determines if the key is assigned to any command(s) in the settings. If so, it puts the command in a queue for processing. If not, no Command Button events will be generated for the key, but you'll still see the physical key events.
- When it's time to process the command, a "commandbuttondown" (or the "bg" equivalent) is generated for the mapped command. It doesn't matter to PinballY which physical key generated the command at this point, so this event only has the mapped command, with no information on the original key that was pressed. This event lets you work in terms of the assigned meaning of the key, regardless of which physical key was used to generate the command.

As with key and joystick events, a "button down" event is sent when the user presses the button, and a "button up" event is sent when the user releases the button. A command button event can also auto-repeat if the user holds down the originating key.

The default processing that PinballY does almost always ignores the "up" events; commands are generally only triggered by key press events. PinballY repeats some command actions on auto-repeat events, such as moving through the game wheel with the next/previous keys, and it ignores auto-repeats for some other commands. Regardless of the internal response, though, the sequence of Command Button events - button down, repeat button down, button up - is always generated the same way for all keys with commands assigned.

The settings allow a single physical key to be mapped to more than one command. When a key with multiple assigned commands is pressed, the program fires multiple Command Button events - one per assigned command - for the same physical key press. The only button that's commonly mapped to multiple commands is the Exit button, which is usually mapped to both the "Exit" command and the "Exit Game" command. However, the ability to map multiple commands to a key isn't restricted to that case and could be applied to any key and any combination of commands.

There are four command button event subtypes:

- commandbuttondown: Fires when a key mapped to a command is pressed while the application is in the foreground. Fires again each time the key auto-repeats.
- commandbuttonup: Fires when a key mapped to a command is released and the application is in the foreground.
- commandbuttonbgdown: Fires when a key mapped to a command is pressed while the application is in the background, and again on each auto-repeat.
- commandbuttonbgup: Fires when a command key is released while the application is in the background.

## How this event differs from raw keyboard events

In many cases, the relationship between raw keyboard events and Command Button events is one-to-one. But it's not always, which is the whole reason that the CommandButton event is exposed as a separate event from the raw keyboard event.

There are two main places where the two event types can differ.

The first is the fairly obvious one: most keys aren't mapped to commands in the user's settings, so most keys won't generate CommandButton events at all. We wanted Javascript to have access to all of the low-level keyboard events, for greater flexibility in customizing the program, so we had to provide Javascript events for all keys, whether mapped to commands or not. That's why the raw key events are there. We also wanted to simplify things for Javascript code that only cares about the abstract commands, which is why the CommandButton events are also there.

The second difference between raw key events and CommandButton events is more complex, and has to do with auto-repeat handling. At the raw hardware level, Windows generates auto-repeat events at fixed intervals, no matter how quickly or slowly the application wants to process the repeat events. Windows stores the repeats in a buffer until the application processes them. These timed repeat events are reflected in the raw keyboard events in Javascript. CommandButton events also can auto-repeat, but their auto-repeat timing is determined by PinballY, according to the rate at which PinballY wants to process the repeats. The simple timing scheme that Windows uses at the hardware level can lead to undesirable behavior when it's faster or slower than the program's natural processing speed for the keys. PinballY tries to be more responsive by synchronizing CommandButton repeat events to its on-screen animation timing.

In most cases, these differences shouldn't matter to Javascript code, because you'll just handle one or the other type of event depending on the effect you're trying to achieve. The differences would only matter if you were trying for some reason to correlate raw key events with the CommandButton events they lead to. If you're doing that, you just need to be sure not to assume that the events are perfectly correlated: that is, don't write code that depends upon one CommandButton event being generated for every raw key event.

## Properties

This event type has all of the standard event properties and methods (see the Event class), plus the following:

- background: true if the original key press happened while the program was in the background.
- command: a string with the name of the command assigned to the key in the user's option settings. This is one of the following:
  - "Coin1" = the first coin chute switch (usually the leftmost chute), sometimes wired to a "Coin In" button on the front panel
  - "Coin2" = the second coin chute switch (usually the middle chute, not typically present on a two-chute US coin door)
  - "Coin3" = the third coin chute switch (usually the right chute)
  - "Coin4" = the fourth coin chute switch (on a US coin door, typically wired to the dollar bill acceptor)
  - "CoinDoor" = the Coin Door button (usually assigned to the coin door switch in a pin cab, which either sends a keystroke each time the door switches between closed and open, or is held down while the door is open, depending on how the cabinet is wired)
  - "Exit" = the Exit button, which cancels the current menu, closes popups, etc; usually assigned to the Exit button on a pin cab
  - "ExitGame" = the Exit Game button, which terminates a running game; usually assigned to the Exit button on a pin cab
  - "FrameCounter" = toggles the on-screen frame counter on or off in the active window
  - "FullScreen" = toggles between full-screen and windowed mode in the active window
  - "Information" = shows the game information popup (the same display activated with the "Information" command in the main menu)
  - "Instructions" = shows the instruction card for the current game as a popup overlay
  - "Launch" = launch the current game without displaying the menu; usually assigned to the Launch Ball button on a pin cab
  - "Next" = the Next button, which switches to the next game, selects the next menu item, etc; usually assigned to the right flipper button on a pin cab
  - "NextPage" = the Next Page button, which advances to the next letter of the alphabet in the game wheel, advances to the next page of menu items, etc; usually assigned to the right MagnaSave button on a pin cab
  - "PauseGame" = brings PinballY to the foreground if it's currently in the background. When a game is running, this usually has the effect of pausing the game by deactivating its window.
  - "Prev" = the Previous button, which switches to the prior game, selects the previous menu item, etc; usually assigned to the left flipper button on a pin cab
  - "PrevPage" = the Previous Page button, which switches to the previous letter of the alphabet in the game wheel, scrolls up a page of menu items, etc; usually assigned to the left MagnaSave button on a pin cab
  - "RotateMonitor" = rotates the active window's interior graphics clockwise by 90°
  - "Select" = the Select button, which brings up the menu, selects the current menu item, etc; usually assigned to the Start button on a pin cab
  - "Service1" = the first service panel button, usually assigned to the "Escape/Cancel" button on the operator controls inside the coin door on a cabinet
  - "Service2" = the second service panel button, usually "-/Previous" on the operator controls
  - "Service3" = the third service panel button, usually "+/Next" on the operator controls
  - "Service4" = the fourth service panel button, usually "Enter/Select" on the operator controls
  - "Settings" = shows the Options dialog
- repeat: true if the key is an auto-repeat event while the key is being held down.