extensions/common/api/system_display.idl

   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.
   6 namespace 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 };