mouse-lock.html
author Vincent Scheib <scheib@google.com>
Tue, 25 Oct 2011 11:32:27 -0700
changeset 134 536cc04c0377
parent 133 d6110048bf5c
child 135 7df1fb3c1fbc
permissions -rw-r--r--
Mouse Lock: Work in progress on initial spec conversion: Document interface
<!DOCTYPE html>
<html lang="en">
  <head>
    <title>Mouse Lock</title>
    <meta http-equiv='Content-Type' content='text/html;charset=utf-8'/>
    <meta name="viewport" content="width=device-width">
    <!--
      === NOTA BENE ===
      For the three scripts below, if your spec resides on dev.w3 you can check them
      out in the same tree and use relative links so that they'll work offline,
     -->
    <script src='http://dev.w3.org/2009/dap/ReSpec.js/js/respec.js' class='remove'></script>
    <script class='remove'>
      var respecConfig = {
        // specification status (e.g. WD, LCWD, NOTE, etc.). If in doubt use ED.
        specStatus:           "ED",

        // the specification's short name, as in http://www.w3.org/TR/short-name/
        shortName:            "mouse-lock",

        // if your specification has a subtitle that goes below the main
        // formal title, define it here
        // subtitle   :  "an excellent document",

        // if you wish the publication date to be other than today, set this
        //publishDate:  "2011-01-01",

        // if the specification's copyright date is a range of years, specify
        // the start date here:
        // copyrightStart: "2005"

        // if there is a previously published draft, uncomment this and set its YYYY-MM-DD date
        // and its maturity status
        // previousPublishDate:  "1977-03-15",
        // previousMaturity:  "WD",

        // if there a publicly available Editor's Draft, this is the link
        edDraftURI:           "http://dvcs.w3.org/hg/webevents/raw-file/default/mouse-lock.html",

        // if this is a LCWD, uncomment and set the end of its review period
        // lcEnd: "2009-08-05",

        // if you want to have extra CSS, append them to this list
        // it is recommended that the respec.css stylesheet be kept
        extraCSS:             ["http://www.w3.org/StyleSheets/TR/W3C-TR.css", "http://dev.w3.org/2009/dap/ReSpec.js/css/respec.css"],

        // editors, add as many as you like
        // only "name" is required
        editors:  [
            { name: "Vincent Scheib", url: "http://www.scheib.net",
        company: "Google", companyURL: "http://www.google.com/" },
        ],

        // authors, add as many as you like.
        // This is optional, uncomment if you have authors as well as editors.
        // only "name" is required. Same format as editors.

        //authors:  [
        //    { name: "Your Name", url: "http://example.org/",
        //      company: "Your Company", companyURL: "http://example.com/" },
        //],

        // name of the WG
        wg:           "Web Events Working Group",

        // URI of the public WG page
        wgURI:        "http://www.w3.org/2010/webevents/",

        // name (with the @w3c.org) of the public mailing to which comments are due
        wgPublicList: "public-webevents",

        // URI of the patent status for this WG, for Rec-track documents
        // !!!! IMPORTANT !!!!
        // This is important for Rec-track documents, do not copy a patent URI from a random
        // document unless you know what you're doing. If in doubt ask your friendly neighbourhood
        // Team Contact.
        wgPatentURI:  "http://www.w3.org/2004/01/pp-impl/45559/status",
      };
    </script>

    <style type="text/css">
      .event {
        font-family: monospace;
        color: #459900;
      }

      pre.idl {
        white-space: pre-wrap;
      }
    </style>
  </head>
  <body>
    <section id='abstract'>
      This specification defines an API that provides scripted access to raw
      mouse movement data while locking the target of mouse events to a single
      element and removing the cursor from view.  This is an essential input
      mode for certain classes of applications, especially first person
      perspective 3D applications and 3D modelling software.
    </section>
    
    <section id="sotd"> <!-- Status of This Document -->
      Conversion in progress from the <a href="http://goo.gl/9G8pd">Version 
      0.8, 2011-10-20 Draft Spec</a> Google Document.
    </section>

    </section> 

    <section id='introduction' class='informative'>

      <h2>Introduction</h2>

      <p>The Mouse Lock API provides for input methods of applications based on 
      the movement of the mouse, not just the absolute position of a cursor.  A 
      popular example is that of first person movement controls in three 
      dimensional graphics applications such as games.  Movement of the mouse is 
      interpreted for rotation of the view-port, there is no limit to how far 
      movement can go, and no mouse cursor is displayed.</p>
      
      <p>Mouse Lock is related to Mouse Capture [MDCCAP].  Capture provides 
      continued event delivery to a target element while a mouse is being 
      dragged, but ceases when the mouse button is released.  Mouse Lock differs 
      by being persistent, not limited by screen boundaries, sending events 
      regardless of mouse button state, hiding the cursor, and not releasing 
      until an API call or specific release gesture by the user.</p> 

    </section>

    <section id='conformance'>
      <p class="issue" id="issue-whatever">
        Please check this section is OK . 
      </p>

      <p>
        This specification defines conformance criteria that apply to a single
        product: the <dfn id="dfn-user-agent">user agent</dfn> that implements
        the interfaces that it contains.
      </p>

      <p>
        Implementations that use ECMAScript to implement the APIs defined in
        this specification MUST implement them in a manner consistent with the
        ECMAScript Bindings defined in the Web IDL specification [[!WEBIDL]] as
        this specification uses that specification and terminology.
      </p>

      <p>
        A conforming implementation is required to implement all fields
        defined in this specification.
      </p>
    </section>

    <section>
      <h2>Extensions to the <a>Document</a> Interface</h2>
      <p>
        The <a>Document</a> interface [[!DOM-LEVEL-3-CORE]] contains methods
        providing the ability to enter, exit, and poll the state of mouse lock.
      </p>

      <dl title='partial interface Document' class='idl'>
        <dt>void lockMouse ()</dt>
        <dd>
          <dfn title="lockMouse"></dfn>

          <p>The <code>lockMouse</code> method requests that the mouse be locked 
          to a given DOM element <code>target</code>. It must immediately
          return. Two optional callback parameters provide asynchronous 
          notification of success (<code>successCallback</code>) or failure
          (<code>failureCallback</code>) to acquire the locked state. The user 
          agent must determine if mouse lock state will be entered and call the 
          appropriate callback if it was provided.  Because a user agent may 
          prompt a user for permission to enter mouse lock the response must be 
          asynchronous.</p>

          <p>Mouse lock must succeed only if the window is in focus and the 
          user-agent is the active application of the operating system. The 
          target element of <code>lockMouse</code> need not be in focus.</p>

          <p>Mouse lock must succeed only if the target element is in the DOM 
          tree. If the target element is removed from the DOM tree after mouse 
          lock is entered then mouse lock will be lost.</p>

          <p>If the mouse is already locked to the same element, a repeated 
          call to <code>lockMouse</code> will succeed and the 
          <code>successCallback</code> called. If 
          another element is locked a user agent must transfer the mouse lock to 
          the new target and call the <a>mouselocklost</a> callback for the previous 
          target.</p>

          <p>Once in the locked state the user agent must fire all relevant user 
          generated <code>MouseEvent</code> events (for example: <code>mousemove</code>, <code>mousedown</code>, 
          <code>mouseup</code>, <code>click</code>, <code>wheel</code>)[DOMMOUSE] to the target of mouse lock, and 
          not fire mouse events to other elements. Events that require the 
          concept of a mouse cursor must not be dispatched (for example: 
          <code>mouseover</code>, <code>mouseout</code>).</p>
          
          <p>In the locked state the system mouse cursor 
          must be hidden. Movement and button presses of the mouse must not 
          cause the window to lose focus.</p>

          <p>Synthetic mouse events created by application script act the same 
          regardless of lock state.<p>

          <dl class='parameters'>
            <dt>in Element target</dt> <dd></dd>
            <dt>in optional VoidCallback successCallback</dt> <dd></dd>
            <dt>in optional VoidCallback failureCallback</dt> <dd></dd>
          </dl>
        </dd>

        <dt>void unlockMouse ()</dt>
        <dd>
          <dfn title="unlockMouse"></dfn>

          <p>The <code>unlockMouse</code> method cancels the mouse lock state.
          The system mouse cursor must be displayed again and positioned at 
          the same location that it was when mouse lock was entered (the same
          location that is reported in screenX/Y when the mouse is locked).</p>
        </dd>

        <dt>Element mouseLocked ()</dt>
        <dd>
          <dfn title="mouseLocked"></dfn>

          <p>The <code>mouseLocked</code> method returns the element that is
          the current target of mouse lock, or null if not locked.</p>
        </dd>
      </dl>
    </section>

    <section>
      <h2><a>mouselocklost</a> Event</h2>

      <p>User agents must allow a new DOM event type, named
      <code>mouselocklost</code> of type <code>MouseLockLostEvent</code>
      and must fire on the element object that is the current target of
      mouse lock when mouse lock is lost or disabled for any reason.</p>

      <dl title='interface MouseLockLostEvent : Event' class='idl'>
      </dl>
    </section>

    <section class='appendix informative'>
      <h2>Acknowledgements</h2>

      <p>Many have made contributions to the discussions of this
        specification:</p>

      <ul>
        <li>Adam Barth</li>
        <li>Alexey Proskuryakov</li>
        <li>Aryeh Gregor</li>
        <li>Brandon Andrews</li>
        <li>Glenn Maynard</li>
        <li>Gregg Tavares</li>
        <li>John Villar</li>
        <li>Jonas Sicking</li>
        <li>Klaas Heidstra</li>
        <li>Olli Pettay</li>
        <li>Robert O'Callahan</li>
        <li>Tab Atkins Jr.</li>
      </ul>

      <p>Please let me know if I have inadvertently omitted your name.</p>
    </section>
  </body>
</html>