Skip to content

Commit

Permalink
[mediaqueries-5] Move the definition of display-mode back to APPMANIFEST
Browse files Browse the repository at this point in the history 
Closes #7306
Closes #7307
  • Loading branch information
@mgiuca @grorg
mgiuca authored and grorg committed Apr 12, 2024
1 parent 7fa3a64 commit e8cc514
Showing 1 changed file with 76 additions and 66 deletions.
142 changes: 76 additions & 66 deletions mediaqueries-5/Overview.bs
View file
Expand Up @@ -1306,104 +1306,112 @@ Display Modes: the ''display-mode'' media feature </h3>
Type: discrete
</pre>

The 'display-mode' media feature represents the [=display mode=] of the web application.
Child browsing contexts reflect the [=display mode=] of their [=top-level browsing context=].

A <dfn export>display mode</dfn> represents
how the web application is being presented within the context of an OS (e.g., in fullscreen, etc.).
Display modes correspond to user interface (UI) metaphors
and functionality in use on a given platform.
The UI conventions of the display modes are purely advisory
and implementers are free to interpret them how they best see fit.

This specification defines the following [=display modes=]:
<dl dfn-for="display mode" export>
The '@media/display-mode' media feature describes the mode in which the current [=browsing context=] is
currently being presented to the end user. In child browsing contexts, the [=display mode=] must
match that of the [=top-level browsing context=].

This feature is primarily used to determine which [=display mode=] the user agent has applied to
an [=application context=]. As such, the values of this feature correspond to the [=display
mode|display modes=] defined in [[APPMANIFEST]]. However, it can also be used in non-application
contexts to determine whether the viewport is in other modes, such as
fullscreen or picture-in-picture.


<dl dfn-type=value dfn-for="@media/display-mode">
<dt><dfn>fullscreen</dfn>
<dd>
The web application is displayed with browser UI elements hidden
and takes up the entirety of the available display area.
The browsing context is displayed with browser UI elements hidden and takes up the entirety of
the available display area. The fullscreen context may have been caused by the [=display
mode/fullscreen=] display mode in the [=application manifest=], by the {{requestFullscreen()}}
method of the [[FULLSCREEN|Fullscreen API]], or through some other means (such as the user
manually activating fullscreen mode using the user agent's built-in controls).

Corresponds to the [=display mode/fullscreen=] display mode.

<dt><dfn>standalone</dfn>
<dd>
The web application is displayed to look and feel like a standalone native application.
This can include the application having a different window,
its own icon in the application launcher, etc.
In this mode,
the user agent excludes standard browser UI elements
such as an URL bar,
but standard system UI elements,
such as window decorations, a system status bar, and/or a system back button,
remain available.
The [=display mode/standalone=] display mode is in use. Only applicable in an [=application
context=].

<dt><dfn>minimal-ui</dfn>
<dd>
This mode is similar to [=display mode/standalone=],
but provides the end-user with some means to access
a minimal set of UI elements for controlling navigation
(i.e., back, forward, reload, and perhaps some way of viewing the document's address).
A user agent may include other platform specific UI elements,
such as "share" and "print" buttons
or whatever is customary on the platform and user agent.
The [=display mode/minimal-ui=] display mode is in use. Only applicable in an [=application
context=].

<dt><dfn>browser</dfn>
<dd>
The web application is displayed using the platform-specific convention
for opening hyperlinks in the user agent
(e.g., in a browser tab or a new window).
The browsing context is displayed using the platform-specific convention for opening
hyperlinks in the user agent (e.g., in a browser tab or web browser window with controls such
as an address bar). This should be used for non-[=application context|application contexts=]
where no other display mode is appropriate.

Corresponds to the [=display mode/browser=] display mode.

<dt><dfn>picture-in-picture</dfn>
<dd>
This mode allows users to continue consuming media while they interact
with other sites or applications on their device.
The web application is displayed in a floating and always-on-top window.
The browsing context is displayed in a floating and always-on-top window.
A user agent may include other platform specific UI elements,
such as "back-to-tab" and "site information" buttons
or whatever is customary on the platform and user agent.

</dl>

<details class="note">
<summary>The [=display mode/fullscreen=] [=display mode=] is distinct from the [[FULLSCREEN|Fullscreen API]].</summary>
<div class="example">
For example, the [=application manifest=] can request the [=display mode/standalone=] [=display
mode=] as follows:
<pre class="lang-json">
{
"display": "standalone"
}
</pre>

This media query can be used to determine whether the user agent has actually applied the
[=display mode/standalone=] mode:

The [=display mode/fullscreen=] [=display mode=] describes the fullscreen state of the browser viewport,
while the [[FULLSCREEN|Fullscreen API]] operates on an element contained within the viewport.
As such, a web application can have its [=display mode=] set to [=display mode/fullscreen=],
even while {{fullscreenElement}} returns <code>null</code>,
and {{fullscreenEnabled}} returns <code>false</code>.
<pre class="lang-css">@media (display-mode: standalone) { … }</pre>

The ''fullscreen'' <a>display mode</a> is also not directly related
The user agent could set '@media/display-mode' to any of the other values, depending on the
actual mode currently in use.
</div>

<details class="note">
<summary>The [=display mode/fullscreen=] [=display mode=] is distinct from the
[[FULLSCREEN|Fullscreen API]].</summary>

The ''fullscreen'' value for [=display-mode=] is not directly related
to the CSS '':fullscreen'' pseudo-class.
The '':fullscreen'' pseudo-class matches an element
exclusively when that element is put into the fullscreen element stack.
However, a side effect of calling the {{requestFullscreen()}} method
on an element using the [[FULLSCREEN|Fullscreen API]]
can be that the browser enters a fullscreen mode at the OS-level,
in which case both '':fullscreen'' and ''(display-mode: fullscreen)'' will match.
</details>

<div class="example">
On some platforms,
it is possible for a user--
or a [[APPMANIFEST|Web Application Manifest]]--
to put a web application into fullscreen
without invoking the [[FULLSCREEN|Fullscreen API]].
When this happens,
the '':fullscreen'' pseudo class will not match,
but ''(display-mode: fullscreen)'' will match.
This is exemplified in CSS code below:

<pre class="lang-css">
/* applies when the viewport is fullscreen */
@media (display-mode: fullscreen) {
...
}
<div class="example">
On some platforms,
it is possible for a user--
or a [[APPMANIFEST|Web Application Manifest]]--
to put a web application into fullscreen
without invoking the [[FULLSCREEN|Fullscreen API]].
When this happens,
the '':fullscreen'' pseudo class will not match,
but ''(display-mode: fullscreen)'' will match.
This is exemplified in CSS code below:

<pre class="lang-css">
/* applies when the viewport is fullscreen */
@media (display-mode: fullscreen) { … }

/* applies when an element is fullscreen */
#game:fullscreen { … }
</pre>
</div>
</details>

/* applies when an element is fullscreen */
#game:fullscreen {
...
}
</pre>
</div>
Note: Additional values for this media feature may be added in the future to
match new [=display mode|display modes=] added to [[APPMANIFEST]].

<!--
████████ ████ ██████ ████████ ███████ ██ ██ ███ ██ ████ ████████ ██ ██
Expand Down Expand Up @@ -3411,6 +3419,8 @@ In addition to editorial changes and minor clarifications,
the following changes and additions were made to this module since the
<a href="https://www.w3.org/TR/2021/WD-mediaqueries-5-20211218/">2021-12-18 Working Draft</a>:

* Moved 'display mode' definition back to [[APPMANIFEST]] ('display-mode' media feature remains
here). (See <a href="https://github.com/w3c/csswg-drafts/issues/7306">Issue 7306</a>)
* Establish a normative reference for [[Display-P3]]
* Disallow use of ''layer'' as a media type, rather than merely treat it as an unknown one, for compatibility with [=cascade layers=].
* Clarify intent of 'prefers-reduced-motion'
Expand All @@ -3423,7 +3433,7 @@ In addition to editorial changes and minor clarifications,
the following changes and additions were made to this module since the
<a href="https://www.w3.org/TR/2020/WD-mediaqueries-5-20200731/">2020-07-31 Working Draft</a>:

* Adopted 'display-mode' from [[APPMANIFEST]].
* Adopted 'display mode' definition and media feature from [[APPMANIFEST]].
(See <a href="https://github.com/w3c/csswg-drafts/issues/6343">Issue 6343</a>)
* Dropped the media features what were meant to query about the geometry of the video plane
in <a href="#video-prefixed-features">bi-plane implementations</a>:
Expand Down

0 comments on commit e8cc514

Please sign in to comment.