mouse-lock.html
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=http://dvcs.w3.org/hg/pointerlock/raw-file/default/index.html">
     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='http://dev.w3.org/2009/dap/ReSpec.js/js/respec.js' 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",
       
    17 
       
    18         // the specification's short name, as in http://www.w3.org/TR/short-name/
       
    19         shortName:            "mouse-lock",
       
    20 
       
    21         // if your specification has a subtitle that goes below the main
       
    22         // formal title, define it here
       
    23         // subtitle   :  "an excellent document",
       
    24 
       
    25         // if you wish the publication date to be other than today, set this
       
    26         //publishDate:  "2011-01-01",
       
    27 
       
    28         // if the specification's copyright date is a range of years, specify
       
    29         // the start date here:
       
    30         // copyrightStart: "2005"
       
    31 
       
    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",
       
    36 
       
    37         // if there a publicly available Editor's Draft, this is the link
       
    38         edDraftURI:           "http://dvcs.w3.org/hg/webevents/raw-file/default/mouse-lock.html",
       
    39 
       
    40         // if this is a LCWD, uncomment and set the end of its review period
       
    41         // lcEnd: "2009-08-05",
       
    42 
       
    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:             ["http://www.w3.org/StyleSheets/TR/W3C-TR.css", "http://dev.w3.org/2009/dap/ReSpec.js/css/respec.css"],
       
    46 
       
    47         // editors, add as many as you like
       
    48         // only "name" is required
       
    49         editors:  [
       
    50             { name: "Vincent Scheib", url: "http://www.scheib.net",
       
    51         company: "Google", companyURL: "http://www.google.com/" },
       
    52         ],
       
    53 
       
    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.
       
    57 
       
    58         //authors:  [
       
    59         //    { name: "Your Name", url: "http://example.org/",
       
    60         //      company: "Your Company", companyURL: "http://example.com/" },
       
    61         //],
       
    62 
       
    63         // name of the WG
       
    64         wg:           "Web Events Working Group",
       
    65 
       
    66         // URI of the public WG page
       
    67         wgURI:        "http://www.w3.org/2010/webevents/",
       
    68 
       
    69         // name (with the @w3c.org) of the public mailing to which comments are due
       
    70         wgPublicList: "public-webevents",
       
    71 
       
    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:  "http://www.w3.org/2004/01/pp-impl/45559/status",
       
    78       };
       
    79     </script>
       
    80 
       
    81     <style type="text/css">
       
    82       .event {
       
    83         font-family: monospace;
       
    84         color: #459900;
       
    85       }
       
    86 
       
    87       pre.idl {
       
    88         white-space: pre-wrap;
       
    89       }
       
    90     </style>
       
    91 
       
    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="http://dvcs.w3.org/hg/pointerlock/raw-file/default/index.html">http://dvcs.w3.org/hg/pointerlock/raw-file/default/index.html</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>
       
   106 
       
   107     <section id="sotd"> <!-- Status of This Document -->
       
   108     </section>
       
   109 
       
   110     <section id='introduction' class='informative'>
       
   111 
       
   112       <h2>Introduction</h2>
       
   113 
       
   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>
       
   120 
       
   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>
       
   127 
       
   128     </section>
       
   129 
       
   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>
       
   136 
       
   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>
       
   143 
       
   144       <p>
       
   145         A conforming implementation is required to implement all fields
       
   146         defined in this specification.
       
   147       </p>
       
   148     </section>
       
   149 
       
   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>
       
   157 
       
   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>
       
   165 
       
   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>
       
   172 
       
   173       <dl title='interface PointerLock' class='idl'>
       
   174         <dt>void lock ()</dt>
       
   175         <dd>
       
   176           <dfn title="lock"></dfn>
       
   177 
       
   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>
       
   187 
       
   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>
       
   191 
       
   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>
       
   195 
       
   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>
       
   201 
       
   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>
       
   210 
       
   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>
       
   214 
       
   215           <p>Synthetic mouse events created by application script act the same
       
   216           regardless of lock state.<p>
       
   217 
       
   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>
       
   224 
       
   225         <dt>void unlock ()</dt>
       
   226         <dd>
       
   227           <dfn title="unlock"></dfn>
       
   228 
       
   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>
       
   235 
       
   236         <dt>readonly attribute bool isLocked</dt>
       
   237         <dd>
       
   238           <dfn title="isLocked"></dfn>
       
   239 
       
   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>
       
   245 
       
   246     <section>
       
   247       <h2><dfn><code>pointerlocklost</code></dfn> Event</h2>
       
   248 
       
   249       <p>When mouse lock is lost or disabled for any reason <a>user agents</a>
       
   250       must <a
       
   251       href="http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#concept-event-fire">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>
       
   256 
       
   257     <section>
       
   258       <h2>Extensions to the <a>MouseEvent</a> Interface</h2>
       
   259 
       
   260       <p>User agents must extend the MouseEvent interface [<a
       
   261       href="http://dev.w3.org/2006/webapi/DOM-Level-3-Events/html/DOM3-Events.html#events-MouseEvent">DOMMOUSE</a>]
       
   262       with two members:</p>
       
   263 
       
   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>
       
   270 
       
   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>
       
   277 
       
   278       <p><code>movementX</code>/<code>Y</code> must be valid regardless of mouse
       
   279       lock state.</p>
       
   280 
       
   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>
       
   287 
       
   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>
       
   298 
       
   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>
       
   310 
       
   311     <section>
       
   312       <h2>Requirements</h2>
       
   313 
       
   314       <p>The Mouse Lock API must provide a default system action to unlock the
       
   315       mouse.</p>
       
   316 
       
   317       <p>The Mouse Lock API must be agnostic to the underlying system-specific
       
   318       mouse locking mechanism.</p>
       
   319 
       
   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>
       
   323 
       
   324     <section class='informative'>
       
   325       <h2>Use Cases</h2>
       
   326 
       
   327       <section>
       
   328         <h2>Relative view-port rotation of free moving virtual actors</h2>
       
   329 
       
   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>
       
   338 
       
   339       <section>
       
   340         <h2>Free rotation of 3D models or panning of 2D layers</h2>
       
   341 
       
   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>
       
   347 
       
   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>
       
   352 
       
   353       <section>
       
   354         <h2>Relative movement of actors</h2>
       
   355 
       
   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>
       
   363 
       
   364       <section>
       
   365         <h2>Jog movement over spinner controls</h2>
       
   366 
       
   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>
       
   377 
       
   378       <section>
       
   379         <h2>Synthetic cursor interaction with HTML DOM UI</h2>
       
   380 
       
   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>
       
   389 
       
   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>
       
   409 
       
   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>
       
   415 
       
   416       <section>
       
   417         <h2>View-port panning by moving a mouse cursor against the bounds of a
       
   418         view-port.</h2>
       
   419 
       
   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>
       
   429 
       
   430       <section>
       
   431         <h2>Game Lobby, timer based mouse lock</h2>
       
   432 
       
   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>
       
   439 
       
   440       <section>
       
   441         <h2>Game Portal</h2>
       
   442 
       
   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>
       
   448 
       
   449     </section>
       
   450 
       
   451     <section class='informative'>
       
   452       <h2>Security</h2>
       
   453 
       
   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>
       
   458 
       
   459           <li>Mouse Lock will remove the ability of a user to interact with user
       
   460           agent and operating system controls</li>
       
   461 
       
   462           <li>Mouse Lock can be called repeated by script after user exits mouse
       
   463           lock, blocking user from meaningful progress.</li>
       
   464 
       
   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>
       
   469 
       
   470         <p>Responses:</p>
       
   471         <ul>
       
   472           <li>User agents may limit what security origins may lock the mouse.</li>
       
   473 
       
   474           <li>User agents may prompt for confirmation before locking, this
       
   475           preference may be saved as a content setting.</li>
       
   476 
       
   477           <li>Keyboard based escape will always be provided, e.g.  Esc key.</li>
       
   478 
       
   479           <li>Persistent display of escape instructions can be provided.</li>
       
   480 
       
   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>
       
   484 
       
   485           <li>Changing to new tabs, windows, or any other action that causes a page
       
   486           to lose focus will exit mouse lock.</li>
       
   487 
       
   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>
       
   491 
       
   492         <p>Recommendations:</p>
       
   493         <ul>
       
   494           <li>Esc key should exit mouse lock.</li>
       
   495 
       
   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>
       
   499 
       
   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>
       
   506 
       
   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>
       
   510 
       
   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>
       
   517 
       
   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>
       
   524 
       
   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>
       
   532 
       
   533         <p>Examples of user agent scenarios:</p>
       
   534 
       
   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>
       
   545 
       
   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>
       
   552 
       
   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>
       
   558 
       
   559         <p>Chrome / Chromium has a design document page for their implementation
       
   560         of mouse lock: <a
       
   561         href="http://www.chromium.org/developers/design-documents/mouse-lock">http://www.chromium.org/developers/design-documents/mouse-lock</a></p>
       
   562 
       
   563     </section>
       
   564 
       
   565     <section class='informative'>
       
   566       <h2>Frequently Asked Questions</h2>
       
   567 
       
   568       <section>
       
   569         <h2>Why not merge with Mouse Capture: setCapture()?</h2>
       
   570 
       
   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>
       
   576 
       
   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>
       
   583 
       
   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>
       
   592 
       
   593       <section>
       
   594         <h2>Why not repurpose MouseEvent's .clientX/Y .screenX/Y?</h2>
       
   595 
       
   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>
       
   601 
       
   602       <section>
       
   603         <h2>Why use .movementX/Y instead of .deltaX/Y?</h2>
       
   604 
       
   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="http://dev.w3.org/2006/webapi/DOM-Level-3-Events/html/DOM3-Events.html#events-wheelevents">DOM
       
   609         3 'wheel' event</a>.</p>
       
   610       </section>
       
   611 
       
   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>
       
   617 
       
   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>
       
   631 
       
   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>
       
   644 
       
   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>
       
   658 
       
   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>
       
   663 
       
   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>
       
   668 
       
   669       <section>
       
   670         <h2>High resolution deltas / High frequency updates?</h2>
       
   671 
       
   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>
       
   677 
       
   678       <section>
       
   679         <h2>Why modify MouseEvent and reuse existing mouse events instead of
       
   680         creating a mouse delta event?</h2>
       
   681 
       
   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>
       
   692 
       
   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>
       
   698 
       
   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>
       
   702 
       
   703         <p>Therefore the minimal change to add movementX/Y to MouseEvent is
       
   704         selected to reduce API and implementation complexity.</p>
       
   705       </section>
       
   706 
       
   707       <section>
       
   708         <h2>Why separate targets for mouse events under mouse lock and keyboard
       
   709         input focus?</h2>
       
   710 
       
   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>
       
   718 
       
   719     </section>
       
   720 
       
   721     <section class='appendix informative'>
       
   722       <h2>Acknowledgements</h2>
       
   723 
       
   724       <p>Many have made contributions to the discussions of this
       
   725         specification:</p>
       
   726 
       
   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>
       
   741 
       
   742       <p>Please let me know if I have inadvertently omitted your name.</p>
       
   743     </section>
       
   744   </body>
     9   </body>
   745 </html>
    10 </html>