mouse-lock.html
changeset 136 e6b893606800
parent 135 7df1fb3c1fbc
child 137 2a0c78eeaa2d
equal deleted inserted replaced
135:7df1fb3c1fbc 136:e6b893606800
   146         defined in this specification.
   146         defined in this specification.
   147       </p>
   147       </p>
   148     </section>
   148     </section>
   149 
   149 
   150     <section>
   150     <section>
   151       <h2>Extensions to the <a>Document</a> Interface</h2>
   151       <h2>Extensions to the <a>Navigator</a> Interface</h2>
   152       <p>
   152       <p>
   153         The <a>Document</a> interface [[!DOM-LEVEL-3-CORE]] contains methods
   153         The <a>Navigator</a> interface [[!NAVIGATOR]] contains a
       
   154         <code>pointer</code> attribute providing access to the
       
   155         <a>MouseLockable</a> interface.
       
   156       </p>
       
   157 
       
   158       <dl title='partial interface Navigator' class='idl'>
       
   159         <dt>readonly attribute MouseLockable pointer</dt>
       
   160         <dd>
       
   161           <dfn title="pointer"></dfn>
       
   162         </dd>
       
   163       </dl>
       
   164     </section>
       
   165 
       
   166     <section>
       
   167       <h2><a>MouseLockable</a> Interface</h2>
       
   168       <p>
       
   169         The <a>MouseLockable</a> interface contains methods
   154         providing the ability to enter, exit, and poll the state of mouse lock.
   170         providing the ability to enter, exit, and poll the state of mouse lock.
   155       </p>
   171       </p>
   156 
   172 
   157       <dl title='partial interface Document' class='idl'>
   173       <dl title='interface MouseLockable' class='idl'>
   158         <dt>void lockMouse ()</dt>
   174         <dt>void lock ()</dt>
   159         <dd>
   175         <dd>
   160           <dfn title="lockMouse"></dfn>
   176           <dfn title="lock"></dfn>
   161 
   177 
   162           <p>The <code>lockMouse</code> method requests that the mouse be locked
   178           <p>The <code>lock</code> method requests that the mouse be locked
   163           to a given DOM element <code>target</code>. It must immediately
   179           to a given DOM element <code><dfn>target</dfn></code>. It must immediately
   164           return. Two optional callback parameters provide asynchronous
   180           return. Two optional callback parameters provide asynchronous
   165           notification of success (<code>successCallback</code>) or failure
   181           notification of success (<code>successCallback</code>) or failure
   166           (<code>failureCallback</code>) to acquire the locked state. The user
   182           (<code>failureCallback</code>) to acquire the locked state. The user
   167           agent must determine if mouse lock state will be entered and call the
   183           agent must determine if mouse lock state will be entered and call the
   168           appropriate callback if it was provided.  Because a <a>user agent</a> may
   184           appropriate callback if it was provided.  Because a <a>user agent</a> may
   169           prompt a user for permission to enter mouse lock the response must be
   185           prompt a user for permission to enter mouse lock the response must be
   170           asynchronous.</p>
   186           asynchronous.</p>
   171 
   187 
   172           <p>Mouse lock must succeed only if the window is in focus and the
   188           <p>Mouse lock must succeed only if the window is in focus and the
   173           user-agent is the active application of the operating system. The
   189           user-agent is the active application of the operating system. The
   174           target element of <code>lockMouse</code> need not be in focus.</p>
   190           <code>target</code> of <code>lock</code> need not be in focus.</p>
   175 
   191 
   176           <p>Mouse lock must succeed only if the target element is in the DOM
   192           <p>Mouse lock must succeed only if the <code>target</code> is in the DOM
   177           tree. If the target element is removed from the DOM tree after mouse
   193           tree.  If the <code>target</code> is removed from the DOM tree after mouse
   178           lock is entered then mouse lock will be lost.</p>
   194           lock is entered then mouse lock will be lost.</p>
   179 
   195 
   180           <p>If the mouse is already locked to the same element, a repeated
   196           <p>If the mouse is already locked to the same element, a repeated call to
   181           call to <code>lockMouse</code> will succeed and the
   197           <code>lock</code> will succeed and the <code>successCallback</code>
   182           <code>successCallback</code> called. If
   198           called.  If another element is locked a <a>user agent</a> must transfer
   183           another element is locked a <a>user agent</a> must transfer the mouse lock to
   199           the mouse lock to the new <code>target</code> and call the
   184           the new target and call the <a><code>mouselocklost</code></a> callback for the previous
   200           <a><code>mouselocklost</code></a> callback for the previous target.</p>
   185           target.</p>
       
   186 
   201 
   187           <p>Once in the locked state the <a>user agent</a> must fire all relevant
   202           <p>Once in the locked state the <a>user agent</a> must fire all relevant
   188           user generated <code>MouseEvent</code> events (for example:
   203           user generated <code>MouseEvent</code> events (for example:
   189           <code>mousemove</code>, <code>mousedown</code>, <code>mouseup</code>,
   204           <code>mousemove</code>, <code>mousedown</code>, <code>mouseup</code>,
   190           <code>click</code>, <code>wheel</code>)[<a
   205           <code>click</code>, <code>wheel</code>)[<a
   191           href="http://dev.w3.org/2006/webapi/DOM-Level-3-Events/html/DOM3-Events.html#events-MouseEvent">DOMMOUSE</a>]
   206           href="http://dev.w3.org/2006/webapi/DOM-Level-3-Events/html/DOM3-Events.html#events-MouseEvent">DOMMOUSE</a>]
   192           to the target of mouse lock, and not fire mouse events to other elements.
   207           to the <code>target</code> of mouse lock, and not fire mouse events to
   193           Events that require the concept of a mouse cursor must not be dispatched
   208           other elements.  Events that require the concept of a mouse cursor must
   194           (for example: <code>mouseover</code>, <code>mouseout</code>).</p>
   209           not be dispatched (for example: <code>mouseover</code>,
       
   210           <code>mouseout</code>).</p>
   195 
   211 
   196           <p>In the locked state the system mouse cursor
   212           <p>In the locked state the system mouse cursor
   197           must be hidden. Movement and button presses of the mouse must not
   213           must be hidden. Movement and button presses of the mouse must not
   198           cause the window to lose focus.</p>
   214           cause the window to lose focus.</p>
   199 
   215 
   205             <dt>in optional VoidCallback successCallback</dt> <dd></dd>
   221             <dt>in optional VoidCallback successCallback</dt> <dd></dd>
   206             <dt>in optional VoidCallback failureCallback</dt> <dd></dd>
   222             <dt>in optional VoidCallback failureCallback</dt> <dd></dd>
   207           </dl>
   223           </dl>
   208         </dd>
   224         </dd>
   209 
   225 
   210         <dt>void unlockMouse ()</dt>
   226         <dt>void unlock ()</dt>
   211         <dd>
   227         <dd>
   212           <dfn title="unlockMouse"></dfn>
   228           <dfn title="unlock"></dfn>
   213 
   229 
   214           <p>The <code>unlockMouse</code> method cancels the mouse lock state.
   230           <p>The <code>unlock</code> method cancels the mouse lock state.
   215           The system mouse cursor must be displayed again and positioned at
   231           The system mouse cursor must be displayed again and positioned at
   216           the same location that it was when mouse lock was entered (the same
   232           the same location that it was when mouse lock was entered (the same
   217           location that is reported in <code>screenX</code>/<code>Y</code>
   233           location that is reported in <code>screenX</code>/<code>Y</code>
   218           when the mouse is locked).</p>
   234           when the mouse is locked).</p>
   219         </dd>
   235         </dd>
   220 
   236 
   221         <dt>Element mouseLocked ()</dt>
   237         <dt>bool islocked ()</dt>
   222         <dd>
   238         <dd>
   223           <dfn title="mouseLocked"></dfn>
   239           <dfn title="islocked"></dfn>
   224 
   240 
   225           <p>The <code>mouseLocked</code> method returns the element that is
   241           <p>The <code>islocked</code> method returns true is the mouse is
   226           the current target of mouse lock, or null if not locked.</p>
   242           currently locked.</p>
   227         </dd>
   243         </dd>
   228       </dl>
   244       </dl>
   229     </section>
   245     </section>
   230 
   246 
   231     <section>
   247     <section>
   232       <h2><dfn><code>mouselocklost</code></dfn> Event</h2>
   248       <h2><dfn><code>mouselocklost</code></dfn> Event</h2>
   233 
   249 
   234       <p>User agents must allow a new DOM event type, named
   250       <p>When mouse lock is lost or disabled for any reason <a>user agents</a>
   235       <code>mouselocklost</code> of type <code>MouseLockLostEvent</code>
   251       must <a
   236       and must fire on the element object that is the current target of
   252       href="http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#concept-event-fire">fire
   237       mouse lock when mouse lock is lost or disabled for any reason.</p>
   253       an event</a> named <code>mouselocklost</code> with its
   238 
   254       <code>bubble</code> attribute set to true to the mouse lock
   239       <dl title='interface MouseLockLostEvent : Event' class='idl'>
   255       <a>target</a> element.</p>
   240       </dl>
       
   241     </section>
   256     </section>
   242 
   257 
   243     <section>
   258     <section>
   244       <h2>Extensions to the <a>MouseEvent</a> Interface</h2>
   259       <h2>Extensions to the <a>MouseEvent</a> Interface</h2>
   245 
   260 
   445           <li>User agents may limit what security origins may lock the mouse.</li>
   460           <li>User agents may limit what security origins may lock the mouse.</li>
   446 
   461 
   447           <li>User agents may prompt for confirmation before locking, this
   462           <li>User agents may prompt for confirmation before locking, this
   448           preference may be saved as a content setting.</li>
   463           preference may be saved as a content setting.</li>
   449 
   464 
   450           <li>Keyboard based escape will always be provided, e.g.  ESC key.</li>
   465           <li>Keyboard based escape will always be provided, e.g.  Esc key.</li>
   451 
   466 
   452           <li>Persistent display of escape instructions can be provided.</li>
   467           <li>Persistent display of escape instructions can be provided.</li>
   453 
   468 
   454           <li>Repeated escapes of mouse lock can signal <a>user agent</a> to not re-lock
   469           <li>Repeated escapes of mouse lock can signal <a>user agent</a> to not re-lock
   455           the mouse without more specific user intent gesture, e.g.  similar to how
   470           the mouse without more specific user intent gesture, e.g.  similar to how
   462           agent and operating system.</li>
   477           agent and operating system.</li>
   463         </ul>
   478         </ul>
   464 
   479 
   465         <p>Recommendations:</p>
   480         <p>Recommendations:</p>
   466         <ul>
   481         <ul>
   467           <li>ESC key should exit mouse lock.</li>
   482           <li>Esc key should exit mouse lock.</li>
   468 
   483 
   469           <li>Preferences per sub-domain can be used to allow or block mouse lock,
   484           <li>Preferences per sub-domain can be used to allow or block mouse lock,
   470           similar to popup, geolocation, and fullscreen.</li>
   485           similar to pop-up, geolocation, and fullscreen.</li>
   471         </ul>
   486         </ul>
   472 
   487 
   473         <p>Mouse Lock is a required user interaction mode for certain application
   488         <p>Mouse Lock is a required user interaction mode for certain application
   474         types, but carries a usability concern if maliciously used.  An attacker
   489         types, but carries a usability concern if maliciously used.  An attacker
   475         could remove the ability for a user to control their mouse cursor on their
   490         could remove the ability for a user to control their mouse cursor on their
   482         discussion illustrates considerations and plausible implementations.</p>
   497         discussion illustrates considerations and plausible implementations.</p>
   483 
   498 
   484         <dl>
   499         <dl>
   485           <dt>Escape from mouse lock must always be possible.</dt>
   500           <dt>Escape from mouse lock must always be possible.</dt>
   486           <dd>Based on device the mechanisms will vary, but obvious examples include
   501           <dd>Based on device the mechanisms will vary, but obvious examples include
   487           the keyboard escape key "ESC" and any control that moves the system focus
   502           the keyboard escape key "Esc" and any control that moves the system focus
   488           away from the web page (window management keystrokes that change windows,
   503           away from the web page (window management keystrokes that change windows,
   489           operating system buttons such as the Windows key).</dd>
   504           operating system buttons such as the Windows key).</dd>
   490 
   505 
   491           <dt>Escape instructions may be communicated.</dt>
   506           <dt>Escape instructions may be communicated.</dt>
   492           <dd>User agents can provide persistent on screen instructions, or
   507           <dd>User agents can provide persistent on screen instructions, or
   522           shown, likely for a brief period of time to not detriment the full screen
   537           shown, likely for a brief period of time to not detriment the full screen
   523           experience.  Entry to mouse lock may be gated by a user explicitly
   538           experience.  Entry to mouse lock may be gated by a user explicitly
   524           confirming the action via a dialog.</dd>
   539           confirming the action via a dialog.</dd>
   525 
   540 
   526           <dt>A permissive approach</dt>
   541           <dt>A permissive approach</dt>
   527           <dd>May permit mouse lock for the target or ancestor of a a user gesture
   542           <dd>May permit mouse lock for the target or ancestor of a user gesture
   528           without prompt.  Escape instructions would likely be displayed
   543           target without prompt.  Escape instructions would likely be displayed
   529           persistently in a non full screen view.</dd>
   544           persistently in a non full screen view.</dd>
   530         </dl>
   545         </dl>
   531 
   546 
   532         <p>Chrome / Chromium has a design document page for their implementation
   547         <p>Chrome / Chromium has a design document page for their implementation
   533         of mouse lock: <a
   548         of mouse lock: <a
   542         <h2>Why not merge with Mouse Capture: setCapture()?</h2>
   557         <h2>Why not merge with Mouse Capture: setCapture()?</h2>
   543 
   558 
   544         <p>Mouse Capture [<a
   559         <p>Mouse Capture [<a
   545         href="https://developer.mozilla.org/en/DOM/element.setCapture">MDCCAP</a>]
   560         href="https://developer.mozilla.org/en/DOM/element.setCapture">MDCCAP</a>]
   546         handles low security risk mouse event target lock for the duration of a
   561         handles low security risk mouse event target lock for the duration of a
   547         mouse drag gesture.  Mouse Lock removes the concept the the cursor and
   562         mouse drag gesture.  Mouse Lock removes the concept of the cursor and
   548         directs all events to a given target.  They are related, but
   563         directs all events to a given target.  They are related, but
   549         different.</p>
   564         different.</p>
   550 
   565 
   551         <p>If a browser implemented both, it would be reasonable to support a
   566         <p>If a browser implemented both, it would be reasonable to support a
   552         combination of traits: The security simplicity of "automatically release
   567         combination of traits: The security simplicity of "automatically release
   553         lock when mouse up" and the increased functionality of total control over
   568         lock when mouse up" and the increased functionality of total control over
   554         mouse input and removal of the system cursor.  The security trait would
   569         mouse input and removal of the system cursor.  The security trait would
   555         allow more permissive use of the feature for applications that only
   570         allow more permissive use of the feature for applications that only
   556         required a short burst of mouse lock during a drag event.</p>
   571         required a short burst of mouse lock during a drag event.</p>
   557 
   572 
   558         <p>This functionaility is omitted from the initial version of this spec
   573         <p>This functionality is omitted from the initial version of this spec
   559         because it helps the minor use cases in windowed mode but we still do not
   574         because it helps the minor use cases in windowed mode but we still do not
   560         have an implementation solving the major ones.  And, to implement this a
   575         have an implementation solving the major ones.  And, to implement this a
   561         browser must implement both, which none does yet.  It is not clear if this
   576         browser must implement both, which none does yet.  It is not clear if this
   562         feature should live on .lockMouse or on .setCapture.  If both were
   577         feature should live on .lock or on .setCapture.  If both were
   563         implemented, either API could be augmented fairly easily to offer the
   578         implemented, either API could be augmented fairly easily to offer the
   564         hybrid functionality.</p>
   579         hybrid functionality.</p>
   565       </section>
   580       </section>
   566 
   581 
   567       <section>
   582       <section>
   575 
   590 
   576       <section>
   591       <section>
   577         <h2>Why use .movementX/Y instead of .deltaX/Y?</h2>
   592         <h2>Why use .movementX/Y instead of .deltaX/Y?</h2>
   578 
   593 
   579         <p>When the mouse is locked 'wheel' events should be sent to the mouse
   594         <p>When the mouse is locked 'wheel' events should be sent to the mouse
   580         lock target element just as 'mousemove' events are.  There is a naming
   595         lock <a>target</a> element just as 'mousemove' events are.  There is a naming
   581         conflict with .deltaX/Y/Z as defined in <a
   596         conflict with .deltaX/Y/Z as defined in <a
   582         href="http://dev.w3.org/2006/webapi/DOM-Level-3-Events/html/DOM3-Events.html#events-wheelevents">DOM
   597         href="http://dev.w3.org/2006/webapi/DOM-Level-3-Events/html/DOM3-Events.html#events-wheelevents">DOM
   583         3 'wheel' event</a>.</p>
   598         3 'wheel' event</a>.</p>
   584       </section>
   599       </section>
   585 
   600 
   586       <section>
   601       <section>
   587         <h2>Why bundle all functionality (hiding cursor, providing mouse deltas)
   602         <h2>Why bundle all functionality (hiding cursor, providing mouse deltas)
   588         instead of using CSS to hide the cursor, always providing delta values,
   603         instead of using CSS to hide the cursor, always providing delta values,
   589         and offering an API to restrict the cursor movement to a portion of the
   604         and offering an API to restrict the cursor movement to a portion of the
   590         webpage?</h2>
   605         web page?</h2>
   591 
   606 
   592         <p>There are good motivations to provide a more fine grained approach.
   607         <p>There are good motivations to provide a more fine grained approach.
   593         E.g.  the use case "View-port panning by moving a mouse cursor against the
   608         E.g.  the use case "View-port panning by moving a mouse cursor against the
   594         bounds of a view-port" doesn't require hiding the mouse cursor, only
   609         bounds of a view-port" doesn't require hiding the mouse cursor, only
   595         bounding it and always having delta values available.  Also, this
   610         bounding it and always having delta values available.  Also, this
   624         to bound the cursor to a specific rectangle, and prototypes have not yet
   639         to bound the cursor to a specific rectangle, and prototypes have not yet
   625         been developed to demonstrate building that behavior by e.g.  invisible
   640         been developed to demonstrate building that behavior by e.g.  invisible
   626         windows with xlib or manual cursor movement on Mac.  Unaccelerated Delta
   641         windows with xlib or manual cursor movement on Mac.  Unaccelerated Delta
   627         values have been proposed to be accessed by reading raw Human Interface
   642         values have been proposed to be accessed by reading raw Human Interface
   628         Device (HID) data.  E.g.  WM_INPUT messages on windows, and USB device
   643         Device (HID) data.  E.g.  WM_INPUT messages on windows, and USB device
   629         apis on Mac / Linux.  The challenge here is interpreting and normalizing
   644         APIs on Mac / Linux.  The challenge here is interpreting and normalizing
   630         the units to some consistent and specifiable scale.  Also, most APIs
   645         the units to some consistent and specifiable scale.  Also, most APIs
   631         considered to date are limited to USB devices.</p>
   646         considered to date are limited to USB devices.</p>
   632 
   647 
   633         <p>It would be reasonable to consider adding these capabilities in the
   648         <p>It would be reasonable to consider adding these capabilities in the
   634         future, as the currently specified mouse lock API would be easy to
   649         future, as the currently specified mouse lock API would be easy to
   644         <h2>High resolution deltas / High frequency updates?</h2>
   659         <h2>High resolution deltas / High frequency updates?</h2>
   645 
   660 
   646         <p>Not yet, for the same reasons in the previous Q.  See "Why bundle all
   661         <p>Not yet, for the same reasons in the previous Q.  See "Why bundle all
   647         functionality (hiding cursor, providing mouse deltas) instead of using CSS
   662         functionality (hiding cursor, providing mouse deltas) instead of using CSS
   648         to hide the cursor, always providing delta values, and offering an API to
   663         to hide the cursor, always providing delta values, and offering an API to
   649         restrict the cursor movement to a portion of the webpage?" above.</p>
   664         restrict the cursor movement to a portion of the web page?" above.</p>
   650       </section>
   665       </section>
   651 
   666 
   652       <section>
   667       <section>
   653         <h2>Why modify MouseEvent and reuse existing mouse events instead of
   668         <h2>Why modify MouseEvent and reuse existing mouse events instead of
   654         creating a mousedelta event?</h2>
   669         creating a mouse delta event?</h2>
   655 
   670 
   656         <p>When under mouse lock many mouse events remain relevant, e.g.  click,
   671         <p>When under mouse lock many mouse events remain relevant, e.g.  click,
   657         mousedown, etc.  These all share the same event data structure MouseEvent.
   672         mousedown, etc.  These all share the same event data structure MouseEvent.
   658         If movement data were reported via a new data structure then a new event
   673         If movement data were reported via a new data structure then a new event
   659         would be needed for reporting delta movement.  The new data structure
   674         would be needed for reporting delta movement.  The new data structure
   660         would have many parallels to MouseEvent to offer the same conveniences,
   675         would have many parallels to MouseEvent to offer the same conveniences,
   661         e.g.  button and modifier key states.  When handling click, down, and up
   676         e.g.  button and modifier key states.  When handling click, down, and up
   662         events would the existing mousedown, mouseup be used?  If so, they would
   677         events would the existing mousedown, mouseup be used?  If so, they would
   663         provide .clientX/Y and .screenX/Y with no useful data, but would lack the
   678         provide .clientX/Y and .screenX/Y with no useful data, but would lack the
   664         convenience of containing the current movement data.  Or, new events would
   679         convenience of containing the current movement data.  Or, new events would
   665         also be required for when the moues is locked.</p>
   680         also be required for when the mouse is locked.</p>
   666 
   681 
   667         <p>Also, movementX/Y are convenient even when the mouse is not locked.
   682         <p>Also, movementX/Y are convenient even when the mouse is not locked.
   668         This spec requires movement members to always be valid, even when the
   683         This spec requires movement members to always be valid, even when the
   669         mouse cursor exists.  This reduces code required to track the last cursor
   684         mouse cursor exists.  This reduces code required to track the last cursor
   670         state and mouseover/mouseout transistions if applications which to make
   685         state and mouseover/mouseout transitions if applications wish to make
   671         use of delta motion of the mouse.  This may be convenient even if the
   686         use of delta motion of the mouse.</p>
   672         mouse is not fully locked and the deficiencies of no locked target of
       
   673         events, out of window, and screen borders clamping dat exist.</p>
       
   674 
   687 
   675         <p>The only negative of adding movementX/Y to MouseEvent appears to be the
   688         <p>The only negative of adding movementX/Y to MouseEvent appears to be the
   676         unused values in clientX/Y and screenX/Y when under mouse lock.  This does
   689         unused values in clientX/Y and screenX/Y when under mouse lock.  This does
   677         not seem to be a significant problem.</p>
   690         not seem to be a significant problem.</p>
   678 
   691 
   686 
   699 
   687         <p>Consider a game with a 3D view controlled by moving the mouse cursor,
   700         <p>Consider a game with a 3D view controlled by moving the mouse cursor,
   688         while the user may still chat with other users via a text console.  It is
   701         while the user may still chat with other users via a text console.  It is
   689         reasonable for the application to accept text input to an element that is
   702         reasonable for the application to accept text input to an element that is
   690         different than where mouse events are being dispatched.  This is similar
   703         different than where mouse events are being dispatched.  This is similar
   691         to preexisting behavior of receiving mousemove events over any element
   704         to pre-existing behavior of receiving mousemove events over any element
   692         while typing into a form on a page.</p>
   705         while typing into a form on a page.</p>
   693       </section>
   706       </section>
   694 
   707 
   695     </section>
   708     </section>
   696 
   709