From 39ccb2f1b13c19a2c8c99982bad87620578ac1a9 Mon Sep 17 00:00:00 2001 From: Marcos Caceres Date: Wed, 6 Dec 2023 18:26:44 +1100 Subject: [PATCH 1/6] Add keyboard locking option --- fullscreen.bs | 78 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 78 insertions(+) diff --git a/fullscreen.bs b/fullscreen.bs index a772f2c..3f5e163 100644 --- a/fullscreen.bs +++ b/fullscreen.bs @@ -57,6 +57,12 @@ unset.

All <{iframe}> elements have an associated iframe fullscreen flag. Unless stated otherwise it is unset. +

All documents have an associated keyboard lock flag. This flag indicates +whether the keyboard lock is active for the document. When the flag is set, the document captures +and handles key inputs as specified by a passed {{FullscreenKeyboardLock}} enum value. When the +flag is not set, keyboard inputs are processed in the default manner by the user agent and the +operating system. +

All documents have an associated fullscreen element. The fullscreen element is the topmost element in the document's top layer whose fullscreen flag is set, if any, and null otherwise. @@ -178,7 +184,14 @@ enum FullscreenNavigationUI { "hide" }; +enum FullscreenKeyboardLock { + "application", + "none", + "system" +} + dictionary FullscreenOptions { + FullscreenKeyboardLock keyboardLock = "none"; FullscreenNavigationUI navigationUI = "auto"; }; @@ -218,6 +231,18 @@ partial interface mixin DocumentOrShadowRoot { free to honor user preference over the application's. The default value "{{FullscreenNavigationUI/auto}}" indicates no application preference. +

+ When supplied, options's {{FullscreenOptions/keyboardLock}} member indicates whether + the supplied keyboard lock mode should apply. + + If set to "{{FullscreenKeyboardLock/application}}", [=application-level keyboard lock=] should + be applied. + + If set to "{{FullscreenKeyboardLock/system}}", [=system-level keyboard lock=] should 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. +
document . {{Document/fullscreenEnabled}}

Returns true if document has the ability to display elements fullscreen and fullscreen is supported, or false otherwise. @@ -340,6 +365,12 @@ are: steps. +

  • + If, {{FullscreenOptions}}'s {{FullscreenOptions/keyboardLock}}'s value is not supported, + reject promise with a {{NotSupportedError}} exception and terminate these + steps. +
    • +

  • Let fullscreenElements be an ordered set initially consisting of this. @@ -379,6 +410,16 @@ are: doc's list of pending fullscreen events. +

  • + Depending on the value of {{FullscreenOptions}}'s {{FullscreenOptions/keyboardLock}}: +
    +
    "{{FullscreenKeyboardLock/application}}"
    +

    Apply an [=application-level keyboard lock=]. +

    "{{FullscreenKeyboardLock/system}}"
    +

    Apply a [=system-level keyboard lock=]. +

    +
    • +

    The order in which elements are fullscreened is not observable, because run the fullscreen steps is invoked in tree order. @@ -494,6 +535,8 @@ could be an open <{dialog}> element.

  • Return promise, and run the remaining steps in parallel. +

  • Run [=the release the keyboard lock steps=] with doc. +

  • Run the [=fully unlock the screen orientation steps=] with doc.

  • If resize is true, resize doc's viewport to its "normal" dimensions. @@ -583,6 +626,11 @@ corresponding event handler content attributes for {{Element}} objects in

    The user agent may end any fullscreen session without instruction from the end user or call to {{Document/exitFullscreen()}} whenever the user agent deems it necessary. +

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

    There should be a simple and intuitive method for users to override keyboard locking, reverting +control back to the system or user agent.

    Rendering

    @@ -640,6 +688,30 @@ iframe:fullscreen { +

    keyboard lock

    + +

    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. + +

    A keyboard lock enables web applications to capture and handle key inputs directly, +bypassing the default behavior typically executed by the user agent (in the case of +"{{FullscreenKeyboardLock/application}}") or operating system (in the case of +"{{FullscreenKeyboardLock/system}}"). When the [=keyboard lock flag=] is set for a [=document=], key +events that would normally trigger user agent or system-level actions are instead redirected to the +web application in fullscreen. + +

    +
    Application-level keyboard lock
    +

    Captures all keys that the user agent would ordinarily receive, except those reserved for + critical system functions or security shortcuts (e.g., Ctrl+Alt+Del). +

    System-level keyboard lock
    +

    capture a wider range of keys, including those used for system-level navigation and + shortcuts (e.g., Alt+Tab), subject to user consent and user agent implementation. +

    + +

    Permissions Policy Integration

    @@ -677,6 +749,12 @@ delivered with the document through which it is nested.

    This prevents e.g. content from third parties to go fullscreen without explicit permission. +

    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. + +

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

    From 2abdfda51361925bf399f08d9b48732464bc06fc Mon Sep 17 00:00:00 2001 From: Marcos Caceres Date: Wed, 6 Dec 2023 18:37:47 +1100 Subject: [PATCH 2/6] Bikeshed fixes --- fullscreen.bs | 16 +++++++++++++--- 1 file changed, 13 insertions(+), 3 deletions(-) diff --git a/fullscreen.bs b/fullscreen.bs index 3f5e163..2651915 100644 --- a/fullscreen.bs +++ b/fullscreen.bs @@ -188,7 +188,7 @@ enum FullscreenKeyboardLock { "application", "none", "system" -} +}; dictionary FullscreenOptions { FullscreenKeyboardLock keyboardLock = "none"; @@ -535,7 +535,7 @@ could be an open <{dialog}> element.

  • Return promise, and run the remaining steps in parallel. -

  • Run [=the release the keyboard lock steps=] with doc. +

  • [=Run the release the keyboard lock steps=] with doc.

  • Run the [=fully unlock the screen orientation steps=] with doc. @@ -688,7 +688,7 @@ iframe:fullscreen { -

    keyboard lock

    +

    keyboard locking

    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 @@ -711,6 +711,16 @@ web application in fullscreen. shortcuts (e.g., Alt+Tab), subject to user consent and user agent implementation. +

    +

    To run the release the keyboard lock steps for a document + document, run these steps: +

      +

    1. If the [=keyboard lock flag=] for the document is not set, abort these steps. +

    2. Deactivate the keyboard lock and restore the handling of keyboard inputs to the default + behavior of the user agent and the operating system.

    3. Set the [=keyboard lock flag=] for + the document to false. +

    +

    Permissions Policy Integration

    From 72f9326dca0e306ae53f8d6e8aac4cb3f3f9bcb4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marcos=20C=C3=A1ceres?= Date: Wed, 6 Dec 2023 18:41:02 +1100 Subject: [PATCH 3/6] Update fullscreen.bs --- fullscreen.bs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/fullscreen.bs b/fullscreen.bs index 2651915..091e6ad 100644 --- a/fullscreen.bs +++ b/fullscreen.bs @@ -366,7 +366,7 @@ are:
  • - If, {{FullscreenOptions}}'s {{FullscreenOptions/keyboardLock}}'s value is not supported, + If {{FullscreenOptions}}'s {{FullscreenOptions/keyboardLock}}'s value is not supported, reject promise with a {{NotSupportedError}} exception and terminate these steps.
    • From fee721d52c25f7be6dcbacdb5928325f4bfffc9b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marcos=20C=C3=A1ceres?= Date: Wed, 6 Dec 2023 18:42:28 +1100 Subject: [PATCH 4/6] Update fullscreen.bs --- fullscreen.bs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/fullscreen.bs b/fullscreen.bs index 091e6ad..0757159 100644 --- a/fullscreen.bs +++ b/fullscreen.bs @@ -707,7 +707,7 @@ web application in fullscreen.

    Captures all keys that the user agent would ordinarily receive, except those reserved for critical system functions or security shortcuts (e.g., Ctrl+Alt+Del).

    System-level keyboard lock
    -

    capture a wider range of keys, including those used for system-level navigation and +

    Capture a wider range of keys, including those used for system-level navigation and shortcuts (e.g., Alt+Tab), subject to user consent and user agent implementation. From 0087119728ef355003525dcdc45301fd9032776f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marcos=20C=C3=A1ceres?= Date: Wed, 6 Dec 2023 18:57:42 +1100 Subject: [PATCH 5/6] Update fullscreen.bs --- fullscreen.bs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/fullscreen.bs b/fullscreen.bs index 0757159..31aa65a 100644 --- a/fullscreen.bs +++ b/fullscreen.bs @@ -61,7 +61,7 @@ stated otherwise it is unset. whether the keyboard lock is active for the document. When the flag is set, the document captures and handles key inputs as specified by a passed {{FullscreenKeyboardLock}} enum value. When the flag is not set, keyboard inputs are processed in the default manner by the user agent and the -operating system. +operating system. Unless stated otherwise it is unset.

    All documents have an associated fullscreen element. The fullscreen element is the topmost element in the document's From f67040225fb71dabe486e15ed20f14485f4777b0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marcos=20C=C3=A1ceres?= Date: Fri, 8 Dec 2023 16:34:28 +1100 Subject: [PATCH 6/6] Apply suggestions from code review Co-authored-by: Martin Thomson --- fullscreen.bs | 16 +++++++++++----- 1 file changed, 11 insertions(+), 5 deletions(-) diff --git a/fullscreen.bs b/fullscreen.bs index 31aa65a..7b3319a 100644 --- a/fullscreen.bs +++ b/fullscreen.bs @@ -688,9 +688,9 @@ iframe:fullscreen { -

    keyboard locking

    +

    Keyboard Locking

    -

    keyboard Locking enhances the functionality of web applications running in fullscreen by allowing +

    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. @@ -704,20 +704,26 @@ web application in fullscreen.

    Application-level keyboard lock
    -

    Captures all keys that the user agent would ordinarily receive, except those reserved for - critical system functions or security shortcuts (e.g., Ctrl+Alt+Del). +

    Captures all keys that the user agent would ordinarily receive, such as those that open or + close windows. This excludes those reserved for system-level interactions, such + as key presses that open system menus or switch applications.

    System-level keyboard lock

    Capture a wider range of keys, including those used for system-level navigation and shortcuts (e.g., Alt+Tab), subject to user consent and user agent implementation.

    +

    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. +

    To run the release the keyboard lock steps for a document document, run these steps:

    1. If the [=keyboard lock flag=] for the document is not set, abort these steps.

    2. Deactivate the keyboard lock and restore the handling of keyboard inputs to the default - behavior of the user agent and the operating system.

    3. Set the [=keyboard lock flag=] for + behavior of the user agent and the operating system. +

    4. Set the [=keyboard lock flag=] for the document to false.