[Exposed=Window, SecureContext]
interface Gamepad {
+ attribute EventHandler onbuttondown;
+ attribute EventHandler onbuttonup;
+ attribute EventHandler onbuttonchange;
+ attribute EventHandler onaxischange;
+
readonly attribute DOMString id;
readonly attribute long index;
readonly attribute boolean connected;
@@ -208,6 +213,34 @@
An array containing the maximum logical value for each button.
+ -
+ onbuttondown attribute
+
+ -
+ {{Gamepad/onbuttondown}} is an [=event handler IDL attribute=] for the
+
buttondown event type.
+
+ -
+ onbuttonup attribute
+
+ -
+ {{Gamepad/onbuttonup}} is an [=event handler IDL attribute=] for the
+
buttonup event type.
+
+ -
+ onbuttonchange attribute
+
+ -
+ {{Gamepad/onbuttonchange}} is an [=event handler IDL attribute=] for the
+
buttonchange event type.
+
+ -
+ onaxischange attribute
+
+ -
+ {{Gamepad/onaxischange}} is an [=event handler IDL attribute=] for the
+
axischange event type.
+
-
id attribute
@@ -295,81 +328,6 @@
different values (or values in a different order).
- Receiving new input values
-
- When the system receives new input values from a gamepad, run the following steps:
-
-
- - Let |gamepad:Gamepad| be the {{Gamepad}} instance in |navigator:Navigator|.{{[[gamepads]]}} representing the gamepad.
-
- Let |axisValues:sequence<unsigned long>| be the gamepad's ordered array of logical axis input values.
-
- Let |buttonValues:sequence<unsigned long>| be the gamepad's ordered array of logical button input values.
-
- Queue a task (where?) to update gamepad state for |gamepad| with |axisValues| and |buttonValues|.
-
- To update gamepad state for |gamepad| with an ordered array of logical axis input values |axisValues:sequence<unsigned long>| and an ordered array of logical button input values |buttonValues:sequence<unsigned long>|, run the following steps:
-
- - Let |now:DOMHighResTimeStamp| be a {{DOMHighResTimeStamp}} representing the current time.
-
- Let |gamepadsStart:DOMHighResTimeStamp| be the |navigationStart:DOMHighResTimeStamp| attribute of the {{PerformanceTiming}} interface.
-
- Set |gamepad|.{{Gamepad/timestamp}} to |now| − |gamepadsStart|.
-
- Let |axisCount:long| be the length of |axisValues|.
-
- Initialize |rawAxisIndex:long| to be 0.
-
- While |rawAxisIndex| < |axisCount|:
-
- - Let |mappedIndex:long| be the value for key |rawAxisIndex| in |gamepad|.{{[[axisMapping]]}}.
-
- Let |logicalValue:unsigned long| be the value at index |rawAxisIndex| in |axisValues|.
-
- Let |logicalMinimum:unsigned long| be the value for key |rawAxisIndex| in |gamepad|.{{[[axisMinimums]]}}.
-
- Let |logicalMaximum:unsigned long| be the value for key |rawAxisIndex| in |gamepad|.{{[[axisMaximums]]}}.
-
- Let |normalizedValue:double| be 2 (|logicalValue| − |logicalMinimum|) / (|logicalMaximum| − |logicalMinimum|) − 1.
-
- Set the value at index |axisIndex| of |gamepad|.{{Gamepad/axes}} to |normalizedValue|.
-
- Increment |rawAxisIndex|.
-
- - Let |buttonCount:long| be the length of |buttonValues|.
-
- Initialize |rawButtonIndex:long| to be 0.
-
- While |rawButtonIndex| < |buttonCount|:
-
- - Let |mappedIndex:long| be the value for key |rawButtonIndex| in |gamepad|.{{[[buttonMapping]]}}.
-
- Let |logicalValue:unsigned long| be the value at index |rawButtonIndex| in |buttonValues|.
-
- Let |logicalMinimum:unsigned long| be the value for key |rawButtonIndex| in |gamepad|.{{[[buttonMinimums]]}}.
-
- Let |logicalMaximum:unsigned long| be the value for key |rawButtonIndex| in |gamepad|.{{[[buttonMaximums]]}}.
-
- Let |normalizedValue:double| be (|logicalValue| − |logicalMinimum|) / (|logicalMaximum| − |logicalMinimum|).
-
- Let |button:GamepadButton| be the {{GamepadButton}} object at index |mappedIndex| of |gamepad|.{{Gamepad/buttons}}.
-
- Set |button|.{{GamepadButton/value}} to |normalizedValue|.
-
- If the button has a digital switch to indicate a pure pressed or released state, set |button|.{{GamepadButton/pressed}} to `true` if the button is pressed or `false` if it is not pressed.
-
- Otherwise, set |button|.{{GamepadButton/pressed}} to `true` if the value is above the button press threshold or `false` if it is not above the threshold.
-
- - If the button is capable of detecting touch, set |button|.{{GamepadButton/touched}} to `true` if the button is currently being touched.
-
- Otherwise, set |button|.{{GamepadButton/touched}} to |button|.{{GamepadButton/pressed}}.
-
- - Increment |rawButtonIndex|.
-
- - If |navigator|.{{[[hasGamepadGesture]]}} is `false` and |gamepad| contains a gamepad user gesture:
-
- - Set |navigator|.{{[[hasGamepadGesture]]}} to `true`.
-
- For each |connectedGamepad:Gamepad| of |navigator|.{{[[gamepads]]}}:
-
- - If |connectedGamepad| is not `null`:
-
- - Set |connectedGamepad|.{{Gamepad/timestamp}} to |now| − |gamepadsStart|.
-
- [[=Fire an event=]] named `"gamepadconnected"` at |window:Window| using {{GamepadEvent}} with its {{GamepadEvent/gamepad}} attribute initialized to |connectedGamepad|.
-
-
-
-
-
- The user agent MUST provide methods for retrieving ordered arrays of axis inputs and button inputs for a gamepad such that there is a unique element in the axis array for each axis input and a unique element in the button array for each button input.
- If the system enumerates axis and button inputs in a consistent order, then the methods SHOULD provide the inputs in that order.
- Otherwise, the methods MAY use any consistent ordering.
-
-
- The user agent MUST provide methods for retrieving ordered arrays of minimum logical values and maximum logical values for each gamepad input.
- The ordering of these arrays MUST match the ordering of the ordered array of axis inputs and ordered array of button inputs.
-
-
- The user agent MUST provide methods for retrieving ordered arrays of logical axis input values and button input values.
- These arrays MUST contain the most recent values received from the gamepad for each button and axis input.
- The ordering of these arrays MUST match the ordering of the ordered array of axis inputs and ordered array of button inputs.
-
@@ -589,6 +547,168 @@
+
+
+ GamepadAxisEvent Interface
+
+
+ [Exposed=Window, SecureContext]
+
+ interface GamepadAxisEvent: Event {
+ constructor(DOMString type, GamepadAxisEventInit eventInitDict);
+ readonly attribute long gamepadIndex;
+ readonly attribute long axisIndex;
+ readonly attribute double axisSnapshot;
+ readonly attribute DOMHighResTimeStamp gamepadTimestamp;
+ };
+
+
+ -
+ gamepadIndex attribute
+
+ -
+ The {{Gamepad/index}} attribute of the {{Gamepad}} associated with this event.
+
+ -
+ axisIndex attribute
+
+ -
+ The index of the axis in the {{Gamepad/axes}} array.
+
+ -
+ axisSnapshot attribute
+
+ -
+ The axis value at the time when this event was created.
+
+ -
+ gamepadTimestamp attribute
+
+ -
+ The {{Gamepad/timestamp}} of the {{Gamepad}} associated with this event at the time when the event was created.
+
+
+
+
+ GamepadAxisEventInit dictionary
+
+
+ dictionary GamepadAxisEventInit : EventInit {
+ required long gamepadIndex;
+ required long axisIndex;
+ required double axisSnapshot;
+ required DOMHighResTimeStamp gamepadTimestamp;
+ };
+
+
+ -
+ gamepadIndex member
+
+ -
+ The gamepad index for the event.
+
+ -
+ axisIndex member
+
+ -
+ The button index for the event.
+
+ -
+ axisSnapshot member
+
+ -
+ A copy of the current button state.
+
+ -
+ gamepadTimestamp member
+
+ -
+ The gamepad timestamp for the event.
+
+
+
+
+
+
+ GamepadButtonEvent Interface
+
+
+ [Exposed=Window, SecureContext]
+
+ interface GamepadButtonEvent: Event {
+ constructor(DOMString type, GamepadButtonEventInit eventInitDict);
+ readonly attribute long gamepadIndex;
+ readonly attribute long buttonIndex;
+ readonly attribute GamepadButton buttonSnapshot;
+ readonly attribute DOMHighResTimeStamp gamepadTimestamp;
+ };
+
+
+ -
+ gamepadIndex attribute
+
+ -
+ The {{Gamepad/index}} attribute of the {{Gamepad}} associated with this event.
+
+ -
+ buttonIndex attribute
+
+ -
+ The index of the {{GamepadButton}} in the {{Gamepad/buttons}} array.
+
+ -
+ buttonSnapshot attribute
+
+ -
+ A copy of the {{GamepadButton}} at the time when this event was created.
+
+ -
+ gamepadTimestamp attribute
+
+ -
+ The {{Gamepad/timestamp}} of the {{Gamepad}} associated with this event at the time when the event was created.
+
+
+
+
+ GamepadButtonEventInit dictionary
+
+
+ dictionary GamepadButtonEventInit : EventInit {
+ required long gamepadIndex;
+ required long buttonIndex;
+ required GamepadButton buttonSnapshot;
+ required DOMHighResTimeStamp gamepadTimestamp;
+ };
+
+
+ -
+ gamepadIndex member
+
+ -
+ The gamepad index for the event.
+
+ -
+ buttonIndex member
+
+ -
+ The button index for the event.
+
+ -
+ buttonSnapshot member
+
+ -
+ A copy of the current button state.
+
+ -
+ gamepadTimestamp member
+
+ -
+ The gamepad timestamp for the event.
+
+
+
+
Remapping
@@ -1081,15 +1201,131 @@
-
- Other events
-
+ The axischange, buttondown, buttonup, and buttonchange events
+
+ When the system receives new input values from a gamepad, run the following steps:
+
+
+ - Let |gamepad:Gamepad| be the {{Gamepad}} instance in |navigator:Navigator|.{{[[gamepads]]}} representing the gamepad.
+
- Let |axisValues:sequence<unsigned long>| be the gamepad's ordered array of logical axis input values.
+
- Let |buttonValues:sequence<unsigned long>| be the gamepad's ordered array of logical button input values.
+
- Queue a task (where?) to update gamepad state for |gamepad| with |axisValues| and |buttonValues|.
+
+ To update gamepad state for |gamepad| with an ordered array of logical axis input values |axisValues:sequence<unsigned long>| and an ordered array of logical button input values |buttonValues:sequence<unsigned long>|, run the following steps:
+
+ - Initialize |oldGamepad:Gamepad?| to `null`.
+
- If the value at index |gamepad|.{{Gamepad/index}} of |navigator:Navigator|.{{[[gamepads]]}} is not `null`, then set |oldGamepad| to a copy of that {{Gamepad}}.
+
- Let |now:DOMHighResTimeStamp| be a {{DOMHighResTimeStamp}} representing the current time.
+
- Let |gamepadsStart:DOMHighResTimeStamp| be the |navigationStart:DOMHighResTimeStamp| attribute of the {{PerformanceTiming}} interface.
+
- Set |gamepad|.{{Gamepad/timestamp}} to |now| − |gamepadsStart|.
+
- Let |rawAxisCount:long| be the length of |axisValues|.
+
- Initialize |rawAxisIndex:long| to be 0.
+
- While |rawAxisIndex| < |rawAxisCount|:
+
+ - Let |mappedIndex:long| be the value for key |rawAxisIndex| in |gamepad|.{{[[axisMapping]]}}.
+
- Let |logicalValue:unsigned long| be the value at index |rawAxisIndex| in |axisValues|.
+
- Let |logicalMinimum:unsigned long| be the value for key |rawAxisIndex| in |gamepad|.{{[[axisMinimums]]}}.
+
- Let |logicalMaximum:unsigned long| be the value for key |rawAxisIndex| in |gamepad|.{{[[axisMaximums]]}}.
+
- Let |normalizedValue:double| be 2 (|logicalValue| − |logicalMinimum|) / (|logicalMaximum| − |logicalMinimum|) − 1.
+
- Set the value at index |axisIndex| of |gamepad|.{{Gamepad/axes}} to |normalizedValue|.
+
- Increment |rawAxisIndex|.
+
+ - Let |rawButtonCount:long| be the length of |buttonValues|.
+
- Initialize |rawButtonIndex:long| to be 0.
+
- While |rawButtonIndex| < |rawButtonCount|:
+
+ - Let |mappedIndex:long| be the value for key |rawButtonIndex| in |gamepad|.{{[[buttonMapping]]}}.
+
- Let |logicalValue:unsigned long| be the value at index |rawButtonIndex| in |buttonValues|.
+
- Let |logicalMinimum:unsigned long| be the value for key |rawButtonIndex| in |gamepad|.{{[[buttonMinimums]]}}.
+
- Let |logicalMaximum:unsigned long| be the value for key |rawButtonIndex| in |gamepad|.{{[[buttonMaximums]]}}.
+
- Let |normalizedValue:double| be (|logicalValue| − |logicalMinimum|) / (|logicalMaximum| − |logicalMinimum|).
+
- Let |button:GamepadButton| be the {{GamepadButton}} object at index |mappedIndex| of |gamepad|.{{Gamepad/buttons}}.
+
- Set |button|.{{GamepadButton/value}} to |normalizedValue|.
+
- If the button has a digital switch to indicate a pure pressed or released state, set |button|.{{GamepadButton/pressed}} to `true` if the button is pressed or `false` if it is not pressed.
+
+ Otherwise, set |button|.{{GamepadButton/pressed}} to `true` if the value is above the button press threshold or `false` if it is not above the threshold.
+
+ - If the button is capable of detecting touch, set |button|.{{GamepadButton/touched}} to `true` if the button is currently being touched.
+
+ Otherwise, set |button|.{{GamepadButton/touched}} to |button|.{{GamepadButton/pressed}}.
+
+ - Increment |rawButtonIndex|.
+
+ - If |navigator|.{{[[hasGamepadGesture]]}} is `false` and |gamepad| contains a gamepad user gesture:
+
+ - Set |navigator|.{{[[hasGamepadGesture]]}} to `true`.
+
- For each |connectedGamepad:Gamepad| of |navigator|.{{[[gamepads]]}}:
+
+ - If |connectedGamepad| is not `null`:
+
+ - Set |connectedGamepad|.{{Gamepad/timestamp}} to |now| − |gamepadsStart|.
+
- [[=Fire an event=]] named `"gamepadconnected"` at |window:Window| using {{GamepadEvent}} with its {{GamepadEvent/gamepad}} attribute initialized to |connectedGamepad|.
+
+
+
+ - If |navigator|.{{[[hasGamepadGesture]]}} is `false`, abort these steps.
+
- If |oldGamepad| is `null`, abort these steps.
+
- Let |axisCount:long| be the length of |gamepad|.{{Gamepad/axes}}.
+
- Initialize |axisIndex:long| to be 0.
+
- While |axisIndex| < |axisCount|:
+
+ - Let |oldValue:double| be the value at index |axisIndex| of |oldGamepad|.{{Gamepad/axes}}.
+
- Let |newValue:double| be the value at index |axisIndex| of |gamepad|.{{Gamepad/axes}}.
+
- If |oldValue| is not |newValue|:
+
+ - [=Fire an event=] named `"axischange"` at |gamepad| using {{GamepadAxisEvent}} with its {{GamepadAxisEvent/gamepadIndex}} attribute initialized to |gamepad|.{{Gamepad/index}}, its {{GamepadAxisEvent/axisIndex}} attribute initialized to |axisIndex|, its {{GamepadAxisEvent/axisSnapshot}} attribute initialized to |newValue|, and its {{GamepadAxisEvent/gamepadTimestamp}} attribute initialized to |now|.
+
+ - Increment |axisIndex|.
+
+ - Let |buttonCount:long| be the length of |gamepad|.{{Gamepad/buttons}}.
+
- Initialize |buttonIndex:long| to be 0.
+
- While |buttonIndex| < |buttonCount|:
+
+ - Let |oldButton:GamepadButton| be the {{GamepadButton}} at index |buttonIndex| of |oldGamepad|.{{Gamepad/buttons}}.
+
- Let |newButton:GamepadButton| be the {{GamepadButton}} at index |buttonIndex| of |gamepad|.{{Gamepad/buttons}}.
+
- If |oldButton|.{{GamepadButton/value}} is not |newButton|.{{GamepadButton/value}}, then:
+
+ - [=Fire an event=] named `"buttonchange"` at |gamepad| using {{GamepadButtonEvent}} with its {{GamepadButtonEvent/gamepadIndex}} attribute initialized to |gamepad|.{{Gamepad/index}}, its {{GamepadButtonEvent/buttonIndex}} attribute initialized to |buttonIndex|, its {{GamepadButtonEvent/buttonSnapshot}} attribute initialized to a copy of |newButton|, and its {{GamepadButtonEvent/gamepadTimestamp}} attribute initialized to |now|.
+
+ - If |oldButton|.{{GamepadButton/pressed}} is `false` and |newButton|.{{GamepadButton/pressed}} is `true`, then:
+
+ - [=Fire an event=] named `"buttondown"` at |gamepad| using {{GamepadButtonEvent}} with its {{GamepadButtonEvent/gamepadIndex}} attribute initialized to |gamepad|.{{Gamepad/index}}, its {{GamepadButtonEvent/buttonIndex}} attribute initialized to |buttonIndex|, its {{GamepadButtonEvent/buttonSnapshot}} attribute initialized to a copy of |newButton|, and its {{GamepadButtonEvent/gamepadTimestamp}} attribute initialized to |now|.
+
+ - If |oldButton|.{{GamepadButton/pressed}} is `true` and |newButton|.{{GamepadButton/pressed}} is `false`, then:
+
+ - [=Fire an event=] named `"buttonup"` at |gamepad| using {{GamepadButtonEvent}} with its {{GamepadButtonEvent/gamepadIndex}} attribute initialized to |gamepad|.{{Gamepad/index}}, its {{GamepadButtonEvent/buttonIndex}} attribute initialized to |buttonIndex|, its {{GamepadButtonEvent/buttonSnapshot}} attribute initialized to a copy of |newButton|, and its {{GamepadButtonEvent/gamepadTimestamp}} attribute initialized to |now|.
+
+ - Increment |buttonIndex|.
+
+
- More discussion needed, on whether to include or exclude axis and
- button changed events, and whether to roll them more together
- (gamepadchanged?), separate somewhat
- (gamepadaxischanged?), or separate by individual axis and
- button.
+ The user agent MUST provide methods for retrieving ordered arrays of axis inputs and button inputs for a gamepad such that there is a unique element in the axis array for each axis input and a unique element in the button array for each button input.
+ If the system enumerates axis and button inputs in a consistent order, then the methods SHOULD provide the inputs in that order.
+ Otherwise, the methods MAY use any consistent ordering.
+
+
+ The user agent MUST provide methods for retrieving ordered arrays of minimum logical values and maximum logical values for each gamepad input.
+ The ordering of these arrays MUST match the ordering of the ordered array of axis inputs and ordered array of button inputs.
+
+
+ The user agent MUST provide methods for retrieving ordered arrays of logical axis input values and button input values.
+ These arrays MUST contain the most recent values received from the gamepad for each button and axis input.
+ The ordering of these arrays MUST match the ordering of the ordered array of axis inputs and ordered array of button inputs.
+
+
+ User agents implementing this specification must provide a new DOM event named axischange.
+ The corresponding event MUST be of type GamepadAxisEvent and, if allowed to use the `"gamepad"` permission, MUST fire on the gamepad object.
+
+
+ User agents implementing this specification must provide new DOM events named buttondown, buttonup, and buttonchange.
+ The corresponding events MUST be of type GamepadButtonEvent and, if allowed to use the `"gamepad"` permission, MUST fire on the gamepad object.
+
+
+ Registration for and firing of these events MUST follow the usual behavior of DOM Events. [[DOM]]
+
+
+ A user agent MUST NOT dispatch these event types if the
+ environment settings object is a non-secure context.