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.