chrome.system.display
- Description
Use the
system.display
API to query display metadata. - Permissions
system.display
Summary
- Types
- Methods
chrome.system.display.clearTouchCalibration(id: string)
chrome.system.display.completeCustomTouchCalibration(pairs: TouchCalibrationPairQuad, bounds: Bounds)
chrome.system.display.enableUnifiedDesktop(enabled: boolean)
chrome.system.display.getDisplayLayout(callback: function)
chrome.system.display.getInfo(flags?: GetInfoFlags, callback: function)
chrome.system.display.overscanCalibrationAdjust(id: string, delta: Insets)
chrome.system.display.overscanCalibrationComplete(id: string)
chrome.system.display.overscanCalibrationReset(id: string)
chrome.system.display.overscanCalibrationStart(id: string)
chrome.system.display.setDisplayLayout(layouts: DisplayLayout[], callback: function)
chrome.system.display.setDisplayProperties(id: string, info: DisplayProperties, callback: function)
chrome.system.display.setMirrorMode(info: MirrorModeInfo, callback: function)
chrome.system.display.showNativeTouchCalibration(id: string, callback: function)
chrome.system.display.startCustomTouchCalibration(id: string)
- Events
Types
Bounds
Properties
- heightnumber
The height of the display in pixels.
- leftnumber
The x-coordinate of the upper-left corner.
- topnumber
The y-coordinate of the upper-left corner.
- widthnumber
The width of the display in pixels.
DisplayLayout
Properties
- idstring
The unique identifier of the display.
- offsetnumber
The offset of the display along the connected edge. 0 indicates that the topmost or leftmost corners are aligned.
- parentIdstring
The unique identifier of the parent display. Empty if this is the root.
- position
The layout position of this display relative to the parent. This will be ignored for the root.
DisplayMode
Properties
- deviceScaleFactornumber
The display mode device scale factor.
- heightnumber
The display mode height in device independent (user visible) pixels.
- heightInNativePixelsnumber
The display mode height in native pixels.
- isInterlacedboolean optional
True if this mode is interlaced, false if not provided.
- isNativeboolean
True if the mode is the display's native mode.
- isSelectedboolean
True if the display mode is currently selected.
- refreshRatenumber
The display mode refresh rate in hertz.
- uiScalenumber optional
Deprecated. Use
displayZoomFactor
The display mode UI scale factor.
- widthnumber
The display mode width in device independent (user visible) pixels.
- widthInNativePixelsnumber
The display mode width in native pixels.
DisplayProperties
Properties
- boundsOriginXnumber optional
If set, updates the display's logical bounds origin along the x-axis. Applied together with
DisplayProperties.boundsOriginY
. Defaults to the current value if not set andDisplayProperties.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 usinggetInfo
. The bounds origin cannot be changed on the primary display. - boundsOriginYnumber optional
If set, updates the display's logical bounds origin along the y-axis. See documentation for
DisplayProperties.boundsOriginX
parameter. - displayModeDisplayMode optional
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.
- displayZoomFactornumber optional
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.
- isPrimaryboolean optional
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.
DisplayProperties.isUnified
may be set and bounds origin may not). - isUnifiedboolean optional
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. - mirroringSourceIdstring optional
Deprecated. 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.
- overscanInsets optional
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.
- rotationnumber optional
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.
DisplayUnitInfo
Properties
- availableDisplayZoomFactorsnumber[]
A list of zoom factor values that can be set for the display.
- bounds
The display's logical bounds.
- displayZoomFactornumber
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.
- dpiXnumber
The number of pixels per inch along the x-axis.
- dpiYnumber
The number of pixels per inch along the y-axis.
- edidEdid optional
NOTE: This is only available to Chrome OS Kiosk apps and Web UI.
- hasTouchSupportboolean
True if this display has a touch input device associated with it.
- idstring
The unique identifier of the display.
- isEnabledboolean
True if this display is enabled.
- isInternalboolean
True if this is an internal display.
- isPrimaryboolean
True if this is the primary display.
- isUnifiedboolean
True for all displays when in unified desktop mode. See documentation for
enableUnifiedDesktop
. - mirroringDestinationIdsstring[]
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|.
- mirroringSourceIdstring
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).
- 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.
- namestring
The user-friendly name (e.g. "HP LCD monitor").
- overscan
The display's insets within its screen's bounds. Currently exposed only on ChromeOS. Will be set to empty insets on other platforms.
- rotationnumber
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.
- 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.
Edid
Properties
- manufacturerIdstring
3 character manufacturer code. See Sec. 3.4.1 page 21. Required in v1.4.
- productIdstring
2 byte manufacturer-assigned code, Sec. 3.4.2 page 21. Required in v1.4.
- yearOfManufacturenumber
Year of manufacturer, Sec. 3.4.4 page 22. Required in v1.4.
GetInfoFlags
Properties
- singleUnifiedboolean optional
If set to true, only a single
DisplayUnitInfo
will be returned bygetInfo
when in unified desktop mode (seeenableUnifiedDesktop
). Defaults to false.
Insets
Properties
- bottomnumber
The y-axis distance from the bottom bound.
- leftnumber
The x-axis distance from the left bound.
- rightnumber
The x-axis distance from the right bound.
- topnumber
The y-axis distance from the top bound.
MirrorModeInfo
Properties
- mirroringDestinationIdsstring[] optional
The ids of the mirroring destination displays. This is only valid for 'mixed'.
- mirroringSourceIdstring optional
The id of the mirroring source display. This is only valid for 'mixed'.
- mode
The mirror mode that should be set.
Point
Properties
- xnumber
The x-coordinate of the point.
- ynumber
The y-coordinate of the point.
TouchCalibrationPair
TouchCalibrationPairQuad
Properties
- pair1
First pair of touch and display point required for touch calibration.
- pair2
Second pair of touch and display point required for touch calibration.
- pair3
Third pair of touch and display point required for touch calibration.
- pair4
Fourth pair of touch and display point required for touch calibration.
LayoutPosition
Layout position, i.e. edge of parent that the display is attached to.
Enum
"top"
, "right"
, "bottom"
, or "left"
MirrorMode
Mirror mode, i.e. different ways of how a display is mirrored to other displays.
Enum
"off"
, "normal"
, or "mixed"
Methods
clearTouchCalibration
chrome.system.display.clearTouchCalibration(id: string)
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
- idstring
The display's unique identifier.
completeCustomTouchCalibration
chrome.system.display.completeCustomTouchCalibration(pairs: TouchCalibrationPairQuad, bounds: Bounds)
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
The pairs of point used to calibrate the display.
- bounds
Bounds of the display when the touch calibration was performed. |bounds.left| and |bounds.top| values are ignored.
enableUnifiedDesktop
chrome.system.display.enableUnifiedDesktop(enabled: boolean)
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
- enabledboolean
True if unified desktop should be enabled.
getDisplayLayout
chrome.system.display.getDisplayLayout(callback: function)
Requests the layout info for all displays. NOTE: This is only available to Chrome OS Kiosk apps and Web UI.
Parameters
- callbackfunction
The callback to invoke with the results.
The callback parameter should be a function that looks like this:
(layouts: DisplayLayout[]) => {...}
- layouts
getInfo
chrome.system.display.getInfo(flags?: GetInfoFlags, callback: function)
Requests the information for all attached display devices.
Parameters
- flagsGetInfoFlags optional
Options affecting how the information is returned.
- callbackfunction
The callback to invoke with the results.
The callback parameter should be a function that looks like this:
(displayInfo: DisplayUnitInfo[]) => {...}
- displayInfo
overscanCalibrationAdjust
chrome.system.display.overscanCalibrationAdjust(id: string, delta: Insets)
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
- idstring
The display's unique identifier.
- delta
The amount to change the overscan insets.
overscanCalibrationComplete
chrome.system.display.overscanCalibrationComplete(id: string)
Complete overscan adjustments for a display by saving the current values and hiding the overlay.
Parameters
- idstring
The display's unique identifier.
overscanCalibrationReset
chrome.system.display.overscanCalibrationReset(id: string)
Resets the overscan insets for a display to the last saved value (i.e before Start was called).
Parameters
- idstring
The display's unique identifier.
overscanCalibrationStart
chrome.system.display.overscanCalibrationStart(id: string)
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
- idstring
The display's unique identifier.
setDisplayLayout
chrome.system.display.setDisplayLayout(layouts: DisplayLayout[], callback: function)
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
- layouts
The layout information, required for all displays except the primary display.
- callbackfunction
Empty function called when the function finishes. To find out whether the function succeeded,
runtime.lastError
should be queried.The callback parameter should be a function that looks like this:
() => {...}
setDisplayProperties
chrome.system.display.setDisplayProperties(id: string, info: DisplayProperties, callback: function)
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
- idstring
The display's unique identifier.
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|.
- callbackfunction
Empty function called when the function finishes. To find out whether the function succeeded,
runtime.lastError
should be queried.The callback parameter should be a function that looks like this:
() => {...}
setMirrorMode
chrome.system.display.setMirrorMode(info: MirrorModeInfo, callback: function)
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
- info
The information of the mirror mode that should be applied to the display mode.
- callbackfunction
Empty function called when the function finishes. To find out whether the function succeeded,
runtime.lastError
should be queried.The callback parameter should be a function that looks like this:
() => {...}
showNativeTouchCalibration
chrome.system.display.showNativeTouchCalibration(id: string, callback: function)
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
- idstring
The display's unique identifier.
- callbackfunction
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.
The callback parameter should be a function that looks like this:
(success: boolean) => {...}
- successboolean
startCustomTouchCalibration
chrome.system.display.startCustomTouchCalibration(id: string)
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
- idstring
The display's unique identifier.
Events
onDisplayChanged
chrome.system.display.onDisplayChanged.addListener(listener: function)
Fired when anything changes to the display configuration.
Event
- listenerfunction
The listener parameter should be a function that looks like this:
() => {...}