From 674234fd71ef7dc1e2f5442f4130dfc1f37617a1 Mon Sep 17 00:00:00 2001 From: Alvin Ji Date: Fri, 27 Oct 2023 00:39:38 +0000 Subject: [PATCH 01/11] squash --- index.html | 713 +++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 496 insertions(+), 217 deletions(-) diff --git a/index.html b/index.html index 237c3fd..876c21f 100644 --- a/index.html +++ b/index.html @@ -68,7 +68,10 @@ ], github: "w3c/pointerlock", group: "webapps", - xref: "web-platform" + xref: { + specs: ["uievents"], + profile: "web-platform", + }, }; @@ -145,125 +148,408 @@

- pointerlockchange and pointerlockerror Events + Glossary

-

- Two events are used to communicate pointer lock state change or an - error in changing state. They are named pointerlockchange and pointerlockerror. If pointer - lock is entered or exited for any reason a - {{Document/pointerlockchange}} event must be sent. -

-

- User agents must deliver these events by queuing a task to fire an event of the - appropriate name with its bubbles attribute [[DOM]] set to - false to the pointer lock target element's [=Node/node - document=]. -

-

- 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. -

+
+
+ Engagement gesture +
+
+ An event generated by the user agent as a result of user interaction + processed by the user agent to interact with the page. e.g. `click`, + but not `mousemove`. Engagement gestures are any events included in + the definition of being triggered by [=user activation=] with the + addition of `keypress` and `keyup`. Note that operating system level + accessibility and internationalization features may intercept + gestures before the user agent processes them for interaction with a + page. E.g. multiple key press codes used to enter an extended + international character. +
+
+
+
+

+ Pointer Lock and Interfaces +

+
+

+ The pointer lock state definition +

+

+ The [=pointer lock state=] is the state where a single DOM element, + which we will call the pointer-lock target, receives all + mouse events and the cursor is hidden. +

+

+ Once in the [=pointer lock state=] the [=user agent=] has a + [=pointer-lock target=], a pointer-lock options, which is + a {{PointerLockOptions}} and a cursor position which is a + pair of numbers representing the location of the system mouse cursor + when the Pointer Lock State was entered (the same location that is + reported in `screenX`, `screenY`). The [=pointer-lock target=] must + receive all relevant user generated {{MouseEvent}} events: namely, + all user-generated `mousemove`, `mousedown`, `mouseup`, `click`, + `dblclick`, `auxclick`, and `wheel` [[ui-events]]. No other elements + may receive these events while in [=pointer lock state=]. There will + be no dispatching of events that require the concept of a mouse + cursor: namely, `mouseenter`, `mouseleave`, `mouseover`, `mouseout`, + `drag`, and `drop`. +

+

+ While in the [=pointer lock state=] if the [=pointer-lock options=]' + {{PointerLockOptions/unadjustedMovement}} member is `true` 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 guarantee getting the raw + events. If the {{PointerLockOptions}}' + {{PointerLockOptions/unadjustedMovement}} member is `false` UA must + rely on the default behavior of the underlying platform regarding the + mouse acceleration. +

+

+ In the [=pointer lock state=] the system mouse cursor must be hidden. + Movement and button presses of the mouse must not cause the window to + lose focus. +

+

+ Synthetic mouse events created by application script act the same + regardless of lock state. +

+
+
+

+ `PointerLockOptions` dictionary +

+ 
+          dictionary PointerLockOptions {
+            boolean unadjustedMovement = false;
+          };
+
+
+
+ PointerLockOptions dictionary +
+
+

+ The options dictionary to customize how the pointer behaves in + the locked mode. +

+
+
+ unadjustedMovement member +
+
+

+ If this value is set to `true`, then the pointer movements will + not be affected by the underlying platform modications such as + mouse accelaration. +

+
+
+
+
+

+ `pointerlockchange` and `pointerlockerror` Events +

+

+ Two events are used to communicate pointer lock state change or an + error in changing state. They are named pointerlockchange + and pointerlockerror. If pointer lock is entered or exited + for any reason a {{Document/pointerlockchange}} event must be sent. +

+

+ The [=user agents=] must deliver these events by queuing a task to [=fire an event=] of the + appropriate name with its `bubbles` attribute [[DOM]] set to false to + the pointer lock [=Event/target=] element's [=Node/node document=]. +

+

+ 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. +

+
+
+

+ Exit Pointer Lock +

+

+ The process of exiting pointer lock, given an element, is as follows: +

+
    +
  1. The system mouse cursor must be displayed again and positioned at + [=cursor position=] +
    2. +
  2. [=Queue an element task=], given this element, on the [=user + interaction task source=] to do the following: +
      +
    1. [=Fire an event=] named {{pointerlockchange}} at the given + element's [=Node/node document=] +
      2. +
    +
    3. +
  3. Exit the [=pointer lock state=] by setting [=pointer-lock + target=], [=pointer-lock options=], and [=cursor position=] to null. +
    4. +
+

Extensions to the `Element` Interface

- The Element interface is extended to provide the ability to - request the the pointer be locked. + The {{Element}} interface is extended to provide the ability to request + the pointer be locked. 

         partial interface Element {
-          undefined requestPointerLock();
+          Promise<undefined> requestPointerLock(optional PointerLockOptions options = {});
         };
+ 
+        const lock_element = document.getElementById("lock_element");
+        const lock_button = document.getElementById("lock");
+        lock_button.addEventListener("click", async (event) => {
+            try {
+                await lock_element.requestPointerLock({ unadjustedMovement: true });
+                console.log("successfully locked!");
+            } catch (e) {
+                console.log("lock failed with error: ", e);
+            }
+        });
+
- requestPointerLock() method + requestPointerLock({{PointerLockOptions}} options) method

- Requests that the pointer be locked to a DOM element - target. The user agent determines if pointer lock - state will be entered, and upon lock state change or error MUST - send either a {{Document/pointerlockchange}} or - {{Document/pointerlockerror}} event respectively. -

-

- Pointer lock MUST fail if the document object's [=Document/active - sandboxing flag set=] has the sandboxed pointer lock browsing - context flag set. -

-

- Pointer lock MUST fail unless the target's - shadow-including root is the active document of a - [=Document/browsing context=] which is (or has an ancestor - browsing context which is) in focus by a window which is in - focus by the operating system's window manager. The target - element and its [=Document/browsing context=] need not be in focus. -

-

- Pointer lock is a transient activation-gated API, therefore - a {{requestPointerLock()}} call MUST fail if the relevant global - object of [=this=] does not have transient activation. - This prevents locking upon initial navigation or re-acquiring lock - without user's attention. -

-

- A {{requestPointerLock()}} call immediately after the default - unlock gesture MUST fail even when transient activation - is available, to prevent malicious sites from acquiring an - unescapable locked state through repeated lock attempts. On the - other hand, a {{requestPointerLock()}} call immediately after a - programmatic lock exit (through a {{Document/exitPointerLock()}} - call) MUST succeed when transient activation is available, - to enable applications to move frequently between interaction - modes, possibly through a timer or remote network activity. -

- -

- If any element (including this one), whose shadow-including - root is same as this element's shadow-including root, is - already locked (or pending lock) the pointer lock target - must be updated to this element and a - {{Document/pointerlockchange}} event sent. -

-

- If any element, whose shadow-including root is a different - document, is already locked the request must fail and a - {{Document/pointerlockerror}} event be sent. -

-

- Once in the locked state the user agent must fire all - relevant user generated {{MouseEvent}} events (for example: - `mousemove`, `mousedown`, `mouseup`, `click`, and `wheel`) - [[ui-events]] to the target 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`). -

-

- 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. -

-

- Synthetic mouse events created by application script act the same - regardless of lock state. + When requestPointerLock() invoked, perform the following + steps:

+
    +
  1. Let |promise:Promise| be [=a new promise=]. +
    2. +
  2. When a window is in focus, if the [=this=]'s [=shadow-including + root=] is the [=navigable/active document=] of a [=Document/browsing + context=] (or has an [=tree/ancestor=] [=browsing context=]) which is not in + focus: +
      +
    1. [=Queue an element task=] on the [=user interaction task + source=], given [=this=], to perform the following steps: +
        +
      1. [=Fire an event=] named {{pointerlockerror}} at + [=this=]'s [=Node/node document=]. +
        2. +
      2. [=Reject=] |promise| with a + {{"WrongDocumentError"}} {{DOMException}}. +
        3. +
      +
      2. +
    2. Return promise. +
      3. +
    +
    3. +
  3. If the user agent's [=pointer-lock target=] is an element whose + [=shadow-including root=] is not equal to [=this=]'s + [=shadow-including root=], then: +
      +
    1. [=Queue an element task=] on the [=user interaction task + source=], given this, to perform the following steps: +
        +
      1. [=Fire an event=] named {{pointerlockerror}} at + [=this=]'s [=Node/node document=]. +
        2. +
      2. [=Reject=] promise with a + "{{InvalidStateError}}" {{DOMException}}. +
        3. +
      +
      2. +
    2. Return promise. +
      3. +
    +
    4. +
  4. If the user agent's [=pointer-lock target=]'s + [=shadow-including root=] is equal to [=this=]'s [=shadow-including + root=], then: +
      +
    1. If [=options=] are equivalent to the current [=pointer-lock + options=] +
        +
      1. Set [=pointer-lock target=] to [=this=] +
        2. +
      2. [=Queue an element task=] on the [=user interaction + task source=], given this, to perform the following steps: +
          +
        1. [=Fire an event=] named {{pointerlockchange}} at + [=this=]'s [=Node/node document=]. +
          2. +
        2. [=Resolve=] the promise. +
          3. +
        +
        3. +
      +
      2. +
    2. If [=options=] are not equivalent to the user agent's + current [=pointer-lock options=] and [=options=] are not + supported: +
        +
      1. [=Queue an element task=] on the [=user interaction + task source=], given this, to perform the following steps: +
          +
        1. [=Reject=] promise with a + "{{NotSupportedError}}" {{DOMException}}. +
          2. +
        +
        2. +
      2. Return promise. +
        3. +
      +
      3. +
    3. If [=options=] are not equivalent to the current + [=pointer-lock options=] and [=options=] are supported then + perform the following steps +
        +
      1. Update the user agent's [=pointer-lock target=] to this + element. +
        2. +
      2. Update the user agent's [=pointer-lock options=] to + [=options=] +
        3. +
      3. [=Queue an element task=] on the [=user interaction + task source=], given this, to perform the following steps: +
          +
        1. [=Fire an event=] named {{pointerlockchange}} at + [=this=]'s [=Node/node document=]. +
          2. +
        2. The promise must be resolved. +
          3. +
        +
        4. +
      4. Return promise. +
        5. +
      +
      4. +
    +
    5. +
  5. If the request was not started from an [=engagement gesture=] + and the {{Document}} has not previously released a successful Pointer + Lock with {{Document/exitPointerLock()}}: +
      +
    1. [=Queue an element task=] on the [=user interaction task + source=], given this, to perform the following steps: +
        +
      1. [=Fire an event=] named {{pointerlockerror}} at + [=this=]'s [=Node/node document=]. +
        2. +
      2. [=Reject=] promise with a + "{{NotAllowedError}}" {{DOMException}}. +
        3. +
      +
      2. +
    2. Return promise. +
      3. +
    + +
    6. +
  6. If [=this=]'s [=Node/node document=]'s [=active sandboxing + flag set=] has the [=sandboxed pointer lock browsing context + flag=] set: +
      +
    1. [=Queue an element task=] on the [=user interaction task + source=], given this, to perform the following steps: +
        +
      1. [=Fire an event=] named {{pointerlockerror}} at + [=this=]'s [=Node/node document=]. +
        2. +
      2. [=Reject=] promise with a + "{{SecurityError}}" {{DOMException}}. +
        3. +
      +
      2. +
    2. Return promise. +
      3. +
    +
    7. +
  7. If [=options=]["{{PointerLockOptions/unadjustedMovement}}"] is + true and the platform does not support + {{PointerLockOptions/unadjustedMovement}}: +
      +
    1. [=Queue an element task=] on the [=user interaction task + source=], given this, to perform the following steps: +
        +
      1. [=Fire an event=] named {{pointerlockerror}} at + [=this=]'s [=Node/node document=]. +
        2. +
      2. [=Reject=] promise with a + "{{NotSupportedError}}" {{DOMException}}. +
        3. +
      +
      2. +
    2. Return promise. +
      3. +
    + +
    8. +
  8. If none of the above errors have occured +
      +
    1. Enter [=pointer lock state=] by performing the following: +
        +
      1. Set the user agent's [=pointer-lock target=] to + [=this=]. +
        2. +
      2. Set the user agent's [=cursor position=] to the current + system mouse location. +
        3. +
      3. Set the [=pointer-lock options=] to [=options=]. +
        4. +
      +
      2. +
    2. [=Queue an element task=] on the [=user interaction task + source=], given this, to perform the following steps: +
        +
      1. [=Fire an event=] named {{pointerlockchange}} at + [=this=]'s [=Node/node document=]. +
        2. +
      2. [=Resolve=] the promise. +
        3. +
      +
      3. +
    +
    9. +
  9. Return promise. +
    10. +
@@ -284,7 +570,7 @@

- An event handler idl attribute for + An [=event handler idl attribute=] for {{Document/pointerlockchange}} events.

@@ -293,7 +579,7 @@

- An event handler idl attribute for + An [=event handler idl attribute=] for {{Document/pointerlockerror}} events.

@@ -301,18 +587,16 @@

exitPointerLock() method
-

- Initiates an exit from pointer lock state if currently locked to a - target whose shadow-including root is this document, and - sends a {{Document/pointerlockchange}} event when the lock state - has been exited. -

-

- The system mouse cursor must be displayed again and positioned at - the same location that it was when pointer lock was entered (the - same location that is reported in screenX, - screenY, when the pointer is locked). -

+
    +
  1. If the user agent's pointer-lock target is null, then return. +
    2. +
  2. If [=pointer-lock target=]'s [=shadow-including root=]is not + equal to [=this=]'s [=Node/node document=], return. +
    3. +
  3. [=Exit pointer lock=] with the user agent's [=pointer-lock + target=]. +
    4. +
@@ -322,7 +606,7 @@ 

         partial interface mixin DocumentOrShadowRoot {
-          readonly attribute Element ? pointerLockElement;
+          readonly attribute Element? pointerLockElement;
         };
@@ -331,10 +615,10 @@

- While the pointer is locked, returns the result of - retargeting the element, which is the target for mouse - events, against [=this=] element if the result and [=this=] element - are in the same tree, otherwise returns null. + While the pointer is locked, returns the result of [=retargeting=] + the element, which is the target for mouse events, against [=this=] + element if the result and [=this=] element are in the same tree, + otherwise returns null.

Returns null if lock is pending or if pointer is unlocked. @@ -354,18 +638,15 @@

</body>

- Note: the example uses fictional shadow-root element - to denote a [=Element/shadow root=] instance. + Note: the example uses fictional `shadow-root` element to denote a + [=Element/shadow root=] instance.

- If #canvas1 is the target, - document.pointerLockElement returns - #host1, and root1.pointerLockElement - returns #canvas1. The result of retargeting - #canvas1 against #root2 is - #host1, but as #host1 is not in the same - tree as #root2, null will be returned for - root2.pointerLockElement. + If `#canvas1` is the target, `document.pointerLockElement` returns + `#host1`, and `root1.pointerLockElement` returns `#canvas1`. The + result of [=retargeting=] `#canvas1` against `#root2` is `#host1`, + but as `#host1` is not in the same tree as `#root2`, null will be + returned for `root2.pointerLockElement`.

@@ -390,63 +671,60 @@

- The attributes {{movementX}} {{movementY}} must provide the change - in position of the pointer, as if the values of - screenX, screenY, were stored between two - subsequent mousemove events eNow and - ePrevious and the difference taken movementX = - eNow.screenX-ePrevious.screenX. + The attributes {{movementX}} and {{movementY}} must provide the + change in position of the pointer, as if the values of `screenX`, + `screenY`, were stored between two subsequent `mousemove` events + `eNow` and `ePrevious` and the difference taken `movementX = + eNow.screenX - ePrevious.screenX`.

- {{movementX}}/{{movementY}} must be zero for all mouse events - except mousemove. All motion data must be delivered - via mousemove events such that between any two mouse - events earlierEvent and currentEvent the - value of currentEvent.screenX-earlierEvent.screenX is - equivalent to the sum of all {{movementX}} {{movementY}}/code> - events after earlierEvent, with the exception of when - screenX can not be updated because the pointer is clipped by the - user agent screen boundaries. + {{movementX}} and {{movementY}} must be zero for all mouse events + except `mousemove`. All motion data must be delivered via + `mousemove` events such that between any two mouse events + `earlierEvent` and `currentEvent` the value of + `currentEvent.screenX - earlierEvent.screenX` is equivalent to the + sum of all {{movementX}} in the events after `earlierEvent`, with + the exception of when screenX can not be updated because the + pointer is clipped by the [=user agent=] screen boundaries.

- {{movementX}}/{{movementY}} must be updated regardless of pointer - lock state. + {{movementX}} and {{movementY}} must be updated regardless of + pointer lock state.

- When unlocked, the system cursor can exit and re-enter the user - agent window. If it does so and the user agent was not - the target of operating system mouse move events then the most - recent pointer position will be unknown to the user agent - and {{movementX}}/{{movementY}} can not be computed and must be set + When unlocked, the system cursor can exit and re-enter the [=user + agent=] window. If it does so and the [=user agent=] was not the + target of operating system mouse move events then the most recent + pointer position will be unknown to the [=user agent=] and + {{movementX}} / {{movementY}} can not be computed and must be set to zero.

- When pointer lock is enabled clientX, - clientY, screenX, and - screenY must hold constant values as if the pointer - did not move at all once pointer lock was entered. But - {{movementX}}/{{movementY}} must continue to provide the change in - position of the pointer as when the pointer is unlocked. There will - be no limit to {{movementX}}/{{movementY}} values if the mouse is + When pointer lock is enabled `clientX`, `clientY`, `screenX`, and + `screenY` must hold constant values as if the pointer did not move + at all once pointer lock was entered. But {{movementX}} and + {{movementY}} must continue to provide the change in position of + the pointer as when the pointer is unlocked. There will be no limit + to {{movementX}} and {{movementY}} values if the mouse is continuously moved in a single direction. The concept of the mouse cursor will have been removed, and it will not move off the window or be clamped by a screen edge.

- The un-initialized value of {{movementX}}/{{movementY}} must be - 0. + The un-initialized value of {{movementX}} and {{movementY}} must be + `0`.

Large movement values must not appear in situations when mouse input is interupted, such as the mouse cursor leaving the window - and then re-entering at another location. If a User agent + and then re-entering at another location. If a [=user agent=] experiences a gap in receiving mouse input data from the operating - system then the next generated mousemove event must - have {{movementX}}/{{movementY}} set to 0. These gaps - may appear for example when the User agent receives a mouse - leaving event at the window system API. As an exception mouse - capture may allow the User agent to continue receiving mouse - events when the cursor moves outside the window. + system then the next generated `mousemove` event must have + {{movementX}} and {{movementY}} set to `0`. These gaps may appear + for example when the [=user agent=] receives a mouse leaving event + at the window system API. As an exception mouse capture may allow + the [=user agent=] to continue receiving mouse events when the + cursor moves outside the window.

@@ -481,29 +759,30 @@

A default unlock gesture must always be available that will - exit pointer lock. + [=exit pointer lock=] with the [=user agent=]'s [=pointer-lock + target=].

- Pointer lock must be exited if the target becomes disconnected, or the user - agent, window, or tab loses focus. Moving focus between elements of - active documents, including between [=Document/browsing - contexts=] , does not exit pointer lock. E.g. using the keyboard to + Pointer lock must be exited if the [=pointer-lock target=] becomes disconnected, or the [=user agent=], + window, or tab loses focus. Moving focus between elements of + [=navigable/active document=], including between [=Document/browsing + contexts=] , does not [=exit pointer lock=]. E.g. using the keyboard to move focus between contents of frames or iframes will not exit.

Pointer lock must not be exited when fullscreen [[FULLSCREEN]] is entered or exited unless the pointer is required to enable interaction - with the user agent graphical user interface, the default - unlock gesture was used to exit both fullscreen and pointer lock, - or window or tab focus was lost. + with the [=user agent=] graphical user interface, the [=default unlock + gesture=] was used to exit both fullscreen and pointer lock, or window + or tab focus was lost.

@@ -586,7 +865,7 @@

interact with DOM. E.g. the following code should permit a custom cursor to send click events while the pointer is locked:

- 
+        
             document.addEventListener("click", function (e) {
               if (e._isSynthetic)
                 return;
@@ -606,10 +885,10 @@ 

             });
         

         

-          Note that synthetic clicks may not be permitted by a user
-          agent to produce the same default action as a non-synthetic
-          click. However, application handlers can still take action and
-          provide user interface with existing HTML & DOM mechanisms.
+          Note that synthetic clicks may not be permitted by a [=user agent=]
+          to produce the same default action as a non-synthetic click. However,
+          application handlers can still take action and provide user interface
+          with existing HTML & DOM mechanisms.

@@ -637,9 +916,9 @@

Games that use pointer lock may desire a traditional UI and system cursor while players prepare in a game lobby. Games usually start after a short timer when all players are ready. Ideally the game - could then switch to pointer lock mode without a user - activation. Players should be able to seamlessly move from the - game lobby into game navigation. + could then switch to pointer lock mode without a [=user activation=]. + Players should be able to seamlessly move from the game lobby into + game navigation.

@@ -665,50 +944,50 @@

  • User actions may be misdirected to elements the user did not intend to interact with.
    • -
  • Pointer Lock will remove the ability of a user to interact with - user agent and operating system controls +
  • Pointer Lock will remove the ability of a user to interact with [= + user agent=] and operating system controls
  • Pointer Lock can be called repeated by script after user exits pointer lock, blocking user from meaningful progress.
    • -
  • Full screen exit instructions are displayed in some user - agents when the pointer is moved to the top of the screen. During - pointer lock that gesture is not possible. +
  • Full screen exit instructions are displayed in some [=user agent=]s + when the pointer is moved to the top of the screen. During pointer lock + that gesture is not possible.

    • Responses:

      -
    • - User agents may limit what security origins may lock the - pointer. +
    • The [=user agents=] may limit what security origins may lock the + pointer.
      • -
    • - User agents may prompt for confirmation before locking, this - preference may be saved as a content setting. +
    • The [=user agents=] may prompt for confirmation before locking, + this preference may be saved as a content setting.
      • -
    • Escape will always be provided by a default unlock gesture, +
    • Escape will always be provided by a [=default unlock gesture=], e.g. Esc key.
    • Persistent display of escape instructions can be provided.
      • -
    • Repeated escapes of pointer lock can signal user agent to - not re-lock the pointer without more specific user action, e.g. similar - to how Chrome suppresses repeated alert() calls. +
    • Repeated escapes of pointer lock can signal [=user agent=] to not + re-lock the pointer without more specific user action, e.g. similar to + how Chrome suppresses repeated alert() calls.
    • Changing to new tabs, windows, or any other action that causes a - page to lose focus will exit pointer lock. + page to lose focus will [=exit pointer lock=] with the [=user agent=]'s + [=pointer-lock target=].
    • Pointer lock can only be engaged when the window is in focus in the - user agent and operating system. + [=user agent=] and operating system.

    Recommendations:

      -
    • Esc key should exit pointer lock. +
    • Esc key should [=exit pointer lock=] with the user agent's + [=pointer-lock target=].
    • Preferences per sub-domain can be used to allow or block pointer lock, similar to pop-up, geolocation, and fullscreen. @@ -718,12 +997,12 @@

      Pointer lock is a required user interaction mode for certain application types, but carries a usability concern if maliciously used. An attacker could remove the ability for a user to control their mouse - cursor on their system. User agents will prevent this by always - providing a mechanism to exit pointer lock, by informing the user of - how, and by limiting how pointer lock can be entered. + cursor on their system. [=user agents=] will prevent this by always + providing a mechanism to [=exit pointer lock=], by informing the user + of how, and by limiting how pointer lock can be entered.

      - User agents will determine their own appropriate policies, which + [=user agents=] will determine their own appropriate policies, which may be specialized per device or differ based on user options.

    @@ -777,8 +1056,8 @@

    When the pointer is locked 'wheel' events should be sent to the - pointer lock target element just as 'mousemove' events are. - There is a naming conflict with .deltaX/Y/Z as defined in DOM 3 'wheel' event.

    @@ -812,10 +1091,10 @@

    movement data are provided in. This specification defines .movementX/Y precisely as the same values that could be recorded when the mouse is not under lock by changes in .screenX/Y. Implementations - across multiple user agents and operating systems will easily - be able to meet that requirement and provide application developers - and users with a consistent experience. Further, users are expected - to have already configured the full system of hardware input and + across multiple [=user agents=] and operating systems will easily be + able to meet that requirement and provide application developers and + users with a consistent experience. Further, users are expected to + have already configured the full system of hardware input and operating system options resulting in a comfortable control the system mouse cursor. By specifying .movementX/Y in the same units mouse lock API applications will be instantly usable to all users From 52893f015bb9505c3268d2e5702153cc30473a1f Mon Sep 17 00:00:00 2001 From: Alvin Ji Date: Tue, 19 Dec 2023 02:32:10 +0000 Subject: [PATCH 02/11] format correction and polishment --- index.html | 91 +++++++++++++++++++++++++++--------------------------- 1 file changed, 46 insertions(+), 45 deletions(-) diff --git a/index.html b/index.html index 876c21f..6b6b740 100644 --- a/index.html +++ b/index.html @@ -186,30 +186,31 @@

    a {{PointerLockOptions}} and a cursor position which is a pair of numbers representing the location of the system mouse cursor when the Pointer Lock State was entered (the same location that is - reported in `screenX`, `screenY`). The [=pointer-lock target=] must - receive all relevant user generated {{MouseEvent}} events: namely, + reported in `screenX`, `screenY`). The [=pointer-lock target=] + receives all relevant user generated {{MouseEvent}} events: namely, all user-generated `mousemove`, `mousedown`, `mouseup`, `click`, `dblclick`, `auxclick`, and `wheel` [[ui-events]]. No other elements - may receive these events while in [=pointer lock state=]. There will - be no dispatching of events that require the concept of a mouse - cursor: namely, `mouseenter`, `mouseleave`, `mouseover`, `mouseout`, - `drag`, and `drop`. + receive these events while in [=pointer lock state=]. There will be + no dispatching of events that require the concept of a mouse cursor: + namely, `mouseenter`, `mouseleave`, `mouseover`, `mouseout`, `drag`, + and `drop`.

    While in the [=pointer lock state=] if the [=pointer-lock options=]' {{PointerLockOptions/unadjustedMovement}} member is `true` 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 guarantee getting the raw - events. If the {{PointerLockOptions}}' - {{PointerLockOptions/unadjustedMovement}} member is `false` UA must - rely on the default behavior of the underlying platform regarding the - mouse acceleration. + coordinates shall not be affected by the underlying platform + behaviors such as mouse acceleration. In other words, the user agent + uses the APIs provided by the underlying platform to guarantee + getting the raw events. If the {{PointerLockOptions}}' + {{PointerLockOptions/unadjustedMovement}} member is `false` The user + agent relies on the default behavior of the underlying platform + regarding the mouse acceleration.

    - In the [=pointer lock state=] the system mouse cursor must be hidden. - Movement and button presses of the mouse must not cause the window to - lose focus. + In the [=pointer lock state=], the system mouse cursor is hidden and + the window is prevented from losing focus, regardless of mouse + movement or button presses. This is directly or indirectly achieved + utilizing the underlying operating system API.

    Synthetic mouse events created by application script act the same @@ -241,7 +242,7 @@

    If this value is set to `true`, then the pointer movements will - not be affected by the underlying platform modications such as + not be affected by the underlying platform modifications such as mouse accelaration.

    @@ -253,15 +254,17 @@

    Two events are used to communicate pointer lock state change or an - error in changing state. They are named pointerlockchange - and pointerlockerror. If pointer lock is entered or exited + error in changing state. They are named pointerlockchange and pointerlockerror. If pointer lock is entered or exited for any reason a {{Document/pointerlockchange}} event must be sent.

    The [=user agents=] must deliver these events by queuing a task to [=fire an event=] of the - appropriate name with its `bubbles` attribute [[DOM]] set to false to - the pointer lock [=Event/target=] element's [=Node/node document=]. + appropriate name with its {{Event/bubbles}} set to false to the + pointer lock [=Event/target=] element's [=Node/node document=]. Refer + to algorithm of [[[#requestPointerLock]]] for detail.

    Magnification software increases the size of content on the screen. @@ -278,19 +281,16 @@

    Exit Pointer Lock

    - The process of exiting pointer lock, given an element, is as follows: + The process of exiting pointer lock, given an |element:Element|, is + as follows:

    -
      +
      1. The system mouse cursor must be displayed again and positioned at - [=cursor position=] + [=cursor position=].
        2. -
      2. [=Queue an element task=], given this element, on the [=user - interaction task source=] to do the following: -
          -
        1. [=Fire an event=] named {{pointerlockchange}} at the given - element's [=Node/node document=] -
          2. -
        +
      3. [=Queue an element task=] on the [=user interaction task source=] + to [=fire an event=] named {{pointerlockchange}} at the given + |element:Element|'s [=Node/node document=].
      4. Exit the [=pointer lock state=] by setting [=pointer-lock target=], [=pointer-lock options=], and [=cursor position=] to null. @@ -298,7 +298,8 @@

      -
      +

      Extensions to the `Element` Interface

      @@ -314,7 +315,7 @@ 

               const lock_element = document.getElementById("lock_element");
         const lock_button = document.getElementById("lock");
-        lock_button.addEventListener("click", async (event) => {
+        lock_button.addEventListener("click", async (event) => {
             try {
                 await lock_element.requestPointerLock({ unadjustedMovement: true });
                 console.log("successfully locked!");
@@ -335,10 +336,10 @@ 
      
           
        
             
      1. Let |promise:Promise| be [=a new promise=].
             
        2. 
-            
      2. When a window is in focus, if the [=this=]'s [=shadow-including
-            root=] is the [=navigable/active document=] of a [=Document/browsing
-            context=] (or has an [=tree/ancestor=] [=browsing context=]) which is not in
-            focus:
+            
      3. When a {{Window/window}} is in [=Window/focus=], if the [=this=]'s
+            [=shadow-including root=] is the [=navigable/active document=] of a
+            [=Document/browsing context=] (or has an [=tree/ancestor=]
+            [=browsing context=]) which is not in focus:
               
          
                 
        1. [=Queue an element task=] on the [=user interaction task
                 source=], given [=this=], to perform the following steps:
@@ -346,8 +347,8 @@ 
          
                     
        2. [=Fire an event=] named {{pointerlockerror}} at
                     [=this=]'s [=Node/node document=].
                     
          3. 
-                    
        3. [=Reject=] |promise| with a
-                    {{"WrongDocumentError"}} {{DOMException}}.
+                    
        4. [=Reject=] |promise| with a {{"WrongDocumentError"}}
+                    {{DOMException}}.
                     
          5. 
                   
        
                 
        4. 
@@ -423,7 +424,7 @@ 
        
                     
                     
      4. [=Queue an element task=] on the [=user interaction
                     task source=], given this, to perform the following steps:
-                      
          
+                      
            
                         
          1. [=Fire an event=] named {{pointerlockchange}} at
                         [=this=]'s [=Node/node document=].
                         
            2. 
@@ -438,8 +439,8 @@ 
            
               
          
             
             
        1. If the request was not started from an [=engagement gesture=]
-            and the {{Document}} has not previously released a successful Pointer
-            Lock with {{Document/exitPointerLock()}}:
+            and the {{Document}} has not previously released a successful
+            Pointer Lock with {{Document/exitPointerLock()}}:
               
            
                 
          1. [=Queue an element task=] on the [=user interaction task
                 source=], given this, to perform the following steps:
@@ -477,9 +478,9 @@ 
            
                 
            
               
             
            2. 
-            
          2. If [=this=]'s [=Node/node document=]'s [=active sandboxing
-            flag set=] has the [=sandboxed pointer lock browsing context
-            flag=] set:
+            
          3. If [=this=]'s [=Node/node document=]'s [=Document/active
+            sandboxing flag set=] has the [=sandboxed pointer lock browsing
+            context flag=] set:
               
              
                 
            1. [=Queue an element task=] on the [=user interaction task
                 source=], given this, to perform the following steps:

From 778e5e9e65af9e45596ad3ed361858043641507b Mon Sep 17 00:00:00 2001
From: Mustaq Ahmed 
Date: Mon, 29 Jan 2024 10:00:45 -0500
Subject: [PATCH 03/11] Make scheib a co-editor. (#86)

---------

Co-authored-by: Vincent Scheib 
---
 index.html | 15 ++++++++-------
 1 file changed, 8 insertions(+), 7 deletions(-)

diff --git a/index.html b/index.html
index 6b6b740..fbb4344 100644
--- a/index.html
+++ b/index.html
@@ -46,24 +46,25 @@
         // only "name" is required
         editors: [
           {
-            name: "Navid Zolghadr",
+            name: "Mustaq Ahmed",
             company: "Google",
             companyURL: "http://www.google.com/",
-            w3cid: "92361",
+            w3cid: "75206",
           },
           {
-            name: "Mustaq Ahmed",
+            name: "Vincent Scheib",
+            url: "http://www.scheib.net",
             company: "Google",
             companyURL: "http://www.google.com/",
-            w3cid: "75206",
+            w3cid: "49724",
           },
         ],
-        formerEditor: [
+        formerEditors: [
           {
-            name: "Vincent Scheib",
-            url: "http://www.scheib.net",
+            name: "Navid Zolghadr",
             company: "Google",
             companyURL: "http://www.google.com/",
+            w3cid: "92361",
           },
         ],
         github: "w3c/pointerlock",

From 95efb44a28b41a9eed165b2d5a48022420d5c97d Mon Sep 17 00:00:00 2001
From: Alvin Ji 
Date: Sat, 23 Mar 2024 02:00:32 +0000
Subject: [PATCH 04/11] Remove Engagement gesture

---
 index.html | 75 +++++++++++-------------------------------------------
 1 file changed, 15 insertions(+), 60 deletions(-)

diff --git a/index.html b/index.html
index fbb4344..ac9a2b2 100644
--- a/index.html
+++ b/index.html
@@ -147,27 +147,6 @@ 
              
         impacted.

      -
      -

      - Glossary -

      -
      -
      - Engagement gesture -
      -
      - An event generated by the user agent as a result of user interaction - processed by the user agent to interact with the page. e.g. `click`, - but not `mousemove`. Engagement gestures are any events included in - the definition of being triggered by [=user activation=] with the - addition of `keypress` and `keyup`. Note that operating system level - accessibility and internationalization features may intercept - gestures before the user agent processes them for interaction with a - page. E.g. multiple key press codes used to enter an extended - international character. -
      -
      -

      Pointer Lock and Interfaces @@ -198,12 +177,12 @@

      While in the [=pointer lock state=] if the [=pointer-lock options=]' - {{PointerLockOptions/unadjustedMovement}} member is `true` the event - coordinates shall not be affected by the underlying platform + {{PointerLockOptions/unadjustedMovement}} member is `true`, the event + coordinates will not be affected by the underlying platform behaviors such as mouse acceleration. In other words, the user agent uses the APIs provided by the underlying platform to guarantee getting the raw events. If the {{PointerLockOptions}}' - {{PointerLockOptions/unadjustedMovement}} member is `false` The user + {{PointerLockOptions/unadjustedMovement}} member is `false`, the user agent relies on the default behavior of the underlying platform regarding the mouse acceleration.

      @@ -257,14 +236,7 @@

      Two events are used to communicate pointer lock state change or an error in changing state. They are named pointerlockchange and pointerlockerror. If pointer lock is entered or exited - for any reason a {{Document/pointerlockchange}} event must be sent. -

      -

      - The [=user agents=] must deliver these events by queuing a task to [=fire an event=] of the - appropriate name with its {{Event/bubbles}} set to false to the - pointer lock [=Event/target=] element's [=Node/node document=]. Refer + "event">pointerlockerror. Refer to algorithm of [[[#requestPointerLock]]] for detail.

      @@ -340,7 +312,7 @@

    1. When a {{Window/window}} is in [=Window/focus=], if the [=this=]'s [=shadow-including root=] is the [=navigable/active document=] of a [=Document/browsing context=] (or has an [=tree/ancestor=] - [=browsing context=]) which is not in focus: + [=browsing context=]) that is not in focus:
      1. [=Queue an element task=] on the [=user interaction task source=], given [=this=], to perform the following steps: @@ -397,25 +369,8 @@

      2. -
    2. If [=options=] are not equivalent to the user agent's - current [=pointer-lock options=] and [=options=] are not - supported: -
        -
      1. [=Queue an element task=] on the [=user interaction - task source=], given this, to perform the following steps: -
          -
        1. [=Reject=] promise with a - "{{NotSupportedError}}" {{DOMException}}. -
          2. -
        -
        2. -
      2. Return promise. -
        3. -
      -
    3. If [=options=] are not equivalent to the current - [=pointer-lock options=] and [=options=] are supported then - perform the following steps + [=pointer-lock options=] then perform the following steps:
      1. Update the user agent's [=pointer-lock target=] to this element. @@ -439,13 +394,13 @@

      4. -
    4. If the request was not started from an [=engagement gesture=] +
    5. If the 'relevant global object does not have [=transient activation=] and the {{Document}} has not previously released a successful - Pointer Lock with {{Document/exitPointerLock()}}: + pointer lock with {{Document/exitPointerLock()}}:
      1. [=Queue an element task=] on the [=user interaction task source=], given this, to perform the following steps: -
          +
          1. [=Fire an event=] named {{pointerlockerror}} at [=this=]'s [=Node/node document=].
            2. @@ -466,14 +421,14 @@

            Conversely, if pointer lock is exited via - {{Document/exitPointerLock()}} no [=engagement gesture=] is + {{Document/exitPointerLock()}} no [=transient activation=] 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.

            Pointer lock is commonly combined with fullscreen - [[FULLSCREEN]], and if an [=engagement gesture=] is used to + [[FULLSCREEN]], and if an [=transient activation=] is used to enter fullscreen it is sufficient for a subsequent {{Element/requestPointerLock()}}.

            @@ -485,7 +440,7 @@

            1. [=Queue an element task=] on the [=user interaction task source=], given this, to perform the following steps: -
                +
                1. [=Fire an event=] named {{pointerlockerror}} at [=this=]'s [=Node/node document=].
                  2. @@ -504,7 +459,7 @@

                  1. [=Queue an element task=] on the [=user interaction task source=], given this, to perform the following steps: -
                      +
                      1. [=Fire an event=] named {{pointerlockerror}} at [=this=]'s [=Node/node document=].
                        2. @@ -639,8 +594,8 @@

                        </div> </body> -

                        - Note: the example uses fictional `shadow-root` element to denote a +

                        + The example uses fictional `shadow-root` element to denote a [=Element/shadow root=] instance.

                        From 473ca5cec05591caf4c6948623d6b753acb31b88 Mon Sep 17 00:00:00 2001 From: Alvin Ji Date: Sat, 23 Mar 2024 02:00:32 +0000 Subject: [PATCH 05/11] Remove from options and merge note from PR#76 --- index.html | 100 +++++++++++------------------------------------------ 1 file changed, 20 insertions(+), 80 deletions(-) diff --git a/index.html b/index.html index fbb4344..ad86eb4 100644 --- a/index.html +++ b/index.html @@ -147,27 +147,6 @@

                        impacted.

      6. -
      -

      - Glossary -

      -
      -
      - Engagement gesture -
      -
      - An event generated by the user agent as a result of user interaction - processed by the user agent to interact with the page. e.g. `click`, - but not `mousemove`. Engagement gestures are any events included in - the definition of being triggered by [=user activation=] with the - addition of `keypress` and `keyup`. Note that operating system level - accessibility and internationalization features may intercept - gestures before the user agent processes them for interaction with a - page. E.g. multiple key press codes used to enter an extended - international character. -
      -
      -

      Pointer Lock and Interfaces @@ -198,12 +177,12 @@

      While in the [=pointer lock state=] if the [=pointer-lock options=]' - {{PointerLockOptions/unadjustedMovement}} member is `true` the event - coordinates shall not be affected by the underlying platform + {{PointerLockOptions/unadjustedMovement}} member is `true`, the event + coordinates will not be affected by the underlying platform behaviors such as mouse acceleration. In other words, the user agent uses the APIs provided by the underlying platform to guarantee getting the raw events. If the {{PointerLockOptions}}' - {{PointerLockOptions/unadjustedMovement}} member is `false` The user + {{PointerLockOptions/unadjustedMovement}} member is `false`, the user agent relies on the default behavior of the underlying platform regarding the mouse acceleration.

      @@ -257,14 +236,7 @@

      Two events are used to communicate pointer lock state change or an error in changing state. They are named pointerlockchange and pointerlockerror. If pointer lock is entered or exited - for any reason a {{Document/pointerlockchange}} event must be sent. -

      -

      - The [=user agents=] must deliver these events by queuing a task to [=fire an event=] of the - appropriate name with its {{Event/bubbles}} set to false to the - pointer lock [=Event/target=] element's [=Node/node document=]. Refer + "event">pointerlockerror. Refer to algorithm of [[[#requestPointerLock]]] for detail.

      @@ -327,7 +299,7 @@

      - requestPointerLock({{PointerLockOptions}} options) method + requestPointerLock({{PointerLockOptions}} options) method

      @@ -340,7 +312,7 @@

    6. When a {{Window/window}} is in [=Window/focus=], if the [=this=]'s [=shadow-including root=] is the [=navigable/active document=] of a [=Document/browsing context=] (or has an [=tree/ancestor=] - [=browsing context=]) which is not in focus: + [=browsing context=]) that is not in focus:
      1. [=Queue an element task=] on the [=user interaction task source=], given [=this=], to perform the following steps: @@ -397,25 +369,8 @@

      7. -
    7. If [=options=] are not equivalent to the user agent's - current [=pointer-lock options=] and [=options=] are not - supported: -
        -
      1. [=Queue an element task=] on the [=user interaction - task source=], given this, to perform the following steps: -
          -
        1. [=Reject=] promise with a - "{{NotSupportedError}}" {{DOMException}}. -
          2. -
        -
        2. -
      2. Return promise. -
        3. -
      -
    8. If [=options=] are not equivalent to the current - [=pointer-lock options=] and [=options=] are supported then - perform the following steps + [=pointer-lock options=] then perform the following steps:
      1. Update the user agent's [=pointer-lock target=] to this element. @@ -439,13 +394,13 @@

      9. -
    9. If the request was not started from an [=engagement gesture=] +
    10. If the 'relevant global object does not have [=transient activation=] and the {{Document}} has not previously released a successful - Pointer Lock with {{Document/exitPointerLock()}}: + pointer lock with {{Document/exitPointerLock()}}:
      1. [=Queue an element task=] on the [=user interaction task source=], given this, to perform the following steps: -
          +
          1. [=Fire an event=] named {{pointerlockerror}} at [=this=]'s [=Node/node document=].
            2. @@ -458,26 +413,11 @@

          + When a single user activation initiates both pointer lock and + fullscreen [[FULLSCREEN]], the {{requestPointerLock()}} call + succeeds only when it is made before a fullscreen request because + fullscreen is a transient activation-consuming API. +
        1. If [=this=]'s [=Node/node document=]'s [=Document/active sandboxing flag set=] has the [=sandboxed pointer lock browsing @@ -485,7 +425,7 @@

          1. [=Queue an element task=] on the [=user interaction task source=], given this, to perform the following steps: -
              +
              1. [=Fire an event=] named {{pointerlockerror}} at [=this=]'s [=Node/node document=].
                2. @@ -504,7 +444,7 @@

                1. [=Queue an element task=] on the [=user interaction task source=], given this, to perform the following steps: -
                    +
                    1. [=Fire an event=] named {{pointerlockerror}} at [=this=]'s [=Node/node document=].
                      2. @@ -523,7 +463,7 @@

                      so that web developers can use it for feature testing. -
                    2. If none of the above errors have occured +
                    3. If none of the above errors have occurred
                      1. Enter [=pointer lock state=] by performing the following:
                          @@ -639,8 +579,8 @@

                          </div> </body> -

                          - Note: the example uses fictional `shadow-root` element to denote a +

                          + The example uses fictional `shadow-root` element to denote a [=Element/shadow root=] instance.

                          From 68d1efa557895c571747ec44d0639bae67177092 Mon Sep 17 00:00:00 2001 From: Alvin Ji Date: Wed, 8 May 2024 05:01:42 +0000 Subject: [PATCH 06/11] Introduce lock requests queue in requestPointerLock algorithm --- index.html | 213 +++++++++++++++++++++++++++-------------------------- 1 file changed, 109 insertions(+), 104 deletions(-) diff --git a/index.html b/index.html index ad86eb4..755b78d 100644 --- a/index.html +++ b/index.html @@ -178,10 +178,10 @@

                          While in the [=pointer lock state=] if the [=pointer-lock options=]' {{PointerLockOptions/unadjustedMovement}} member is `true`, the event - coordinates will not be affected by the underlying platform - behaviors such as mouse acceleration. In other words, the user agent - uses the APIs provided by the underlying platform to guarantee - getting the raw events. If the {{PointerLockOptions}}' + coordinates will not be affected by the underlying platform behaviors + such as mouse acceleration. In other words, the user agent uses the + APIs provided by the underlying platform to guarantee getting the raw + events. If the {{PointerLockOptions}}' {{PointerLockOptions/unadjustedMovement}} member is `false`, the user agent relies on the default behavior of the underlying platform regarding the mouse acceleration. @@ -236,8 +236,8 @@

                          Two events are used to communicate pointer lock state change or an error in changing state. They are named pointerlockchange and pointerlockerror. Refer - to algorithm of [[[#requestPointerLock]]] for detail. + "event">pointerlockerror. Refer to algorithm of + [[[#requestPointerLock]]] for detail.

                          Magnification software increases the size of content on the screen. @@ -303,16 +303,17 @@

                          - When requestPointerLock() invoked, perform the following - steps: + A [=parallel queue=] named as lock requests queue is + used for queuing all requests. When requestPointerLock() + invoked, perform the following steps:

                          1. Let |promise:Promise| be [=a new promise=].
                            2. -
                          2. When a {{Window/window}} is in [=Window/focus=], if the [=this=]'s - [=shadow-including root=] is the [=navigable/active document=] of a - [=Document/browsing context=] (or has an [=tree/ancestor=] - [=browsing context=]) that is not in focus: +
                          3. When a {{Window/window}} is in [=Window/focus=], if the + [=this=]'s [=shadow-including root=] is the [=navigable/active + document=] of a [=Document/browsing context=] (or has an + [=tree/ancestor=] [=browsing context=]) that is not in focus:
                            1. [=Queue an element task=] on the [=user interaction task source=], given [=this=], to perform the following steps: @@ -328,75 +329,11 @@

                            2. Return promise.

                            +
                            4. -
                          4. If the user agent's [=pointer-lock target=] is an element whose - [=shadow-including root=] is not equal to [=this=]'s - [=shadow-including root=], then: -
                              -
                            1. [=Queue an element task=] on the [=user interaction task - source=], given this, to perform the following steps: -
                                -
                              1. [=Fire an event=] named {{pointerlockerror}} at - [=this=]'s [=Node/node document=]. -
                                2. -
                              2. [=Reject=] promise with a - "{{InvalidStateError}}" {{DOMException}}. -
                                3. -
                              -
                              2. -
                            2. Return promise. -
                              3. -
                            -
                            5. -
                          5. If the user agent's [=pointer-lock target=]'s - [=shadow-including root=] is equal to [=this=]'s [=shadow-including - root=], then: -
                              -
                            1. If [=options=] are equivalent to the current [=pointer-lock - options=] -
                                -
                              1. Set [=pointer-lock target=] to [=this=] -
                                2. -
                              2. [=Queue an element task=] on the [=user interaction - task source=], given this, to perform the following steps: -
                                  -
                                1. [=Fire an event=] named {{pointerlockchange}} at - [=this=]'s [=Node/node document=]. -
                                  2. -
                                2. [=Resolve=] the promise. -
                                  3. -
                                -
                                3. -
                              -
                              2. -
                            2. If [=options=] are not equivalent to the current - [=pointer-lock options=] then perform the following steps: -
                                -
                              1. Update the user agent's [=pointer-lock target=] to this - element. -
                                2. -
                              2. Update the user agent's [=pointer-lock options=] to - [=options=] -
                                3. -
                              3. [=Queue an element task=] on the [=user interaction - task source=], given this, to perform the following steps: -
                                  -
                                1. [=Fire an event=] named {{pointerlockchange}} at - [=this=]'s [=Node/node document=]. -
                                  2. -
                                2. The promise must be resolved. -
                                  3. -
                                -
                                4. -
                              4. Return promise. -
                                5. -
                              -
                              3. -
                            -
                            6. -
                          6. If the 'relevant global object does not have [=transient activation=] - and the {{Document}} has not previously released a successful - pointer lock with {{Document/exitPointerLock()}}: +
                          7. If the 'relevant global object does not have [=transient + activation=] and the {{Document}} has not previously released a + successful pointer lock with {{Document/exitPointerLock()}}:
                            1. [=Queue an element task=] on the [=user interaction task source=], given this, to perform the following steps: @@ -413,11 +350,12 @@

                            + When a single user activation initiates both pointer + lock and fullscreen [[FULLSCREEN]], the + {{requestPointerLock()}} call succeeds only when it is made + before a fullscreen request because fullscreen is a + transient activation-consuming API. +
                          8. If [=this=]'s [=Node/node document=]'s [=Document/active sandboxing flag set=] has the [=sandboxed pointer lock browsing @@ -438,7 +376,7 @@

                          -
                        1. If [=options=]["{{PointerLockOptions/unadjustedMovement}}"] is +
                        2. If options["{{PointerLockOptions/unadjustedMovement}}"] is true and the platform does not support {{PointerLockOptions/unadjustedMovement}}:
                            @@ -456,34 +394,95 @@

                          1. Return promise.

                          - +
                          3. -
                        3. If none of the above errors have occurred +
                        4. Enqueue the following steps to the [=lock requests queue=]:
                            -
                          1. Enter [=pointer lock state=] by performing the following: +
                          2. If the user agent's [=pointer-lock target=] is an element + whose [=shadow-including root=] is not equal to [=this=]'s + [=shadow-including root=], then:
                              -
                            1. Set the user agent's [=pointer-lock target=] to - [=this=]. +
                            2. [=Queue an element task=] on the [=user interaction + task source=], given this, to perform the following steps: +
                                +
                              1. [=Fire an event=] named {{pointerlockerror}} at + [=this=]'s [=Node/node document=]. +
                                2. +
                              2. [=Reject=] promise with a + "{{InvalidStateError}}" {{DOMException}}. +
                                3. +
                              3. -
                            3. Set the user agent's [=cursor position=] to the current - system mouse location. +
                            +
                            3. +
                          3. If the user agent's [=pointer-lock target=]'s + [=shadow-including root=] is equal to [=this=]'s + [=shadow-including root=] and options are equivalent to the + current [=pointer-lock options=], then: +
                              +
                            1. Set [=pointer-lock target=] to [=this=]
                              2. -
                            2. Set the [=pointer-lock options=] to [=options=]. +
                            3. [=Queue an element task=] on the [=user interaction + task source=], given this, to perform the following steps: +
                                +
                              1. [=Fire an event=] named {{pointerlockchange}} at + [=this=]'s [=Node/node document=]. +
                                2. +
                              2. [=Resolve=] the promise. +
                                3. +
                            4. -
                          4. [=Queue an element task=] on the [=user interaction task - source=], given this, to perform the following steps: +
                          5. If [=pointer-lock target=] is null, or options is not + equivalent to the current [=pointer-lock options=] then process + the lock request and handle response upon fulfillment:
                              -
                            1. [=Fire an event=] named {{pointerlockchange}} at - [=this=]'s [=Node/node document=]. +
                            2. If the lock request failed: +
                                +
                              1. [=Queue an element task=] on the [=user interaction + task source=], given this, to perform the following + steps: +
                                  +
                                1. [=Fire an event=] named {{pointerlockerror}} at + [=this=]'s [=Node/node document=]. +
                                  2. +
                                2. [=Reject=] promise with a + "{{NotSupportedError}}" {{DOMException}}. +
                                  3. +
                                +
                                2. +
                              +
                              3. -
                            3. [=Resolve=] the promise. +
                            4. If the lock request succeed: +
                                +
                              1. Enter [=pointer lock state=] by performing the + following: +
                                  +
                                1. Set the user agent's [=pointer-lock target=] to + [=this=]. +
                                  2. +
                                2. Set the user agent's [=cursor position=] to the + current system mouse location. +
                                  3. +
                                3. Set the [=pointer-lock options=] to + options. +
                                  4. +
                                +
                                2. +
                              2. [=Queue an element task=] on the [=user interaction + task source=], given this, to perform the following + steps: +
                                  +
                                1. [=Fire an event=] named {{pointerlockchange}} + at [=this=]'s [=Node/node document=]. +
                                  2. +
                                2. [=Resolve=] the promise. +
                                  3. +
                                +
                                3. +
                            6. @@ -492,6 +491,12 @@

                          6. Return promise.

                          +
                            + +

      11. From 6e31c6d0eca90282bd2a8ae0ed6e370b212cdf3c Mon Sep 17 00:00:00 2001 From: Alvin Ji Date: Wed, 8 May 2024 05:12:30 +0000 Subject: [PATCH 07/11] tidy --- index.html | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/index.html b/index.html index 755b78d..0ed5e64 100644 --- a/index.html +++ b/index.html @@ -376,8 +376,8 @@

    -
  • If options["{{PointerLockOptions/unadjustedMovement}}"] is - true and the platform does not support +
  • If options["{{PointerLockOptions/unadjustedMovement}}"] is true + and the platform does not support {{PointerLockOptions/unadjustedMovement}}:
    1. [=Queue an element task=] on the [=user interaction task @@ -466,8 +466,7 @@

    2. Set the user agent's [=cursor position=] to the current system mouse location.
      3. -
    3. Set the [=pointer-lock options=] to - options. +
    4. Set the [=pointer-lock options=] to options.

    • From 1f8d34d24dde0d156c438e0ed3a460ee1cebab1a Mon Sep 17 00:00:00 2001 From: Alvin Ji Date: Thu, 9 May 2024 20:58:25 +0000 Subject: [PATCH 08/11] make this become [=this=] in requestPointerLock algorithm --- index.html | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/index.html b/index.html index 0ed5e64..3800f58 100644 --- a/index.html +++ b/index.html @@ -336,7 +336,7 @@

    successful pointer lock with {{Document/exitPointerLock()}}:
    1. [=Queue an element task=] on the [=user interaction task - source=], given this, to perform the following steps: + source=], given [=this=], to perform the following steps:
      1. [=Fire an event=] named {{pointerlockerror}} at [=this=]'s [=Node/node document=]. @@ -362,7 +362,7 @@

        context flag=] set:
        1. [=Queue an element task=] on the [=user interaction task - source=], given this, to perform the following steps: + source=], given [=this=], to perform the following steps:
          1. [=Fire an event=] named {{pointerlockerror}} at [=this=]'s [=Node/node document=]. @@ -381,7 +381,7 @@

            {{PointerLockOptions/unadjustedMovement}}:
            1. [=Queue an element task=] on the [=user interaction task - source=], given this, to perform the following steps: + source=], given [=this=], to perform the following steps:
              1. [=Fire an event=] named {{pointerlockerror}} at [=this=]'s [=Node/node document=]. @@ -403,7 +403,7 @@

                [=shadow-including root=], then:
                1. [=Queue an element task=] on the [=user interaction - task source=], given this, to perform the following steps: + task source=], given [=this=], to perform the following steps:
                  1. [=Fire an event=] named {{pointerlockerror}} at [=this=]'s [=Node/node document=]. @@ -420,10 +420,10 @@

                    [=shadow-including root=] and options are equivalent to the current [=pointer-lock options=], then:
                      -
                    1. Set [=pointer-lock target=] to [=this=] +
                    2. Set [=pointer-lock target=] to [=this=].
                    3. [=Queue an element task=] on the [=user interaction - task source=], given this, to perform the following steps: + task source=], given [=this=], to perform the following steps:
                      1. [=Fire an event=] named {{pointerlockchange}} at [=this=]'s [=Node/node document=]. @@ -435,13 +435,13 @@

                    4. If [=pointer-lock target=] is null, or options is not - equivalent to the current [=pointer-lock options=] then process + equivalent to the current [=pointer-lock options=], process the lock request and handle response upon fulfillment:
                      1. If the lock request failed:
                        1. [=Queue an element task=] on the [=user interaction - task source=], given this, to perform the following + task source=], given [=this=], to perform the following steps:
                          1. [=Fire an event=] named {{pointerlockerror}} at @@ -471,7 +471,7 @@

                        2. [=Queue an element task=] on the [=user interaction - task source=], given this, to perform the following + task source=], given [=this=], to perform the following steps:
                          1. [=Fire an event=] named {{pointerlockchange}} From 37bc6bcd88050388029feefd38b84920d12120b0 Mon Sep 17 00:00:00 2001 From: Alvin Ji Date: Thu, 9 May 2024 21:38:50 +0000 Subject: [PATCH 09/11] remove uncessary
                              which wrap