Skip to main content

Get information about the connected displays and the position of the windows in relation to those displays.


Updated

The Multi-Screen Window Location API is part of the capabilities project and is currently under development. This post will be updated as implementation progresses.

The Multi-Screen Window Location API allows you to list the displays connected to your machine and place windows on specific displays.

Suggested use cases

Examples of sites that can use this API include:

  • Multi-window graphical editors at the
    Gimp You can place various editing tools in precisely placed windows.
  • Virtual trading desks can display market trends in multiple windows, any of which can be viewed in full screen mode.
  • Slide show applications can display speaker notes on the internal main screen and the presentation on an external projector.

Actual state

He passed Condition
1. Create an explainer To complete
2. Create initial draft specification To complete
3. Collect feedback and repeat the design In progress
4. Proof of origin In progress
5. Launch Not started

How to Use the Multi-Screen Window Location API

Enabling via chrome: // flags

To experiment with the multiscreen window placement API locally, without a source test token, enable the #enable-experimental-web-platform-features flag on chrome://flags.

Enable support during the proof of origin phase

Starting with Chrome 86, the Multi-Screen Window Location API will be available as a proof of origin in Chrome. Proof of Origin is expected to finish on Chrome 88 (Feb 24, 2021).

Origin testing allows you to test new features and provide feedback on their usability, practicality, and effectiveness to the web standards community. For more information, see the Origin testing guide for web developers. To enroll in this or any other proof of origin, visit the registration page.

Register for proof of origin

  1. Request a token by your origin.
  2. Add the token to your pages. There are two ways to do it:
    • Add a origin-trial tag to the header of each page. For example, this might look like this:
    • If you can configure your server, you can also add the token using a Origin-Trial HTTP header. The resulting response header should look like this:
      Origin-Trial: TOKEN_GOES_HERE

The problem

The time-tested approach to controlling windows,
Window.open (), unfortunately unaware of additional screens. While some aspects of this API seem a bit archaic, like its
windowFeatures
DOMString parameter, however, has served us well over the years. To specify a window
position, you can pass the coordinates as left and top (or screenX and screenY respectively) and pass the desired
Size how
width and height (or innerWidth and innerHeight respectively). For example, to open a 400 × 300 window at 50 pixels from the left and 50 pixels from the top, this is the code you can use:

const popup = window . open (
"https://example.com/" ,
"My Popup" ,
"left = 50, top = 50, width = 400, height = 300"
) ;

You can get information about the current screen by looking at the
window.screen property, which returns a Screen object. This is the output on my MacBook Air 13 ″:

window . screen ;

Like most people who work in technology, I have had to adapt to the new work reality and set up my own home office. Mine looks like the photo below (if you are interested, you can read the
full details about my setup). The iPad next to my MacBook Air is connected to the laptop via
Sidecarso when I need it, I can quickly turn the iPad into a second screen.

desk-8653333
A multi-screen setup.

If I want to take advantage of the larger screen, I can put the popup from the above code example on the second screen. I do it like this:

popup . moveTo ( 2500 , 50 ) ;

This is a rough assumption, as there is no way to know the dimensions of the second screen. The information of window.screen It only covers the built-in screen, but not the iPad screen. The reported width of the built-in screen was 1680 pixels, so moving to
2500 pixels might work to change the window to the iPad, as me I happen to know that it is located to the right of my MacBook Air. How can I do this in the general case? Turns out there is a better way than guessing. That's the way it is the multiscreen window placement API.

Feature detection

To check if the multiscreen window placement API is supported, use:

if ( "getScreens" in window ) {
}

the window-placement Excuse me

Before I can use the multiscreen window placement API, I must ask the user for permission to do so. The new window-placement The permit can be consulted with the
Permissions API like:

let granted = false ;
try {
const { state } = await navigator . permissions . query ( { name : "window-placement" } ) ;
granted = state === "granted" ;
} catch {
}

The Navigator
can
Choose to display the permission request dynamically on the first attempt to use any of the new API methods. Read on for more information.

the isMultiScreen () method

To use the multiscreen window placement API, I'll first call the
Window.isMultiScreen () method. Returns a promise that is resolved with true or false, depending on whether one or more displays are currently connected to the machine. For my setup it goes back true.

await window . isMultiScreen ( ) ;

the getScreens () method

Now that I know the current setup is multi-screen, I can get more information about the second screen using Window.getScreens (). Returns a promise that resolves to an array of Screen objects. On my MacBook Air 13 with an iPad attached, this returns an array of two Screen objects:

await window . getScreens ( ) ;

Notice how the value of left for iPad starts at 1680, which is exactly the width of the built-in screen. This allows me to determine exactly how the screens are logically arranged (side by side, one on top of the other, etc.). There is also data now for each screen to show if it is a internal one and if it is a primary one. Please note that the built-in screen
not necessarily the main screen. They both also have go, which, if it persists in the browser sessions, allows to restore the distribution of the windows.

the screenschange event

The only thing missing now is a way to detect when my display settings change. A new event
screenschange, it does exactly that: it fires every time the constellation on the screen changes. (Note that "screens" is plural in the event name). It is also activated when the resolution of one of the connected displays changes or when a new or existing display is (physically or virtually in the case of Sidecar) connected or disconnected.

Note that you have to search the details of the new screen asynchronously, screenschange The event itself does not provide this data. This can change in the future. For now, you can find the screen details by calling window.getScreens () As shown below.

window . addEventListener ( 'screenschange' , async ( event ) => {
console . log ( 'I am there, but mostly useless' , event ) ;
const details = await window . getScreens ( ) ;
} ) ;

New full screen options

Until now, you could request that items be displayed in full screen mode via the appropriate name
requestFullScreen ()

method. The method takes a options parameter where you can pass
FullscreenOptions. Until now, his only property has been
navigationUI. Multiscreen Window Location API adds a new one screen property that allows you to determine on which screen to start full-screen view. For example, if you want the main screen to be full screen:

try {
const primaryScreen = ( await getScreens ( ) ) . filter ( ( screen ) => screen . primary ) [ 0 ] ;
await document . body . requestFullscreen ( { screen : primaryScreen } ) ;
} catch ( err ) {
console . error ( err . name , err . message ) ;
}

Polyfill

The multiscreen window placement API cannot be populated, but you can adjust its shape so that you can code exclusively with the new API:

if ( ! ( "getScreens" in window ) ) {
window . getScreens = async ( ) => [ window . screen ] ;
window . isMultiScreen = async ( ) => false ;
}

The other aspects of the API: the onscreenschange event and the screen property of the
FullscreenOptions: Unsupported browsers would never fire or silently ignore, respectively.

Manifestation

If you are like me, you closely monitor the development of different cryptocurrencies. (I don't actually do it, but for the sake of this article, I guess I do.) To keep track of the cryptocurrencies I own, I have developed a web application that allows me to observe the markets in a lifetime. situations, like from the comfort of my bed, where I have a decent single screen setup.

tv-4772243
Relax and watch the markets.

When it comes to crypto, the markets can get choppy at any time. If this were to happen, I can quickly move to my desktop where I have a multi-display setup. I can click on any coin window and quickly see the full details in a full screen view on the opposite screen. Below is a recent photo of me taken during the last YCY blood bath. It caught me completely off guard and left me
with my hands on my face.

panik-5684572
In panic, witnessing YCY's bloodbath.

You can play with it manifestation embedded below, or view your source code in failure.

Security and permissions

The Chrome team has designed and implemented the Multi-Screen Window Location API using the basic principles defined in Control access to powerful features of the web platform, including user control, transparency and ergonomics. The Multi-Screen Window Location API exposes new information about the displays connected to a device, increasing the fingerprint footprint of users, especially those with multiple displays constantly connected to their devices. As a mitigation of this privacy issue, the exposed screen properties are limited to the minimum necessary for common location use cases. User permission is required for sites to retrieve information from multiple screens and place windows on other screens.

User control

The user is in full control of the exposure of their settings. They can accept or reject the permission request and revoke a previously granted permission through the site's information feature in the browser.

Transparency

The fact that permission to use the Multi-Screen Window Location API has been granted is exposed in the browser's site information and can also be viewed through the Permissions API.

Permission persistence

The browser retains the permission grants. The permission can be revoked through the browser's site information.

Feedback

The Chrome team wants to hear about your experiences with the Multi-Screen Window Location API.

Tell us about the API design

Is there something in the API that is not working as expected? Or are you missing any methods or properties you need to implement your idea? Have a question or comment about the security model?

  • File a spec issue in the corresponding GitHub repositoryor add your thoughts to an existing problem.

Report a problem with the deployment

Found a bug with the Chrome implementation? Or is the implementation different from the specification?

  • File a bug in new.crbug.com. Be sure to include as much detail as you can, simple instructions to reproduce, and enter Blink> WindowDialog at
    Components box. Failure works great for quick and easy sharing of reps.

Show API support

Thinking of using the multiscreen window placement API? Your public support helps the Chrome team prioritize features and shows other browser vendors how important it is to support them.

  • Share how you plan to use it in the WICG Speech Thread
  • Send a tweet to @Cromodev with the #WindowPlacement hashtag and let us know where and how you are using it.
  • Ask other browser vendors to implement the API.

Helpful Links

Thanks

The multiscreen window location API specification was edited by
Victor Costan and
Joshua bell. The API was implemented by
Mike wasserman. This article was reviewed by
Joe medley,
François beaufortand Kayce Basques. Thanks to Laura Torrent Puig for the photos.

error: Attention: Protected content.