// 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 DisplayMode {
    // The display mode width in device independent (user visible) pixels.
    long width;

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

    // The display mode width in native pixels.
    long widthInNativePixels;

    // The display mode height in native pixels.
    long heightInNativePixels;

    // The display mode UI scale factor.
    double uiScale;

    // The display mode device scale factor.
    double deviceScaleFactor;

    // True if the mode is the display's native mode.
    boolean isNative;

    // True if the display mode is currently selected.
    boolean isSelected;
  };

  // Layout position, i.e. edge of parent that the display is attached to.
  enum LayoutPosition { top, right, bottom, left };

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

    // The unique identifier of the parent display. Empty if this is the root.
    DOMString parentId;

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

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

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

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

    // 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).
    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;

    // 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.
    DisplayMode[] modes;
  };

  dictionary DisplayProperties {
    // Chrome OS only. If set and not empty, enables mirroring for this display.
    // Otherwise disables mirroring for this display. 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.
    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;

    // If set, updates the display mode to the mode matching this value.
    DisplayMode? displayMode;
  };

  callback DisplayInfoCallback = void (DisplayUnitInfo[] displayInfo);
  callback DisplayLayoutCallback = void (DisplayLayout[] layouts);
  callback SetDisplayUnitInfoCallback = void();
  callback SetDisplayLayoutCallback = void();

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

    // Get the layout info for all displays.
    // NOTE: This is only available to Chrome OS Kiosk apps and Web UI.
    static void getDisplayLayout(DisplayLayoutCallback 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.
    // NOTE: This is only available to Chrome OS Kiosk apps and Web UI.
    // |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);

    // 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.
    // |layouts|: The layout information, required for all displays except
    //     the primary display.
    // |callback|: Empty function called when the function finishes. To find out
    //     whether the function succeeded, $(ref:runtime.lastError) should be
    //     queried.
    static void setDisplayLayout(DisplayLayout[] layouts,
                                 optional SetDisplayLayoutCallback callback);

    // Enables/disables the unified desktop feature. Note that this simply
    // enables the feature, but will not change the actual desktop mode.
    // (That is, if the desktop is in mirror mode, it will stay in mirror mode)
    // NOTE: This is only available to Chrome OS Kiosk apps and Web UI.
    // |enabled|: True if unified desktop should be enabled.
    static void enableUnifiedDesktop(boolean enabled);

    // 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.
    // |id|: The display's unique identifier.
    static void overscanCalibrationStart(DOMString id);

    // Adjusts the current overscan insets for a display. Typically this should
    // etiher 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.
    // |id|: The display's unique identifier.
    // |delta|: The amount to change the overscan insets.
    static void overscanCalibrationAdjust(DOMString id, Insets delta);

    // Resets the overscan insets for a display to the last saved value (i.e
    // before Start was called).
    // |id|: The display's unique identifier.
    static void overscanCalibrationReset(DOMString id);

    // Complete overscan adjustments for a display  by saving the current values
    // and hiding the overlay.
    // |id|: The display's unique identifier.
    static void overscanCalibrationComplete(DOMString id);
  };

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