Skip to content

Latest commit

 

History

History
57 lines (47 loc) · 4.2 KB

HOWTO.md

File metadata and controls

57 lines (47 loc) · 4.2 KB
Raw

How to use the Window Management API

The Window Management API is currently available in Chrome:

  • Chrome 100+ enables Window Management APIs by default.
  • Chrome 93+ supports Window Management APIs with either one of these flags enabled:
    • chrome://flags#enable-experimental-web-platform-features
    • chrome --enable-blink-features=WindowPlacement

Try these basic API demos, which request permission to use info about your screens to open and place windows:

Here is an example of how to use the API:

async function main() {
  // Run feature detection.
  if (!('getScreenDetails' in window)) {
    console.log('The Window Manamgenet API is not supported.');
    return;
  }
  // Detect the presence of extended screen areas.
  if (window.screen.isExtended) {
    // Request extended screen information.
    const screenDetails = await window.getScreenDetails();

    // Find the primary screen, show some content fullscreen there.
    const primaryScreen = screenDetails.screens.find(s => s.isPrimary);
    document.documentElement.requestFullscreen({screen : primaryScreen});

    // Find a different screen, fill its available area with a new window.
    const otherScreen = screenDetails.screens.find(s => s != primaryScreen);
    window.open(url, '_blank', `left=${otherScreen.availLeft},` +
                               `top=${otherScreen.availTop},` +
                               `width=${otherScreen.availWidth},` +
                               `height=${otherScreen.availHeight}`);
  } else {
    // Arrange content within the traditional single-screen environment.
  }
};

How to use API enhancements

Fullscreen Companion Window permits sites with the window-management permission to initiate a multi-screen experience from a single user activation. Specifically, this proposed enhancement allows scripts to open a popup window when requesting fullscreen on a specific screen of a multi-screen device. Test this by invoking "Fullscreen slide and open notes" in the window-placement-demo.

  • Chrome 104+ enables this enhancement by default.
  • Chrome 102+ supports this enhancement with this flag enabled:
    • chrome --enable-features=WindowPlacementFullscreenCompanionWindow

Fullscreen Capability Delegation allows a frame to relinquish its transient user activation, in order to permit another frame (e.g. child, opener, opened popup, sibling) to request fullscreen. This tangential feature enhances multi-screen web applications by enabling a companion window to offer controls for its fullscreen opener. Specifically, fullscreen capability delegation allows a gesture on a companion window to "swap" the displays used for the fullscreen and companion windows. Test this by invoking "Fullscreen slide and open notes" in the window-placement-demo, focusing the companion popup window, and pressing the [s] key to swap screens.

  • Chrome 104+ enables this enhancement by default.
  • Chrome 103+ supports this enhancement with this flag enabled:
    • chrome --enable-blink-features=CapabilityDelegationFullscreenRequest

Accurate Screen Labels refines the ScreenDetailed.label implementation by replacing the current placeholder values (e.g. 'External Display 1') with data sourced from display device EDIDs (e.g. 'HP Z27n') and higher-level OS APIs (e.g. language localized 'Built-in Retina Display'). These more accurate labels match those shown by OSes in display settings UI surfaces. Test this by observing the screen label strings displayed in the window-placement-demo.

  • Chrome 104+ supports this enhancement on some OSes with this flag enabled:
    • chrome --enable-blink-features=WindowPlacementEnhancedScreenLabels