Skip to content

Commit

Permalink
[css-viewport] Add the segments property (w3c#9237).
Browse files Browse the repository at this point in the history
This property exposes in JavaScript what is already exposed to
CSS via env() variables.

TAG review w3ctag/design-reviews#689.

CSSWG Approval: w3c#9237#issuecomment-2160730855

Fixes w3c#9237.
  • Loading branch information
darktears committed Jul 16, 2024
1 parent 3db9601 commit dc2d78b
Showing 1 changed file with 46 additions and 0 deletions.
46 changes: 46 additions & 0 deletions css-viewport/Overview.bs
Original file line number Diff line number Diff line change
Expand Up @@ -526,6 +526,52 @@ The <dfn export>unscaled</dfn> value of a CSS length relative to an element is t
The {{Window/devicePixelRatio}} of a frame is multiplied by the [=effective zoom=] inherited by its parent frame.
</h3>

<h2 id=extensions-to-the-window-interface>Extensions to the {{Window}} Interface</h2>

<pre class=idl>
partial interface Window {
[SameObject, Replaceable] readonly attribute Viewport? viewport;
};
</pre>

<h2 id=viewport>Viewport</h2>

<h3 id="the-viewport-interface">The {{Viewport}} Interface</h3>

<pre class=idl>
[Exposed=Window]
interface Viewport : EventTarget {
readonly attribute FrozenArray&lt;DOMRect> segments;
};
</pre>

<h2 id='segments'>
The <dfn attribute for=Viewport>segments</dfn> property
</h2>

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 ''<length>/px''.

Additonal details about the definition of a viewport segment can be found here : [[css-env-1#viewport-segments]].

The {{segments}} attribute must run these steps:
1. If the {{Viewport}}'s associated {{Document}} is not <a>fully active</a>, return 0.
2. Returns null if there is only a single viewport segment and abort these steps.
3. Otherwise, return the {{Viewport}}'s segments array.

<div class=non-normative>
<em>This section is not normative.</em>

The {{segments}} property represents an immutable snapshot of the device {{segments}} when the value was queried.
If the device state changes (rotation, window resize, <a spec="DEVICE-POSTURE">posture</a> change), the value previously retrieved will be invalid. Developers can listen to {{ScreenOrientation/onchange|Screen Orientation}}, {{Window/resize|Window Resize}}, or {{DevicePosture/onchange|Posture}} changes events to detect device state changes.

<div class="example">
If a viewport of 400px by 400px is split horizontally into two side-by-side segments, the {{segments}} array will have the following content:
<code highlight=javascript>[DOMRect(0, 0, 400, 200), DOMRect(0, 200, 400, 200)]</code>
</div>

</div>

<h2 class="no-num" id="changes">Appendix A. Changes</h2>

This appendix is <em>informative</em>.
Expand Down

0 comments on commit dc2d78b

Please sign in to comment.