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