Skip to content

Add keyboard locking option #232

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
marcoscaceres wants to merge 13 commits into
base: main
Choose a base branch
from
+83 −1
Open

Add keyboard locking option #232

Changes from all commits
Commits
Show all changes
13 commits
Select commit Hold shift + click to select a range
1149402
Add keyboard locking option
marcoscaceres Dec 6, 2023
8b58287
Bikeshed fixes
marcoscaceres Dec 6, 2023
dc8e971
Update fullscreen.bs
marcoscaceres Dec 6, 2023
71be4b1
Update fullscreen.bs
marcoscaceres Dec 6, 2023
41d4f1d
Update fullscreen.bs
marcoscaceres Dec 6, 2023
f7a41e0
Apply suggestions from code review
marcoscaceres Dec 8, 2023
c334cd4
Rename 'application' to 'browser'
zcorpan Apr 15, 2026
9bce1d5
Avoid 'should' in non-normative text
zcorpan Apr 15, 2026
f3f66c4
Add 'removing steps' to link-defaults
zcorpan Apr 16, 2026
0447e6e
Remove the 'system' enum
zcorpan Apr 16, 2026
d7eb7a9
Fix validation error
zcorpan Apr 17, 2026
11a7f57
Store 'keyboard lock flag' on element instead of document
zcorpan Apr 22, 2026
f4149b1
Set |error| to true if keyboard lock is not supported, so it gets the…
zcorpan Apr 22, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
84 changes: 83 additions & 1 deletion fullscreen.bs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,7 @@ spec:dom
type:dfn; for:/; text:document
type:dfn; for:/; text:element
type:interface; text:Document
type:dfn; text:removing steps
spec:infra
type:dfn; for:set; text:for each
type:dfn; text:string
Expand Down Expand Up @@ -87,7 +88,7 @@ is an <a>ordered set</a> of (<a>string</a>, <a>element</a>) <a>tuples</a>. It is
</ol>

<p>To <dfn>unfullscreen an <var>element</var></dfn>, unset <var>element</var>'s
<a>fullscreen flag</a> and <a>iframe fullscreen flag</a> (if any), and
<a>fullscreen flag</a>, <a>iframe fullscreen flag</a> (if any), and <a>keyboard lock flag</a>, and
<a>remove from the top layer immediately</a> given <var>element</var>.

<p>To <dfn>unfullscreen a <var>document</var></dfn>,
Expand Down Expand Up @@ -149,6 +150,9 @@ these steps:
<p><dfn>Fullscreen is supported</dfn> if there is no previously-established user preference,
security risk, or platform limitation.

<p><dfn>Keyboard lock is supported</dfn> if there is no previously-established user preference,
security risk, or platform limitation.

<hr>

<div algorithm>
Expand Down Expand Up @@ -177,7 +181,24 @@ steps:
<p class=note>These steps integrate with the <a for=/>event loop</a> defined in HTML. [[!HTML]]
</div>

<hr>

<p>All <a>elements</a> have an associated <dfn>keyboard lock flag</dfn>. Unless stated otherwise it is unset.

<p>A [=document=] has <dfn>keyboard lock</dfn> active when its [=fullscreen element=] is not null and the [=fullscreen element=]'s [=keyboard lock flag=] is true, and inactive otherwise.

<div algorithm>
<p>To <dfn>run the release the keyboard lock steps</dfn> for a <a>document</a>
<var>document</var>, run these steps:

<ol>
<li><p>If <var>document</var>'s <a>fullscreen element</a> is null, then return.

<li><p>If the [=keyboard lock flag=] for <var>document</var>'s <a>fullscreen element</a> is false, then return.

<li><p>Set the [=keyboard lock flag=] for <var>document</var>'s <a>fullscreen element</a> to false.
</ol>
</div>

<h2 id=api>API</h2>

Expand All @@ -188,7 +209,13 @@ enum FullscreenNavigationUI {
"hide"
};

enum FullscreenKeyboardLock {
"browser",
"none"
};

Comment thread
zcorpan marked this conversation as resolved.
dictionary FullscreenOptions {
FullscreenKeyboardLock keyboardLock = "none";
Comment thread
zcorpan marked this conversation as resolved.
FullscreenNavigationUI navigationUI = "auto";
};

Expand Down Expand Up @@ -228,6 +255,14 @@ partial interface mixin DocumentOrShadowRoot {
free to honor user preference over the application's. The default value
"{{FullscreenNavigationUI/auto}}" indicates no application preference.

When supplied, <var>options</var>'s {{FullscreenOptions/keyboardLock}} member indicates whether
the supplied keyboard lock mode will apply.

If set to "{{FullscreenKeyboardLock/browser}}", [=keyboard lock=] can be applied.

User agents are always free to honor user preference over the application's. The default value
"{{FullscreenKeyboardLock/none}}" indicates no keyboard lock is applied.

<dt><code><var>document</var> . {{Document/fullscreenEnabled}}</code>
<dd><p>Returns true if <var>document</var> has the ability to display <a>elements</a> fullscreen
and <a>fullscreen is supported</a>, or false otherwise.
Expand Down Expand Up @@ -292,6 +327,8 @@ are:
algorithm is <a>triggered by a user generated orientation change</a>.
</ul>

<li><p>If <var>options</var>["{{FullscreenOptions/keyboardLock}}"] is "{{FullscreenKeyboardLock/browser}}" and <a>keyboard lock is supported</a> is false, then set <var>error</var> to true.

<li><p>If <var>error</var> is false, then <a>consume user activation</a> given
<var>pendingDoc</var>'s <a>relevant global object</a>.

Expand Down Expand Up @@ -392,6 +429,17 @@ are:
<p class=note>The order in which elements are <a lt="fullscreen an element">fullscreened</a>
is not observable, because <a>run the fullscreen steps</a> is invoked in <a>tree order</a>.

<li>
<p>Depending on the value of <var>options</var>["{{FullscreenOptions/keyboardLock}}"]:

<dl class=switch>
<dt>"{{FullscreenKeyboardLock/browser}}"</dt>
<dd><p>Set the [=keyboard lock flag=] for <a>this</a> to true.

<dt>"{{FullscreenKeyboardLock/none}}"</dt>
<dd><p>Set the [=keyboard lock flag=] for <a>this</a> to false.
</dl>

<li><p>Resolve <var>promise</var> with undefined.
</ol>

Expand Down Expand Up @@ -506,6 +554,8 @@ could be an open <{dialog}> element.

<li><p>Return <var>promise</var>, and run the remaining steps <a>in parallel</a>.

<li><p>[=Run the release the keyboard lock steps=] with <var>doc</var>.

<li><p>Run the [=fully unlock the screen orientation steps=] with <var>doc</var>.

<li><p>If <var>resize</var> is true, resize <var>doc</var>'s viewport to its "normal" dimensions.
Expand Down Expand Up @@ -595,6 +645,11 @@ algorithm as part of the <a>close request steps</a>. This takes precedence over
<p>The user agent may end any fullscreen session without a <a>close request</a> or call to
{{Document/exitFullscreen()}} whenever the user agent deems it necessary.

<p>Users should be clearly notified when [=keyboard locking=] is active, possibly through browser UI
indicators.

<p>There should be a simple and intuitive method for users to override keyboard locking, reverting
Copy link
Copy Markdown

@martinthomson martinthomson Dec 6, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It would be really nice if we could standardize this. That way, the experience is consistent across browsers.

I don't regard this as essential, but it would be nice.

Copy link
Copy Markdown
Member Author

@marcoscaceres marcoscaceres Dec 8, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agree... though this might need to happen after browsers ship something and if we all align. I guess it would be a SHOULD (or even MAY) level thing. History suggests that we will naturally converge on a UI/UX convention for this.

control back to the system or user agent.


<h2 id=rendering>Rendering</h2>
Expand Down Expand Up @@ -652,6 +707,27 @@ iframe:fullscreen {



<h2 id="keyboard-locking">Keyboard Locking</h2>

<p>Keyboard locking enhances the functionality of web applications running in fullscreen by allowing
them to intercept certain key inputs that would typically be handled by either the system or the
user agent. This is useful in scenarios such as gaming or remote desktop applications, where keys
like ESC or function keys are integral to the application's functionality.

<p>A [=keyboard lock=] enables web applications to capture and handle key inputs directly, bypassing
the default behavior typically executed by the user agent or operating system. Key events that would
normally trigger user agent or system-level actions are instead redirected to the web application in
fullscreen. Such key events (for individual keys or keyboard shortcuts) may either have no action
while [=keyboard lock=] is active, or it could still have the same action but allow the web page to
call {{Event/preventDefault()}} to cancel the action.

<p>Whenever a [=document=]'s [=keyboard lock=] is changed from active to inactive, user agents must deactivate the keyboard lock and restore the handling of keyboard inputs to the default behavior of the user agent and the operating system.

<p>User agents should reserve an additional input for the purposes of exiting fullscreen. There are
also some system-level key sequences or combinations that cannot be intercepted for security
reasons, such as Ctrl+Alt+Del on Windows.


<h2 id=permissions-policy-integration oldids=feature-policy-integration>Permissions Policy
Integration</h2>

Expand Down Expand Up @@ -689,6 +765,12 @@ delivered with the <a>document</a> through which it is nested.

<p>This prevents e.g. content from third parties to go fullscreen without explicit permission.

<p>When applying a [=keyboard lock=], only a limited set of keys, primarily those not involving
system control or privacy risks (like Alt+Tab, Ctrl+Alt+Del), can be locked via the API.

<p>When applying a [=keyboard lock=], user agents should implement safeguards to prevent abuse of
this feature, such as allowing users to override the lock.



<h2 id=old-links class=no-num oldids="new-stacking-layer, top-layer, top-layer-add, ::backdrop-pseudo-element, css-pe-backdrop">Previously-hosted definitions</h2>
Expand Down