- From: jameshollyergoogle <notifications@github.com>
- Date: Tue, 04 Aug 2020 15:26:04 -0700
- To: w3c/pointerlock <pointerlock@noreply.github.com>
- Cc: Subscribed <subscribed@noreply.github.com>
- Message-ID: <w3c/pointerlock/pull/49/review/450863882@github.com>
@jameshollyergoogle commented on this pull request.
Domenic, thanks for all the reviews. I tried my best. I am sure there is still more to do. Let me know what you think.
> + error in changing state. They are named <dfn>pointerlockchange</dfn>
+ and <dfn>pointerlockerror</dfn>. If pointer lock is entered or exited
+ for any reason a <a>pointerlockchange</a> event must be sent.
+ </p>
+ <p>
+ <a>User agents</a> must deliver these events by <a data-lt=
+ "queue a task">queuing a task</a> to <a>fire an event</a> of the
+ appropriate name with its <code>bubbles</code> attribute [[DOM]] set to
+ false to the pointer lock <a>target</a> element's <a>node document</a>.
+ </p>
+ <p class="note">
+ Magnification software increases the size of content on the screen. It
+ uses the mouse to move the magnified point of focus around. When a
+ pointer lock is initiated, the magnification software needs to switch
+ to using the keyboard to move the magnified point of focus around
+ instead. When a pointerlockchange event is fired, web browsers
I think there is something more specific that you mean that I am missing? Are you saying to change the wording or should I also put it somewhere not in a note?
> + we will call the <dfn>target</dfn>, receives all mouse events and the cursor
+ is hidden.</p>
+ <p>
+ Once in the <a>Pointer Lock State</a> the <a>user agent</a> must fire all
+ relevant user generated {{MouseEvent}} events (for example:
+ `mousemove`, `mousedown`, `mouseup`, `click`, and `wheel`)
+ [[ui-events]] to the <a>target</a> of pointer lock, and not fire
+ mouse events to other elements. Events that require the concept of
+ a mouse cursor must not be dispatched (for example: `mouseover`,
+ `mouseout`, `drag`, and `drop`).
+ </p>
+ <p>
+ <dl data-dfn-for="PointerLockOptions" data-link-for=
+ "PointerLockOptions">
+ While in the <a>Pointer Lock State</a> if <a>unadjustedMovement</a> is
+ <code>true</code> the event coordinates must not be affected by the
I changed the text to explicitly call unadjustedMovement as a member of PointerLockOptions and removed the undefined option.
> + While in the <a>Pointer Lock State</a> if <a>unadjustedMovement</a> is
+ <code>true</code> the event coordinates must not be affected by the
+ underlying platform behaviors such as mouse acceleration. In other
+ words, UA must use the APIs provided by the underlying platform to
+ guaranteee getting the raw events. If <a>unadjustedMovement</a>
+ is <code>undefined</code> or <code>false</code> UA must rely on the
+ default behavior of the underlying platform regarding the mouse
+ acceleration.
+ </dl>
+ </p>
+ <p>
+ In the <a>Pointer Lock State</a> the system mouse cursor must be hidden.
+ Movement and button presses of the mouse must not cause the window
+ to lose focus.
+ </p>
+ <p>
done
> + If this value is set to `true`, then the pointer movements will
+ not be affected by the underlying platform modications such as
+ mouse accelaration.
+ </p>
+ </dd>
+ </dl>
+ </section>
+ <section>
+ <h3>
+ `"pointerlockchange"` and `"pointerlockerror"` Events
+ </h3>
+ <p>
+ Two events are used to communicate pointer lock state change or an
+ error in changing state. They are named <dfn>pointerlockchange</dfn>
+ and <dfn>pointerlockerror</dfn>. If pointer lock is entered or exited
+ for any reason a <a>pointerlockchange</a> event must be sent.
removed
> + </p>
+ </dd>
+ </dl>
+ </section>
+ <section>
+ <h3>
+ `"pointerlockchange"` and `"pointerlockerror"` Events
+ </h3>
+ <p>
+ Two events are used to communicate pointer lock state change or an
+ error in changing state. They are named <dfn>pointerlockchange</dfn>
+ and <dfn>pointerlockerror</dfn>. If pointer lock is entered or exited
+ for any reason a <a>pointerlockchange</a> event must be sent.
+ </p>
+ <p>
+ <a>User agents</a> must deliver these events by <a data-lt=
Remove the whole paragraph right? That makes section 3.3 consist of only 2 notes. Is that ok or maybe these notes should be moved to somewhere else? Maybe section 5?
> - relevant user generated {{MouseEvent}} events (for example:
- `mousemove`, `mousedown`, `mouseup`, `click`, and `wheel`)
- [[ui-events]] to the <a>target</a> of pointer lock, and not fire
- mouse events to other elements. Events that require the concept of
- a mouse cursor must not be dispatched (for example: `mouseover`,
- `mouseout`, `drag`, and `drop`).
- </p>
- <p>
- In the locked state the system mouse cursor must be hidden.
- Movement and button presses of the mouse must not cause the window
- to lose focus.
- </p>
- <p>
- Synthetic mouse events created by application script act the same
- regardless of lock state.
+ RequestPointerLock() will follow these steps
Done.
> - mouse events to other elements. Events that require the concept of
- a mouse cursor must not be dispatched (for example: `mouseover`,
- `mouseout`, `drag`, and `drop`).
- </p>
- <p>
- In the locked state the system mouse cursor must be hidden.
- Movement and button presses of the mouse must not cause the window
- to lose focus.
- </p>
- <p>
- Synthetic mouse events created by application script act the same
- regardless of lock state.
+ RequestPointerLock() will follow these steps
+ <ol>
+ <li>
+ If the the <a>target</a>'s
I changed it to use this's with the href. However, I don't completely understand why.
> - <p>
- In the locked state the system mouse cursor must be hidden.
- Movement and button presses of the mouse must not cause the window
- to lose focus.
- </p>
- <p>
- Synthetic mouse events created by application script act the same
- regardless of lock state.
+ RequestPointerLock() will follow these steps
+ <ol>
+ <li>
+ If the the <a>target</a>'s
+ <a>shadow-including root</a> is the <a>active document</a> of a
+ [=Document/browsing context=] which is (or has an <a>ancestor
+ browsing context</a> which is) in focus by a window which is in
+ focus by the operating system's window manager queue <a>pointerlockerror</a>
Done.
> + "{{WrongDocumentError}}" {{DOMException}}.
+ </li>
+ <li>
+ If the pointer is already locked by an element whose <a>shadow-including root</a> is a different
+ document queue <a>pointerlockerror</a> and <a href="https://heycam.github.io/webidl/#reject">reject</a>
+ the promise with a "{{InUseAttributeError}}" {{DOMException}}.
+ </li>
+ <li>
+ If the pointer is already locked by an element whose <a>shadow-including root</a> is a different
+ document queue <a>pointerlockerror</a> and <a href="https://heycam.github.io/webidl/#reject">reject</a>
+ the promise with a "{{InUseAttributeError}}" {{DOMException}}.
+ </li>
+ <li>
+ If any element (including this one), whose <a>shadow-including
+ root</a> is same as this element's <a>shadow-including root</a>, is
+ already locked (or pending lock) follow these steps:
Ok I tried to clean this up a bit. Let me know what you think.
> - </p>
- <p class="note">
- Magnification software increases the size of content on the screen. It
- uses the mouse to move the magnified point of focus around. When a
- pointer lock is initiated, the magnification software needs to switch
- to using the keyboard to move the magnified point of focus around
- instead. When a pointerlockchange event is fired, web browsers
- therefore need to make sure the event is communicated to assistive
- technologies like screen magnifiers.
- </p>
+ <section>
+ <h3>
+ The <dfn>Pointer Lock State</dfn> Definition
+ </h3>
+ <p><a>Pointer Lock State</a> is the state where a single DOM element, which
+ we will call the <dfn>target</dfn>, receives all mouse events and the cursor
Changed to state the user agent has the target and change the name to pointer-lock target.
> - <p>
- Synthetic mouse events created by application script act the same
- regardless of lock state.
+ RequestPointerLock() will follow these steps
+ <ol>
+ <li>
+ If the the <a>target</a>'s
+ <a>shadow-including root</a> is the <a>active document</a> of a
+ [=Document/browsing context=] which is (or has an <a>ancestor
+ browsing context</a> which is) in focus by a window which is in
+ focus by the operating system's window manager queue <a>pointerlockerror</a>
+ and <a href="https://heycam.github.io/webidl/#reject">reject</a> the promise with a
+ "{{WrongDocumentError}}" {{DOMException}}.
+ </li>
+ <li>
+ If the pointer is already locked by an element whose <a>shadow-including root</a> is a different
Done. Is it appropriate to link shadow-including root twice in one sentence or would one link be enough? I linked it twice.
> - regardless of lock state.
+ RequestPointerLock() will follow these steps
+ <ol>
+ <li>
+ If the the <a>target</a>'s
+ <a>shadow-including root</a> is the <a>active document</a> of a
+ [=Document/browsing context=] which is (or has an <a>ancestor
+ browsing context</a> which is) in focus by a window which is in
+ focus by the operating system's window manager queue <a>pointerlockerror</a>
+ and <a href="https://heycam.github.io/webidl/#reject">reject</a> the promise with a
+ "{{WrongDocumentError}}" {{DOMException}}.
+ </li>
+ <li>
+ If the pointer is already locked by an element whose <a>shadow-including root</a> is a different
+ document queue <a>pointerlockerror</a> and <a href="https://heycam.github.io/webidl/#reject">reject</a>
+ the promise with a "{{InUseAttributeError}}" {{DOMException}}.
I chose InvalidStateError(NotAllowedError is now used for requiring user gesture) and will update Chrome's implementation to match this before shipping.
> + <li>
+ If the the <a>target</a>'s
+ <a>shadow-including root</a> is the <a>active document</a> of a
+ [=Document/browsing context=] which is (or has an <a>ancestor
+ browsing context</a> which is) in focus by a window which is in
+ focus by the operating system's window manager queue <a>pointerlockerror</a>
+ and <a href="https://heycam.github.io/webidl/#reject">reject</a> the promise with a
+ "{{WrongDocumentError}}" {{DOMException}}.
+ </li>
+ <li>
+ If the pointer is already locked by an element whose <a>shadow-including root</a> is a different
+ document queue <a>pointerlockerror</a> and <a href="https://heycam.github.io/webidl/#reject">reject</a>
+ the promise with a "{{InUseAttributeError}}" {{DOMException}}.
+ </li>
+ <li>
+ If the pointer is already locked by an element whose <a>shadow-including root</a> is a different
Yea, looks like it. Removed.
> + If the pointer is already locked by an element whose <a>shadow-including root</a> is a different
+ document queue <a>pointerlockerror</a> and <a href="https://heycam.github.io/webidl/#reject">reject</a>
+ the promise with a "{{InUseAttributeError}}" {{DOMException}}.
+ </li>
+ <li>
+ If the pointer is already locked by an element whose <a>shadow-including root</a> is a different
+ document queue <a>pointerlockerror</a> and <a href="https://heycam.github.io/webidl/#reject">reject</a>
+ the promise with a "{{InUseAttributeError}}" {{DOMException}}.
+ </li>
+ <li>
+ If any element (including this one), whose <a>shadow-including
+ root</a> is same as this element's <a>shadow-including root</a>, is
+ already locked (or pending lock) follow these steps:
+ <ol>
+ <li>
+ If the <a>pointerLockOptions</a> have not changed the pointer lock <a>target</a>
That was on purpose. This is the success for changing of pointer lock as opposed to the success of acquiring pointer lock. It does not require a user gesture. In the implementation this branches off before checking the other pieces because it does not require the same checks. The NotSupportedError is kind of a duplicate in this substep but, I did not know how to separate this out.
> + </li>
+ <li>
+ If the options have changed and the new options are supported the pointer lock <a>target</a>
+ must be updated to this element, the new options must be used, a <a>pointerlockchange</a>
+ event sent, and the promise must <a>resolve</a>.
+ </li>
+ </ol>
+ </li>
+ <li>
+ If any element (including this one), whose <a>shadow-including
+ root</a> is same as this element's <a>shadow-including root</a>, is
+ already locked (or pending lock) the pointer lock <a>target</a>
+ must be updated to this element, a <a>pointerlockchange</a>
+ event sent and the promise must <a>Resolve</a>.
+ </li>
+ <li data-link-for="Document">
Oh cool I like that better too.
> + <li>
+ If the options have changed and the new options are supported the pointer lock <a>target</a>
+ must be updated to this element, the new options must be used, a <a>pointerlockchange</a>
+ event sent, and the promise must <a>resolve</a>.
+ </li>
+ </ol>
+ </li>
+ <li>
+ If any element (including this one), whose <a>shadow-including
+ root</a> is same as this element's <a>shadow-including root</a>, is
+ already locked (or pending lock) the pointer lock <a>target</a>
+ must be updated to this element, a <a>pointerlockchange</a>
+ event sent and the promise must <a>Resolve</a>.
+ </li>
+ <li data-link-for="Document">
+ If the request was not started from an <a>engagement gesture</a> and
That page is not the correct link. The engagement gesture is different from tracking user activation.
> + </li>
+ </ol>
+ </li>
+ <li>
+ If any element (including this one), whose <a>shadow-including
+ root</a> is same as this element's <a>shadow-including root</a>, is
+ already locked (or pending lock) the pointer lock <a>target</a>
+ must be updated to this element, a <a>pointerlockchange</a>
+ event sent and the promise must <a>Resolve</a>.
+ </li>
+ <li data-link-for="Document">
+ If the request was not started from an <a>engagement gesture</a> and
+ the Document has not previously released a successful Pointer Lock with
+ {{exitPointerLock()}} queue <a>pointerlockerror</a> and
+ <a href="https://heycam.github.io/webidl/#reject">reject</a> the promise
+ with a "{{ConstraintError}}" {{DOMException}}.
Changed.
> + <p>
+ Conversely, if pointer lock is exited via {{exitPointerLock()}}
+ no <a>engagement gesture</a> is required to reenter pointer lock.
+ This enables applications that frequently move between
+ interaction modes, and ones that may do so based on a timer or
+ remote network activity.
+ </p>
+ <p data-link-for="Element">
+ Pointer lock is commonly combined with fullscreen [[FULLSCREEN]],
+ and if an <a>engagement gesture</a> is used to enter fullscreen
+ it is sufficient for a subsequent {{requestPointerLock()}}.
+ </p>
+ </aside>
+ </li>
+ <li>
+ if the document object's
done.
> + sandboxing flag set</a> has the <a>sandboxed pointer lock browsing
+ context flag</a> set queue <a>pointerlockerror</a> and
+ <a href="https://heycam.github.io/webidl/#reject">reject</a> the
+ promise with a "{{SecurityError}}" {{DOMException}}.
+ </li>
+ <li>
+ <dl data-dfn-for="PointerLockOptions" data-link-for=
+ "PointerLockOptions">
+ If if <a>unadjustedMovement</a> is true and the platform does not
+ support <a>unadjustedMovement</a> queue <a>pointerlockerror</a> and
+ <a href="https://heycam.github.io/webidl/#reject">reject</a> the
+ promise with a "{{NotSupportedError}}" {{DOMException}}.
+ </dl>
+ <aside class="note" data-link-for="Document">
+ "{{NotSupportedError}}" {{DOMException}} should be reserved for
+ unsupported options in future iterations of this spec.
I added that text. We now have support coming out for all platforms except Android(which does not make any sense for this API anyway). Do you still think this is important?
> @@ -332,7 +454,7 @@ <h2>
</dt>
<dd>
<p>
- Initiates an exit from pointer lock state if currently locked to a
+ Initiates an exit from <a>pointer lock state</a> if currently locked to a
I changed this and did my best to define "exit pointer lock". I am sure you will have some comments on it though.
--
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/w3c/pointerlock/pull/49#pullrequestreview-450863882
Received on Tuesday, 4 August 2020 22:26:19 UTC