[System-Keyboard-Lock] Forward navigator functions to RenderFrameHost

third_party/WebKit/Source/modules/keyboard_lock/NavigatorKeyboardLock.idl

+// Copyright 2017 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+// The supplement of Navigator to process navigator.requestKeyLock() and
+// navigator.cancelKeyLock() web APIs to implement
+// https://garykac.github.io/system-keyboard-lock/.

[foolip, 2017/04/17 08:46:05]

Just a link to the spec will suffice, most IDL files are like that.

[Hzj_jie, 2017/04/18 02:26:08]

Done.

+partial interface Navigator {
+    // Requests to receive a set of key codes

[foolip, 2017/04/17 08:46:05]

Please copy the spec'd IDL verbatim and make the minimal number of changes
necessary, which is the extra extended attributes.

This documentation would be good for the methods in the NavigatorKeyboardLock.h
file, perhaps.

[Hzj_jie, 2017/04/18 02:26:08]

Done.

+    // (https://www.w3.org/TR/uievents/#interface-keyboardevent) in string
+    // format.
+    // The Promise will be rejected if the user or browser do not allow the web
+    // page to use this API. Otherwise, web page should expect to receive the
+    // key presses once the Promise has been resolved. This API does best effort
+    // to deliver the key codes: due to the platform restrictions, some keys or
+    // key combinations may not be able to receive or intercept by the user
+    // agent.
+    // - Making two requests concurrently without waiting for one Promise to
+    //   finish is disallowed, the second Promise will be rejected immediately.
+    // - Making a second request after the Promise of the first one has finished
+    //   is allowed; the second request will overwrite the key codes reserved.
+    // - Passing in an empty keyCodes array will reserve all keys.
+    [RuntimeEnabled=KeyboardLock, CallWith=ScriptState] Promise<void> requestKeyLock(DOMString[] keyCodes);

[foolip, 2017/04/17 08:46:05]

The argument should be "optional sequence<DOMString> keyCodes". Maybe that
actually doesn't make sense, though, what does it mean to request no keys in
particular?

[Hzj_jie, 2017/04/18 02:26:08]

Passing in an empty keyCodes array will reserve all keys.

[foolip, 2017/04/18 05:10:57]

OK. In that case it probably makes sense to add " = []" in the spec as the
default argument value. Otherwise the spec will have to say the same thing in
prose for both a missing argument and an empty array.

[Hzj_jie, 2017/04/19 00:45:54]

Updated.
TODOs have been added, and point to the corresponding issues.

+
+    // Removes all reserved keys. This function is also asynchronized, the web
+    // page may still receive reserved keys after this function has finished.
+    // Once the web page is closed, the user agent implictly executes this API.

[foolip, 2017/04/17 08:46:05]

Is such an implicit call anywhere in the code?

[Hzj_jie, 2017/04/18 02:26:08]

Yes, the logic is in browser process, which has not been implemented. The
"implicitly" here indicates the key lock status is session based, and won't be
kept by the user agent.

[foolip, 2017/04/18 05:10:57]

The spec should probably define precisely which events it is that causes this to
happen. In https://fullscreen.spec.whatwg.org/ it's "Whenever the unloading
document cleanup steps run with a document, fully exit fullscreen document."

[Hzj_jie, 2017/04/19 00:45:54]

Done.
TODO has been added, and point to the corresponding issue.

+    [RuntimeEnabled=KeyboardLock] void cancelKeyLock();
+};