1// Copyright 2013 The Chromium Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style license that can be
3// found in the LICENSE file.
4
5// Use the <code>system.display</code> API to query display metadata.
6namespace system.display {
7
8  dictionary Bounds {
9    // The x-coordinate of the upper-left corner.
10    long left;
11
12    // The y-coordinate of the upper-left corner.
13    long top;
14
15    // The width of the display in pixels.
16    long width;
17
18    // The height of the display in pixels.
19    long height;
20  };
21
22  dictionary Insets {
23    // The x-axis distance from the left bound.
24    long left;
25
26    // The y-axis distance from the top bound.
27    long top;
28
29    // The x-axis distance from the right bound.
30    long right;
31
32    // The y-axis distance from the bottom bound.
33    long bottom;
34  };
35
36  dictionary DisplayUnitInfo {
37    // The unique identifier of the display.
38    DOMString id;
39
40    // The user-friendly name (e.g. "HP LCD monitor").
41    DOMString name;
42
43    // Identifier of the display that is being mirrored on the display unit.
44    // If mirroring is not in progress, set to an empty string.
45    // Currently exposed only on ChromeOS. Will be empty string on other
46    // platforms.
47    DOMString mirroringSourceId;
48
49    // True if this is the primary display.
50    boolean isPrimary;
51
52    // True if this is an internal display.
53    boolean isInternal;
54
55    // True if this display is enabled.
56    boolean isEnabled;
57
58    // The number of pixels per inch along the x-axis.
59    double dpiX;
60
61    // The number of pixels per inch along the y-axis.
62    double dpiY;
63
64    // The display's clockwise rotation in degrees relative to the vertical
65    // position.
66    // Currently exposed only on ChromeOS. Will be set to 0 on other platforms.
67    long rotation;
68
69    // The display's logical bounds.
70    Bounds bounds;
71
72    // The display's insets within its screen's bounds.
73    // Currently exposed only on ChromeOS. Will be set to empty insets on
74    // other platforms.
75    Insets overscan;
76
77    // The usable work area of the display within the display bounds. The work
78    // area excludes areas of the display reserved for OS, for example taskbar
79    // and launcher.
80    Bounds workArea;
81  };
82
83  dictionary DisplayProperties {
84    // If set and not empty, starts mirroring between this and the display with
85    // the provided id (the system will determine which of the displays is
86    // actually mirrored).
87    // If set and not empty, stops mirroring between this and the display with
88    // the specified id (if mirroring is in progress).
89    // If set, no other parameter may be set.
90    DOMString? mirroringSourceId;
91
92    // If set to true, makes the display primary. No-op if set to false.
93    boolean? isPrimary;
94
95    // If set, sets the display's overscan insets to the provided values. Note
96    // that overscan values may not be negative or larger than a half of the
97    // screen's size. Overscan cannot be changed on the internal monitor.
98    // It's applied after <code>isPrimary</code> parameter.
99    Insets? overscan;
100
101    // If set, updates the display's rotation.
102    // Legal values are [0, 90, 180, 270]. The rotation is set clockwise,
103    // relative to the display's vertical position.
104    // It's applied after <code>overscan</code> paramter.
105    long? rotation;
106
107    // If set, updates the display's logical bounds origin along x-axis. Applied
108    // together with <code>boundsOriginY</code>, if <code>boundsOriginY</code>
109    // is set. Note that, when updating the display origin, some constraints
110    // will be applied, so the final bounds origin may be different than the one
111    // set. The final bounds can be retrieved using $(ref:getInfo).
112    // The bounds origin is applied after <code>rotation</code>.
113    // The bounds origin cannot be changed on the primary display. Note that is
114    // also invalid to set bounds origin values if <code>isPrimary</code> is
115    // also set (as <code>isPrimary</code> parameter is applied first).
116    long? boundsOriginX;
117
118    // If set, updates the display's logical bounds origin along y-axis.
119    // See documentation for <code>boundsOriginX</code> parameter.
120    long? boundsOriginY;
121  };
122
123  callback DisplayInfoCallback = void (DisplayUnitInfo[] displayInfo);
124  callback SetDisplayUnitInfoCallback = void();
125
126  interface Functions {
127    // Get the information of all attached display devices.
128    static void getInfo(DisplayInfoCallback callback);
129
130    // Updates the properties for the display specified by |id|, according to
131    // the information provided in |info|. On failure, $(ref:runtime.lastError)
132    // will be set.
133    // |id|: The display's unique identifier.
134    // |info|: The information about display properties that should be changed.
135    //     A property will be changed only if a new value for it is specified in
136    //     |info|.
137    // |callback|: Empty function called when the function finishes. To find out
138    //     whether the function succeeded, $(ref:runtime.lastError) should be
139    //     queried.
140    static void setDisplayProperties(
141        DOMString id,
142        DisplayProperties info,
143        optional SetDisplayUnitInfoCallback callback);
144  };
145
146  interface Events {
147    // Fired when anything changes to the display configuration.
148    static void onDisplayChanged();
149  };
150};
151