JoystickButtonEvent
This is the Event subclass that represents joystick button events.
There are four joystick button event subtypes:
- joystickbuttondown: Fires when the user presses a joystick
button while PinballY is in the foreground. Also fires each time the
button "auto-repeats" while the user is holding it down.
- joystickbuttonup: Fires when the user releases a button
while the program is in the foreground.
- joystickbuttonbgdown: Fires when the user presses a joystick
button while PinballY is in the background (that is, while another
application's window is in front and has keyboard focus). Also fires
each time the button "auto-repeats" while the program is in the background.
- joystickbuttonbgup: Fires when the user releases a button
while the program is in the background.
Joystick button events are always fired on the mainWindow
object.
Properties
This event type has all of the standard event properties and methods
(see the Event class), plus the following:
- background: true if the application was in the background when
the event occurred, false if not. PinballY processes button presses
that occur while it's in the background so that it can monitor
"Exit Game" and "Pause Game" commands while a game is running.
- button: A number representing which button on the joystick
was pressed. Joystick buttons are usually numbered consecutively from
1 to the number of buttons on the unit, although that may be more of
a convention than a rule. The exact button numbering is determined
by the joystick's manufacturer, so it's arbitrary and peculiar to
each specific joystick make and model. The easiest way to figure
out which physical button on a device maps to which number in
the software events is to use a joystick viewer
(such as the Windows "Set up USB game controller" control panel),
pressing each physical button in turn to see which button number
lights up in the viewer. The button numbering is generally
fixed in the hardware for a given device, so the numbers that light
up in the control panel should match the numbers you see reported
in PinballY joystick events.
- repeat: true if this is an auto-repeat button event from
a button being held down, false if not. (Windows joystick devices
don't have a concept of "auto-repeat" the way that keyboards do,
but PinballY provides simulated auto-repeat to make joystick buttons
more consistent with keyboard behavior, so that pin cab buttons work
the same way in PinballY whether wired through a keyboard or joystick encoder
device. PinballY uses the system keyboard control panel settings to
simulate auto-repeat events for joysticks with the same timing as
for keyboard keys.)
- repeatCount: Indicates the number of times this button
press has been auto-repeated so far while the user is holding the
button down. This is 0 (zero) on the initial button press, 1 on
the first auto-repeat event, 2 on the second auto-repeat, etc.
Note that repeatCount is always 0 when repeat is
false, and non-zero when repeatCount is true, so in a way
this contains the same information as repeat, just with
the added detail of the number of repeats so far during the
current button press.
- unit: The "logical unit number" of the joystick that
generated the event, representing which joystick the button belongs to.
If multiple joysticks are attached to the system, this allows the
program to distinguish which one generated the event. The logical
unit number isn't anything Windows knows about; it's just an internal
ID assigned by PinballY to tell joysticks apart. This value can be
passed to mainWindow.getJoystickInfo()
to retrieve the device descriptor for the joystick.
Background events
As with keyboard events, the joystick
system uses separate event types for button presses that occur
when the program is in the foreground and background. The reasons
to separate the events are the same as for keyboard events; refer
to the key event section for details.