extensions/common/api/system_display.idl

// Copyright 2013 The Chromium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

// Use the <code>system.display</code> API to query display metadata.
namespace system.display {

  dictionary Bounds {
    // The x-coordinate of the upper-left corner.
    long left;

    // The y-coordinate of the upper-left corner.
    long top;

    // The width of the display in pixels.
    long width;

    // The height of the display in pixels.
    long height;
  };

  dictionary Insets {
    // The x-axis distance from the left bound.
    long left;

    // The y-axis distance from the top bound.
    long top;

    // The x-axis distance from the right bound.
    long right;

    // The y-axis distance from the bottom bound.
    long bottom;
  };

  dictionary DisplayUnitInfo {
    // The unique identifier of the display.
    DOMString id;

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

    // Identifier of the display that is being mirrored on the display unit.
    // If mirroring is not in progress, set to an empty string.
    // Currently exposed only on ChromeOS. Will be empty string on other
    // platforms.
    DOMString mirroringSourceId;

    // True if this is the primary display.
    boolean isPrimary;

    // True if this is an internal display.
    boolean isInternal;

    // True if this display is enabled.
    boolean isEnabled;

    // The number of pixels per inch along the x-axis.
    double dpiX;

    // The number of pixels per inch along the y-axis.
    double dpiY;

    // 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.
    long rotation;

    // The display's logical bounds.
    Bounds bounds;

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

    // 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.
    Bounds workArea;
  };

  dictionary DisplayProperties {
    // If set and not empty, starts mirroring between this and the display with
    // the provided id (the system will determine which of the displays is
    // actually mirrored).
    // If set and not empty, stops mirroring between this and the display with
    // the specified id (if mirroring is in progress).
    // If set, no other parameter may be set.
    DOMString? mirroringSourceId;

    // If set to true, makes the display primary. No-op if set to false.
    boolean? isPrimary;

    // 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.
    // It's applied after <code>isPrimary</code> parameter.
    Insets? overscan;

    // 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.
    // It's applied after <code>overscan</code> paramter.
    long? rotation;

    // If set, updates the display's logical bounds origin along x-axis. Applied
    // together with <code>boundsOriginY</code>, if <code>boundsOriginY</code>
    // 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 $(ref:getInfo).
    // The bounds origin is applied after <code>rotation</code>.
    // The bounds origin cannot be changed on the primary display. Note that is
    // also invalid to set bounds origin values if <code>isPrimary</code> is
    // also set (as <code>isPrimary</code> parameter is applied first).
    long? boundsOriginX;

    // If set, updates the display's logical bounds origin along y-axis.
    // See documentation for <code>boundsOriginX</code> parameter.
    long? boundsOriginY;
  };

  callback DisplayInfoCallback = void (DisplayUnitInfo[] displayInfo);
  callback SetDisplayUnitInfoCallback = void();

  interface Functions {
    // Get the information of all attached display devices.
    static void getInfo(DisplayInfoCallback callback);

    // Updates the properties for the display specified by |id|, according to
    // the information provided in |info|. On failure, $(ref:runtime.lastError)
    // will be set.
    // |id|: The display's unique identifier.
    // |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|.
    // |callback|: Empty function called when the function finishes. To find out
    //     whether the function succeeded, $(ref:runtime.lastError) should be
    //     queried.
    static void setDisplayProperties(
        DOMString id,
        DisplayProperties info,
        optional SetDisplayUnitInfoCallback callback);
  };

  interface Events {
    // Fired when anything changes to the display configuration.
    static void onDisplayChanged();
  };
};