Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

spec gamepadbuttondown and gamepadbuttonup events (issue #4) #15

Closed
wants to merge 1 commit into from
Closed

spec gamepadbuttondown and gamepadbuttonup events (issue #4) #15

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
226 changes: 165 additions & 61 deletions index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -441,6 +441,171 @@ <h2><dfn>GamepadEvent</dfn> Interface</h2>
</dl>
</section>

<section>
<h2><dfn>GamepadButtonEvent</dfn> Interface</h2>
<dl title='[Constructor(GamepadButtonEventInit eventInitDict)] interface GamepadButtonEvent : Event'
class='idl'>
<dt>readonly attribute Gamepad gamepad</dt>

<dd>

The single gamepad attribute provides access to the associated
gamepad data for this event.

</dd>

<dt>readonly attribute GamepadButton button</dt>
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Firefox's implementation uses a button index instead of a GamepadButton:

gamepadbuttondown { target: Window → /, isTrusted: true, button: 1, gamepad: Gamepad, currentTarget: Window → /, eventPhase: 2, bubbles: false, cancelable: false, defaultPrevented: false, composed: false, timeStamp: 1530125797442210 }

I think it would be better to include the button index to make it easier for listeners to know which button was pressed. The GamepadButton can be accessed through the gamepad attribute once we know the index, but it's difficult to determine a button's index from a GamepadButton.


<dd>

The single button attribute provides access to the associated
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The event is asynchronous, but gamepad data is polled synchronously. This means that the button state in GamepadButton may not match the state as described by the event. For instance, for a gamepadbuttondown event, e.button.pressed may no longer be true if the button was released between the time the event was fired and when it was handled.

This proposal should be modified to indicate if the state in e.button is intended to preserve the button's state when the event was generated or if it should report the current button state.

button data for this event.

</dd>

</dl>
<dl title='dictionary GamepadButtonEventInit : EventInit' class='idl'>
<dt>required Gamepad gamepad</dt>
<dd>
The gamepad associated with this event.
</dd>
<dt>required GamepadButton button</dt>
<dd>
The button associated with this event.
</dd>
</dl>
</section>

<section>

<h3 id="event-gamepadconnected">The <dfn class="event">gamepadconnected</dfn> event</h3>

<p>
User agents implementing this specification must provide a new DOM
event, named <a><code>gamepadconnected</code></a>. The corresponding
event MUST be of type
<a href="#gamepadevent-interface"><code>GamepadEvent</code></a> and
MUST fire on the <code>window</code> object. Registration for and
firing of the <a><code>gamepadconnected</code></a> event MUST follow
the usual behavior of DOM4 Events. [[!DOM4]]
</p>

<p>
A <a>user agent</a> MUST dispatch this event type to indicate the
user has connected a gamepad. If a gamepad was already connected
when the page was loaded, the <a><code>gamepadconnected</code></a>
event SHOULD be dispatched when the user presses a button or moves
an axis.
</p>

</section>

<section>

<h3 id="event-gamepaddisconnected">The <dfn class="event">gamepaddisconnected</dfn> event</h3>

<p>
User agents implementing this specification must provide a new DOM
event, named <a><code>gamepaddisconnected</code></a>. The
corresponding event MUST be of type
<a href="#gamepadevent-interface"><code>GamepadEvent</code></a>
and MUST fire on the <code>window</code> object. Registration for
and firing of the <a><code>gamepaddisconnected</code></a> event MUST
follow the usual behavior of DOM4 Events. [[!DOM4]]
</p>

<p>
When a gamepad is disconnected from the <a>user agent</a>, if the
<a>user agent</a> has previously dispatched a
<a href="event-gamepadconnected"><code>gamepadconnected</code></a>
event for that gamepad to a window, a
<a><code>gamepaddisconnected</code></a> event MUST be dispatched to
that same window.
</p>

</section>

<section>

<h3 id="event-gamepadbuttondown">The <dfn class="event">gamepadbuttondown</dfn> event</h3>

<p>
User agents implementing this specification must provide a new DOM
event, named <a><code>gamepadbuttondown</code></a>. The
corresponding event MUST be of type
<a href="#gamepadevent-interface"><code>GamepadEvent</code></a>
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

GamepadButtonEvent

and MUST fire on the <code>window</code> object. Registration for
and firing of the <a><code>gamepadbuttondown</code></a> event MUST
follow the usual behavior of DOM4 Events. [[!DOM4]]
</p>

<p>
A <a>user agent</a> MUST dispatch this event type to indicate the
user has pressed down an individual button on a gamepad.
</p>

<p>
If a gamepad was already connected when the page was loaded but the
<a>user agent</a> has not yet dispatched a
<a href="#event-gamepadconnected"><code>gamepadconnected</code></a>
to a window, the
<a href="#event-gamepadconnected"><code>gamepadconnected</code></a>
event MUST be dispatched before dispatching the
<a><code>gamepadbuttondown</code></a> event to that same window.
</p>

<p>
The <a><code>gamepadbuttondown</code></a> event type must be
dispatched before the
<a href="#event-gamepadbuttonup"><code>gamepadbuttonup</code></a>
event associated with the same key.
</p>

</section>

<section>

<h3 id="event-gamepadbuttonup">The <dfn class="event">gamepadbuttonup</dfn> event</h3>

<p>
User agents implementing this specification must provide a new DOM
event, named <a><code>gamepadbuttonup</code></a>. The corresponding
event MUST be of type
<a href="#gamepadbuttonevent-interface"><code>GamepadButtonEvent</code></a>
and MUST fire on the <code>window</code> object. Registration for
and firing of the <a><code>gamepadbuttonup</code></a> event MUST
follow the usual behavior of DOM4 Events. [[!DOM4]]
</p>

<p>
A <a>user agent</a> MUST dispatch this event type to indicate the
user has released an individual button on a gamepad.
</p>

<p>
The <a><code>gamepadbuttonup</code></a> event type must be
dispatched after the
<a href="#event-gamepadbuttondown"><code>gamepadbuttondown</code></a>
event associated with the same key.
</p>

</section>

<section>

<h3>Other events</h3>

<p>

<i>More discussion is needed on whether to include events for axis
changes (e.g., <code>gamepadaxismove</code> for whenever the value of
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please also consider adding a gamepadbuttonmove event in order to better support gamepads that expose buttons with analog values.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

good call, thanks!

an axis changes, or <code>gamepadaxischange</code> for whenever the
active axis changes), etc.</i>
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What is an active axis?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

good call, will remove the part about active; that doesn't make sense. multiple axes could change. perhaps "axis changes" could be detected by higher-level abstractions (content libraries).


</p>

</section>

<section>
<h2>Remapping</h2>

Expand Down Expand Up @@ -530,67 +695,6 @@ <h2>Usage Examples</h2>

</section>

<section>

<h3 id="event-gamepadconnected">The <dfn class="event">gamepadconnected</dfn> event</h3>

<p>
User agents implementing this specification must provide a new DOM
event, named <code>gamepadconnected</code>. The corresponding event
MUST be of type <code>GamepadEvent</code> and MUST fire on the
<code>window</code> object. Registration for and firing of the
<code>gamepadconnected</code> event MUST follow the usual behavior
of DOM4 Events. [[!DOM4]]
</p>

<p>
A <a>user agent</a> MUST dispatch this event type to indicate the
user has connected a gamepad. If a gamepad was already connected
when the page was loaded, the <a>gamepadconnected</a> event SHOULD be
dispatched when the user presses a button or moves an axis.
</p>

</section>

<section>

<h3 id="event-gamepaddisconnected">The <dfn class="event">gamepaddisconnected</dfn> event</h3>

<p>
User agents implementing this specification must provide a new DOM
event, named <code>gamepaddisconnected</code>. The corresponding event
MUST be of type <code>GamepadEvent</code> and MUST fire on the
<code>window</code> object. Registration for and firing of the
<code>gamepaddisconnected</code> event MUST follow the usual behavior
of DOM4 Events. [[!DOM4]]
</p>

<p>
When a gamepad is disconnected from the <a>user agent</a>, if the
<a>user agent</a> has previously dispatched a
<a>gamepadconnected</a> event for that gamepad to a window, a
<a>gamepaddisconnected</a> event MUST be dispatched to that same
window.
</p>

</section>

<section>

<h3>Other events</h3>

<p>

<i>More discussion needed, on whether to include or exclude axis and button
changed events, and whether to roll them more together
(<code>gamepadchanged</code>?), separate somewhat
(<code>gamepadaxischanged</code>?), or separate by individual axis
and button.</i>

</p>

</section>

<section class='appendix informative'>
<h2>Acknowledgements</h2>
<p>
Expand Down