GeezerVison

1. Introduction

2. Terminology

In CSS 2.1 a viewport is a feature of a user agent for continuous media and used to establish the initial containing block for continuous media. For paged media, the initial containing block is based on the page area. The page area can be set through @page rules.

This specification introduces a way of overriding the size of the viewport provided by the user agent (UA). Because of this, we need to define initial viewport, layout viewport and visual viewport.

initial viewport

This refers to the viewport before any UA or author styles have overridden the viewport given by the window or viewing area of the UA.

Note: The initial viewport size will change with the size of the window or viewing area.

layout viewport

This is the viewport you get after processing the viewport <meta> tag.

visual viewport

This is the portion of the layout viewport that is currently visible, obtained by result of applying scale transform to it. This transform is applied to the canvas of the layout viewport and does not affect its internal coordinate space. The magnitude of the scale transform is known as the visual viewport’s scale factor.

Note: The visual viewport can be smaller than the layout viewport.

Note: The scale transform of the visual viewport is often referred to as "pinch-zoom". Conceptually, this transform changes the size of the CSS reference pixel and changes the size of the layout viewport (inversally) proportionally so that it does not cause reflow of the page’s contents.

When the layout viewport cannot fit inside the window or viewing area, either because the layout viewport is larger than the initial viewport or the zoom factor causes only parts of the layout viewport to be visible, the UA should offer a scrolling or panning mechanism.

Note: The visual viewport’s scrolling area is the layout viewport.

It is recommended that initially the upper-left corners of the layout viewport and the window or viewing area are aligned if the base direction of the document is ltr. Similarly, that the upper-right corners are aligned when the base direction is rtl. The base direction for a document is defined as the computed value of the direction property for the first <BODY> element of an HTML or XHTML document. For other document types, it is the computed direction for the root element.

2.1. Display feature definition

Below is an illustration describing the concept of display features and how they divide the viewport in segments:

3. Viewport <meta> element

Specify me

3.1. Properties

The recognized properties in the viewport <meta> element are:

• width
• height
• initial-scale
• minimum-scale
• maximum-scale
• user-scalable
• interactive-widget

3.2. Parsing algorithm

Below is an algorithm for parsing the content attribute of the <meta> tag produced from testing Safari on the iPhone. The testing was done on an iPod touch running iPhone OS 4. The UA string of the browser: "Mozilla/5.0 (iPod; U; CPU iPhone OS 4_0 like Mac OS X; en-us) AppleWebKit/532.9 (KHTML, like Gecko) Version/4.0.5 Mobile/8A293 Safari/6531.22.7". The pseudo code notation used is based on the notation used in [Algorithms].

The whitespace class contains the following characters (ascii):

• Horizontal tab (0x09)
• Line feed (0x0a)
• Carriage return (0x0d)
• Space (0x20)

The recognized separator between property/value pairs is comma for the Safari implementation. Some implementations have supported both commas and semicolons. Because of that, existing content use semicolons instead of commas. Authors should be using comma in order to ensure content works as expected in all UAs, but implementors may add support for both to ensure interoperability for existing content.

The separator class contains the following characters (ascii), with comma as the preferred separator and semicolon as optional:

• Comma (0x2c)
• Semicolon (0x3b)

Parse-Content(S)
i ← 1
while i ≤ length[S]
	do while i ≤ length[S] and S[i] in [whitespace, separator, '=']
		do i ← i + 1
	if i ≤ length[S]
		then i ← Parse-Property(S, i)

Parse-Property(S, i)
start ← i
while i ≤ length[S] and S[i] not in [whitespace, separator, '=']
	do i ← i + 1
if i > length[S] or S[i] in [separator]
	then return i
property-name ← S[start .. (i - 1)]
while i ≤ length[S] and S[i] not in [separator, '=']
	do i ← i + 1
if i > length[S] or S[i] in [separator]
	then return i
while i ≤ length[S] and S[i] in [whitespace, '=']
	do i ← i + 1
if i > length[S] or S[i] in [separator]
	then return i
start ← i
while i ≤ length[S] and S[i] not in [whitespace, separator, '=']
	do i ← i + 1
property-value ← S[start .. (i - 1)]
Set-Property(property-name, property-value)
return i

Set-Property matches the listed property names case-insensitively. The property-value strings are interpreted as follows:

1. If a prefix of property-value can be converted to a number using strtod, the value will be that number. The remainder of the string is ignored.
2. If the value can not be converted to a number as described above, the whole property-value string will be matched with the following strings case-insensitively: yes, no, device-width, device-height
3. If the string did not match any of the known strings, the value is unknown.

3.3. extend-to-zoom

Specify extend-to-zoom behavior by the viewport meta tag

3.4. interactive-widget

The interactive-widget property specifies the effect that interactive UI widgets have on the page’s viewports. It defines whether widgets overlay a given viewport or whether the viewport is shrunken so that it remains fully visible while the widget is showing. Interactive UI widgets are transient user agent or operating system UI through which a user can provide input.

The following is a list of valid values for interactive-widget and the associated viewport-resizing behavior:

overlays-content

Interactive UI widgets MUST NOT resize the initial viewport nor the visual viewport. The user agent must perform the same steps as when VirtualKeyboard.overlaysContent is set to true.

resizes-content

Interactive UI widgets MUST resize the initial viewport by the interactive widget.

Since the visual viewport’s size is derived from the initial viewport, resizes-content will cause a resize of both the initial and visual viewports.

resizes-visual

Interactive UI widgets MUST resize the visual viewport but MUST NOT resize the initial viewport.

If no value, or an invalid value, is set for interactive-widget, the behavior implied by resizes-visual is used as the default.

To resize a viewport by an interactive widget, subtract from it the intersection of the viewport rect with the widget’s OS reported bounding rect. In cases where this would result in a non-rectangular viewport, the behavior is user agent defined.

3.4.1. Interaction with virtualKeyboard.overlaysContent

[VIRTUAL-KEYBOARD] provides an imperative API to apply the overlays-content behavior via the VirtualKeyboard.overlaysContent attribute. This attribute shadows the value set to interactive-widget, namely:

When VirtualKeyboard.overlaysContent is set to true, the UA MUST ignore any value set to interactive-widget when determining the resizing behavior of interactive widgets.

When VirtualKeyboard.overlaysContent is set to false, the UA MUST use the value set to interactive-widget, or the default behavior if a value is not set, when determining the resizing behavior of interactive widgets.

Getting the value of VirtualKeyboard.overlaysContent MUST return only the value previously set to it.

4. The zoom property

An element becomes zoomed when the zoom property has a positive computed value different than 1 (or when a flat tree ancestor has zoom).

To apply zoom, the used value of a CSS property (including values inside of path() strings) is pre-multiplied (before any other steps in the used value stage) by the used value of zoom for the element. It also multiplies the natural size of all replaced elements, background images, and nested frames (except for fenced frames [FENCED-FRAME]) by the used value of zoom.

Note: This results in a magnification or minification effect.

Nested values of zoom multiply, resulting in additional scaling of <length> values. The used value for zoom is always its effective zoom.

The zoom property has no effect on <length> property values with computed values that are auto or <percentage>.

Note: Unlike transform, scaling the zoom property affects layout.

Note: The computed value of font-size is never <percentage>; thus zoom always applies.

Note: zoom does not affect or prevent transform scaling.

The values of this property have the following meanings:

<number>

Positive floating point number indicating a zoom factor. Numbers smaller than 1.0 indicate a "zoom out" or minification effect, while numbers greater than 1.0 indicate a "zoom in" or magnification effect. A 0 value is treated as if it was 1.

Note: The treatment of 0 is a web compatibility quirk.

<percentage>

Positive floating point number, followed by a percentage character ("%") which indicates a zoom factor multiplied by 100. A 0 percentage is treated as if it was 100%.

Note: The treatment of 0 is a web compatibility quirk.

Negative values for zoom are illegal.

<div class="messageBox">
  <div class="label">Text of the label</div>
</div>

<style>
.messageBox {
    width: 10em;
    padding: 2em;
    border: medium solid lightblue;
}

.messageBox:hover {
    zoom: 150%;
}

.label {
    background: lightgrey;
    padding: 1em;
    text-align: center;
}
</style>

<div style="zoom: 2">
  Middle text
  <div style="zoom: 2">
     Inner text
  <div>
<div>
Outer text

<div style="zoom: 2">
  <img src="...">
  <iframe src="..."></iframe>
<div>

The effective zoom of an element is the product of its computed value of zoom and all flat tree ancestors' computed values of zoom.

The scaled value of a CSS length is the used value of that length; in particular it includes zoom.

The unscaled value of a CSS length relative to an element is the scaled value divided by the element’s effective zoom.

4.1. DOM and CSSOM interaction

Computed style APIs (i.e., all values returned by getComputedStyle()) that are non-auto and non-percentage lengths must be unscaled.

The getBoundingClientRect, getClientRects, and IntersectionObserver APIs must return rects with scaled lengths.

All other APIs related to element geometries must return unscaled lengths (except as detailed below). This is explained in detail in CSSOM View § 7 Extensions to the HTMLElement Interface.

In cases where properties (such as scrollTop) are propagated to the viewport, APIs for these lengths must be in viewport units, and not be divided by the zoom of the element.

The devicePixelRatio of a frame is multiplied by the effective zoom inherited by its parent frame.

5. Extensions to the Window Interface

partial interface Window {
[SameObject, Replaceable] readonly attribute Viewport viewport;
};

6. The Viewport Interface

[Exposed=Window]
interface Viewport {
  readonly attribute FrozenArray<DOMRect>? segments;
};

7. The segments property

The segments property is an array of DOMRect that represent the dimensions of each existing viewport segment. Each DOMRect contains the geometry of the segment (x, y, width, height) in CSS px.

Additional details about the definition of a viewport segment can be found here: CSS Environment Variables 1 § 2.3 Viewport segment variables.

The segments attribute getter steps are:

1. If the Viewport’s associated Document is not fully active, return null.

2. Let topLevelTraversable be document’s relevant global object’s navigable’s top-level traversable.

3. If topLevelTraversable.[[DisplayFeaturesOverride]] is non-null, return Viewport’s segments array calculated from topLevelTraversable.[[DisplayFeaturesOverride]].

4. If there is only a single viewport segment (typically the size of the Viewport) return an array with that single segment.

5. Otherwise, return the Viewport’s segments array calculated from the hardware features.

Privacy Considerations

No new privacy considerations have been reported on this specification.

Security Considerations

No new security considerations have been reported on this specification.

Appendix A. Changes

This appendix is informative.

Since the 29 March 2016 Working Draft

• Added interactive-widgets property to viewport meta
• Removed @viewport rule
• Renamed spec from device-adapt to css-viewport
• CSSViewportRule exposed to Window

Since the 15 September 2011 First Public Working Draft.

• Made various editorial improvements and clarifications.
• Added OM Interfaces.
• Added semi-colon as separator in meta viewport.
• Created UA stylesheets section.
• Added recommendation for when to respect orientation property.
• Dropped support for the resolution descriptor.
• Decouple width/height and zoom, introducing extend-to-zoom value for meta viewport translation.
• Made normative rules about interaction of @viewport and @media.
• Allow 0 for <viewport-length> and zoom values
• Removed support for device-width/height.
• Apply @viewport to top level document only.
• Extend [CSS3-CONDITIONAL] rather than CSS21 for nesting in @media.

Appendix B. Automation

Automation of the segments property

A display feature override is a struct encapsulating the result of a single display feature. It has a orientation (a string that is either "vertical" or "horizontal"), a mask length (a positive number describing the length of the feature in CSS px), and an offset (which describe the distance from the origin of the viewport in CSS px).

Internal slots

Extensions Commands

Set display features

This extension command creates a setup that emulates a set of display feature override by taking a list of display features as parameter.

enum OrientationType {
  "vertical",
  "horizontal"
};

interface DisplayFeature {
  readonly attribute OrientationType orientation;
  readonly attribute double offset;
  readonly attribute double maskLength;
};

{
  "features": [
    {
      "orientation": "horizontal",
      "offset": 190,
      "maskLength": 20
    }
  ]
}

1. Let features be the result of invoking getting a property "features" from parameters.
2. If features is not a Array, return error with WebDriver error code invalid argument.
3. Let parsedFeatures be a new list of display feature override.
4. For each feature item in features:
   1. If feature item is not an Object, return error with WebDriver error code invalid argument.
   2. Let mask length be the result of invoking getting a property "maskLength" from feature item.
   3. If mask length is not a Number or its value is NaN, +∞, −∞, or negative return error with WebDriver error code invalid argument.
   4. Let offset be the result of invoking getting a property "offset" from feature item.
   5. If offset is not a Number or its value is NaN, +∞, −∞, or negative return error with WebDriver error code invalid argument.
   6. Let orientation be the result of invoking getting a property "orientation" from feature item.
   7. If orientation is not a string, return error with WebDriver error code invalid argument.
   8. If orientation is neither "vertical" or "vertical", return error with WebDriver error code invalid argument.
   9. If orientation is "vertical" and mask length + offset is greater than viewport width including the size of the rendered scrollbar, return error with WebDriver error code invalid argument.
   10. If orientation is "vertical" and mask length + offset is greater than viewport height including the size of the rendered scrollbar, return error with WebDriver error code invalid argument.
   11. Let override be a new display feature override.
   12. Set override’s mask length to mask length.
   13. Set override’s orientation to orientation.
   14. Set override’s offset to offset.
   15. Append override to parsedFeatures.
5. Let topLevelTraversable be the current browsing context’s top-level traversable.
6. Set topLevelTraversable.[[DisplayFeaturesOverride]] to parsedFeatures.
7. Return success with data null.

Clear display features

1. Let topLevelTraversable be the current browsing context’s top-level traversable.
2. Set topLevelTraversable. [[DisplayFeaturesOverride]] to null.
3. Return success with data null.