diff --git a/index.html b/index.html index 9f3acc2..f5caa7c 100644 --- a/index.html +++ b/index.html @@ -51,7 +51,9 @@ allows for the screen orientation to be locked under certain preconditions. This is particularly useful for applications such as computer games, where users physically rotate the device, but the - screen orientation itself should not change. + screen orientation itself should not change. The specification also + defines CSS media features to enable feature detection of orientation + locking capabilities.

@@ -888,6 +890,137 @@

condition=].

+
+

+ CSS Integration +

+
+

+ The `can-lock-orientation` media feature +

+

+ The can-lock-orientation media feature is + used to query whether the user agent supports locking the screen + orientation in the current context. +

+

+ Value: none | auto +

+

+ The can-lock-orientation media feature can be used to test + whether the user agent supports screen orientation locking + functionality. +

+
+
+ `none` +
+
+

+ The user agent does not support screen orientation locking, or + locking is not possible in the current context. This includes + cases where: +

+
    +
  • The user agent does not implement the Screen Orientation API +
    • +
  • The document is not [=Document/fully active=] +
    • +
  • The document has the [=sandboxed orientation lock browsing + context flag=] set +
    • +
  • The document's [=Document/visibility state=] is "hidden" +
    • +
  • The current context doesn't meet the [=pre-lock conditions=] +
    • +
+

+ This keyword value evaluates as false in the [=boolean context=]. +

+
+
+ `auto` +
+
+ The user agent supports screen orientation locking and locking is + possible in the current context, meaning a call to + {{ScreenOrientation/lock()}} could potentially succeed. This + keyword value evaluates as true in the [=boolean context=]. +
+
+

+ The can-lock-orientation media feature evaluates to `auto` + when orientation locking functionality is available, but this doesn't + guarantee that a specific lock request will succeed. Factors such as + platform limitations or specific orientation support may still cause + {{ScreenOrientation/lock()}} to fail. +

+
+

+ The following example shows how to use the + can-lock-orientation media feature to conditionally display + orientation-related UI: +

+ 
+            /* Hide rotation controls when orientation locking is not supported */
+            .rotation-controls {
+              display: none;
+            }
+
+            @media (can-lock-orientation) {
+              .rotation-controls {
+                display: block;
+              }
+            }
+
+

+ In JavaScript, the media feature can be queried using: +

+ 
+            if (window.matchMedia('(can-lock-orientation)').matches) {
+              // Orientation locking is potentially available
+              showOrientationControls();
+            } else {
+              // Orientation locking is not available
+              hideOrientationControls();
+            }
+
+
+
+

+ Privacy considerations for `can-lock-orientation` +

+

+ To prevent fingerprinting through user preferences or device + capabilities, user agents SHOULD consider the following privacy + mitigations: +

+
    +
  • When user preferences disable orientation locking, user agents + MAY still report `can-lock-orientation: auto` and only fail at the + time of actual {{ScreenOrientation/lock()}} invocation. This + prevents revealing user preference settings through CSS. +
    • +
  • In private browsing modes, user agents SHOULD normalize the + behavior to always report `can-lock-orientation: auto` for contexts + where the API would normally be available, regardless of user + preferences or detailed device capabilities. +
    • +
  • User agents SHOULD NOT use device-specific orientation support + capabilities (such as whether specific orientations are physically + possible) to determine the media feature value, as this could + reveal device characteristics. +
    • +
+

+ These privacy considerations ensure that the + can-lock-orientation media feature provides useful + functionality for progressive enhancement while minimizing + potential fingerprinting vectors. +

+
+
+

Accessibility considerations