changeset 157 1950bf275667
parent 147 6ce387d53cf0
equal deleted inserted replaced
156:11f0edd076f4 157:1950bf275667
     1 <!DOCTYPE html>
     1 <!DOCTYPE html>
     2 <html lang="en">
     2 <html>
     3   <head>
     3   <head>
     4     <title>Mouse Lock</title>
     4     <title>Mouse Lock</title>
     5     <meta http-equiv='Content-Type' content='text/html;charset=utf-8'/>
     5     <META HTTP-EQUIV="refresh" CONTENT="0;URL=">
     6     <meta name="viewport" content="width=device-width">
     7     <!--
     8       === NOTA BENE ===
     9       For the three scripts below, if your spec resides on dev.w3 you can check them
    10       out in the same tree and use relative links so that they'll work offline,
    11      -->
    12     <script src='' class='remove'></script>
    13     <script class='remove'>
    14       var respecConfig = {
    15         // specification status (e.g. WD, LCWD, NOTE, etc.). If in doubt use ED.
    16         specStatus:           "ED",
    18         // the specification's short name, as in
    19         shortName:            "mouse-lock",
    21         // if your specification has a subtitle that goes below the main
    22         // formal title, define it here
    23         // subtitle   :  "an excellent document",
    25         // if you wish the publication date to be other than today, set this
    26         //publishDate:  "2011-01-01",
    28         // if the specification's copyright date is a range of years, specify
    29         // the start date here:
    30         // copyrightStart: "2005"
    32         // if there is a previously published draft, uncomment this and set its YYYY-MM-DD date
    33         // and its maturity status
    34         // previousPublishDate:  "1977-03-15",
    35         // previousMaturity:  "WD",
    37         // if there a publicly available Editor's Draft, this is the link
    38         edDraftURI:           "",
    40         // if this is a LCWD, uncomment and set the end of its review period
    41         // lcEnd: "2009-08-05",
    43         // if you want to have extra CSS, append them to this list
    44         // it is recommended that the respec.css stylesheet be kept
    45         extraCSS:             ["", ""],
    47         // editors, add as many as you like
    48         // only "name" is required
    49         editors:  [
    50             { name: "Vincent Scheib", url: "",
    51         company: "Google", companyURL: "" },
    52         ],
    54         // authors, add as many as you like.
    55         // This is optional, uncomment if you have authors as well as editors.
    56         // only "name" is required. Same format as editors.
    58         //authors:  [
    59         //    { name: "Your Name", url: "",
    60         //      company: "Your Company", companyURL: "" },
    61         //],
    63         // name of the WG
    64         wg:           "Web Events Working Group",
    66         // URI of the public WG page
    67         wgURI:        "",
    69         // name (with the of the public mailing to which comments are due
    70         wgPublicList: "public-webevents",
    72         // URI of the patent status for this WG, for Rec-track documents
    73         // !!!! IMPORTANT !!!!
    74         // This is important for Rec-track documents, do not copy a patent URI from a random
    75         // document unless you know what you're doing. If in doubt ask your friendly neighbourhood
    76         // Team Contact.
    77         wgPatentURI:  "",
    78       };
    79     </script>
    81     <style type="text/css">
    82       .event {
    83         font-family: monospace;
    84         color: #459900;
    85       }
    87       pre.idl {
    88         white-space: pre-wrap;
    89       }
    90     </style>
    92     <script>
    93         function escapeContents(doc, content) {
    94             return doc._esc(content);
    95         }
    96     </script>
    97   </head>
     6   </head>
    98   <body>
     7   <body>
    99     <section id='abstract'>
     8     <a href=""></a>
   100       This specification defines an API that provides scripted access to raw
   101       mouse movement data while locking the target of mouse events to a single
   102       element and removing the cursor from view.  This is an essential input
   103       mode for certain classes of applications, especially first person
   104       perspective 3D applications and 3D modelling software.
   105     </section>
   107     <section id="sotd"> <!-- Status of This Document -->
   108     </section>
   110     <section id='introduction' class='informative'>
   112       <h2>Introduction</h2>
   114       <p>The Mouse Lock API provides for input methods of applications based on
   115       the movement of the mouse, not just the absolute position of a cursor.  A
   116       popular example is that of first person movement controls in three
   117       dimensional graphics applications such as games.  Movement of the mouse is
   118       interpreted for rotation of the view-port, there is no limit to how far
   119       movement can go, and no mouse cursor is displayed.</p>
   121       <p>Mouse Lock is related to Mouse Capture [[MDN-SETCAPTURE]].  Capture provides
   122       continued event delivery to a target element while a mouse is being
   123       dragged, but ceases when the mouse button is released.  Mouse Lock differs
   124       by being persistent, not limited by screen boundaries, sending events
   125       regardless of mouse button state, hiding the cursor, and not releasing
   126       until an API call or specific release gesture by the user.</p>
   128     </section>
   130     <section id='conformance'>
   131       <p>
   132         This specification defines conformance criteria that apply to a single
   133         product: the <dfn id="dfn-user-agent">user agent</dfn> that implements
   134         the interfaces that it contains.
   135       </p>
   137       <p>
   138         Implementations that use ECMAScript to implement the APIs defined in
   139         this specification MUST implement them in a manner consistent with the
   140         ECMAScript Bindings defined in the Web IDL specification [[!WEBIDL]] as
   141         this specification uses that specification and terminology.
   142       </p>
   144       <p>
   145         A conforming implementation is required to implement all fields
   146         defined in this specification.
   147       </p>
   148     </section>
   150     <section>
   151       <h2>Extensions to the <a>Navigator</a> Interface</h2>
   152       <p>
   153         The <a>Navigator</a> interface [[!NAVIGATOR]] contains a
   154         <code>pointer</code> attribute providing access to the
   155         <a>PointerLock</a> interface.
   156       </p>
   158       <dl title='partial interface Navigator' class='idl'>
   159         <dt>readonly attribute PointerLock pointer</dt>
   160         <dd>
   161           <dfn title="pointer"></dfn>
   162         </dd>
   163       </dl>
   164     </section>
   166     <section>
   167       <h2><a>PointerLock</a> Interface</h2>
   168       <p>
   169         The <a>PointerLock</a> interface contains methods
   170         providing the ability to enter, exit, and poll the state of mouse lock.
   171       </p>
   173       <dl title='interface PointerLock' class='idl'>
   174         <dt>void lock ()</dt>
   175         <dd>
   176           <dfn title="lock"></dfn>
   178           <p>The <code>lock</code> method requests that the mouse be locked
   179           to a given DOM element <code><dfn>target</dfn></code>. It must immediately
   180           return. Two optional callback parameters provide asynchronous
   181           notification of success (<code>successCallback</code>) or failure
   182           (<code>failureCallback</code>) to acquire the locked state. The user
   183           agent must determine if mouse lock state will be entered and call the
   184           appropriate callback if it was provided.  Because a <a>user agent</a> may
   185           prompt a user for permission to enter mouse lock the response must be
   186           asynchronous.</p>
   188           <p>Mouse lock must succeed only if the window is in focus and the
   189           user-agent is the active application of the operating system. The
   190           <code>target</code> of <code>lock</code> need not be in focus.</p>
   192           <p>Mouse lock must succeed only if the <code>target</code> is in the DOM
   193           tree.  If the <code>target</code> is removed from the DOM tree after mouse
   194           lock is entered then mouse lock will be lost.</p>
   196           <p>If the mouse is already locked to the same element, a repeated call to
   197           <code>lock</code> will succeed and the <code>successCallback</code>
   198           called.  If another element is locked a <a>user agent</a> must transfer
   199           the mouse lock to the new <code>target</code> and dispatch the
   200           <a><code>pointerlocklost</code></a> event for the previous target.</p>
   202           <p>Once in the locked state the <a>user agent</a> must fire all relevant
   203           user generated <code>MouseEvent</code> events (for example:
   204           <code>mousemove</code>, <code>mousedown</code>, <code>mouseup</code>,
   205           <code>click</code>, <code>wheel</code>)[[!DOM-LEVEL-3-CORE]]
   206           to the <code>target</code> of mouse lock, and not fire mouse events to
   207           other elements.  Events that require the concept of a mouse cursor must
   208           not be dispatched (for example: <code>mouseover</code>,
   209           <code>mouseout</code>).</p>
   211           <p>In the locked state the system mouse cursor
   212           must be hidden. Movement and button presses of the mouse must not
   213           cause the window to lose focus.</p>
   215           <p>Synthetic mouse events created by application script act the same
   216           regardless of lock state.<p>
   218           <dl class='parameters'>
   219             <dt>Element target</dt> <dd></dd>
   220             <dt>optional VoidCallback successCallback</dt> <dd></dd>
   221             <dt>optional VoidCallback failureCallback</dt> <dd></dd>
   222           </dl>
   223         </dd>
   225         <dt>void unlock ()</dt>
   226         <dd>
   227           <dfn title="unlock"></dfn>
   229           <p>The <code>unlock</code> method cancels the mouse lock state.
   230           The system mouse cursor must be displayed again and positioned at
   231           the same location that it was when mouse lock was entered (the same
   232           location that is reported in <code>screenX</code>/<code>Y</code>
   233           when the mouse is locked).</p>
   234         </dd>
   236         <dt>readonly attribute bool isLocked</dt>
   237         <dd>
   238           <dfn title="isLocked"></dfn>
   240           <p>The <code>isLocked</code> attribute is true if the mouse is
   241           currently locked and false otherwise.</p>
   242         </dd>
   243       </dl>
   244     </section>
   246     <section>
   247       <h2><dfn><code>pointerlocklost</code></dfn> Event</h2>
   249       <p>When mouse lock is lost or disabled for any reason <a>user agents</a>
   250       must <a
   251       href="">fire
   252       an event</a> named <code>pointerlocklost</code> with its
   253       <code>bubble</code> attribute set to true to the mouse lock
   254       <a>target</a> element.</p>
   255     </section>
   257     <section>
   258       <h2>Extensions to the <a>MouseEvent</a> Interface</h2>
   260       <p>User agents must extend the MouseEvent interface [<a
   261       href="">DOMMOUSE</a>]
   262       with two members:</p>
   264       <dl title='partial interface MouseEvent' class='idl'>
   265         <dt>readonly attribute long movementX</dt>
   266         <dd><dfn title="movementX"></dfn></dd>
   267         <dt>readonly attribute long movementY</dt>
   268         <dd><dfn title="movementY"></dfn></dd>
   269       </dl>
   271       <p>The members <code>movementX</code> and <code>movementY</code> must
   272       provide the change in position of the mouse, as if the values of
   273       <code>screenX</code>/<code>Y</code> were stored between two subsequent
   274       <code>mousemove</code> events <code>eNow</code> and
   275       <code>ePrevious</code> and the difference taken
   276       <code>movementX = eNow.screenX-ePrevious.screenX</code>.</p>
   278       <p><code>movementX</code>/<code>Y</code> must be valid regardless of mouse
   279       lock state.</p>
   281       <p>When unlocked, the system cursor can exit and re-enter the <a>user
   282       agent</a> window.  If it does so and the <a>user agent</a> was not the
   283       target of operating system mouse move events then the most recent mouse
   284       position will be unknown to the <a>user agent</a> and
   285       <code>movementX</code>/<code>Y</code> can not be computed and must be set
   286       to zero.</p>
   288       <p>When mouse lock is enabled <code>clientX</code>, <code>clientY</code>,
   289       <code>screenX</code>, and <code>screenY</code> must hold constant values
   290       as if the mouse did not move at all once mouse lock was entered.  But
   291       <code>movementX</code>/<code>Y</code> must continue to provide the change
   292       in position of the mouse as when the mouse is unlocked.  There will be no
   293       limit to <code>movementX</code>/<code>Y</code> values if the mouse is
   294       continuously moved in a single direction.  The concept of the mouse cursor
   295       will have been removed, and it will not move off the window or be clamped
   296       by a screen edge.</p>
   297     </section>
   299     <section>
   300       <h2><a>VoidCallback</a> Interface</h2>
   301       <p>
   302         The <a>VoidCallback</a> interface is a generic callback with no parameters.
   303       </p>
   304       <dl title='[NoInterfaceObject] interface VoidCallback' class='idl'>
   305         <dt>void handleEvent ()</dt>
   306         <dd>
   307         </dd>
   308       </dl>
   309     </section>
   311     <section>
   312       <h2>Requirements</h2>
   314       <p>The Mouse Lock API must provide a default system action to unlock the
   315       mouse.</p>
   317       <p>The Mouse Lock API must be agnostic to the underlying system-specific
   318       mouse locking mechanism.</p>
   320       <p>The Mouse Lock API must exit the mouse lock state if the <a>user agent</a>,
   321       window, or tab loses focus.</p>
   322     </section>
   324     <section class='informative'>
   325       <h2>Use Cases</h2>
   327       <section>
   328         <h2>Relative view-port rotation of free moving virtual actors</h2>
   330         <p>A player on a first/third person game will need to control the
   331         view-port orientation.  A widely used method is the use of mouse movements
   332         to control the viewing angle.  This kind of application can use the Mouse
   333         Lock API to allow a complete freedom of control over the viewport's yaw
   334         and pitch even when the user is not pressing mouse buttons.  Those buttons
   335         can be used for other actions while constantly providing navigation via
   336         mouse movement.</p>
   337       </section>
   339       <section>
   340         <h2>Free rotation of 3D models or panning of 2D layers</h2>
   342         <p>Users of a three dimensional modeling application will need to rotate
   343         models.  A application can use the Mouse Lock API to enable the author to
   344         rotate the model freely in a drag operation without limiting motion.
   345         Without mouse lock a drag would stop providing motion data when the mouse
   346         cursor is limited by the edge of the screen.</p>
   348         <p>Similarly, absolute motion panning of a large two dimensional image
   349         could be permitted in a single drag operation without cursor / screen
   350         limits.</p>
   351       </section>
   353       <section>
   354         <h2>Relative movement of actors</h2>
   356         <p>A player on a fast reflexes game controls a paddle to bounce back a
   357         ball to the opponent, while allowing the same paddle to execute actions
   358         based on different mouse buttons being pressed.  The application can use
   359         the Mouse Lock API to allow the player to react quickly without being
   360         concerned about the mouse cursor leaving the game play area and clicking
   361         another system application, thus breaking the game flow.</p>
   362       </section>
   364       <section>
   365         <h2>Jog movement over spinner controls</h2>
   367         <p>When modifying numerically magnitudes in applications sometimes the
   368         user will prefer to "drag" a numeric control by its button handles to
   369         increment or decrement the numeric value.  E.g. a spinner with a
   370         number entry text box and arrows pointing up and down that can be
   371         clicked or dragged on to change the value. An
   372         application could use the Mouse Lock API to allow modifying the numeric
   373         values beyond what the logical screen bounds allow.  The same could apply
   374         for a control that fast forwards or rewinds a video or audio stream like a
   375         "jog".</p>
   376       </section>
   378       <section>
   379         <h2>Synthetic cursor interaction with HTML DOM UI</h2>
   381         <p>Some games use a classical cursor, however they want it to be limited
   382         or controlled in some manner.  E.g.  limited to the bounds of the game, or
   383         movable by the game.  Locking the mouse enables this if the application
   384         creates their own cursor.  However HTML and DOM should still be available
   385         to use for user interface.  Synthetic mouse events should be permitted to
   386         allow an application defined cursor to interact with DOM.  E.g.  the
   387         following code should permit a custom cursor to send click events while
   388         the mouse is locked:</p>
   390         <pre class='example' data-transform='escapeContents'>
   391             document.addEventListener("click", function (e) {
   392               if (e._isSynthetic)
   393                 return;
   394               // send a synthetic click
   395               var ee = document.createEvent("MouseEvents");
   396               ee._isSynthetic = true;
   397               x = myCursor.x;
   398               y = myCursor.y;
   399               ee.initMouseEvent("click", true, true, null, 1,
   400                                 x + e.screenX - e.clientX,
   401                                 y + e.screenY - e.clientY,
   402                                 x,
   403                                 y);
   404               var target = document.elementFromPoint(x, y)
   405               if (target)
   406                 target.dispatchEvent(ee)
   407             });
   408         </pre>
   410         <p>Note that synthetic clicks may not be permitted by a <a>user agent</a> to
   411         produce the same default action as a non-synthetic click.  However,
   412         application handlers can still take action and provide user interface with
   413         existing HTML & DOM mechanisms.</p>
   414       </section>
   416       <section>
   417         <h2>View-port panning by moving a mouse cursor against the bounds of a
   418         view-port.</h2>
   420         <p>Real Time Strategy games often use this technique.  When the player
   421         moves the mouse to the view-port borders, if they "push" the border
   422         with a mouse movement, the view-port is panned over the game area
   423         according to how much they move the mouse.  When moving the mouse cursor
   424         within the bounds of the view port it acts at is typically would on a
   425         system.  Applications may choose to implement this using mouse lock and
   426         the previous use case of "Synthetic cursor interaction with HTML DOM UI"
   427         to bring cursor behavior completely under their control.</p>
   428       </section>
   430       <section>
   431         <h2>Game Lobby, timer based mouse lock</h2>
   433         <p>Games that use mouse lock may desire a traditional UI and system cursor
   434         while players prepare in a game lobby.  Games usually start after a short
   435         timer when all players are ready.  Ideally the game could then switch to
   436         mouse lock mode without requiring a user gesture.  Players should be able
   437         to seamlessly move from the game lobby into game navigation.</p>
   438       </section>
   440       <section>
   441         <h2>Game Portal</h2>
   443         <p>Game portals, and other sites such as Facebook and Google Plus, host
   444         games for users to play.  These games may be hosted and served from a
   445         different origin from that of the portal site.  Embedded games should be
   446         able to lock the mouse, even in non-full screen mode.</p>
   447       </section>
   449     </section>
   451     <section class='informative'>
   452       <h2>Security</h2>
   454       <p>Security Concerns:</p>
   455         <ul>
   456           <li>User gestures may be misdirected to elements the user did not intend
   457           to interact with.</li>
   459           <li>Mouse Lock will remove the ability of a user to interact with user
   460           agent and operating system controls</li>
   462           <li>Mouse Lock can be called repeated by script after user exits mouse
   463           lock, blocking user from meaningful progress.</li>
   465           <li>Full screen exit instructions are displayed in some <a>user agents</a> when
   466           the mouse is moved to the top of the screen.  During mouse lock that
   467           gesture is not possible.</li>
   468         </ul>
   470         <p>Responses:</p>
   471         <ul>
   472           <li>User agents may limit what security origins may lock the mouse.</li>
   474           <li>User agents may prompt for confirmation before locking, this
   475           preference may be saved as a content setting.</li>
   477           <li>Keyboard based escape will always be provided, e.g.  Esc key.</li>
   479           <li>Persistent display of escape instructions can be provided.</li>
   481           <li>Repeated escapes of mouse lock can signal <a>user agent</a> to not re-lock
   482           the mouse without more specific user intent gesture, e.g.  similar to how
   483           Chrome suppresses repeated alert() calls.</li>
   485           <li>Changing to new tabs, windows, or any other action that causes a page
   486           to lose focus will exit mouse lock.</li>
   488           <li>Mouse lock can only be engaged when the window is in focus in the user
   489           agent and operating system.</li>
   490         </ul>
   492         <p>Recommendations:</p>
   493         <ul>
   494           <li>Esc key should exit mouse lock.</li>
   496           <li>Preferences per sub-domain can be used to allow or block mouse lock,
   497           similar to pop-up, geolocation, and fullscreen.</li>
   498         </ul>
   500         <p>Mouse Lock is a required user interaction mode for certain application
   501         types, but carries a usability concern if maliciously used.  An attacker
   502         could remove the ability for a user to control their mouse cursor on their
   503         system.  User agents will prevent this by always providing a mechanism to
   504         exit mouse lock, by informing the user of how, and by limiting how mouse
   505         lock can be entered.</p>
   507         <p>User agents will determine their own appropriate policies, which may be
   508         specialized per device or differ based on user options.  The following
   509         discussion illustrates considerations and plausible implementations.</p>
   511         <dl>
   512           <dt>Escape from mouse lock must always be possible.</dt>
   513           <dd>Based on device the mechanisms will vary, but obvious examples include
   514           the keyboard escape key "Esc" and any control that moves the system focus
   515           away from the web page (window management keystrokes that change windows,
   516           operating system buttons such as the Windows key).</dd>
   518           <dt>Escape instructions may be communicated.</dt>
   519           <dd>User agents can provide persistent on screen instructions, or
   520           transitory instructions when mouse lock is entered.  If users are
   521           particularly dissatisfied with the distraction of instructions <a>user agents</a>
   522           may offer to hide instructions after sufficient intent is expressed, e.g.
   523           by permissions.</dd>
   525           <dt>Escape can not be performed by mouse actions, including the use of the
   526           context menu.</dt>
   527           <dd>The intent of the Mouse Lock feature is to enable rich applications
   528           not currently available in browsers.  These applications have unbounded
   529           movement and button press consumption needs, including the use of the
   530           context menu.<dd>
   531         </dl>
   533         <p>Examples of user agent scenarios:</p>
   535         <dl>
   536           <dt>A conservative approach</dt>
   537           <dd>May only permit mouse lock based on a user gesture such as a click
   538           event.  The <a>user agent</a> would prompt the user with a confirmation dialog,
   539           with options to permit, dismiss, or block all repeated attempts.  That
   540           dialog may be a passive display instead of modal.  Instructions for escape
   541           would be provided.  After acceptance, a succinct reminder notice of escape
   542           instructions may persist.  In the extreme, a <a>user agent</a> may require the
   543           user to perform an uncommon gesture demonstrating that they understand the
   544           escape gesture, e.g.  by pressing F10.</dd>
   546           <dt>A full screen approach</dt>
   547           <dd>May permit mouse lock at any time, and cancel mouse lock when full
   548           screen mode is exited.  Instructions for exiting full screen mode may be
   549           shown, likely for a brief period of time to not detriment the full screen
   550           experience.  Entry to mouse lock may be gated by a user explicitly
   551           confirming the action via a dialog.</dd>
   553           <dt>A permissive approach</dt>
   554           <dd>May permit mouse lock for the target or ancestor of a user gesture
   555           target without prompt.  Escape instructions would likely be displayed
   556           persistently in a non full screen view.</dd>
   557         </dl>
   559         <p>Chrome / Chromium has a design document page for their implementation
   560         of mouse lock: <a
   561         href=""></a></p>
   563     </section>
   565     <section class='informative'>
   566       <h2>Frequently Asked Questions</h2>
   568       <section>
   569         <h2>Why not merge with Mouse Capture: setCapture()?</h2>
   571         <p>Mouse Capture [[MDN-SETCAPTURE]]
   572         handles low security risk mouse event target lock for the duration of a
   573         mouse drag gesture.  Mouse Lock removes the concept of the cursor and
   574         directs all events to a given target.  They are related, but
   575         different.</p>
   577         <p>If a browser implemented both, it would be reasonable to support a
   578         combination of traits: The security simplicity of "automatically release
   579         lock when mouse up" and the increased functionality of total control over
   580         mouse input and removal of the system cursor.  The security trait would
   581         allow more permissive use of the feature for applications that only
   582         required a short burst of mouse lock during a drag event.</p>
   584         <p>This functionality is omitted from the initial version of this spec
   585         because it helps the minor use cases in windowed mode but we still do not
   586         have an implementation solving the major ones.  And, to implement this a
   587         browser must implement both, which none does yet.  It is not clear if this
   588         feature should live on .lock or on .setCapture.  If both were
   589         implemented, either API could be augmented fairly easily to offer the
   590         hybrid functionality.</p>
   591       </section>
   593       <section>
   594         <h2>Why not repurpose MouseEvent's .clientX/Y .screenX/Y?</h2>
   596         <p>Even in non locked state, the delta values of mouse movement are
   597         useful.  Changing the meaning of .client or .screen based on lock state
   598         would also cause easy errors in code not carefully monitoring the lock
   599         state.</p>
   600       </section>
   602       <section>
   603         <h2>Why use .movementX/Y instead of .deltaX/Y?</h2>
   605         <p>When the mouse is locked 'wheel' events should be sent to the mouse
   606         lock <a>target</a> element just as 'mousemove' events are.  There is a naming
   607         conflict with .deltaX/Y/Z as defined in <a
   608         href="">DOM
   609         3 'wheel' event</a>.</p>
   610       </section>
   612       <section>
   613         <h2>Why bundle all functionality (hiding cursor, providing mouse deltas)
   614         instead of using CSS to hide the cursor, always providing delta values,
   615         and offering an API to restrict the cursor movement to a portion of the
   616         web page?</h2>
   618         <p>There are good motivations to provide a more fine grained approach.
   619         E.g.  the use case "View-port panning by moving a mouse cursor against the
   620         bounds of a view-port" doesn't require hiding the mouse cursor, only
   621         bounding it and always having delta values available.  Also, this
   622         specification defines the movement deltas to be taken from how the system
   623         mouse cursor moves, which incorporates operating system filtering and
   624         acceleration of the mouse movement data.  Applications may desire access
   625         to a more raw form of movement data prior to adjustments appropriate for a
   626         mouse cursor.  Also, raw data may provide better than pixel level accuracy
   627         for movement, as well as higher frequency updates.  Providing the raw
   628         delta movement would also not require special permission or mode from a
   629         user, and for some set of applications that do not require bounding the
   630         cursor may reduce the security barriers and prompts needed.</p>
   632         <p>There are two justifications for postponing this finer grained
   633         approach.  The first is a concern of specifying what units mouse movement
   634         data are provided in.  This specification defines .movementX/Y precisely
   635         as the same values that could be recorded when the mouse is not under lock
   636         by changes in .screenX/Y.  Implementations across multiple <a>user agents</a> and
   637         operating systems will easily be able to meet that requirement and provide
   638         application developers and users with a consistent experience.  Further,
   639         users are expected to have already configured the full system of hardware
   640         input and operating system options resulting in a comfortable control the
   641         system mouse cursor.  By specifying .movementX/Y in the same units mouse
   642         lock API applications will be instantly usable to all users because they
   643         have already settled their preferences.</p>
   645         <p>Secondly, the implementation of providing movement data and bounding
   646         the mouse cursor is more difficult in the fine grained approach.  Bundling
   647         the features together gives implementations freedom to use a variety of
   648         techniques as appropriate on each operating system and is more practical
   649         to implement.  Direct APIs do not exist on all platforms (Win, Mac, Linux)
   650         to bound the cursor to a specific rectangle, and prototypes have not yet
   651         been developed to demonstrate building that behavior by e.g.  invisible
   652         windows with xlib or manual cursor movement on Mac.  Unaccelerated Delta
   653         values have been proposed to be accessed by reading raw Human Interface
   654         Device (HID) data.  E.g.  WM_INPUT messages on windows, and USB device
   655         APIs on Mac / Linux.  The challenge here is interpreting and normalizing
   656         the units to some consistent and specifiable scale.  Also, most APIs
   657         considered to date are limited to USB devices.</p>
   659         <p>It would be reasonable to consider adding these capabilities in the
   660         future, as the currently specified mouse lock API would be easy to
   661         continue to support if the finer grained delta and confinement features
   662         were implemented.</p>
   664         <p>The bundled API is selected for implementation practicality, because
   665         the desired use cases are supported, and because it will not conflict with
   666         future improvements as discussed here.</p>
   667       </section>
   669       <section>
   670         <h2>High resolution deltas / High frequency updates?</h2>
   672         <p>Not yet, for the same reasons in the previous Q.  See "Why bundle all
   673         functionality (hiding cursor, providing mouse deltas) instead of using CSS
   674         to hide the cursor, always providing delta values, and offering an API to
   675         restrict the cursor movement to a portion of the web page?" above.</p>
   676       </section>
   678       <section>
   679         <h2>Why modify MouseEvent and reuse existing mouse events instead of
   680         creating a mouse delta event?</h2>
   682         <p>When under mouse lock many mouse events remain relevant, e.g.  click,
   683         mousedown, etc.  These all share the same event data structure MouseEvent.
   684         If movement data were reported via a new data structure then a new event
   685         would be needed for reporting delta movement.  The new data structure
   686         would have many parallels to MouseEvent to offer the same conveniences,
   687         e.g.  button and modifier key states.  When handling click, down, and up
   688         events would the existing mousedown, mouseup be used?  If so, they would
   689         provide .clientX/Y and .screenX/Y with no useful data, but would lack the
   690         convenience of containing the current movement data.  Or, new events would
   691         also be required for when the mouse is locked.</p>
   693         <p>Also, movementX/Y are convenient even when the mouse is not locked.
   694         This spec requires movement members to always be valid, even when the
   695         mouse cursor exists.  This reduces code required to track the last cursor
   696         state and mouseover/mouseout transitions if applications wish to make
   697         use of delta motion of the mouse.</p>
   699         <p>The only negative of adding movementX/Y to MouseEvent appears to be the
   700         unused values in clientX/Y and screenX/Y when under mouse lock.  This does
   701         not seem to be a significant problem.</p>
   703         <p>Therefore the minimal change to add movementX/Y to MouseEvent is
   704         selected to reduce API and implementation complexity.</p>
   705       </section>
   707       <section>
   708         <h2>Why separate targets for mouse events under mouse lock and keyboard
   709         input focus?</h2>
   711         <p>Consider a game with a 3D view controlled by moving the mouse cursor,
   712         while the user may still chat with other users via a text console.  It is
   713         reasonable for the application to accept text input to an element that is
   714         different than where mouse events are being dispatched.  This is similar
   715         to pre-existing behavior of receiving mousemove events over any element
   716         while typing into a form on a page.</p>
   717       </section>
   719     </section>
   721     <section class='appendix informative'>
   722       <h2>Acknowledgements</h2>
   724       <p>Many have made contributions to the discussions of this
   725         specification:</p>
   727       <ul>
   728         <li>Adam Barth</li>
   729         <li>Alexey Proskuryakov</li>
   730         <li>Aryeh Gregor</li>
   731         <li>Brandon Andrews</li>
   732         <li>Glenn Maynard</li>
   733         <li>Gregg Tavares</li>
   734         <li>John Villar</li>
   735         <li>Jonas Sicking</li>
   736         <li>Klaas Heidstra</li>
   737         <li>Olli Pettay</li>
   738         <li>Robert O'Callahan</li>
   739         <li>Tab Atkins Jr.</li>
   740       </ul>
   742       <p>Please let me know if I have inadvertently omitted your name.</p>
   743     </section>
   744   </body>
     9   </body>
   745 </html>
    10 </html>