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:

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:

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: