Add Get/SetDisplayLayout to chrome.system.display extension API

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;
@@ skipping 41 matching lines @@
     // 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).
@@ skipping 73 matching lines @@
 
     // 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();
 
   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.
+    static void setDisplayLayout(DisplayLayout[] layouts);

[asargent_no_longer_on_chrome, 2016/06/16 19:08:30]

optional: you might consider adding a callback which reports back whether the
layouts passed were used successfully or had to be adjusted. Callers can likely
figure that out themselves by listening for the onDisplayChanged, but doing so
might be a bit more cumbersome than if you just told them directly.

[stevenjb, 2016/06/17 01:34:59]

I don't want to add too much complexity to the API in anticipation of usage that
will probably never exist, but this should at least call a void callback when
done so that the error state can be queried, same as with setDisplayProperties.
Done.

+
     // 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.
@@ skipping 17 matching lines @@
     // 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();
   };
 };