From 6ddbc51f946dec000bf1ecac00a53cf08229a95b Mon Sep 17 00:00:00 2001 From: Daniel Libby Date: Mon, 30 Aug 2021 06:09:50 -1000 Subject: [PATCH] [css-env-1] Introduce environment variable indexing and viewport segment environment variables #5622 (#6474) This change adds the ability to index multiple dimensions via the env() syntax. Also adds the viewport segment variables, of which there are 6 values (viewport-segment-{width, height, top, right, bottom, left}), all of which have two dimensions representing their physical location in grid-like organization of the divided viewport. Co-authored-by: Tab Atkins Jr. --- css-env-1/Overview.bs | 94 +++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 91 insertions(+), 3 deletions(-) diff --git a/css-env-1/Overview.bs b/css-env-1/Overview.bs index 085867f6575..b0c0416faab 100644 --- a/css-env-1/Overview.bs +++ b/css-env-1/Overview.bs @@ -52,6 +52,17 @@ These "global" variables have both benefits and downsides versus cascading varia can be retrieved via ''env()'', whereas the element-specific nature of ''var()'' was not an appropriate place to pipe that information in. +Most [=environment variables=] will have a single value at a time. +Some, however, are "indexed", representing multiple values at once, +such as the sizes and positions of several distinct panes of content +in the ''viewport-segment-*'' variables. +To refer to these indexed variables, one or more integers must be provided +alongside the variable name, +like ''viewport-segment-width 1 0'', +to select a single value from the list or grid of possibilities, +similar to selecting one element from a list in a traditional programming language +with a syntax like values[0]. + Environment Variables {#environment} ==================================== @@ -85,18 +96,23 @@ Safe area inset variables {#safe-area-insets} Name Value + Number of dimensions safe-area-inset-top <> + 0 (scalar) safe-area-inset-right <> + 0 (scalar) safe-area-inset-bottom <> + 0 (scalar) safe-area-inset-left <> + 0 (scalar) The safe area insets are four [=environment variables=] that define a rectangle by @@ -108,6 +124,73 @@ the rectangle to be invisible due to the nonrectangular nature of the display. T allows authors to limit the layout of essential content to the space inside of the safe area rectangle. + + +Viewport segment variables {#viewport-segments} +------------------------------------------------------------------ + + + + + + + + + +
Name + Value + Number of dimensions +
viewport-segment-width + <> + 2 +
viewport-segment-height + <> + 2 +
viewport-segment-top + <> + 2 +
viewport-segment-left + <> + 2 +
viewport-segment-bottom + <> + 2 +
viewport-segment-right + <> + 2 +
+ +The viewport segments are [=environment variables=] that define the position and +dimensions of a logically separate region of the viewport. Viewport +segments are created when the viewport is split by one or more hardware features +(such as a fold or a hinge between separate displays) that act as a divider; +segments are the regions of the viewport that can be treated as logically distinct +by the author. + +The viewport segment [=environment variables=] have two dimensions, which represent +the x and y position, respectively, in the two dimensional grid created by the +hardware features separating the segments. +Segments along the left edge have x position ''0'', those in the next column to the right have x position ''1'', etc. +Similarly, segments along the top edge have y position ''0'', etc. + +Note: In certain hardware configurations, the separator itself may occupy logical +space within the viewport. The dimensions of the separator can be computed by +calculating the area between the position of the viewport segments. + +
+ When the viewport is split into two side-by-side segments, the viewport segment on + the left would have indices (0, 0). It's width would be represented as + ''env(viewport-segment-width 0 0, 300px)''. + The viewport segment on the right would have indices (1, 0). + Similarly, for a viewport split into two vertical segments, the viewport segment + on the top would have indices (0, 0) and the one on the bottom (0, 1). +
+ +These variables are only defined when there are at least two such segments. +Viewport units should be used instead when there is no hardware feature +splitting the viewport, otherwise content will not display as intended when +viewed on a device with multiple segments. + Using Environment Variables: the ''env()'' notation {#env-function} =================================================================== @@ -115,7 +198,7 @@ In order to substitute the value of an [=environment variable=] into a CSS conte use the ''env()'' function: 
-	env() = env( <> , <>? )
+	env() = env( <> <>*, <>? )
The ''env()'' function can be used in place of any part of a value in any property on any element, @@ -133,7 +216,10 @@ and in several other places where CSS values are allowed. The first argument to ''env()'' provides the name of an [=environment variable=] to be substituted. -The second argument, if provided, is a fallback value, +Following the first argument are integers that represent indices into the +dimensions of the [=environment variable=], if the provided name +represents an array-like [=environment variable=]. +The argument after the comma, if provided, is a fallback value, which is used as the substitution value when the referenced [=environment variable=] does not exist. @@ -156,7 +242,9 @@ It is only syntax-checked after ''env()'' functions have been [=substituted=]. To substitute an env() in a property or descriptor: 1. If the name provided by the first argument of the ''env()'' function - is a recognized [=environment variable=], + is a recognized [=environment variable=] name, the number of supplied integers + matches the number of dimensions of the [=environment variable=] referenced + by that name, and values of the indices correspond to a known sub-value, replace the ''env()'' function by the value of the named [=environment variable=]. 2. Otherwise, if the ''env()'' function has a fallback value as its second argument,