diff --git a/files/en-us/_redirects.txt b/files/en-us/_redirects.txt index 4d9fdfd60f77ad9..654231a6a1b78b7 100644 --- a/files/en-us/_redirects.txt +++ b/files/en-us/_redirects.txt @@ -2214,17 +2214,17 @@ /en-US/docs/DOM/window.restore /en-US/docs/Web/API/Window/moveTo /en-US/docs/DOM/window.screen /en-US/docs/Web/API/Window/screen /en-US/docs/DOM/window.screen.availHeight /en-US/docs/Web/API/Screen/availHeight -/en-US/docs/DOM/window.screen.availLeft /en-US/docs/Web/API/Screen/availLeft -/en-US/docs/DOM/window.screen.availTop /en-US/docs/Web/API/Screen/availTop +/en-US/docs/DOM/window.screen.availLeft /en-US/docs/Web/API/ScreenDetailed/availLeft +/en-US/docs/DOM/window.screen.availTop /en-US/docs/Web/API/ScreenDetailed/availTop /en-US/docs/DOM/window.screen.availWidth /en-US/docs/Web/API/Screen/availWidth /en-US/docs/DOM/window.screen.colorDepth /en-US/docs/Web/API/Screen/colorDepth /en-US/docs/DOM/window.screen.height /en-US/docs/Web/API/Screen/height -/en-US/docs/DOM/window.screen.left /en-US/docs/Web/API/Screen/left +/en-US/docs/DOM/window.screen.left /en-US/docs/Web/API/ScreenDetailed/left /en-US/docs/DOM/window.screen.lockOrientation /en-US/docs/Web/API/Screen/lockOrientation /en-US/docs/DOM/window.screen.mozBrightness /en-US/docs/Web/API/Screen/mozBrightness /en-US/docs/DOM/window.screen.mozEnabled /en-US/docs/Web/API/Screen/mozEnabled /en-US/docs/DOM/window.screen.pixelDepth /en-US/docs/Web/API/Screen/pixelDepth -/en-US/docs/DOM/window.screen.top /en-US/docs/Web/API/Screen/top +/en-US/docs/DOM/window.screen.top /en-US/docs/Web/API/ScreenDetailed/top /en-US/docs/DOM/window.screen.width /en-US/docs/Web/API/Screen/width /en-US/docs/DOM/window.screenX /en-US/docs/Web/API/Window/screenX /en-US/docs/DOM/window.screenY /en-US/docs/Web/API/Window/screenY @@ -2642,14 +2642,14 @@ /en-US/docs/DOM:window.resizeTo /en-US/docs/Web/API/Window/resizeTo /en-US/docs/DOM:window.screen /en-US/docs/Web/API/Window/screen /en-US/docs/DOM:window.screen.availHeight /en-US/docs/Web/API/Screen/availHeight -/en-US/docs/DOM:window.screen.availLeft /en-US/docs/Web/API/Screen/availLeft -/en-US/docs/DOM:window.screen.availTop /en-US/docs/Web/API/Screen/availTop +/en-US/docs/DOM:window.screen.availLeft /en-US/docs/Web/API/ScreenDetailed/availLeft +/en-US/docs/DOM:window.screen.availTop /en-US/docs/Web/API/ScreenDetailed/availTop /en-US/docs/DOM:window.screen.availWidth /en-US/docs/Web/API/Screen/availWidth /en-US/docs/DOM:window.screen.colorDepth /en-US/docs/Web/API/Screen/colorDepth /en-US/docs/DOM:window.screen.height /en-US/docs/Web/API/Screen/height -/en-US/docs/DOM:window.screen.left /en-US/docs/Web/API/Screen/left +/en-US/docs/DOM:window.screen.left /en-US/docs/Web/API/ScreenDetailed/left /en-US/docs/DOM:window.screen.pixelDepth /en-US/docs/Web/API/Screen/pixelDepth -/en-US/docs/DOM:window.screen.top /en-US/docs/Web/API/Screen/top +/en-US/docs/DOM:window.screen.top /en-US/docs/Web/API/ScreenDetailed/top /en-US/docs/DOM:window.screen.width /en-US/docs/Web/API/Screen/width /en-US/docs/DOM:window.screenX /en-US/docs/Web/API/Window/screenX /en-US/docs/DOM:window.screenY /en-US/docs/Web/API/Window/screenY @@ -3365,14 +3365,14 @@ /en-US/docs/Document_Object_Model_(DOM)/window.restore /en-US/docs/Web/API/Window/moveTo /en-US/docs/Document_Object_Model_(DOM)/window.screen /en-US/docs/Web/API/Window/screen /en-US/docs/Document_Object_Model_(DOM)/window.screen.availHeight /en-US/docs/Web/API/Screen/availHeight -/en-US/docs/Document_Object_Model_(DOM)/window.screen.availLeft /en-US/docs/Web/API/Screen/availLeft -/en-US/docs/Document_Object_Model_(DOM)/window.screen.availTop /en-US/docs/Web/API/Screen/availTop +/en-US/docs/Document_Object_Model_(DOM)/window.screen.availLeft /en-US/docs/Web/API/ScreenDetailed/availLeft +/en-US/docs/Document_Object_Model_(DOM)/window.screen.availTop /en-US/docs/Web/API/ScreenDetailed/availTop /en-US/docs/Document_Object_Model_(DOM)/window.screen.availWidth /en-US/docs/Web/API/Screen/availWidth /en-US/docs/Document_Object_Model_(DOM)/window.screen.colorDepth /en-US/docs/Web/API/Screen/colorDepth /en-US/docs/Document_Object_Model_(DOM)/window.screen.height /en-US/docs/Web/API/Screen/height -/en-US/docs/Document_Object_Model_(DOM)/window.screen.left /en-US/docs/Web/API/Screen/left +/en-US/docs/Document_Object_Model_(DOM)/window.screen.left /en-US/docs/Web/API/ScreenDetailed/left /en-US/docs/Document_Object_Model_(DOM)/window.screen.pixelDepth /en-US/docs/Web/API/Screen/pixelDepth -/en-US/docs/Document_Object_Model_(DOM)/window.screen.top /en-US/docs/Web/API/Screen/top +/en-US/docs/Document_Object_Model_(DOM)/window.screen.top /en-US/docs/Web/API/ScreenDetailed/top /en-US/docs/Document_Object_Model_(DOM)/window.screen.width /en-US/docs/Web/API/Screen/width /en-US/docs/Document_Object_Model_(DOM)/window.screenX /en-US/docs/Web/API/Window/screenX /en-US/docs/Document_Object_Model_(DOM)/window.screenY /en-US/docs/Web/API/Window/screenY @@ -9608,22 +9608,26 @@ /en-US/docs/Web/API/SVGStylable /en-US/docs/Web/API/SVGElement /en-US/docs/Web/API/SVGURIReference /en-US/docs/Web/SVG/Attribute/href /en-US/docs/Web/API/Screen.availHeight /en-US/docs/Web/API/Screen/availHeight -/en-US/docs/Web/API/Screen.availLeft /en-US/docs/Web/API/Screen/availLeft -/en-US/docs/Web/API/Screen.availTop /en-US/docs/Web/API/Screen/availTop +/en-US/docs/Web/API/Screen.availLeft /en-US/docs/Web/API/ScreenDetailed/availLeft +/en-US/docs/Web/API/Screen.availTop /en-US/docs/Web/API/ScreenDetailed/availTop /en-US/docs/Web/API/Screen.availWidth /en-US/docs/Web/API/Screen/availWidth /en-US/docs/Web/API/Screen.colorDepth /en-US/docs/Web/API/Screen/colorDepth /en-US/docs/Web/API/Screen.height /en-US/docs/Web/API/Screen/height -/en-US/docs/Web/API/Screen.left /en-US/docs/Web/API/Screen/left +/en-US/docs/Web/API/Screen.left /en-US/docs/Web/API/ScreenDetailed/left /en-US/docs/Web/API/Screen.lockOrientation /en-US/docs/Web/API/Screen/lockOrientation /en-US/docs/Web/API/Screen.mozBrightness /en-US/docs/Web/API/Screen/mozBrightness /en-US/docs/Web/API/Screen.mozEnabled /en-US/docs/Web/API/Screen/mozEnabled /en-US/docs/Web/API/Screen.onorientationchange /en-US/docs/Web/API/Screen/orientationchange_event /en-US/docs/Web/API/Screen.orientation /en-US/docs/Web/API/Screen/orientation /en-US/docs/Web/API/Screen.pixelDepth /en-US/docs/Web/API/Screen/pixelDepth -/en-US/docs/Web/API/Screen.top /en-US/docs/Web/API/Screen/top +/en-US/docs/Web/API/Screen.top /en-US/docs/Web/API/ScreenDetailed/top /en-US/docs/Web/API/Screen.unlockOrientation /en-US/docs/Web/API/Screen/unlockOrientation /en-US/docs/Web/API/Screen.width /en-US/docs/Web/API/Screen/width +/en-US/docs/Web/API/Screen/availLeft /en-US/docs/Web/API/ScreenDetailed/availLeft +/en-US/docs/Web/API/Screen/availTop /en-US/docs/Web/API/ScreenDetailed/availTop +/en-US/docs/Web/API/Screen/left /en-US/docs/Web/API/ScreenDetailed/left /en-US/docs/Web/API/Screen/onorientationchange /en-US/docs/Web/API/Screen/orientationchange_event +/en-US/docs/Web/API/Screen/top /en-US/docs/Web/API/ScreenDetailed/top /en-US/docs/Web/API/ScreenOrientation/onchange /en-US/docs/Web/API/ScreenOrientation/change_event /en-US/docs/Web/API/ScriptProcessorNode.bufferSize /en-US/docs/Web/API/ScriptProcessorNode/bufferSize /en-US/docs/Web/API/ScriptProcessorNode.onaudioprocess /en-US/docs/Web/API/ScriptProcessorNode/audioprocess_event @@ -10830,19 +10834,19 @@ /en-US/docs/Web/API/window.restore /en-US/docs/Web/API/Window/moveTo /en-US/docs/Web/API/window.screen /en-US/docs/Web/API/Window/screen /en-US/docs/Web/API/window.screen.availHeight /en-US/docs/Web/API/Screen/availHeight -/en-US/docs/Web/API/window.screen.availLeft /en-US/docs/Web/API/Screen/availLeft -/en-US/docs/Web/API/window.screen.availTop /en-US/docs/Web/API/Screen/availTop +/en-US/docs/Web/API/window.screen.availLeft /en-US/docs/Web/API/ScreenDetailed/availLeft +/en-US/docs/Web/API/window.screen.availTop /en-US/docs/Web/API/ScreenDetailed/availTop /en-US/docs/Web/API/window.screen.availWidth /en-US/docs/Web/API/Screen/availWidth /en-US/docs/Web/API/window.screen.colorDepth /en-US/docs/Web/API/Screen/colorDepth /en-US/docs/Web/API/window.screen.height /en-US/docs/Web/API/Screen/height -/en-US/docs/Web/API/window.screen.left /en-US/docs/Web/API/Screen/left +/en-US/docs/Web/API/window.screen.left /en-US/docs/Web/API/ScreenDetailed/left /en-US/docs/Web/API/window.screen.lockOrientation /en-US/docs/Web/API/Screen/lockOrientation /en-US/docs/Web/API/window.screen.mozBrightness /en-US/docs/Web/API/Screen/mozBrightness /en-US/docs/Web/API/window.screen.mozEnabled /en-US/docs/Web/API/Screen/mozEnabled /en-US/docs/Web/API/window.screen.onorientationchange /en-US/docs/Web/API/Screen/orientationchange_event /en-US/docs/Web/API/window.screen.orientation /en-US/docs/Web/API/Screen/orientation /en-US/docs/Web/API/window.screen.pixelDepth /en-US/docs/Web/API/Screen/pixelDepth -/en-US/docs/Web/API/window.screen.top /en-US/docs/Web/API/Screen/top +/en-US/docs/Web/API/window.screen.top /en-US/docs/Web/API/ScreenDetailed/top /en-US/docs/Web/API/window.screen.unlockOrientation /en-US/docs/Web/API/Screen/unlockOrientation /en-US/docs/Web/API/window.screen.width /en-US/docs/Web/API/Screen/width /en-US/docs/Web/API/window.screenX /en-US/docs/Web/API/Window/screenX diff --git a/files/en-us/_wikihistory.json b/files/en-us/_wikihistory.json index 94076fc666f5dc4..4559f29746a019b 100644 --- a/files/en-us/_wikihistory.json +++ b/files/en-us/_wikihistory.json @@ -57782,41 +57782,6 @@ "Gor1" ] }, - "Web/API/Screen/availLeft": { - "modified": "2020-10-15T21:13:04.118Z", - "contributors": [ - "mfuji09", - "ExE-Boss", - "fscholz", - "cvrebert", - "Sebastianz", - "teoli", - "MHasan", - "kscarfone", - "Navin_Jadhav", - "Sheppy", - "jzaruba", - "Mgjbot", - "Yaroukh", - "Gor1" - ] - }, - "Web/API/Screen/availTop": { - "modified": "2020-10-15T21:16:26.852Z", - "contributors": [ - "mfuji09", - "ExE-Boss", - "fscholz", - "cvrebert", - "Sebastianz", - "teoli", - "kosvrouvas", - "Navin_Jadhav", - "Sheppy", - "Mgjbot", - "Gor1" - ] - }, "Web/API/Screen/availWidth": { "modified": "2020-10-15T21:16:26.709Z", "contributors": [ @@ -57867,23 +57832,6 @@ "Gor1" ] }, - "Web/API/Screen/left": { - "modified": "2020-10-15T21:16:24.841Z", - "contributors": [ - "ExE-Boss", - "fscholz", - "cvrebert", - "Sebastianz", - "teoli", - "MHasan", - "namolmes", - "Sheppy", - "Mgjbot", - "Nickolay", - "Jabez", - "Gor1" - ] - }, "Web/API/Screen/lockOrientation": { "modified": "2020-10-15T21:19:41.189Z", "contributors": [ @@ -57995,25 +57943,6 @@ "Gor1" ] }, - "Web/API/Screen/top": { - "modified": "2020-10-15T21:16:23.568Z", - "contributors": [ - "ExE-Boss", - "fscholz", - "cvrebert", - "teoli", - "jswisher", - "Anonymous", - "MHasan", - "chitra_lakhotia", - "Sheppy", - "ethertank", - "jryans", - "Mgjbot", - "Mw22", - "Gor1" - ] - }, "Web/API/Screen/unlockOrientation": { "modified": "2020-10-15T21:23:44.621Z", "contributors": [ @@ -58052,6 +57981,77 @@ "Gor1" ] }, + "Web/API/ScreenDetailed/availLeft": { + "modified": "2020-10-15T21:13:04.118Z", + "contributors": [ + "mfuji09", + "ExE-Boss", + "fscholz", + "cvrebert", + "Sebastianz", + "teoli", + "MHasan", + "kscarfone", + "Navin_Jadhav", + "Sheppy", + "jzaruba", + "Mgjbot", + "Yaroukh", + "Gor1" + ] + }, + "Web/API/ScreenDetailed/availTop": { + "modified": "2020-10-15T21:16:26.852Z", + "contributors": [ + "mfuji09", + "ExE-Boss", + "fscholz", + "cvrebert", + "Sebastianz", + "teoli", + "kosvrouvas", + "Navin_Jadhav", + "Sheppy", + "Mgjbot", + "Gor1" + ] + }, + "Web/API/ScreenDetailed/left": { + "modified": "2020-10-15T21:16:24.841Z", + "contributors": [ + "ExE-Boss", + "fscholz", + "cvrebert", + "Sebastianz", + "teoli", + "MHasan", + "namolmes", + "Sheppy", + "Mgjbot", + "Nickolay", + "Jabez", + "Gor1" + ] + }, + "Web/API/ScreenDetailed/top": { + "modified": "2020-10-15T21:16:23.568Z", + "contributors": [ + "ExE-Boss", + "fscholz", + "cvrebert", + "teoli", + "jswisher", + "Anonymous", + "MHasan", + "chitra_lakhotia", + "Sheppy", + "ethertank", + "jryans", + "Mgjbot", + "Mw22", + "Gor1" + ] + }, "Web/API/ScreenOrientation": { "modified": "2020-11-13T05:33:17.108Z", "contributors": [ diff --git a/files/en-us/web/api/element/requestfullscreen/index.md b/files/en-us/web/api/element/requestfullscreen/index.md index 1ce5f836b5782ac..9c67e1180f23134 100644 --- a/files/en-us/web/api/element/requestfullscreen/index.md +++ b/files/en-us/web/api/element/requestfullscreen/index.md @@ -43,6 +43,8 @@ requestFullscreen(options) - `"auto"` - : The browser will choose which of the above settings to apply. This is the default value. + - `screen` {{optional_inline}} {{experimental_inline}} + - : Specifies on which screen you want to put the element in fullscreen mode. This takes a {{domxref("ScreenDetailed")}} object as a value, representing the chosen screen. ### Return value @@ -157,6 +159,23 @@ elem The promise's resolve handler does nothing, but if the promise is rejected, an error message is displayed by calling {{DOMxRef("Window.alert", "alert()")}}. +### Using the screen option + +If you wanted to make the element fullscreen on the primary OS screen, you could use code like the following: + +```js +try { + const primaryScreen = (await getScreenDetails()).screens.find( + (screen) => screen.isPrimary, + ); + await document.body.requestFullscreen({ screen: primaryScreen }); +} catch (err) { + console.error(err.name, err.message); +} +``` + +The {{domxref("Window.getScreenDetails()")}} method is used to retrieve the {{domxref("ScreenDetails")}} object for the current device, which contains {{domxref("ScreenDetailed")}} objects representing the different available screens. + ## Specifications {{Specifications}} diff --git a/files/en-us/web/api/permissions_api/index.md b/files/en-us/web/api/permissions_api/index.md index 53e01c7cd971293..58290b938e0952b 100644 --- a/files/en-us/web/api/permissions_api/index.md +++ b/files/en-us/web/api/permissions_api/index.md @@ -44,6 +44,7 @@ A non-exhaustive list of permission-aware APIs includes: - [Storage API](/en-US/docs/Web/API/Storage_API): `persistent-storage` - [Web Audio Output Devices API](/en-US/docs/Web/API/Audio_Output_Devices_API): `speaker-selection` - [Web MIDI API](/en-US/docs/Web/API/Web_MIDI_API): `midi` +- [Window Management API](/en-US/docs/Web/API/Window_Management_API): `window-management` ## Examples diff --git a/files/en-us/web/api/screen/availleft/index.md b/files/en-us/web/api/screen/availleft/index.md deleted file mode 100644 index 34902a14d2da7b3..000000000000000 --- a/files/en-us/web/api/screen/availleft/index.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -title: "Screen: availLeft property" -short-title: availLeft -slug: Web/API/Screen/availLeft -page-type: web-api-instance-property -status: - - non-standard -browser-compat: api.Screen.availLeft ---- - -{{APIRef("CSSOM")}}{{Non-standard_Header}} - -Returns the first available pixel from the left side of the screen. - -## Value - -A number. - -## Examples - -```js -let setX = window.screen.width - window.screen.availLeft; -let setY = window.screen.height - window.screen.availTop; -window.moveTo(setX, setY); -``` - -## Notes - -In most cases, this property returns 0. - -If you work with two screens this property, evaluated on the right screen, returns the -width of the left one in pixels (thereby indicating the X coordinate of the left edge of -the screen on the right). - -On Windows, this property depends on which screen is set as your primary, returning the -X coordinate of the leftmost available pixel relative to the primary screen. That is, -the primary screen's left edge always has the X coordinate 0, even if it's not the -leftmost screen. If the secondary screen is to the left of the primary screen, it has a -negative X coordinate to compensate: - -\[1] \[2] - on left screen _availLeft_ returns **0**, on the right -screen it returns the **width** of the left one - -\[2] \[1] - on left screen _availLeft_ returns **-width** of that -screen, on the right screen, it returns **0** - -## Browser compatibility - -{{Compat}} diff --git a/files/en-us/web/api/screen/availtop/index.md b/files/en-us/web/api/screen/availtop/index.md deleted file mode 100644 index a10866766a41ef5..000000000000000 --- a/files/en-us/web/api/screen/availtop/index.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: "Screen: availTop property" -short-title: availTop -slug: Web/API/Screen/availTop -page-type: web-api-instance-property -status: - - non-standard -browser-compat: api.Screen.availTop ---- - -{{APIRef("CSSOM")}}{{Non-standard_Header}} - -Specifies the y-coordinate of the first pixel that is not allocated to permanent or -semipermanent user interface features. - -## Value - -A number. - -## Examples - -```js -let setX = window.screen.width - window.screen.availLeft; -let setY = window.screen.height - window.screen.availTop; -window.moveTo(setX, setY); -``` - -## Notes - -In most cases, this property returns `0`. - -## Browser compatibility - -{{Compat}} diff --git a/files/en-us/web/api/screen/change_event/index.md b/files/en-us/web/api/screen/change_event/index.md new file mode 100644 index 000000000000000..0b66017f54ad6c9 --- /dev/null +++ b/files/en-us/web/api/screen/change_event/index.md @@ -0,0 +1,59 @@ +--- +title: "Screen: change event" +short-title: change +slug: Web/API/Screen/change_event +page-type: web-api-event +status: + - experimental +browser-compat: api.Screen.change_event +--- + +{{APIRef("Window Management API")}}{{SeeCompatTable}} + +The **`change`** event of the {{domxref("Screen")}} interface is fired on a specific screen when it changes in some way — for example available width or height, or orientation. + +Specifically, _change_ means changes to a `Screen` instance's _basic observable properties_, which are: + +- {{domxref("Screen.width", "width")}} +- {{domxref("Screen.height", "height")}} +- {{domxref("Screen.availWidth", "availWidth")}} +- {{domxref("Screen.availHeight", "availHeight")}} +- {{domxref("Screen.colorDepth", "colorDepth")}} +- {{domxref("Screen.orientation", "orientation")}} + +## Syntax + +Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. + +```js +addEventListener("change", (event) => {}); + +onchange = (event) => {}; +``` + +## Event type + +An event of type `change`, the event object of which is structurally equivalent to an {{domxref("Event")}}. + +{{InheritanceDiagram("Event")}} + +## Examples + +```js +const firstScreen = (await window.getScreenDetails()).screens[0]; +firstScreen.addEventListener("change", (event) => { + console.log("The first screen has changed.", event, firstScreen); +}); +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [Window Management API](/en-US/docs/Web/API/Window_Management_API) diff --git a/files/en-us/web/api/screen/index.md b/files/en-us/web/api/screen/index.md index f50981a35f08849..10d8b427a0d2f7f 100644 --- a/files/en-us/web/api/screen/index.md +++ b/files/en-us/web/api/screen/index.md @@ -17,10 +17,6 @@ Note that browsers determine which screen to report as current by detecting whic _Also inherits properties from its parent {{domxref("EventTarget")}}_. -- {{DOMxRef("Screen.availTop")}} {{Non-standard_Inline}} - - : Specifies the y-coordinate of the first pixel that is not allocated to permanent or semipermanent user interface features. -- {{DOMxRef("Screen.availLeft")}} {{Non-standard_Inline}} - - : Returns the first available pixel available from the left side of the screen. - {{DOMxRef("Screen.availHeight")}} - : Specifies the height of the screen, in pixels, minus permanent or semipermanent user interface features displayed by the operating system, such as the Taskbar on Windows. - {{DOMxRef("Screen.availWidth")}} @@ -29,14 +25,12 @@ _Also inherits properties from its parent {{domxref("EventTarget")}}_. - : Returns the color depth of the screen. - {{DOMxRef("Screen.height")}} - : Returns the height of the screen in pixels. -- {{DOMxRef("Screen.left")}} {{Non-standard_Inline}} - - : Returns the distance in pixels from the left side of the main screen to the left side of the current screen. +- {{domxref("Screen.isExtended")}} {{experimental_inline}} + - : Returns `true` if the user's device has multiple screens, and `false` if not. - {{DOMxRef("Screen.orientation")}} - : Returns the {{DOMxRef("ScreenOrientation")}} instance associated with this screen. - {{DOMxRef("Screen.pixelDepth")}} - : Gets the bit depth of the screen. -- {{DOMxRef("Screen.top")}} {{Deprecated_Inline}} {{Non-standard_Inline}} - - : Returns the distance in pixels from the top side of the current screen. - {{DOMxRef("Screen.width")}} - : Returns the width of the screen. - {{DOMxRef("Screen.mozEnabled")}} {{Non-standard_Inline}} {{Deprecated_Inline}} @@ -44,6 +38,19 @@ _Also inherits properties from its parent {{domxref("EventTarget")}}_. - {{DOMxRef("Screen.mozBrightness")}} {{Non-standard_Inline}} {{Deprecated_Inline}} - : Controls the brightness of a device's screen. A double between 0 and 1.0 is expected. +## Non-standard properties + +The following properties are specified as part of the [Window Management API](/en-US/docs/Web/API/Window_Management_API), which makes them available on the {{domxref("ScreenDetailed")}} interface; this is where we have chosen to document them. However, non-standard versions of these properties are available on the `Screen` interface in browsers that don't support that API. See this page's [Browser compatibility](#browser_compatibility) table for details of the non-standard support. + +- {{domxref("ScreenDetailed.availLeft", "Screen.availLeft")}} {{ReadOnlyInline}} {{Non-standard_Inline}} + - : A number representing the x-coordinate (left-hand edge) of the available screen area. +- {{domxref("ScreenDetailed.availTop", "Screen.availTop")}} {{ReadOnlyInline}} {{Non-standard_Inline}} + - : A number representing the y-coordinate (top edge) of the available screen area. +- {{domxref("ScreenDetailed.left", "Screen.left")}} {{ReadOnlyInline}} {{Non-standard_Inline}} + - : A number representing the x-coordinate (left-hand edge) of the total screen area. +- {{domxref("ScreenDetailed.top", "Screen.top")}} {{ReadOnlyInline}} {{Non-standard_Inline}} + - : A number representing the y-coordinate (top edge) of the total screen area. + ## Instance methods _Also inherits methods from its parent {{domxref("EventTarget")}}_. @@ -55,10 +62,12 @@ _Also inherits methods from its parent {{domxref("EventTarget")}}_. ## Events +- {{domxref("Screen.change_event", "change")}} {{experimental_inline}} + - : Fired on a specific screen when it changes in some way — for example available width or height, or orientation. - {{DOMxRef("Screen.orientationchange_event", "orientationchange")}} {{Deprecated_Inline}} {{Non-standard_Inline}} - : Fires when the screen orientation changes. -## Example +## Examples ```js if (screen.pixelDepth < 8) { diff --git a/files/en-us/web/api/screen/isextended/index.md b/files/en-us/web/api/screen/isextended/index.md new file mode 100644 index 000000000000000..e6407a02cfa6a0d --- /dev/null +++ b/files/en-us/web/api/screen/isextended/index.md @@ -0,0 +1,42 @@ +--- +title: "Screen: isExtended property" +short-title: isExtended +slug: Web/API/Screen/isExtended +page-type: web-api-instance-property +status: + - experimental +browser-compat: api.Screen.isExtended +--- + +{{APIRef("Window Management API")}}{{SeeCompatTable}} + +The **`isExtended`** read-only property of the +{{domxref("Screen")}} interface returns `true` if the user's device has multiple screens, and `false` if not. + +This property is typically accessed via `window.screen.isExtended`, and provides a useful test to see if multiple screens are available before attempting to create a multi-window, multi-screen layout using the [Window Management API](/en-US/docs/Web/API/Window_Management_API). + +## Value + +A boolean value — `true` if the device has multiple screens, and `false` if not. + +## Examples + +```js +if (window.screen.isExtended) { + // Create multi-screen window layout +} else { + // Create single-screen window layout +} +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [Window Management API](/en-US/docs/Web/API/Window_Management_API) diff --git a/files/en-us/web/api/screen/left/index.md b/files/en-us/web/api/screen/left/index.md deleted file mode 100644 index 165e8a571f940f8..000000000000000 --- a/files/en-us/web/api/screen/left/index.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: "Screen: left property" -short-title: left -slug: Web/API/Screen/left -page-type: web-api-instance-property -status: - - non-standard -browser-compat: api.Screen.left ---- - -{{APIRef("CSSOM")}}{{Non-standard_Header}} - -Returns the distance in pixels from the left side of the main screen to the left side -of the current screen. - -## Value - -A number. - -## Browser compatibility - -{{Compat}} - -## See also - -- {{DOMxRef("screen.top")}} diff --git a/files/en-us/web/api/screen/top/index.md b/files/en-us/web/api/screen/top/index.md deleted file mode 100644 index 24257cb936c3631..000000000000000 --- a/files/en-us/web/api/screen/top/index.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: "Screen: top property" -short-title: top -slug: Web/API/Screen/top -page-type: web-api-instance-property -status: - - deprecated - - non-standard -browser-compat: api.Screen.top ---- - -{{APIRef("CSSOM")}}{{Deprecated_Header}}{{Non-standard_Header}} - -Returns the distance in pixels from the top side of the current screen. - -## Value - -A number. - -## Specifications - -Not part of any current specification. - -## Browser compatibility - -{{Compat}} - -## See also - -- {{DOMxRef("Screen.left")}} diff --git a/files/en-us/web/api/screendetailed/availleft/index.md b/files/en-us/web/api/screendetailed/availleft/index.md new file mode 100644 index 000000000000000..4a47c1d9e85ed69 --- /dev/null +++ b/files/en-us/web/api/screendetailed/availleft/index.md @@ -0,0 +1,54 @@ +--- +title: "ScreenDetailed: availLeft property" +short-title: availLeft +slug: Web/API/ScreenDetailed/availLeft +page-type: web-api-instance-property +status: + - experimental +browser-compat: api.ScreenDetailed.availLeft +--- + +{{APIRef("Window Management API")}}{{seecompattable}} + +The **`availLeft`** read-only property of the +{{domxref("ScreenDetailed")}} interface is a number representing the x-coordinate (left-hand edge) of the available screen area inside the OS virtual screen arrangement, relative to the [multi-screen origin](/en-US/docs/Web/API/Window_Management_API#multi-screen_origin). + +This is equal to the {{domxref("ScreenDetailed.left")}} property, plus the width of any OS UI element drawn on the left of the screen. Windows cannot be placed in those areas, so `availLeft` is useful for giving you the left boundary of the actual area available to open or place windows. + +> **Note:** A non-standard implementation of the `availLeft` property is available on the `Screen` interface in all browsers. This represents the x-coordinate (left-hand edge) of the _current_ screen's available area (i.e. the screen containing the browser window the code is being run in). See the [Non-standard example](#non-standard_example) below for usage details, and see the [`Screen`](/en-US/docs/Web/API/Screen#browser_compatibility) reference page for browser support information relating to the non-standard implementation. + +## Value + +A number. + +## Examples + +### Window Management API example + +```js +// Available in browsers that support the Window Management API +const screenDetails = await window.getScreenDetails(); + +// Return the availLeft value of the first screen +const screen1AvailLeft = screenDetails.screens[0].availLeft; +``` + +### Non-standard example + +```js +// Available in all browsers +// Return the availLeft value of the current screen +const screenAvailLeft = window.screen.availLeft; +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [Window Management API](/en-US/docs/Web/API/Window_Management_API) diff --git a/files/en-us/web/api/screendetailed/availtop/index.md b/files/en-us/web/api/screendetailed/availtop/index.md new file mode 100644 index 000000000000000..648dee15a25f680 --- /dev/null +++ b/files/en-us/web/api/screendetailed/availtop/index.md @@ -0,0 +1,54 @@ +--- +title: "ScreenDetailed: availTop property" +short-title: availTop +slug: Web/API/ScreenDetailed/availTop +page-type: web-api-instance-property +status: + - experimental +browser-compat: api.ScreenDetailed.availTop +--- + +{{APIRef("Window Management API")}}{{seecompattable}} + +The **`availTop`** read-only property of the +{{domxref("ScreenDetailed")}} interface is a number representing the y-coordinate (top edge) of the available screen area inside the OS virtual screen arrangement, relative to the [multi-screen origin](/en-US/docs/Web/API/Window_Management_API#multi-screen_origin). + +This is equal to the {{domxref("ScreenDetailed.top")}} property, plus the height of any OS UI element drawn at the top of the screen. Windows cannot be placed in those areas, so `availTop` is useful for giving you the top boundary of the actual area available to open or place windows. + +> **Note:** A non-standard implementation of the `availTop` property is available on the `Screen` interface in all browsers. This represents the y-coordinate (top edge) of the _current_ screen's available area (i.e. the screen containing the browser window the code is being run in). See the [Non-standard example](#non-standard_example) below for usage details, and see the [`Screen`](/en-US/docs/Web/API/Screen#browser_compatibility) reference page for browser support information relating to the non-standard implementation. + +## Value + +A number. + +## Examples + +### Window Management API example + +```js +// Available in browsers that support the Window Management API +const screenDetails = await window.getScreenDetails(); + +// Return the availTop value of the first screen +const screen1AvailTop = screenDetails.screens[0].availTop; +``` + +### Non-standard example + +```js +// Available in all browsers +// Return the availTop value of the current screen +const screenAvailTop = window.screen.availTop; +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [Window Management API](/en-US/docs/Web/API/Window_Management_API) diff --git a/files/en-us/web/api/screendetailed/devicepixelratio/index.md b/files/en-us/web/api/screendetailed/devicepixelratio/index.md new file mode 100644 index 000000000000000..010b31712399bf6 --- /dev/null +++ b/files/en-us/web/api/screendetailed/devicepixelratio/index.md @@ -0,0 +1,44 @@ +--- +title: "ScreenDetailed: devicePixelRatio property" +short-title: devicePixelRatio +slug: Web/API/ScreenDetailed/devicePixelRatio +page-type: web-api-instance-property +status: + - experimental +browser-compat: api.ScreenDetailed.devicePixelRatio +--- + +{{APIRef("Window Management API")}}{{SeeCompatTable}} + +The **`devicePixelRatio`** read-only property of the +{{domxref("ScreenDetailed")}} interface is a number representing the screen's device pixel ratio. + +This is the same as the value returned by {{domxref("Window.devicePixelRatio")}}, except that `Window.devicePixelRatio`: + +- always returns the device pixel ratio for the {{domxref("ScreenDetails.currentScreen", "current screen", "", "nocode")}}. +- also includes scaling of the window itself, i.e. page zoom (at least on some browser implementations). + +## Value + +A number. + +## Examples + +```js +const screenDetails = await window.getScreenDetails(); + +// Return the device pixel ratio of the first screen +const screen1DPR = screenDetails.screens[0].devicePixelRatio; +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [Window Management API](/en-US/docs/Web/API/Window_Management_API) diff --git a/files/en-us/web/api/screendetailed/index.md b/files/en-us/web/api/screendetailed/index.md new file mode 100644 index 000000000000000..894641cfb6ebd80 --- /dev/null +++ b/files/en-us/web/api/screendetailed/index.md @@ -0,0 +1,99 @@ +--- +title: ScreenDetailed +slug: Web/API/ScreenDetailed +page-type: web-api-interface +status: + - experimental +browser-compat: api.ScreenDetailed +--- + +{{APIRef("Window Management API")}}{{SeeCompatTable}} + +The **`ScreenDetailed`** interface of the [Window Management API](/en-US/docs/Web/API/Window_Management_API) represents detailed information about one specific screen available to the user's device. + +`ScreenDetailed` objects can be accessed via the {{domxref("ScreenDetails.screens")}} and {{domxref("ScreenDetails.currentScreen")}} properties. + +{{InheritanceDiagram}} + +## Instance properties + +_Inherits properties from its parent, {{DOMxRef("Screen")}}._ + +- {{domxref("ScreenDetailed.availLeft", "availLeft")}} {{ReadOnlyInline}} {{Experimental_Inline}} + - : A number representing the x-coordinate (left-hand edge) of the available screen area. +- {{domxref("ScreenDetailed.availTop", "availTop")}} {{ReadOnlyInline}} {{Experimental_Inline}} + - : A number representing the y-coordinate (top edge) of the available screen area. +- {{domxref("ScreenDetailed.devicePixelRatio", "devicePixelRatio")}} {{ReadOnlyInline}} {{Experimental_Inline}} + - : A number representing the screen's device pixel ratio. +- {{domxref("ScreenDetailed.isInternal", "isInternal")}} {{ReadOnlyInline}} {{Experimental_Inline}} + - : A boolean indicating whether the screen is internal to the device or external. +- {{domxref("ScreenDetailed.isPrimary", "isPrimary")}} {{ReadOnlyInline}} {{Experimental_Inline}} + - : A boolean indicating whether the screen is set as the operating system (OS) primary screen or not. +- {{domxref("ScreenDetailed.label", "label")}} {{ReadOnlyInline}} {{Experimental_Inline}} + - : A string providing a descriptive label for the screen, for example "Built-in Retina Display". +- {{domxref("ScreenDetailed.left", "left")}} {{ReadOnlyInline}} {{Experimental_Inline}} + - : A number representing the x-coordinate (left-hand edge) of the total screen area. +- {{domxref("ScreenDetailed.top", "top")}} {{ReadOnlyInline}} {{Experimental_Inline}} + - : A number representing the y-coordinate (top edge) of the total screen area. + +## Examples + +When {{domxref("Window.getScreenDetails()")}} is invoked, the user will be asked for permission to manage windows on all their displays (the status of this permission can be checked using {{domxref("Permissions.query()")}} to query `window-management`). Provided they grant permission, the resulting {{domxref("ScreenDetails")}} object contains details of all the screens available to the user's system. + +```js +const screenDetails = await window.getScreenDetails(); + +// Return the number of screens +const noOfScreens = screenDetails.screens.length; +``` + +You'll still need to use {{domxref("Window.open()")}} to open and manage windows, but the above provides you with better information for doing so in a multi-screen environment. For example, a utility function might look like so: + +```js +function openWindow(left, top, width, height, url) { + const windowFeatures = `left=${left},top=${top},width=${width},height=${height}`; + const windowRef = window.open( + url, + "_blank", // needed for it to open in a new window + windowFeatures, + ); + + // Store a reference to the window in the windowRefs array for later use + windowRefs.push(windowRef); +} +``` + +Each item inside the {{domxref("ScreenDetails.screens")}} array is a `ScreenDetailed` object, which can be used to place a window on a specific screen available to the current device. + +```js +const screen1 = screenDetails.screens[0]; +const screen2 = screenDetails.screens[1]; +// Windows will be a third the width and the full height of the screen +let windowWidth = Math.floor((screen1.availWidth - 3 * WINDOW_CHROME_X) / 3); +let windowHeight = Math.floor(screen1.availHeight - WINDOW_CHROME_Y); + +// Open the reference windows in thirds across the entire height of the primary screen +openWindow( + screen1.availLeft, + screen1.availTop, + windowWidth, + windowHeight, + sites[1].url, +); + +// ... +``` + +> **Note:** See [Multi-window learning environment](https://mdn.github.io/dom-examples/window-management-api/) for a full example (see the [source code](https://github.com/mdn/dom-examples/tree/main/window-management-api) also). + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [Window Management API](/en-US/docs/Web/API/Window_Management_API) diff --git a/files/en-us/web/api/screendetailed/isinternal/index.md b/files/en-us/web/api/screendetailed/isinternal/index.md new file mode 100644 index 000000000000000..c344a8b6ae284d0 --- /dev/null +++ b/files/en-us/web/api/screendetailed/isinternal/index.md @@ -0,0 +1,39 @@ +--- +title: "ScreenDetailed: isInternal property" +short-title: isInternal +slug: Web/API/ScreenDetailed/isInternal +page-type: web-api-instance-property +status: + - experimental +browser-compat: api.ScreenDetailed.isInternal +--- + +{{APIRef("Window Management API")}}{{SeeCompatTable}} + +The **`isInternal`** read-only property of the +{{domxref("ScreenDetailed")}} interface is a boolean indicating whether the screen is internal to the device or external. External devices are generally manufactured separately from the device they are attached to and can be connected and disconnected as needed, whereas internal screens are part of the device and not intended to be disconnected. + +## Value + +A boolean value — `true` if the screen is internal, and `false` if it is external. + +## Examples + +```js +const screenDetails = await window.getScreenDetails(); + +// Is the first screen internal? +const screen1Internal = screenDetails.screens[0].isInternal; +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [Window Management API](/en-US/docs/Web/API/Window_Management_API) diff --git a/files/en-us/web/api/screendetailed/isprimary/index.md b/files/en-us/web/api/screendetailed/isprimary/index.md new file mode 100644 index 000000000000000..b7ded2ac9f88415 --- /dev/null +++ b/files/en-us/web/api/screendetailed/isprimary/index.md @@ -0,0 +1,41 @@ +--- +title: "ScreenDetailed: isPrimary property" +short-title: isPrimary +slug: Web/API/ScreenDetailed/isPrimary +page-type: web-api-instance-property +status: + - experimental +browser-compat: api.ScreenDetailed.isPrimary +--- + +{{APIRef("Window Management API")}}{{SeeCompatTable}} + +The **`isPrimary`** read-only property of the +{{domxref("ScreenDetailed")}} interface is a boolean indicating whether the screen is set as the operating system (OS) primary screen or not. + +The OS hosting the browser will have one primary screen, and one or more secondary screens. The primary screen can usually be specified by the user via OS settings, and generally contains OS UI features such as the taskbar/icon dock. The primary screen may change for a number of resons, such as a screen being unplugged. + +## Value + +A boolean value — `true` if the screen is primary, and `false` if it is secondary. + +## Examples + +```js +const screenDetails = await window.getScreenDetails(); + +// Is the first screen primary? +const screen1Primary = screenDetails.screens[0].isPrimary; +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [Window Management API](/en-US/docs/Web/API/Window_Management_API) diff --git a/files/en-us/web/api/screendetailed/label/index.md b/files/en-us/web/api/screendetailed/label/index.md new file mode 100644 index 000000000000000..b74e5b7ce46ff93 --- /dev/null +++ b/files/en-us/web/api/screendetailed/label/index.md @@ -0,0 +1,41 @@ +--- +title: "ScreenDetailed: label property" +short-title: label +slug: Web/API/ScreenDetailed/label +page-type: web-api-instance-property +status: + - experimental +browser-compat: api.ScreenDetailed.label +--- + +{{APIRef("Window Management API")}}{{SeeCompatTable}} + +The **`label`** read-only property of the +{{domxref("ScreenDetailed")}} interface is a string providing a descriptive label for the screen, for example "Built-in Retina Display". + +This is useful for constructing a list of options to display to the user if you want them to choose a screen to display content on. + +## Value + +A string. + +## Examples + +```js +const screenDetails = await window.getScreenDetails(); + +// Return the label of the first screen +const screen1Label = screenDetails.screens[0].label; +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [Window Management API](/en-US/docs/Web/API/Window_Management_API) diff --git a/files/en-us/web/api/screendetailed/left/index.md b/files/en-us/web/api/screendetailed/left/index.md new file mode 100644 index 000000000000000..3a10dfbac7981ab --- /dev/null +++ b/files/en-us/web/api/screendetailed/left/index.md @@ -0,0 +1,54 @@ +--- +title: "ScreenDetailed: left property" +short-title: left +slug: Web/API/ScreenDetailed/left +page-type: web-api-instance-property +status: + - experimental +browser-compat: api.ScreenDetailed.left +--- + +{{APIRef("Window Management API")}}{{seecompattable}} + +The **`left`** read-only property of the +{{domxref("ScreenDetailed")}} interface is a number representing the x-coordinate (left-hand edge) of the total screen area inside the OS virtual screen arrangement, relative to the [multi-screen origin](/en-US/docs/Web/API/Window_Management_API#multi-screen_origin). + +This is equal to the true left-hand edge, ignoring any OS UI element drawn at the left of the screen. Windows cannot be placed in those areas; to get the left-hand coordinate of the screen area that windows can be placed in, use {{domxref("ScreenDetailed.availLeft")}}. + +> **Note:** In Firefox, a non-standard implementation of the `left` property is available on the `Screen` interface, and represents the x-coordinate (left-hand edge) of the _current_ screen's area (i.e. the screen containing the browser window the code is being run in). See the [Non-standard example](#non-standard_example) below for usage details, and see the [`Screen`](/en-US/docs/Web/API/Screen#browser_compatibility) reference page for browser support information relating to the non-standard implementation. + +## Value + +A number. + +## Examples + +### Window Management API example + +```js +// Available in browsers that support the Window Management API +const screenDetails = await window.getScreenDetails(); + +// Return the absolute left value of the first screen +const screen1Left = screenDetails.screens[0].left; +``` + +### Non-standard example + +```js +// Available in Firefox +// Return the absolute left value of the current screen +const screenLeft = window.screen.left; +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [Window Management API](/en-US/docs/Web/API/Window_Management_API) diff --git a/files/en-us/web/api/screendetailed/top/index.md b/files/en-us/web/api/screendetailed/top/index.md new file mode 100644 index 000000000000000..f343710bdd5952f --- /dev/null +++ b/files/en-us/web/api/screendetailed/top/index.md @@ -0,0 +1,54 @@ +--- +title: "ScreenDetailed: top property" +short-title: top +slug: Web/API/ScreenDetailed/top +page-type: web-api-instance-property +status: + - experimental +browser-compat: api.ScreenDetailed.top +--- + +{{APIRef("Window Management API")}}{{seecompattable}} + +The **`top`** read-only property of the +{{domxref("ScreenDetailed")}} interface is a number representing the y-coordinate (top edge) of the total screen area inside the OS virtual screen arrangement, relative to the [multi-screen origin](/en-US/docs/Web/API/Window_Management_API#multi-screen_origin). + +This is equal to the true top edge, ignoring any OS UI element drawn at the top of the screen. Windows cannot be placed in those areas; to get the top coordinate of the screen area that windows can be placed in, use {{domxref("ScreenDetailed.availTop")}}. + +> **Note:** In Firefox, a non-standard implementation of the `top` property is available on the `Screen` interface, and represents the y-coordinate (top edge) of the _current_ screen's area (i.e. the screen containing the browser window the code is being run in). See the [Non-standard example](#non-standard_example) below for usage details, and see the [`Screen`](/en-US/docs/Web/API/Screen#browser_compatibility) reference page for browser support information relating to the non-standard implementation. + +## Value + +A number. + +## Examples + +### Window Management API example + +```js +// Available in browsers that support the Window Management API +const screenDetails = await window.getScreenDetails(); + +// Return the absolute top value of the first screen +const screen1Top = screenDetails.screens[0].top; +``` + +### Non-standard example + +```js +// Available in Firefox +// Return the absolute top value of the current screen +const screenTop = window.screen.top; +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [Window Management API](/en-US/docs/Web/API/Window_Management_API) diff --git a/files/en-us/web/api/screendetails/currentscreen/index.md b/files/en-us/web/api/screendetails/currentscreen/index.md new file mode 100644 index 000000000000000..266ae6c710bd2d5 --- /dev/null +++ b/files/en-us/web/api/screendetails/currentscreen/index.md @@ -0,0 +1,51 @@ +--- +title: "ScreenDetails: currentScreen property" +short-title: currentScreen +slug: Web/API/ScreenDetails/currentScreen +page-type: web-api-instance-property +status: + - experimental +browser-compat: api.ScreenDetails.currentScreen +--- + +{{APIRef("Window Management API")}}{{SeeCompatTable}} + +The **`currentScreen`** read-only property of the +{{domxref("ScreenDetails")}} interface contains a single {{domxref("ScreenDetailed")}} object representing detailed information about the screen that the current browser window is displayed in. + +## Value + +A {{domxref("ScreenDetailed")}} object. + +## Examples + +```js +// Utility function for opening new windows +function openWindow(left, top, width, height, url) { + const windowFeatures = `left=${left},top=${top},width=${width},height=${height}`; + return window.open(url, "_blank", windowFeatures); +} + +// Open a new window that fills the available area of the current screen. +const currentScreen = (await window.getScreenDetails()).currentScreen; +console.log(`Opening a window to fill screen ${currentScreen.label}`); +const windowRef = openWindow( + currentScreen.availLeft, + currentScreen.availTop, + currentScreen.availWidth, + currentScreen.availHeight, + url, +); +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [Window Management API](/en-US/docs/Web/API/Window_Management_API) diff --git a/files/en-us/web/api/screendetails/currentscreenchange_event/index.md b/files/en-us/web/api/screendetails/currentscreenchange_event/index.md new file mode 100644 index 000000000000000..b5787c58476382f --- /dev/null +++ b/files/en-us/web/api/screendetails/currentscreenchange_event/index.md @@ -0,0 +1,69 @@ +--- +title: "ScreenDetails: currentscreenchange event" +short-title: currentscreenchange +slug: Web/API/ScreenDetails/currentscreenchange_event +page-type: web-api-event +status: + - experimental +browser-compat: api.ScreenDetails.currentscreenchange_event +--- + +{{APIRef("Window Management API")}}{{SeeCompatTable}} + +The **`currentscreenchange`** event of the {{domxref("ScreenDetails")}} interface is fired when the {{domxref("ScreenDetails.currentScreen")}} changes in some way. + +Specifically, a _change_ in this context means either: + +- The current screen changes to a different screen, i.e., the current browser window is moved to a different screen. +- The current screen's _basic observable properties_ change. These are: + - {{domxref("Screen.width", "width")}} + - {{domxref("Screen.height", "height")}} + - {{domxref("Screen.availWidth", "availWidth")}} + - {{domxref("Screen.availHeight", "availHeight")}} + - {{domxref("Screen.colorDepth", "colorDepth")}} + - {{domxref("Screen.orientation", "orientation")}} +- The current screen's _advanced observable properties_ change. These are: + - The screen's position ((x,y) coordinates of the top-left corner) inside the OS virtual screen arrangement, relative to the [multi-screen origin](/en-US/docs/Web/API/Window_Management_API#multi-screen_origin) + - The screen's available position ((x,y) coordinates of the top-left corner) inside the OS virtual screen arrangement, relative to the [multi-screen origin](/en-US/docs/Web/API/Window_Management_API#multi-screen_origin). This is equal to the screen position, plus the width/height of any OS UI elements drawn on the top-left of the screen — windows cannot be placed in those areas + - {{domxref("ScreenDetailed.devicePixelRatio", "devicePixelRatio")}} + - {{domxref("ScreenDetailed.label", "label")}} + - The screen's designation as primary or secondary (see {{domxref("ScreenDetailed.isPrimary", "isPrimary")}}) + - The screen's designation as internal or external (see {{domxref("ScreenDetailed.isInternal", "isInternal")}}) + +## Syntax + +Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. + +```js +addEventListener("currentscreenchange", (event) => {}); + +oncurrentscreenchange = (event) => {}; +``` + +## Event type + +An event of type `currentscreenchange`, the event object of which is structurally equivalent to an {{domxref("Event")}}. + +{{InheritanceDiagram("Event")}} + +## Examples + +```js +const screenDetails = await window.getScreenDetails(); +screenDetails.addEventListener("currentscreenchange", async (event) => { + const details = screenDetails.currentScreen; + console.log("The current screen has changed.", event, details); +}); +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [Window Management API](/en-US/docs/Web/API/Window_Management_API) diff --git a/files/en-us/web/api/screendetails/index.md b/files/en-us/web/api/screendetails/index.md new file mode 100644 index 000000000000000..9d2f2d4940cd903 --- /dev/null +++ b/files/en-us/web/api/screendetails/index.md @@ -0,0 +1,93 @@ +--- +title: ScreenDetails +slug: Web/API/ScreenDetails +page-type: web-api-interface +status: + - experimental +browser-compat: api.ScreenDetails +--- + +{{APIRef("Window Management API")}}{{SeeCompatTable}} + +The **`ScreenDetails`** interface of the [Window Management API](/en-US/docs/Web/API/Window_Management_API) represents the details of all the screens available to the user's device. + +This information is accessed via the {{domxref("Window.getScreenDetails()")}} method. + +> **Note:** `ScreenDetails` is a live object, meaning that it updates as the available screens change. You can therefore keep querying the same object to get updated values, rather than repeatedly calling `getScreenDetails()`. + +{{InheritanceDiagram}} + +## Instance properties + +_Inherits properties from its parent, {{DOMxRef("EventTarget")}}._ + +- {{domxref("ScreenDetails.screens", "screens")}} {{ReadOnlyInline}} {{Experimental_Inline}} + + - : An array of {{domxref("ScreenDetailed")}} objects, each one representing detailed information about one specific screen available to the user's device. + + > **Note:** `screens` only includes "extended" displays, not those that mirror another display. + +- {{domxref("ScreenDetails.currentScreen", "currentScreen")}} {{ReadOnlyInline}} {{Experimental_Inline}} + - : A single {{domxref("ScreenDetailed")}} object representing detailed information about the screen that the current browser window is displayed in. + +## Events + +- {{domxref("ScreenDetails.screenschange_event", "screenschange")}} {{experimental_inline}} + - : Fired when screens are connected to or disconnected from the system. +- {{domxref("ScreenDetails.currentscreenchange_event", "currentscreenchange")}} {{experimental_inline}} + - : Fired when the window's current screen changes in some way — for example available width or height, or orientation. + +## Examples + +> **Note:** See [Multi-window learning environment](https://mdn.github.io/dom-examples/window-management-api/) for a full example (see the [source code](https://github.com/mdn/dom-examples/tree/main/window-management-api) also). + +### Basic screen information access + +When {{domxref("Window.getScreenDetails()")}} is invoked, the user will be asked for permission to manage windows on all their displays (the status of this permission can be checked using {{domxref("Permissions.query()")}} to query `window-management`). Provided they grant permission, the resulting `ScreenDetails` object contains details of all the screens available to the user's system. + +The below example opens a full-size window on each available display. + +```js +const screenDetails = await window.getScreenDetails(); + +// Open a window on each screen of the device +for (const screen of screenDetails.screens) { + openWindow( + screen.availLeft, + screen.availTop, + screen.availWidth, + screen.availHeight, + url, + ); +} +``` + +### Responding to changes in available screens + +You could use the `screenschange` event to detect when the available screens have changed (perhaps when a screen is plugged in or unplugged), report the change, and update window arrangements to suit the new configuration: + +```js +screenDetails.addEventListener("screenschange", () => { + // If the new number of screens is different to the old number of screens, report the difference + if (screenDetails.screens.length !== noOfScreens) { + console.log( + `The screen count changed from ${noOfScreens} to ${screenDetails.screens.length}`, + ); + } + + // Open, close, or rearrange windows as needed, to fit the new screen configuration + updateWindows(); +}); +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [Window Management API](/en-US/docs/Web/API/Window_Management_API) diff --git a/files/en-us/web/api/screendetails/screens/index.md b/files/en-us/web/api/screendetails/screens/index.md new file mode 100644 index 000000000000000..c1a82981320ee8a --- /dev/null +++ b/files/en-us/web/api/screendetails/screens/index.md @@ -0,0 +1,34 @@ +--- +title: "ScreenDetails: screens property" +short-title: screens +slug: Web/API/ScreenDetails/screens +page-type: web-api-instance-property +status: + - experimental +browser-compat: api.ScreenDetails.screens +--- + +{{APIRef("Window Management API")}}{{SeeCompatTable}} + +The **`screens`** read-only property of the +{{domxref("ScreenDetails")}} interface contains an array of {{domxref("ScreenDetailed")}} objects, each one representing detailed information about one specific screen available to the user's device. + +## Value + +An array of {{domxref("ScreenDetailed")}} objects. + +## Examples + +See the main [`ScreenDetails` page](/en-US/docs/Web/API/ScreenDetails#examples) for example usage. + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [Window Management API](/en-US/docs/Web/API/Window_Management_API) diff --git a/files/en-us/web/api/screendetails/screenschange_event/index.md b/files/en-us/web/api/screendetails/screenschange_event/index.md new file mode 100644 index 000000000000000..7697e18467435b7 --- /dev/null +++ b/files/en-us/web/api/screendetails/screenschange_event/index.md @@ -0,0 +1,61 @@ +--- +title: "ScreenDetails: screenschange event" +short-title: screenschange +slug: Web/API/ScreenDetails/screenschange_event +page-type: web-api-event +status: + - experimental +browser-compat: api.ScreenDetails.screenschange_event +--- + +{{APIRef("Window Management API")}}{{SeeCompatTable}} + +The **`screenschange`** event of the {{domxref("ScreenDetails")}} interface is fired when the screens available to the system change in some way. + +Specifically, a _change_ in this context means a screen ({{domxref("ScreenDetailed")}} object) has been added to or removed from the {{domxref("ScreenDetails.screens", "screens")}} array. + +## Syntax + +Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. + +```js +addEventListener("screenschange", (event) => {}); + +onscreenschange = (event) => {}; +``` + +## Event type + +An event of type `screenschange`, the event object of which is structurally equivalent to an {{domxref("Event")}}. + +{{InheritanceDiagram("Event")}} + +## Examples + +You could use the `screenschange` event to detect when the available screens have changed, report the change, close all windows, and then reopen them all to suit the new configuration: + +```js +screenDetails.addEventListener("screenschange", () => { + // If the new number of screens is different to the old number of screens, report the difference + if (screenDetails.screens.length !== noOfScreens) { + console.log( + `The screen count changed from ${noOfScreens} to ${screenDetails.screens.length}`, + ); + } + + // Open, close, or rearrange windows as needed, to fit the new screen configuration + updateWindows(); +}); +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [Window Management API](/en-US/docs/Web/API/Window_Management_API) diff --git a/files/en-us/web/api/window/getscreendetails/index.md b/files/en-us/web/api/window/getscreendetails/index.md new file mode 100644 index 000000000000000..b32c20200dc4622 --- /dev/null +++ b/files/en-us/web/api/window/getscreendetails/index.md @@ -0,0 +1,68 @@ +--- +title: "Window: getScreenDetails() method" +short-title: getScreenDetails() +slug: Web/API/Window/getScreenDetails +page-type: web-api-instance-method +status: + - experimental +browser-compat: api.Window.getScreenDetails +--- + +{{APIRef("Window Management API")}}{{SeeCompatTable}} + +The **`getScreenDetails()`** method of the +{{domxref("Window")}} interface returns a {{jsxref("Promise")}} that fulfills with a {{domxref("ScreenDetails")}} object instance representing the details of all the screens available to the user's device. + +## Syntax + +```js-nolint +getScreenDetails() +``` + +### Parameters + +None. + +### Return value + +A {{jsxref("Promise")}} that fulfills with a {{domxref("ScreenDetails")}} object instance. + +### Exceptions + +- `NotAllowedError` {{domxref("DOMException")}} + - : Thrown if a {{httpheader("Permissions-Policy/window-management", "window-management")}} [Permissions-Policy](/en-US/docs/Web/HTTP/Permissions_Policy) is set that blocks use of the [Window Management API](/en-US/docs/Web/API/Window_Management_API), or if the user has explicitly denied the browser's permission request to use the API. + +## Examples + +When `getScreenDetails()` is invoked, the user will be asked for permission to manage windows on all their displays (the status of this permission can be checked using {{domxref("Permissions.query()")}} to query `window-management`). Provided they grant permission, the resulting {{domxref("ScreenDetails")}} object contains details of all the screens available to the user's system. + +The below example opens a full-size window on each available display. + +```js +const screenDetails = await window.getScreenDetails(); + +// Open a window on each screen of the device +for (const screen of screenDetails.screens) { + openWindow( + screen.availLeft, + screen.availTop, + screen.availWidth, + screen.availHeight, + url, + ); +} +``` + +> **Note:** See [Multi-window learning environment](https://mdn.github.io/dom-examples/window-management-api/) for a full example (see the [source code](https://github.com/mdn/dom-examples/tree/main/window-management-api) also). + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [Window Management API](/en-US/docs/Web/API/Window_Management_API) diff --git a/files/en-us/web/api/window/index.md b/files/en-us/web/api/window/index.md index 3ceaf1929e2d751..4bee49fb6287fdb 100644 --- a/files/en-us/web/api/window/index.md +++ b/files/en-us/web/api/window/index.md @@ -199,6 +199,8 @@ _This interface inherits methods from the {{domxref("EventTarget")}} interface._ - : Gets computed style for the specified element. Computed style indicates the computed values of all CSS properties of the element. - {{domxref("Window.getDefaultComputedStyle()")}} {{Non-standard_Inline}} - : Gets default computed style for the specified element, ignoring author stylesheets. +- {{domxref("Window.getScreenDetails()")}} {{experimental_inline}} + - : Returns a {{jsxref("Promise")}} that fulfills with a {{domxref("ScreenDetails")}} object instance representing the details of all the screens available to the user's device. - {{domxref("Window.getSelection()")}} - : Returns the selection object representing the selected item(s). - {{domxref("Window.matchMedia()")}} diff --git a/files/en-us/web/api/window/moveto/index.md b/files/en-us/web/api/window/moveto/index.md index 7fbd72490c38c9b..8308cc9409a4815 100644 --- a/files/en-us/web/api/window/moveto/index.md +++ b/files/en-us/web/api/window/moveto/index.md @@ -15,6 +15,8 @@ interface moves the current window to the specified coordinates. > contrast, {{domxref("window.moveBy()")}} moves the window relative to its current > location. +> **Note:** On devices with multiple displays, `moveTo()` should position windows relative to the [multi-screen origin](/en-US/docs/Web/API/Window_Management_API#multi-screen_origin). This is true in Chromium-based browsers, while Firefox does it inconsistently, sometimes exhibiting unusual behavior. Safari on the other hand moves it relative to the _current_ screen. + ## Syntax ```js-nolint diff --git a/files/en-us/web/api/window/open/index.md b/files/en-us/web/api/window/open/index.md index 07830bd14557264..845716f371629e9 100644 --- a/files/en-us/web/api/window/open/index.md +++ b/files/en-us/web/api/window/open/index.md @@ -10,6 +10,8 @@ browser-compat: api.Window.open The **`open()`** method of the [`Window`](/en-US/docs/Web/API/Window) interface loads a specified resource into a new or existing browsing context (that is, a tab, a window, or an [iframe](/en-US/docs/Web/HTML/Element/iframe)) under a specified name. +> **Note:** On devices with multiple displays, `open()` should position windows relative to the [multi-screen origin](/en-US/docs/Web/API/Window_Management_API#multi-screen_origin). This is true in Chromium-based browsers, while Firefox does it inconsistently, sometimes exhibiting unusual behavior. Safari on the other hand uses local values, always opening it relative to the primary display. + ## Syntax ```js-nolint diff --git a/files/en-us/web/api/window/screenleft/index.md b/files/en-us/web/api/window/screenleft/index.md index 6369cb511d1f437..4538fc46cd577af 100644 --- a/files/en-us/web/api/window/screenleft/index.md +++ b/files/en-us/web/api/window/screenleft/index.md @@ -16,6 +16,8 @@ to the left side of the screen. > {{domxref("Window.screenX")}} property. `screenLeft` was originally > supported only in IE but was introduced everywhere due to popularity. +> **Note:** On devices with multiple displays, browsers will report the value of `screenLeft` relative to the [multi-screen origin](/en-US/docs/Web/API/Window_Management_API#multi-screen_origin). + ## Value A number equal to the number of CSS pixels from the left edge of the browser viewport diff --git a/files/en-us/web/api/window/screentop/index.md b/files/en-us/web/api/window/screentop/index.md index dc3c62e60988de7..233247e120c0162 100644 --- a/files/en-us/web/api/window/screentop/index.md +++ b/files/en-us/web/api/window/screentop/index.md @@ -16,6 +16,8 @@ the top side of the screen. > {{domxref("Window.screenY")}} property. `screenTop` was originally > supported only in IE but was introduced everywhere due to popularity. +> **Note:** On devices with multiple displays, browsers will report the value of `screenTop` relative to the [multi-screen origin](/en-US/docs/Web/API/Window_Management_API#multi-screen_origin), except for Safari, which returns coordinates relative to the current display. + ## Value A number equal to the number of CSS pixels from the top edge of the browser viewport to diff --git a/files/en-us/web/api/window/screenx/index.md b/files/en-us/web/api/window/screenx/index.md index 6c6c53dde78d34b..e455ee0a82b29a8 100644 --- a/files/en-us/web/api/window/screenx/index.md +++ b/files/en-us/web/api/window/screenx/index.md @@ -16,6 +16,8 @@ the left side of the screen. > browsers in more recent times — {{domxref("Window.screenLeft")}}. This was originally > supported only in IE but was introduced everywhere due to popularity. +> **Note:** On devices with multiple displays, browsers will report the value of `screenX` relative to the [multi-screen origin](/en-US/docs/Web/API/Window_Management_API#multi-screen_origin). + ## Value A number equal to the number of CSS pixels from the left edge of the browser viewport diff --git a/files/en-us/web/api/window/screeny/index.md b/files/en-us/web/api/window/screeny/index.md index 75911c20e8fea99..0d0d7da46b8b3c8 100644 --- a/files/en-us/web/api/window/screeny/index.md +++ b/files/en-us/web/api/window/screeny/index.md @@ -12,6 +12,8 @@ The **`Window.screenY`** read-only property returns the vertical distance, in CS > **Note:** An alias of `screenY` was implemented across modern browsers in more recent times — {{domxref("Window.screenTop")}}. This was originally supported only in IE but was introduced everywhere due to popularity. +> **Note:** On devices with multiple displays, browsers will report the value of `screenY` relative to the [multi-screen origin](/en-US/docs/Web/API/Window_Management_API#multi-screen_origin). + ## Value A number equal to the number of CSS pixels from the top edge of the browser viewport to the top edge of the screen. diff --git a/files/en-us/web/api/window_management_api/index.md b/files/en-us/web/api/window_management_api/index.md new file mode 100644 index 000000000000000..0e7db3ea332ca38 --- /dev/null +++ b/files/en-us/web/api/window_management_api/index.md @@ -0,0 +1,294 @@ +--- +title: Window Management API +slug: Web/API/Window_Management_API +page-type: web-api-overview +status: + - experimental +browser-compat: api.Window.getScreenDetails +--- + +{{SeeCompatTable}}{{DefaultAPISidebar("Window Management API")}} + +The **Window Management API** allows you to return detailed information on the displays connected to your device and more easily place windows on specific screens, paving the way towards more effective multi-screen applications. + +## Concepts and usage + +Historically, we have used {{domxref("Window.open()")}} to manage browser windows related to the current application — opening new windows, resizing and closing existing windows, etc. For example, to open a 400×300 window 50 pixels from the left and top of your screen: + +```js +const myWindow = window.open( + "https://example.com/", + "myWindow", + "left=50,top=50,width=400,height=300", +); +``` + +You can retrieve information about your screen from the {{domxref("Window.screen")}} property, such as how much screen space you have available to place windows in. + +However, the above features are limited. `Window.screen` only returns data about the primary screen, and not secondary displays available to a device. To move a window to a secondary display, you could use {{domxref("Window.moveTo()")}}, but you'd have to guess what coordinates to use based on where it is placed in your setup relative to the primary display. + +The Window Management API provides more robust, flexible window management. It allows you to query whether your display is extended with multiple screens and return information on each screen separately: windows can then be placed on each screen as desired. It also provides event handlers to allow you to respond to changes in the available screens, new fullscreen functionality to choose which screen to put into fullscreen mode (if any), and permissions functionality to control access to the API. + +### Multi-screen origin + +The Window Management API introduces the concept of the **multi-screen origin** — this is the (0,0) coordinate of the host operating system (OS)'s virtual screen arrangement, around which all available screens and windows are positioned. The multi-screen origin is commonly, but not always, the top-left corner of the OS primary screen (which can usually be specified by the user via OS settings, and generally contains OS UI features such as the taskbar/icon dock). + +On devices with multiple displays, the following are true on Chrome. Firefox behaves in the same way, but not reliably/consistently, whereas Safari generally uses local values relative to the _current_ screen. + +- The values of {{domxref("ScreenDetailed.left")}}, {{domxref("ScreenDetailed.top")}}, {{domxref("ScreenDetailed.availLeft")}}, and {{domxref("ScreenDetailed.availTop")}} for each available screen are reported relative to the multi-screen origin. +- The values of {{domxref("Window.screenLeft")}}, {{domxref("Window.screenTop")}}, {{domxref("Window.screenX")}}, {{domxref("Window.screenY")}} for each window are reported relative to the multi-screen origin. +- When using {{domxref("Window.moveTo()")}} and {{domxref("Window.open()")}}, windows are positioned relative to the multi-screen origin. + +Say we have an external monitor of resolution 1920 x 1080 set as the primary monitor, and an internal laptop display of resolution 1440 x 900 set as a secondary monitor. Let's also say that the OS UI takes up 25px at the top of the screen, and is only drawn on the primary screen. + +If the secondary screen was positioned directly to the right of the primary screen, top screen edges in line: + +- The primary screen `left`/`top` values would be (0,0) while its `availLeft`/`availTop` values would be (0,25) — the OS UI thickness is added on. +- The secondary screen `left`/`top` values would be (1920,0) while its `availLeft`/`availTop` values would also be (1920,0) — the OS UI is not drawn on the secondary screen. + +![Two rectangles representing the primary screen with the secondary screen positioned to the right, as described above](primary-screen-left.png) + +However, if the secondary screen was positioned directly to the left of the primary screen, top screen edges in line: + +- The primary screen `left`/`top` values would still be (0,0) while its `availLeft`/`availTop` values would be (0,25). +- The secondary screen `left`/`top` values would be (-1440,0) while its `availLeft`/`availTop` values would also be (-1440,0). + +![Two rectangles representing the primary screen with the secondary screen positioned to the left, as described above](primary-screen-right.png) + +## Use cases + +The Window Management API is useful in cases such as: + +- Multi-window graphics editors and audio processors that may wish to arrange editing tools and panels across different screens. +- Virtual trading desks that want to show market trends in multiple windows and put specific windows of interest in fullscreen mode. +- Slideshow apps that want to show speaker notes on the internal primary screen and the presentation on an external projector. + +## How does it work? + +The core of the Windows Management API is the {{domxref("Window.getScreenDetails()")}} method, which returns an object containing details of all the screens available to the user's system: + +```js +const screenDetails = await window.getScreenDetails(); + +// Return the number of screens +const noOfScreens = screenDetails.screens.length; +``` + +When `getScreenDetails()` is invoked, the user will be asked for permission to manage windows on all their displays (the status of this permission can be checked using {{domxref("Permissions.query()")}} to query `window-management`). Provided they grant permission, the resulting {{domxref("ScreenDetails")}} object contains the following properties: + +- `screens` + + - : An array of {{domxref("ScreenDetailed")}} objects, each one containing detailed information about a separate screen available to the system (see below). This array is also useful for determining the number of available screens, via `screens.length`. + + > **Note:** `screens` only includes "extended" displays, not those that mirror another display. + +- `currentScreen` + - : A single {{domxref("ScreenDetailed")}} object containing detailed information about the screen that the current browser window is displayed in. + +> **Note:** `ScreenDetails` is a live object, meaning that it updates as the available screens change. You can therefore keep querying the same object to get updated values, rather than repeatedly calling `getScreenDetails()`. + +> **Note:** You can gate functionality based on whether the user has more than one screen available using the {{domxref("Screen.isExtended", "Window.screen.isExtended")}} property. This returns `true` if the device has multiple screens, and `false` if not. + +{{domxref("ScreenDetailed")}} objects inherit the properties of the {{domxref("Screen")}} interface, and contain useful information for placing windows on specific screens. For example: + +- `availWidth` and `availHeight` + - : The width and height of the screen area available for opening windows in. These values are equal to `width` and `height`, minus the width/height of any OS-specific user interface elements drawn on the screen. +- `availLeft` and `availTop` + - : The top-left coordinate of the screen area available for opening windows in. These values are equal to `left` and `top`, plus the width/height of any OS-specific user interface elements drawn at the top/left of the screen. +- `isPrimary` + - : A boolean indicating whether this screen is set as the OS primary screen or not. +- `isInternal` + - : A boolean indicating whether this screen is internal to the device or not. +- `label` + - : A string providing a descriptive label for the screen, for example "Built-in Retina Display". This is useful for constructing a list of options to display to the user if you want them to choose a screen to display content on. + +You'll still need to use {{domxref("Window.open()")}} to open and manage windows, but the above provides you with better information for doing so in a multi-screen environment. For example, a utility function might look like so: + +```js +function openWindow(left, top, width, height, url) { + const windowFeatures = `left=${left},top=${top},width=${width},height=${height}`; + const windowRef = window.open( + url, + "_blank", // needed for it to open in a new window + windowFeatures, + ); + + // Store a reference to the window in the windowRefs array + windowRefs.push(windowRef); +} +``` + +You would then invoke this function and open windows on specific screens like this: + +```js +const screen1 = screenDetails.screens[0]; +const screen2 = screenDetails.screens[1]; +// Windows will be a third the width and the full height of the screen +let windowWidth = Math.floor((screen1.availWidth - 3 * WINDOW_CHROME_X) / 3); +let windowHeight = Math.floor(screen1.availHeight - WINDOW_CHROME_Y); + +// Open the reference windows in thirds across the entire height of the primary screen +openWindow( + screen1.availLeft, + screen1.availTop, + windowWidth, + windowHeight, + sites[1].url, +); + +// ... +``` + +As shown in an earlier code block, it is a good idea to keep track of the windows you have open, for example using an array. This allows you to, for example, close them all when one window is closed: + +```js +function closeAllWindows() { + // Loop through all window refs and close each one + windowRefs.forEach((windowRef) => { + windowRef.close(); + }); + windowRefs = []; +} + +// Check whether one of our popup windows has been closed +// If so, close them all + +closeMonitor = setInterval(checkWindowClose, 250); + +function checkWindowClose() { + if (windowRefs.some((windowRef) => windowRef.closed)) { + closeAllWindows(); + clearInterval(closeMonitor); + } +} +``` + +> **Note:** In our experiments, the {{domxref("setInterval()")}} polling method shown above seemed to work best for detecting window closure in the case of multiple windows. Using events such as {{domxref("Window.beforeunload_event", "beforeunload")}}, {{domxref("Window.pagehide_event", "pagehide")}}, or {{domxref("Document.visibilitychange_event", "visibilitychange")}} proved unreliable because, when opening multiple windows at the same time, the rapid shift in focus/visibility seemed to fire the handler function prematurely. + +> **Note:** One concern with the above example is that it uses constant values to represent the size of the Chrome window UI portions in the calculations — `WINDOW_CHROME_X` and `WINDOW_CHROME_Y` — to get the window size calculations correct. This might not produce entirely correctly-sized windows on other future implementations of the API, or future versions of Chrome that might have a different-sized UI. There currently isn't an easy way to work around this. + +### Simple single-window per display case + +If you want to open a single window on each available display that is the full width and height of the display, you could use a pattern like this: + +```js +// Open a window on each screen of the device +for (const screen of screenDetails.screens) { + openWindow( + screen.availLeft, + screen.availTop, + screen.availWidth, + screen.availHeight, + url, + ); +} +``` + +### Window management events + +The Window Management API provides some useful events for responding to changes in the available screens: + +- The `ScreenDetails` {{domxref("ScreenDetails.screenschange_event", "screenschange")}} event + - : Fired when screens are connected to or disconnected from the system. +- The `ScreenDetails` {{domxref("ScreenDetails.currentscreenchange_event", "currentscreenchange")}} event + - : Fired when the window's current screen changes in some way. +- The `Screen` {{domxref("Screen.change_event", "change")}} event + - : Fired on a specific screen when it changes in some way. + +So for example, you could use the `screenschange` event to detect when the available screens have changed (perhaps when a screen is plugged in or unplugged), report the change, close all windows, and update window arrangements to suit the new configuration: + +```js +screenDetails.addEventListener("screenschange", () => { + // If the new number of screens is different to the old number of screens, report the difference + if (screenDetails.screens.length !== noOfScreens) { + console.log( + `The screen count changed from ${noOfScreens} to ${screenDetails.screens.length}`, + ); + } + + // If the windows are open, close them and then open them again + // So that they fit with the new screen configuration + if (windowRefs.length > 0) { + closeAllWindows(); + openWindows(); + } +}); +``` + +### requestFullscreen() screen option + +The Window Management API adds a new `screen` option to the {{domxref("Element.requestFullscreen", "requestFullscreen()")}} method that allows you to specify on which screen you want to put the element in fullscreen mode. For example, if you want to make it fullscreen on the primary OS screen: + +```js +try { + const primaryScreen = (await getScreenDetails()).screens.find( + (screen) => screen.isPrimary, + ); + await document.body.requestFullscreen({ screen: primaryScreen }); +} catch (err) { + console.error(err.name, err.message); +} +``` + +## Permissions policy integration + +The {{httpheader("Permissions-Policy/window-management", "window-management")}} [Permissions-Policy](/en-US/docs/Web/HTTP/Permissions_Policy) can be used to control permission to use the Window Management API. Specifically: + +- Usage of the {{domxref("Window.getScreenDetails()")}} method. If blocked, its {{jsxref("Promise")}} will reject with a `NotAllowedError` exception. +- Querying the {{domxref("Screen.isExtended", "Window.screen.isExtended")}} property. If blocked, it will always return `false`. + +Developers can explicitly grant permission for an {{htmlelement("iframe")}} to use Window Management via the `allow` attribute: + +```html + +``` + +## Interfaces + +- {{domxref("ScreenDetails")}} + - : Represents the details of all the screens available to the user's device. +- {{domxref("ScreenDetailed")}} + - : Represents detailed information about one specific screen available to the user's device. + +## Extensions to other interfaces + +- The `Screen` {{domxref("Screen.change_event", "change")}} event + - : Fired on a specific screen when it changes in some way — for example available width or height, or orientation. +- {{domxref("Screen.isExtended")}} + - : A boolean property that returns `true` if the user's device has multiple screens, and `false` if not. +- {{domxref("Element.requestFullscreen()")}}, the `screen` option + - : Specifies on which screen you want to put the element in fullscreen mode. +- {{domxref("Window.getScreenDetails()")}} + - : Returns a {{jsxref("Promise")}} that fulfills with a {{domxref("ScreenDetails")}} object instance. + +## Examples + +### Feature detection + +You can feature detect the Window Management API by checking for the existence of `getScreenDetails` in the current `window` instance. For example, you might want to provide a button to open a multi-window display if the API is supported, or a different experience such as creating links to the different pages if it isn't: + +```js +if ("getScreenDetails" in window) { + // The Window Management API is supported + createButton(); +} else { + // The Window Management API is not supported + createLinks(sites); +} +``` + +### Full examples + +You can find full examples here: + +- [Multi-window learning environment](https://mdn.github.io/dom-examples/window-management-api/) (see the [source code](https://github.com/mdn/dom-examples/tree/main/window-management-api)). +- [Elmer-inspired trading desk demo](https://window-placement.glitch.me/) (see the [source code](https://glitch.com/edit/#!/window-placement)). +- [Window management demo](https://michaelwasserman.github.io/window-placement-demo/) (see the [source code](https://github.com/michaelwasserman/window-placement-demo)). + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} diff --git a/files/en-us/web/api/window_management_api/primary-screen-left-source.drawio b/files/en-us/web/api/window_management_api/primary-screen-left-source.drawio new file mode 100644 index 000000000000000..fb52def990d813d --- /dev/null +++ b/files/en-us/web/api/window_management_api/primary-screen-left-source.drawio @@ -0,0 +1,85 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/files/en-us/web/api/window_management_api/primary-screen-left.png b/files/en-us/web/api/window_management_api/primary-screen-left.png new file mode 100644 index 000000000000000..02b0c323fb4d960 Binary files /dev/null and b/files/en-us/web/api/window_management_api/primary-screen-left.png differ diff --git a/files/en-us/web/api/window_management_api/primary-screen-right-source.drawio b/files/en-us/web/api/window_management_api/primary-screen-right-source.drawio new file mode 100644 index 000000000000000..ef030426dfb67f3 --- /dev/null +++ b/files/en-us/web/api/window_management_api/primary-screen-right-source.drawio @@ -0,0 +1,85 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/files/en-us/web/api/window_management_api/primary-screen-right.png b/files/en-us/web/api/window_management_api/primary-screen-right.png new file mode 100644 index 000000000000000..6e81abaf1f5a4a3 Binary files /dev/null and b/files/en-us/web/api/window_management_api/primary-screen-right.png differ diff --git a/files/en-us/web/http/headers/permissions-policy/index.md b/files/en-us/web/http/headers/permissions-policy/index.md index 6a8cbb44cf2d58a..f7d34abc05a6832 100644 --- a/files/en-us/web/http/headers/permissions-policy/index.md +++ b/files/en-us/web/http/headers/permissions-policy/index.md @@ -193,6 +193,10 @@ You can specify - : Controls whether or not the current document is allowed to use the {{domxref("Navigator.share","Navigator.share()")}} of Web Share API to share text, links, images, and other content to arbitrary destinations of user's choice, e.g. mobile apps. +- {{httpheader("Permissions-Policy/window-management", "window-management")}} + + - : Controls whether or not the current document is allowed to use the [Window Management API](/en-US/docs/Web/API/Window_Management_API) to manage windows on multiple displays. + - {{httpheader("Permissions-Policy/xr-spatial-tracking", "xr-spatial-tracking")}} {{Experimental_Inline}} - : Controls whether or not the current document is allowed to use the [WebXR Device API](/en-US/docs/Web/API/WebXR_Device_API) to interact with a WebXR session. diff --git a/files/en-us/web/http/headers/permissions-policy/window-management/index.md b/files/en-us/web/http/headers/permissions-policy/window-management/index.md new file mode 100644 index 000000000000000..bfd5475eed856c9 --- /dev/null +++ b/files/en-us/web/http/headers/permissions-policy/window-management/index.md @@ -0,0 +1,44 @@ +--- +title: "Permissions-Policy: window-management" +slug: Web/HTTP/Headers/Permissions-Policy/window-management +page-type: http-permissions-policy-directive +status: + - experimental +browser-compat: http.headers.Permissions-Policy.window-management +--- + +{{HTTPSidebar}}{{SeeCompatTable}} + +The HTTP {{HTTPHeader("Permissions-Policy")}} header `window-management` directive controls whether or not the current document is allowed to use the [Window Management API](/en-US/docs/Web/API/Window_Management_API) to manage windows on multiple displays. + +Where this policy forbids use of the API: + +- {{jsxref("Promise", "Promises")}} returned by the {{domxref("Window.getScreenDetails()")}} method will reject with a `NotAllowedError` exception. +- The {{domxref("Screen.isExtended", "Window.screen.isExtended")}} property will always return `false`. + +## Syntax + +```http +Permissions-Policy: window-management=; +``` + +- `` + - : A list of origins for which permission is granted to use the feature. See [`Permissions-Policy` > Syntax](/en-US/docs/Web/HTTP/Headers/Permissions-Policy#syntax) for more details. + +## Default policy + +The default allowlist for `window-management` is `self`. + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [Window Management API](/en-US/docs/Web/API/Window_Management_API) +- {{HTTPHeader("Permissions-Policy")}} header +- [Permissions Policy](/en-US/docs/Web/HTTP/Permissions_Policy) diff --git a/files/jsondata/GroupData.json b/files/jsondata/GroupData.json index 302ccda5edecdcd..e5f0fdd3f8e5607 100644 --- a/files/jsondata/GroupData.json +++ b/files/jsondata/GroupData.json @@ -2312,6 +2312,17 @@ "properties": ["Navigator.windowControlsOverlay"], "events": [] }, + "Window Management API": { + "overview": ["Window Management API"], + "interfaces": ["ScreenDetails", "ScreenDetailed"], + "methods": ["Element.requestFullscreen()", "Window.getScreenDetails()"], + "properties": ["Screen.isExtended"], + "events": [ + "Screen: change", + "ScreenDetails: currentscreenchange", + "ScreenDetails: screenschange" + ] + }, "XMLHttpRequest": { "overview": ["XMLHttpRequest"], "guides": [