chrome.system.display

Description: Use the system.display API to query display metadata.
Availability: Since Chrome 35.
Permissions: "system.display"

Summary

Types
Bounds
Insets
Point
TouchCalibrationPair
DisplayMode
DisplayLayout
Methods
getInfo − chrome.system.display.getInfo(object flags, function callback)
getDisplayLayout − chrome.system.display.getDisplayLayout(function callback)
setDisplayProperties − chrome.system.display.setDisplayProperties(string id, object info, function callback)
setDisplayLayout − chrome.system.display.setDisplayLayout(array of DisplayLayout layouts, function callback)
enableUnifiedDesktop − chrome.system.display.enableUnifiedDesktop(boolean enabled)
overscanCalibrationStart − chrome.system.display.overscanCalibrationStart(string id)
overscanCalibrationAdjust − chrome.system.display.overscanCalibrationAdjust(string id, Insets delta)
overscanCalibrationReset − chrome.system.display.overscanCalibrationReset(string id)
overscanCalibrationComplete − chrome.system.display.overscanCalibrationComplete(string id)
showNativeTouchCalibration − chrome.system.display.showNativeTouchCalibration(string id, function callback)
startCustomTouchCalibration − chrome.system.display.startCustomTouchCalibration(string id)
completeCustomTouchCalibration − chrome.system.display.completeCustomTouchCalibration(object pairs, Bounds bounds)
clearTouchCalibration − chrome.system.display.clearTouchCalibration(string id)
setMirrorMode − chrome.system.display.setMirrorMode(object info, function callback)
Events
onDisplayChanged

Types

Bounds

properties
integer left

The x-coordinate of the upper-left corner.

integer top

The y-coordinate of the upper-left corner.

integer width

The width of the display in pixels.

integer height

The height of the display in pixels.

Insets

properties
integer left

The x-axis distance from the left bound.

integer top

The y-axis distance from the top bound.

integer right

The x-axis distance from the right bound.

integer bottom

The y-axis distance from the bottom bound.

Point

Since Chrome 57.

properties
integer x

The x-coordinate of the point.

integer y

The y-coordinate of the point.

TouchCalibrationPair

Since Chrome 57.

properties
Point displayPoint

The coordinates of the display point.

Point touchPoint

The coordinates of the touch point corresponding to the display point.

DisplayMode

Since Chrome 52.

properties
integer width

The display mode width in device independent (user visible) pixels.

integer height

The display mode height in device independent (user visible) pixels.

integer widthInNativePixels

The display mode width in native pixels.

integer heightInNativePixels

The display mode height in native pixels.

double (optional) uiScale

Deprecated since Chrome 70. Use displayZoomFactor

The display mode UI scale factor.

double deviceScaleFactor

The display mode device scale factor.

double refreshRate

Since Chrome 67.

The display mode refresh rate in hertz.

boolean isNative

True if the mode is the display's native mode.

boolean isSelected

True if the display mode is currently selected.

boolean (optional) isInterlaced

Since Chrome 74.

True if this mode is interlaced, false if not provided.

DisplayLayout

Since Chrome 53.

properties
string id

The unique identifier of the display.

string parentId

The unique identifier of the parent display. Empty if this is the root.

enum of "top", "right", "bottom", or "left" position

The layout position of this display relative to the parent. This will be ignored for the root.

integer offset

The offset of the display along the connected edge. 0 indicates that the topmost or leftmost corners are aligned.

Methods

getInfo

chrome.system.display.getInfo(object flags, function callback)

Requests the information for all attached display devices.

Parameters
object (optional) flags

Since Chrome 59.

Options affecting how the information is returned.

boolean (optional) singleUnified

If set to true, only a single DisplayUnitInfo will be returned by getInfo when in unified desktop mode (see enableUnifiedDesktop). Defaults to false.

function callback

The callback to invoke with the results.

The callback parameter should be a function that looks like this:

function(array of object displayInfo) {...};
array of object displayInfo

Properties of each object

string id

The unique identifier of the display.

string name

The user-friendly name (e.g. "HP LCD monitor").

object (optional) edid

NOTE: This is only available to Chrome OS Kiosk apps and Web UI.

string manufacturerId

3 character manufacturer code. See Sec. 3.4.1 page 21. Required in v1.4.

string productId

2 byte manufacturer-assigned code, Sec. 3.4.2 page 21. Required in v1.4.

integer yearOfManufacture

Year of manufacturer, Sec. 3.4.4 page 22. Required in v1.4.

string mirroringSourceId

Chrome OS only. Identifier of the display that is being mirrored if mirroring is enabled, otherwise empty. This will be set for all displays (including the display being mirrored).

array of string mirroringDestinationIds

Chrome OS only. Identifiers of the displays to which the source display is being mirrored. Empty if no displays are being mirrored. This will be set to the same value for all displays. This must not include |mirroringSourceId|.

boolean isPrimary

True if this is the primary display.

boolean isInternal

True if this is an internal display.

boolean isEnabled

True if this display is enabled.

boolean isUnified

True for all displays when in unified desktop mode. See documentation for enableUnifiedDesktop.

double dpiX

The number of pixels per inch along the x-axis.

double dpiY

The number of pixels per inch along the y-axis.

integer rotation

The display's clockwise rotation in degrees relative to the vertical position. Currently exposed only on ChromeOS. Will be set to 0 on other platforms. A value of -1 will be interpreted as auto-rotate when the device is in a physical tablet state.

Bounds bounds

The display's logical bounds.

Insets overscan

The display's insets within its screen's bounds. Currently exposed only on ChromeOS. Will be set to empty insets on other platforms.

Bounds workArea

The usable work area of the display within the display bounds. The work area excludes areas of the display reserved for OS, for example taskbar and launcher.

array of DisplayMode modes

The list of available display modes. The current mode will have isSelected=true. Only available on Chrome OS. Will be set to an empty array on other platforms.

boolean hasTouchSupport

True if this display has a touch input device associated with it.

array of double availableDisplayZoomFactors

A list of zoom factor values that can be set for the display.

double displayZoomFactor

The ratio between the display's current and default zoom. For example, value 1 is equivalent to 100% zoom, and value 1.5 is equivalent to 150% zoom.

getDisplayLayout

chrome.system.display.getDisplayLayout(function callback)

Since Chrome 53.

Requests the layout info for all displays. NOTE: This is only available to Chrome OS Kiosk apps and Web UI.

Parameters
function callback

The callback to invoke with the results.

The callback parameter should be a function that looks like this:

function(array of DisplayLayout layouts) {...};
array of DisplayLayout layouts

setDisplayProperties

chrome.system.display.setDisplayProperties(string id, object info, function callback)

Updates the properties for the display specified by |id|, according to the information provided in |info|. On failure, runtime.lastError will be set. NOTE: This is only available to Chrome OS Kiosk apps and Web UI.

Parameters
string id

The display's unique identifier.

object info

The information about display properties that should be changed. A property will be changed only if a new value for it is specified in |info|.

boolean (optional) isUnified

Since Chrome 59.

Chrome OS only. If set to true, changes the display mode to unified desktop (see enableUnifiedDesktop for details). If set to false, unified desktop mode will be disabled. This is only valid for the primary display. If provided, mirroringSourceId must not be provided and other properties will be ignored. This is has no effect if not provided.

string (optional) mirroringSourceId

Deprecated since Chrome 68. Use setMirrorMode.

Chrome OS only. If set and not empty, enables mirroring for this display only. Otherwise disables mirroring for all displays. This value should indicate the id of the source display to mirror, which must not be the same as the id passed to setDisplayProperties. If set, no other property may be set.

boolean (optional) isPrimary

If set to true, makes the display primary. No-op if set to false. Note: If set, the display is considered primary for all other properties (i.e. isUnified may be set and bounds origin may not).

Insets (optional) overscan

If set, sets the display's overscan insets to the provided values. Note that overscan values may not be negative or larger than a half of the screen's size. Overscan cannot be changed on the internal monitor.

integer (optional) rotation

If set, updates the display's rotation. Legal values are [0, 90, 180, 270]. The rotation is set clockwise, relative to the display's vertical position.

integer (optional) boundsOriginX

If set, updates the display's logical bounds origin along the x-axis. Applied together with boundsOriginY. Defaults to the current value if not set and boundsOriginY is set. Note that when updating the display origin, some constraints will be applied, so the final bounds origin may be different than the one set. The final bounds can be retrieved using getInfo. The bounds origin cannot be changed on the primary display.

integer (optional) boundsOriginY

If set, updates the display's logical bounds origin along the y-axis. See documentation for boundsOriginX parameter.

DisplayMode (optional) displayMode

Since Chrome 52.

If set, updates the display mode to the mode matching this value. If other parameters are invalid, this will not be applied. If the display mode is invalid, it will not be applied and an error will be set, but other properties will still be applied.

double (optional) displayZoomFactor

Since Chrome 65.

If set, updates the zoom associated with the display. This zoom performs re-layout and repaint thus resulting in a better quality zoom than just performing a pixel by pixel stretch enlargement.

function (optional) callback

Empty function called when the function finishes. To find out whether the function succeeded, runtime.lastError should be queried.

If you specify the callback parameter, it should be a function that looks like this:

function() {...};

setDisplayLayout

chrome.system.display.setDisplayLayout(array of DisplayLayout layouts, function callback)

Since Chrome 53.

Set the layout for all displays. Any display not included will use the default layout. If a layout would overlap or be otherwise invalid it will be adjusted to a valid layout. After layout is resolved, an onDisplayChanged event will be triggered. NOTE: This is only available to Chrome OS Kiosk apps and Web UI.

Parameters
array of DisplayLayout layouts

The layout information, required for all displays except the primary display.

function (optional) callback

Empty function called when the function finishes. To find out whether the function succeeded, runtime.lastError should be queried.

If you specify the callback parameter, it should be a function that looks like this:

function() {...};

enableUnifiedDesktop

chrome.system.display.enableUnifiedDesktop(boolean enabled)

Since Chrome 46.

Enables/disables the unified desktop feature. If enabled while mirroring is active, the desktop mode will not change until mirroring is turned off. Otherwise, the desktop mode will switch to unified immediately. NOTE: This is only available to Chrome OS Kiosk apps and Web UI.

Parameters
boolean enabled

True if unified desktop should be enabled.

overscanCalibrationStart

chrome.system.display.overscanCalibrationStart(string id)

Since Chrome 53.

Starts overscan calibration for a display. This will show an overlay on the screen indicating the current overscan insets. If overscan calibration for display |id| is in progress this will reset calibration.

Parameters
string id

The display's unique identifier.

overscanCalibrationAdjust

chrome.system.display.overscanCalibrationAdjust(string id, Insets delta)

Since Chrome 53.

Adjusts the current overscan insets for a display. Typically this should either move the display along an axis (e.g. left+right have the same value) or scale it along an axis (e.g. top+bottom have opposite values). Each Adjust call is cumulative with previous calls since Start.

Parameters
string id

The display's unique identifier.

Insets delta

The amount to change the overscan insets.

overscanCalibrationReset

chrome.system.display.overscanCalibrationReset(string id)

Since Chrome 53.

Resets the overscan insets for a display to the last saved value (i.e before Start was called).

Parameters
string id

The display's unique identifier.

overscanCalibrationComplete

chrome.system.display.overscanCalibrationComplete(string id)

Since Chrome 53.

Complete overscan adjustments for a display by saving the current values and hiding the overlay.

Parameters
string id

The display's unique identifier.

showNativeTouchCalibration

chrome.system.display.showNativeTouchCalibration(string id, function callback)

Since Chrome 57.

Displays the native touch calibration UX for the display with |id| as display id. This will show an overlay on the screen with required instructions on how to proceed. The callback will be invoked in case of successful calibration only. If the calibration fails, this will throw an error.

Parameters
string id

The display's unique identifier.

function (optional) callback

Optional callback to inform the caller that the touch calibration has ended. The argument of the callback informs if the calibration was a success or not.

If you specify the callback parameter, it should be a function that looks like this:

function(boolean success) {...};
boolean success

startCustomTouchCalibration

chrome.system.display.startCustomTouchCalibration(string id)

Since Chrome 57.

Starts custom touch calibration for a display. This should be called when using a custom UX for collecting calibration data. If another touch calibration is already in progress this will throw an error.

Parameters
string id

The display's unique identifier.

completeCustomTouchCalibration

chrome.system.display.completeCustomTouchCalibration(object pairs, Bounds bounds)

Since Chrome 57.

Sets the touch calibration pairs for a display. These |pairs| would be used to calibrate the touch screen for display with |id| called in startCustomTouchCalibration(). Always call |startCustomTouchCalibration| before calling this method. If another touch calibration is already in progress this will throw an error.

Parameters
object pairs

The pairs of point used to calibrate the display.

TouchCalibrationPair pair1

First pair of touch and display point required for touch calibration.

TouchCalibrationPair pair2

Second pair of touch and display point required for touch calibration.

TouchCalibrationPair pair3

Third pair of touch and display point required for touch calibration.

TouchCalibrationPair pair4

Fourth pair of touch and display point required for touch calibration.

Bounds bounds

Bounds of the display when the touch calibration was performed. |bounds.left| and |bounds.top| values are ignored.

clearTouchCalibration

chrome.system.display.clearTouchCalibration(string id)

Since Chrome 57.

Resets the touch calibration for the display and brings it back to its default state by clearing any touch calibration data associated with the display.

Parameters
string id

The display's unique identifier.

setMirrorMode

chrome.system.display.setMirrorMode(object info, function callback)

Since Chrome 65.

Sets the display mode to the specified mirror mode. Each call resets the state from previous calls. Calling setDisplayProperties() will fail for the mirroring destination displays. NOTE: This is only available to Chrome OS Kiosk apps and Web UI.

Parameters
object info

The information of the mirror mode that should be applied to the display mode.

enum of "off", "normal", or "mixed" mode

The mirror mode that should be set.

off
Use the default mode (extended or unified desktop).
normal
The default source display will be mirrored to all other displays.
mixed
The specified source display will be mirrored to the provided destination displays. All other connected displays will be extended.
string (optional) mirroringSourceId

The id of the mirroring source display. This is only valid for 'mixed'.

array of string (optional) mirroringDestinationIds

The ids of the mirroring destination displays. This is only valid for 'mixed'.

function (optional) callback

Empty function called when the function finishes. To find out whether the function succeeded, runtime.lastError should be queried.

If you specify the callback parameter, it should be a function that looks like this:

function() {...};

Events

onDisplayChanged

Fired when anything changes to the display configuration.

addListener

chrome.system.display.onDisplayChanged.addListener(function callback)
Parameters
function callback

The callback parameter should be a function that looks like this:

function() {...};