index.bs

<h1>System Keyboard Lock</h1>

<pre class="metadata">
Shortname: systemkeylock
Level:
Group: uievents
Status: WD
TR: http://www.w3.org/TR/systemkeylock/
ED: https://github.com/w3c/systemkeylock/
Repository: garykac/system-keyboard-lock
Previous Version:
	<none>
Editor:
    Gary Kacmarcik, Google, garykac@google.com
    Jamie Walch, Google, jamiewalch@google.com
Abstract:
	This specification defines an API that allows websites to
	capture keys that are normally reserved by the underlying host
	operating system. It is intended to be used by web
	applications that provide a fullscreen immersive experience
	(like games or remote access apps).
</pre>

<pre class="anchors">
urlPrefix: http://www.w3.org/TR/uievents-code/#; type: dfn; spec: uievents-code;
	text: valid KeyboardEvent code
</pre>

<pre class="biblio">
{
	"QuartzEventServices": {
		"title": "Quartz Event Services",
		"href": "https://developer.apple.com/reference/coregraphics/1658572-quartz_event_services"
	},
	"GrabKeyboard": {
		"title": "X11 GrabKeyboard API",
		"href": "https://www.x.org/releases/X11R7.7/doc/xproto/x11protocol.html#requests:GrabKeyboard"
	},
    "LowLevelKeyboardProc": {
		"title": "LowLevelKeyboardProc documentation on MSDN",
		"href": "https://msdn.microsoft.com/en-us/library/windows/desktop/ms644985(v=vs.85).aspx"
	}
}
</pre>

<h2 id="introduction">Introduction</h2>

	Richly interactive web sites, games and remote
	desktop/application streaming experiences want to provide an
	immersive, full screen experience. To accomplish this, sites
	need access to special keys and keyboard shortcuts while they
	are in full screen mode so that they can be used for
	navigation, menus or gaming functionality. Some examples of
	the keys that may be required are Escape, Alt+Tab, Cmd+`, and
	Ctrl+N.

	By default, these keys are not available to the web application because
	they are captured by the browser or the underlying operating
	system. The System Keyboard Lock API enables websites to capture and use
	all available keys allowed by the OS.

<h2 id="API">Activating and Deactivating System Keyboard Lock</h3>

	<pre class="idl" data-highlight="webidl">
	partial interface Navigator {
		[SecureContext] void requestSystemKeyboardLock(optional sequence&lt;DOMString> keyCodes);
		[SecureContext] void cancelSystemKeyboardLock();
	};
	</pre>

	The navigator has <dfn>enable keyboard lock</dfn>, which is a
	boolean that is set to true when System Keyboard Lock is enabled.
	By default, this is set to false.

	The navigator has <dfn>reserved key codes</dfn>, which is a
	sequence of DOMStrings, each of which is a [=valid KeyboardEvent code=]
	as defined in [[UIEvents-Code]].
	By default this sequence is empty (which would capture all keys
	if [=enable keyboard lock=] was enabled).

	<h3 id="requestSystemKeyboardLock">requestSystemKeyboardLock</h3>

		When {{requestSystemKeyboardLock()}} is called, the user agent must
		run the following steps:

		1. Reset [=reserved key codes=] to be an empty sequence.

		2. If the optional {{keyCodes}} argument is present, run the
			following substeps:

			1. Copy the values from {{keyCodes}} into [=reserved key codes=],
				removing any entries which are not [=valid KeyboardEvent codes=]
				or duplicate.

		3. If [=enable keyboard lock=] is currently false, run the following
			substeps:

			1. [=Register a system key press handler=].

			2. Set [=enable keyboard lock=] to be true.

	<h3 id="cancelSystemKeyboardLock">cancelSystemKeyboardLock</h3>

		When {{cancelSystemKeyboardLock()}} is called, the user agent must
		run the following steps:

		1. If [=enable keyboard lock=] is true, then run the following substeps:

			1. [=Unregister the system key press handler=].

			2. Set [=enable keyboard lock=] to be false.

			3. Reset [=reserved key codes=] to be an empty sequence.

<h2 id="handling-events">Handling Keyboard Key Presses</h2>

	<h3 id="key-press-handler">System Key Press Handler</h3>
		A <dfn>system key press handler</dfn> is an platform-specific handler
		that can be used to filter keys at the platform level. Since
		System Keyboard Lock feature is intended to provide access to key
		presses that are not normally made available to the browser (for
		example, Cmd/Alt-Tab), most platforms will require a special handler
		to be set up.

		The [=system key press handler=] must have the following properties:

		* It must process key presses before any user agent keyboard shortcuts
			are handled.
		* Wherever possible, it should process key presses before any system
			keyboard shortcuts are processed.

		<h4 id="registering">Registering</h4>

			To <dfn>register a system key press handler</dfn>, the user agent
			will need to follow the platform-specific steps to add a low-level
			hook that will be called whenever the platform begins to process a
			new key press.

			The exact process for adding a [=system key press handler=] varies
			from platform to platform. For examples of how to register a
			low-level hook to process key presses on common platforms, see
			[[LowLevelKeyboardProc]] for Windows, [[QuartzEventServices]] for
			Mac OS X and [[GrabKeyboard]] for X Windows.

			Note: If the user agent already has a key press handler registered
			for another purpose, then it can optionally extend that handler to
			support the System Keyboard Lock feature (assuming it meets the
			requirements mentioned above).

		<h4 id="unregistering">Unregistering</h4>

			To <dfn>unregister the system key press handler</dfn>, the user
			agent will need to follow the platform-specific steps to remove the
			(previously added) low-level hook for processing new key press.

			As with registering system key press handlers, the process for
			unregistering system key press handlers is also platform-specific.
			See the references listed in [[#registering]] for more details and
			examples.

	<h3 id="handling-keyboard-events">Handling Keyboard Events</h3>

		In response to the user pressing a key, if a
		[=system key press handler=] has been
		<a lt="register a system key press handler">registered</a>,
		it should run the following steps:

		1. Let |isJsFullscreen| be set to true if the user agent is currently in
			fullscreen mode that was initiated by Element.requestFullscreen()
			(see [[Fullscreen]]).

			Note: This can be determined by adding a tracking variable in the
				requestFullscreen() call or by checking to see if
				Document.fullscreenElement is non-null.

		2. Let |hasFocus| be set to true if the current fullscreen document or
			element has input focus.

			Note: The fullscreen element would not have focus, for example, if
			there was a system dialog being displayed with focus.

		3. If |isJsFullscreen|, |hasFocus| and [=enable keyboard lock=] are all set
			to true, then run the following substeps:

			1. Let |keyEvent| be the key event for the new key press.

			2. Let |code| be the value of the {{KeyboardEvent/code}} attribute of |keyEvent|.

			3. If [=reserved key codes=] is empty or if |code| is listed in
				[=reserved key codes=], then run the following substeps:

				1. If |code| is equal to "Escape", then run the following
					substeps:

					1. Optionally overlay a message on the screen telling the
						user that they can Hold the Escape key to exit from
						fullscreen.

					2. If the key is held for 2 seconds, then exit from the
						keyboard handler and pass the key on to the user agent
						for normal processing (which will exit fullscreen).

				2. Dispatch |keyEvent| to the fullsceen document or element.

			4. Else, handle the key event as it normally would be handled,
				either by dispatching a key event or performing the
				usual keyboard shortcut action.

		Note: It is not required that a conforming implementation be able to
		override the OS default behaviour for every key combination.
		Specifically, most platforms have a “secure attention sequence” (e.g.,
		Ctrl-Alt-Del on Windows) that applications cannot override; this
		specification does not supersede that.

<h2 id="fullscreen-considerations">Fullscreen Considerations</h2>

	There are two different types of fullscreen available in modern user agents:
	JavaScript-initiated fullscreen (via the [[Fullscreen]] API) and
	user-initiated fullscreen (when the user enters fullscreen using a keyboard
	shortcut). The user-initiated fullscreen is often referred to as "F11"
	fullscreen since that is a common key shortcut used to enter and exit
	fullscreen mode.

	F11 fullscreen and JavaScript (JS) fullscreen do not behave the same way.
	When a user enters F11 fullscreen, they can only exit it via the same
	keyboard shortcut that they used to enter it -- the exitFullscreen()
	function will not work in this case. In addition, fullscreen events that are
	normally fired for JS fullscreen are not sent for F11 fullscreen.

	Because of these differences (and because there is no standard shortcut
	for F11 fullscreen), the System Keyboard Lock API is only valid when the
	a JavaScript-initiated fullscreen is active. During F11 fullscreen, no
	System Keyboard Lock processing of keyboard events will take place.

<h2 id="mobile">Mobile Device Considerations</h2>

	Issue: What level of support do we need on mobile? Is it enough to say that
	it's a keyboard-focused API and mobile devices typically don't have
	keyboards? What does Chrome do if you activate full-screen on a mobile
	web site and hit Escape from an attached keyboard? It seems like that should
	also be supported.

<h2 id="security">Security Considerations</h2>

	Issue: How does this proposal prevent malicious sites from taking all
	key events and preventing the user from escaping?

	Issue: How could this be used (alone or in conjunction with
	other APIs) to give the user a bad experience?

<h2 id="privacy">Privacy Considerations</h2>

	Not applicable. This API does not use or reveal any personal information
	about the current user.

<h2 id="acknowledgements-contributors">Acknowledgements</h2>

	Thanks to the following people for the discussions that lead
	to the creation of this proposal:

	Jon Dahlke (Google)