Skip to content

Commit

Permalink
Move the definition of display-mode back to APPMANIFEST. Closes w3c#7306
Browse files Browse the repository at this point in the history 
.

This text was moved out of the Manifest spec into CSS mediaqueries-5 in
w3c#6343, along with the display-mode media feature. The
actual definition of display mode belongs in Manifest, while the
display-mode media feature remains here.

Added some more text explaining how the display-mode media feature works
given that this is in a separate spec to where web apps are defined.
  • Loading branch information
@mgiuca
mgiuca committed Feb 26, 2024
1 parent a676261 commit e313f31
Showing 1 changed file with 33 additions and 83 deletions.
116 changes: 33 additions & 83 deletions mediaqueries-5/Overview.bs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1306,104 +1306,54 @@ Display Modes: the ''display-mode'' media feature </h3>
Type: discrete
</pre>

The 'display-mode' media feature represents the [=display mode=] of the web application.
The 'display-mode' media feature represents the [=display mode=] of the current [=browsing context=].
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.
The values of this feature correspond to the [=display mode|display modes=] defined in
[[APPMANIFEST]]. However, this media feature reflects the actual display mode that is being used
on the current browsing context, not necessarily the one that was requested in the web app
manifest (if any).

This specification defines the following [=display modes=]:
<dl dfn-for="display mode" export>
<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.

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

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

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

<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.
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>
On normal web pages, 'display-mode' will have a value of 'browser'. Only pages appearing in the
context of an [=installed web application=] can have a different 'display-mode', reflecting the
way in which the application window is being presented to the end user.

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

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

The ''fullscreen'' <a>display mode</a> is also not directly related
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>
/* applies when an element is fullscreen */
#game:fullscreen {
...
}
</pre>
</div>
</details>

<!--
████████ ████ ██████ ████████ ███████ ██ ██ ███ ██ ████ ████████ ██ ██
Expand Down Expand Up @@ -3413,7 +3363,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 the 'display-mode' 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 e313f31

Please sign in to comment.