mouse-lock.html
author Vincent Scheib <scheib@google.com>
Tue, 25 Oct 2011 15:53:34 -0700
changeset 135 7df1fb3c1fbc
parent 134 536cc04c0377
child 136 e6b893606800
permissions -rw-r--r--
Mouse Lock: Converted spec from Google Doc.
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
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   121
      <p>Mouse Lock is related to Mouse Capture [MDCCAP].  Capture provides
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>
134
536cc04c0377 Mouse Lock: Work in progress on initial spec conversion: Document interface
Vincent Scheib <scheib@google.com>
parents: 133
diff changeset
   151
      <h2>Extensions to the <a>Document</a> Interface</h2>
132
4ec3f28f3e93 Mouse Lock: Work in progress on initial spec conversion
Vincent Scheib <scheib@google.com>
parents:
diff changeset
   152
      <p>
4ec3f28f3e93 Mouse Lock: Work in progress on initial spec conversion
Vincent Scheib <scheib@google.com>
parents:
diff changeset
   153
        The <a>Document</a> interface [[!DOM-LEVEL-3-CORE]] contains methods
4ec3f28f3e93 Mouse Lock: Work in progress on initial spec conversion
Vincent Scheib <scheib@google.com>
parents:
diff changeset
   154
        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
   155
      </p>
4ec3f28f3e93 Mouse Lock: Work in progress on initial spec conversion
Vincent Scheib <scheib@google.com>
parents:
diff changeset
   156
4ec3f28f3e93 Mouse Lock: Work in progress on initial spec conversion
Vincent Scheib <scheib@google.com>
parents:
diff changeset
   157
      <dl title='partial interface Document' class='idl'>
134
536cc04c0377 Mouse Lock: Work in progress on initial spec conversion: Document interface
Vincent Scheib <scheib@google.com>
parents: 133
diff changeset
   158
        <dt>void lockMouse ()</dt>
132
4ec3f28f3e93 Mouse Lock: Work in progress on initial spec conversion
Vincent Scheib <scheib@google.com>
parents:
diff changeset
   159
        <dd>
134
536cc04c0377 Mouse Lock: Work in progress on initial spec conversion: Document interface
Vincent Scheib <scheib@google.com>
parents: 133
diff changeset
   160
          <dfn title="lockMouse"></dfn>
536cc04c0377 Mouse Lock: Work in progress on initial spec conversion: Document interface
Vincent Scheib <scheib@google.com>
parents: 133
diff changeset
   161
135
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   162
          <p>The <code>lockMouse</code> method requests that the mouse be locked
133
d6110048bf5c Mouse Lock: Work in progress on initial spec conversion: Document interface
Vincent Scheib <scheib@google.com>
parents: 132
diff changeset
   163
          to a given DOM element <code>target</code>. It must immediately
135
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   164
          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
   165
          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
   166
          (<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
   167
          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
   168
          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
   169
          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
   170
          asynchronous.</p>
d6110048bf5c Mouse Lock: Work in progress on initial spec conversion: Document interface
Vincent Scheib <scheib@google.com>
parents: 132
diff changeset
   171
135
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   172
          <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
   173
          user-agent is the active application of the operating system. The
134
536cc04c0377 Mouse Lock: Work in progress on initial spec conversion: Document interface
Vincent Scheib <scheib@google.com>
parents: 133
diff changeset
   174
          target element of <code>lockMouse</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
   175
135
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   176
          <p>Mouse lock must succeed only if the target element is in the DOM
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   177
          tree. If the target element 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
   178
          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
   179
135
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   180
          <p>If the mouse is already locked to the same element, a repeated
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   181
          call to <code>lockMouse</code> will succeed and the
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   182
          <code>successCallback</code> called. If
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   183
          another element is locked a <a>user agent</a> must transfer the mouse lock to
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   184
          the new target and call the <a><code>mouselocklost</code></a> callback for the previous
133
d6110048bf5c Mouse Lock: Work in progress on initial spec conversion: Document interface
Vincent Scheib <scheib@google.com>
parents: 132
diff changeset
   185
          target.</p>
d6110048bf5c Mouse Lock: Work in progress on initial spec conversion: Document interface
Vincent Scheib <scheib@google.com>
parents: 132
diff changeset
   186
135
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   187
          <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
   188
          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
   189
          <code>mousemove</code>, <code>mousedown</code>, <code>mouseup</code>,
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   190
          <code>click</code>, <code>wheel</code>)[<a
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   191
          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
   192
          to the target of mouse lock, and not fire mouse events to other elements.
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   193
          Events that require the concept of a mouse cursor must not be dispatched
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   194
          (for example: <code>mouseover</code>, <code>mouseout</code>).</p>
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   195
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   196
          <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
   197
          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
   198
          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
   199
135
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   200
          <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
   201
          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
   202
134
536cc04c0377 Mouse Lock: Work in progress on initial spec conversion: Document interface
Vincent Scheib <scheib@google.com>
parents: 133
diff changeset
   203
          <dl class='parameters'>
536cc04c0377 Mouse Lock: Work in progress on initial spec conversion: Document interface
Vincent Scheib <scheib@google.com>
parents: 133
diff changeset
   204
            <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
   205
            <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
   206
            <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
   207
          </dl>
536cc04c0377 Mouse Lock: Work in progress on initial spec conversion: Document interface
Vincent Scheib <scheib@google.com>
parents: 133
diff changeset
   208
        </dd>
536cc04c0377 Mouse Lock: Work in progress on initial spec conversion: Document interface
Vincent Scheib <scheib@google.com>
parents: 133
diff changeset
   209
536cc04c0377 Mouse Lock: Work in progress on initial spec conversion: Document interface
Vincent Scheib <scheib@google.com>
parents: 133
diff changeset
   210
        <dt>void unlockMouse ()</dt>
536cc04c0377 Mouse Lock: Work in progress on initial spec conversion: Document interface
Vincent Scheib <scheib@google.com>
parents: 133
diff changeset
   211
        <dd>
536cc04c0377 Mouse Lock: Work in progress on initial spec conversion: Document interface
Vincent Scheib <scheib@google.com>
parents: 133
diff changeset
   212
          <dfn title="unlockMouse"></dfn>
536cc04c0377 Mouse Lock: Work in progress on initial spec conversion: Document interface
Vincent Scheib <scheib@google.com>
parents: 133
diff changeset
   213
536cc04c0377 Mouse Lock: Work in progress on initial spec conversion: Document interface
Vincent Scheib <scheib@google.com>
parents: 133
diff changeset
   214
          <p>The <code>unlockMouse</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
   215
          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
   216
          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
   217
          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
   218
          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
   219
        </dd>
536cc04c0377 Mouse Lock: Work in progress on initial spec conversion: Document interface
Vincent Scheib <scheib@google.com>
parents: 133
diff changeset
   220
536cc04c0377 Mouse Lock: Work in progress on initial spec conversion: Document interface
Vincent Scheib <scheib@google.com>
parents: 133
diff changeset
   221
        <dt>Element mouseLocked ()</dt>
536cc04c0377 Mouse Lock: Work in progress on initial spec conversion: Document interface
Vincent Scheib <scheib@google.com>
parents: 133
diff changeset
   222
        <dd>
536cc04c0377 Mouse Lock: Work in progress on initial spec conversion: Document interface
Vincent Scheib <scheib@google.com>
parents: 133
diff changeset
   223
          <dfn title="mouseLocked"></dfn>
536cc04c0377 Mouse Lock: Work in progress on initial spec conversion: Document interface
Vincent Scheib <scheib@google.com>
parents: 133
diff changeset
   224
536cc04c0377 Mouse Lock: Work in progress on initial spec conversion: Document interface
Vincent Scheib <scheib@google.com>
parents: 133
diff changeset
   225
          <p>The <code>mouseLocked</code> method returns the element that is
536cc04c0377 Mouse Lock: Work in progress on initial spec conversion: Document interface
Vincent Scheib <scheib@google.com>
parents: 133
diff changeset
   226
          the current target of mouse lock, or null if not locked.</p>
132
4ec3f28f3e93 Mouse Lock: Work in progress on initial spec conversion
Vincent Scheib <scheib@google.com>
parents:
diff changeset
   227
        </dd>
4ec3f28f3e93 Mouse Lock: Work in progress on initial spec conversion
Vincent Scheib <scheib@google.com>
parents:
diff changeset
   228
      </dl>
4ec3f28f3e93 Mouse Lock: Work in progress on initial spec conversion
Vincent Scheib <scheib@google.com>
parents:
diff changeset
   229
    </section>
4ec3f28f3e93 Mouse Lock: Work in progress on initial spec conversion
Vincent Scheib <scheib@google.com>
parents:
diff changeset
   230
134
536cc04c0377 Mouse Lock: Work in progress on initial spec conversion: Document interface
Vincent Scheib <scheib@google.com>
parents: 133
diff changeset
   231
    <section>
135
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   232
      <h2><dfn><code>mouselocklost</code></dfn> Event</h2>
132
4ec3f28f3e93 Mouse Lock: Work in progress on initial spec conversion
Vincent Scheib <scheib@google.com>
parents:
diff changeset
   233
134
536cc04c0377 Mouse Lock: Work in progress on initial spec conversion: Document interface
Vincent Scheib <scheib@google.com>
parents: 133
diff changeset
   234
      <p>User agents must allow a new DOM event type, named
536cc04c0377 Mouse Lock: Work in progress on initial spec conversion: Document interface
Vincent Scheib <scheib@google.com>
parents: 133
diff changeset
   235
      <code>mouselocklost</code> of type <code>MouseLockLostEvent</code>
536cc04c0377 Mouse Lock: Work in progress on initial spec conversion: Document interface
Vincent Scheib <scheib@google.com>
parents: 133
diff changeset
   236
      and must fire on the element object that is the current target of
536cc04c0377 Mouse Lock: Work in progress on initial spec conversion: Document interface
Vincent Scheib <scheib@google.com>
parents: 133
diff changeset
   237
      mouse lock when mouse lock is lost or disabled for any reason.</p>
536cc04c0377 Mouse Lock: Work in progress on initial spec conversion: Document interface
Vincent Scheib <scheib@google.com>
parents: 133
diff changeset
   238
536cc04c0377 Mouse Lock: Work in progress on initial spec conversion: Document interface
Vincent Scheib <scheib@google.com>
parents: 133
diff changeset
   239
      <dl title='interface MouseLockLostEvent : Event' class='idl'>
536cc04c0377 Mouse Lock: Work in progress on initial spec conversion: Document interface
Vincent Scheib <scheib@google.com>
parents: 133
diff changeset
   240
      </dl>
536cc04c0377 Mouse Lock: Work in progress on initial spec conversion: Document interface
Vincent Scheib <scheib@google.com>
parents: 133
diff changeset
   241
    </section>
132
4ec3f28f3e93 Mouse Lock: Work in progress on initial spec conversion
Vincent Scheib <scheib@google.com>
parents:
diff changeset
   242
135
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   243
    <section>
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   244
      <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
   245
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   246
      <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
   247
      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
   248
      with two members:</p>
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   249
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   250
      <dl title='partial interface MouseEvent' class='idl'>
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   251
        <dt>readonly attribute long movementX</dt>
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   252
        <dd><dfn title="movementX"></dfn></dd>
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   253
        <dt>readonly attribute long movementY</dt>
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   254
        <dd><dfn title="movementY"></dfn></dd>
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   255
      </dl>
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   256
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   257
      <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
   258
      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
   259
      <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
   260
      <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
   261
      <code>ePrevious</code> and the difference taken
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   262
      <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
   263
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   264
      <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
   265
      lock state.</p>
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   266
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   267
      <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
   268
      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
   269
      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
   270
      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
   271
      <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
   272
      to zero.</p>
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   273
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   274
      <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
   275
      <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
   276
      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
   277
      <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
   278
      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
   279
      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
   280
      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
   281
      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
   282
      by a screen edge.</p>
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   283
    </section>
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   284
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   285
    <section>
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   286
      <h2>Requirements</h2>
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>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
   289
      mouse.</p>
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   290
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   291
      <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
   292
      mouse locking mechanism.</p>
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   293
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   294
      <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
   295
      window, or tab loses focus.</p>
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   296
    </section>
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   297
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   298
    <section class='informative'>
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   299
      <h2>Use Cases</h2>
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   300
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   301
      <section>
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   302
        <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
   303
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   304
        <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
   305
        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
   306
        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
   307
        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
   308
        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
   309
        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
   310
        mouse movement.</p>
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   311
      </section>
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   312
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   313
      <section>
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   314
        <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
   315
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   316
        <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
   317
        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
   318
        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
   319
        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
   320
        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
   321
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   322
        <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
   323
        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
   324
        limits.</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>Relative movement of actors</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>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
   331
        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
   332
        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
   333
        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
   334
        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
   335
        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
   336
      </section>
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   337
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   338
      <section>
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   339
        <h2>Jog movement over spinner controls</h2>
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
        <p>When modifying numerically magnitudes in applications sometimes the
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   342
        user will prefer to "drag" a numeric control (e.g.  a spinner [<a
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   343
        href="http://books.zkoss.org/wiki/Small%20Talks/2008/June/Using%20Spinner%20Component">ZKSPINNER</a>])
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   344
        by its button handles to increment or decrement the numeric value.  An
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   345
        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
   346
        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
   347
        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
   348
        "jog".</p>
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   349
      </section>
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   350
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   351
      <section>
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   352
        <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
   353
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   354
        <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
   355
        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
   356
        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
   357
        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
   358
        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
   359
        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
   360
        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
   361
        the mouse is locked:</p>
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   362
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   363
        <pre class='example' data-transform='escapeContents'>
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   364
            document.addEventListener("click", function (e) {
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   365
              if (e._isSynthetic)
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   366
                return;
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   367
              // send a synthetic click
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   368
              var ee = document.createEvent("MouseEvents");
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   369
              ee._isSynthetic = true;
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   370
              x = myCursor.x;
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   371
              y = myCursor.y;
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   372
              ee.initMouseEvent("click", true, true, null, 1,
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   373
                                x + e.screenX - e.clientX,
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   374
                                y + e.screenY - e.clientY,
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   375
                                x,
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   376
                                y);
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   377
              var target = document.elementFromPoint(x, y)
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   378
              if (target)
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   379
                target.dispatchEvent(ee)
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   380
            });
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   381
        </pre>
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   382
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   383
        <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
   384
        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
   385
        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
   386
        existing HTML & DOM mechanisms.</p>
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   387
      </section>
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   388
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   389
      <section>
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   390
        <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
   391
        view-port.</h2>
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   392
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   393
        <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
   394
        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
   395
        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
   396
        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
   397
        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
   398
        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
   399
        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
   400
        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
   401
      </section>
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   402
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   403
      <section>
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   404
        <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
   405
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   406
        <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
   407
        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
   408
        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
   409
        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
   410
        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
   411
      </section>
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   412
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   413
      <section>
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   414
        <h2>Game Portal</h2>
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   415
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   416
        <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
   417
        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
   418
        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
   419
        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
   420
      </section>
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   421
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   422
    </section>
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   423
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   424
    <section class='informative'>
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   425
      <h2>Security</h2>
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   426
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   427
      <p>Security Concerns:</p>
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   428
        <ul>
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   429
          <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
   430
          to interact with.</li>
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   431
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   432
          <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
   433
          agent and operating system controls</li>
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   434
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   435
          <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
   436
          lock, blocking user from meaningful progress.</li>
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   437
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   438
          <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
   439
          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
   440
          gesture is not possible.</li>
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   441
        </ul>
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   442
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   443
        <p>Responses:</p>
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   444
        <ul>
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   445
          <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
   446
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   447
          <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
   448
          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
   449
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   450
          <li>Keyboard based escape will always be provided, e.g.  ESC key.</li>
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   451
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   452
          <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
   453
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   454
          <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
   455
          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
   456
          Chrome suppresses repeated alert() calls.</li>
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
          <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
   459
          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
   460
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   461
          <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
   462
          agent and operating system.</li>
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   463
        </ul>
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   464
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   465
        <p>Recommendations:</p>
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   466
        <ul>
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   467
          <li>ESC key should exit mouse lock.</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>Preferences per sub-domain can be used to allow or block mouse lock,
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   470
          similar to popup, geolocation, and fullscreen.</li>
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   471
        </ul>
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
        <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
   474
        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
   475
        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
   476
        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
   477
        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
   478
        lock can be entered.</p>
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>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
   481
        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
   482
        discussion illustrates considerations and plausible implementations.</p>
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
        <dl>
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   485
          <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
   486
          <dd>Based on device the mechanisms will vary, but obvious examples include
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   487
          the keyboard escape key "ESC" and any control that moves the system focus
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   488
          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
   489
          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
   490
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   491
          <dt>Escape instructions may be communicated.</dt>
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   492
          <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
   493
          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
   494
          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
   495
          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
   496
          by permissions.</dd>
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   497
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   498
          <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
   499
          context menu.</dt>
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   500
          <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
   501
          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
   502
          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
   503
          context menu.<dd>
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   504
        </dl>
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
        <p>Examples of user agent scenarios:</p>
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   507
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   508
        <dl>
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   509
          <dt>A conservative approach</dt>
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   510
          <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
   511
          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
   512
          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
   513
          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
   514
          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
   515
          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
   516
          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
   517
          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
   518
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   519
          <dt>A full screen approach</dt>
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   520
          <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
   521
          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
   522
          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
   523
          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
   524
          confirming the action via a dialog.</dd>
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   525
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   526
          <dt>A permissive approach</dt>
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   527
          <dd>May permit mouse lock for the target or ancestor of a a user gesture
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   528
          without prompt.  Escape instructions would likely be displayed
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   529
          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
   530
        </dl>
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   531
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   532
        <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
   533
        of mouse lock: <a
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   534
        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
   535
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   536
    </section>
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   537
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   538
    <section class='informative'>
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   539
      <h2>Frequently Asked Questions</h2>
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
      <section>
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   542
        <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
   543
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   544
        <p>Mouse Capture [<a
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   545
        href="https://developer.mozilla.org/en/DOM/element.setCapture">MDCCAP</a>]
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   546
        handles low security risk mouse event target lock for the duration of a
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   547
        mouse drag gesture.  Mouse Lock removes the concept the the cursor and
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   548
        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
   549
        different.</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
        <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
   552
        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
   553
        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
   554
        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
   555
        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
   556
        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
   557
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   558
        <p>This functionaility is omitted from the initial version of this spec
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   559
        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
   560
        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
   561
        browser must implement both, which none does yet.  It is not clear if this
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   562
        feature should live on .lockMouse or on .setCapture.  If both were
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   563
        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
   564
        hybrid functionality.</p>
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   565
      </section>
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   566
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   567
      <section>
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   568
        <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
   569
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   570
        <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
   571
        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
   572
        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
   573
        state.</p>
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   574
      </section>
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   575
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   576
      <section>
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   577
        <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
   578
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   579
        <p>When the mouse is locked 'wheel' events should be sent to the mouse
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   580
        lock target element just as 'mousemove' events are.  There is a naming
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   581
        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
   582
        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
   583
        3 'wheel' event</a>.</p>
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   584
      </section>
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   585
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   586
      <section>
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   587
        <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
   588
        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
   589
        and offering an API to restrict the cursor movement to a portion of the
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   590
        webpage?</h2>
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   591
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   592
        <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
   593
        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
   594
        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
   595
        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
   596
        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
   597
        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
   598
        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
   599
        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
   600
        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
   601
        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
   602
        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
   603
        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
   604
        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
   605
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   606
        <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
   607
        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
   608
        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
   609
        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
   610
        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
   611
        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
   612
        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
   613
        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
   614
        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
   615
        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
   616
        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
   617
        have already settled their preferences.</p>
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   618
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   619
        <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
   620
        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
   621
        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
   622
        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
   623
        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
   624
        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
   625
        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
   626
        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
   627
        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
   628
        Device (HID) data.  E.g.  WM_INPUT messages on windows, and USB device
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   629
        apis on Mac / Linux.  The challenge here is interpreting and normalizing
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   630
        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
   631
        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
   632
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   633
        <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
   634
        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
   635
        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
   636
        were implemented.</p>
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   637
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   638
        <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
   639
        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
   640
        future improvements as discussed here.</p>
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   641
      </section>
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   642
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   643
      <section>
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   644
        <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
   645
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   646
        <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
   647
        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
   648
        to hide the cursor, always providing delta values, and offering an API to
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   649
        restrict the cursor movement to a portion of the webpage?" above.</p>
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   650
      </section>
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
      <section>
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   653
        <h2>Why modify MouseEvent and reuse existing mouse events instead of
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   654
        creating a mousedelta event?</h2>
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   655
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   656
        <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
   657
        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
   658
        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
   659
        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
   660
        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
   661
        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
   662
        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
   663
        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
   664
        convenience of containing the current movement data.  Or, new events would
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   665
        also be required for when the moues is locked.</p>
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   666
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   667
        <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
   668
        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
   669
        mouse cursor exists.  This reduces code required to track the last cursor
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   670
        state and mouseover/mouseout transistions if applications which to make
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   671
        use of delta motion of the mouse.  This may be convenient even if the
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   672
        mouse is not fully locked and the deficiencies of no locked target of
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   673
        events, out of window, and screen borders clamping dat exist.</p>
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   674
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   675
        <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
   676
        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
   677
        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
   678
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   679
        <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
   680
        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
   681
      </section>
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   682
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   683
      <section>
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   684
        <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
   685
        input focus?</h2>
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>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
   688
        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
   689
        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
   690
        different than where mouse events are being dispatched.  This is similar
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   691
        to preexisting behavior of receiving mousemove events over any element
7df1fb3c1fbc Mouse Lock: Converted spec from Google Doc.
Vincent Scheib <scheib@google.com>
parents: 134
diff changeset
   692
        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
   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
132
4ec3f28f3e93 Mouse Lock: Work in progress on initial spec conversion
Vincent Scheib <scheib@google.com>
parents:
diff changeset
   697
    <section class='appendix informative'>
4ec3f28f3e93 Mouse Lock: Work in progress on initial spec conversion
Vincent Scheib <scheib@google.com>
parents:
diff changeset
   698
      <h2>Acknowledgements</h2>
4ec3f28f3e93 Mouse Lock: Work in progress on initial spec conversion
Vincent Scheib <scheib@google.com>
parents:
diff changeset
   699
4ec3f28f3e93 Mouse Lock: Work in progress on initial spec conversion
Vincent Scheib <scheib@google.com>
parents:
diff changeset
   700
      <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
   701
        specification:</p>
4ec3f28f3e93 Mouse Lock: Work in progress on initial spec conversion
Vincent Scheib <scheib@google.com>
parents:
diff changeset
   702
4ec3f28f3e93 Mouse Lock: Work in progress on initial spec conversion
Vincent Scheib <scheib@google.com>
parents:
diff changeset
   703
      <ul>
4ec3f28f3e93 Mouse Lock: Work in progress on initial spec conversion
Vincent Scheib <scheib@google.com>
parents:
diff changeset
   704
        <li>Adam Barth</li>
4ec3f28f3e93 Mouse Lock: Work in progress on initial spec conversion
Vincent Scheib <scheib@google.com>
parents:
diff changeset
   705
        <li>Alexey Proskuryakov</li>
4ec3f28f3e93 Mouse Lock: Work in progress on initial spec conversion
Vincent Scheib <scheib@google.com>
parents:
diff changeset
   706
        <li>Aryeh Gregor</li>
4ec3f28f3e93 Mouse Lock: Work in progress on initial spec conversion
Vincent Scheib <scheib@google.com>
parents:
diff changeset
   707
        <li>Brandon Andrews</li>
4ec3f28f3e93 Mouse Lock: Work in progress on initial spec conversion
Vincent Scheib <scheib@google.com>
parents:
diff changeset
   708
        <li>Glenn Maynard</li>
4ec3f28f3e93 Mouse Lock: Work in progress on initial spec conversion
Vincent Scheib <scheib@google.com>
parents:
diff changeset
   709
        <li>Gregg Tavares</li>
4ec3f28f3e93 Mouse Lock: Work in progress on initial spec conversion
Vincent Scheib <scheib@google.com>
parents:
diff changeset
   710
        <li>John Villar</li>
4ec3f28f3e93 Mouse Lock: Work in progress on initial spec conversion
Vincent Scheib <scheib@google.com>
parents:
diff changeset
   711
        <li>Jonas Sicking</li>
4ec3f28f3e93 Mouse Lock: Work in progress on initial spec conversion
Vincent Scheib <scheib@google.com>
parents:
diff changeset
   712
        <li>Klaas Heidstra</li>
4ec3f28f3e93 Mouse Lock: Work in progress on initial spec conversion
Vincent Scheib <scheib@google.com>
parents:
diff changeset
   713
        <li>Olli Pettay</li>
4ec3f28f3e93 Mouse Lock: Work in progress on initial spec conversion
Vincent Scheib <scheib@google.com>
parents:
diff changeset
   714
        <li>Robert O'Callahan</li>
4ec3f28f3e93 Mouse Lock: Work in progress on initial spec conversion
Vincent Scheib <scheib@google.com>
parents:
diff changeset
   715
        <li>Tab Atkins Jr.</li>
4ec3f28f3e93 Mouse Lock: Work in progress on initial spec conversion
Vincent Scheib <scheib@google.com>
parents:
diff changeset
   716
      </ul>
4ec3f28f3e93 Mouse Lock: Work in progress on initial spec conversion
Vincent Scheib <scheib@google.com>
parents:
diff changeset
   717
4ec3f28f3e93 Mouse Lock: Work in progress on initial spec conversion
Vincent Scheib <scheib@google.com>
parents:
diff changeset
   718
      <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
   719
    </section>
4ec3f28f3e93 Mouse Lock: Work in progress on initial spec conversion
Vincent Scheib <scheib@google.com>
parents:
diff changeset
   720
  </body>
4ec3f28f3e93 Mouse Lock: Work in progress on initial spec conversion
Vincent Scheib <scheib@google.com>
parents:
diff changeset
   721
</html>