MD Settings: Display: Add unified desktop control and modify 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 111 matching lines @@
 
     // 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;
 
+    // True for all displays when in unified desktop mode. See documentation
+    // for $(ref:enableUnifiedDesktop).
+    boolean isUnified;
+
     // 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;
@@ skipping 14 matching lines @@
     // 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;
 
     // True if this display has a touch input device associated with it.
     boolean hasTouchSupport;
   };
 
   dictionary DisplayProperties {
+    // Chrome OS only. If set to true, changes the display mode to unifed
+    // desktop (see $(ref:enableUnifiedDesktop) for details). This is only valid
+    // for the primary display. If set, mirroringSourceId must not be set and
+    // other properties may not apply.

[Devlin, 2017/04/11 18:54:08]

Comment what the default is.

[stevenjb, 2017/04/11 19:34:47]

Done.

+    boolean? isUnified;
+
     // 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
@@ skipping 20 matching lines @@
     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;
   };
 
+  dictionary GetInfoFlags {
+    // If set to true, only a single $(ref:DisplayUnitInfo) will be returned
+    // by $(ref:getInfo) when in unified desktop mode (see
+    // $(ref:enableUnifiedDesktop)).

[Devlin, 2017/04/11 18:54:08]

Comment also what the default is.

[stevenjb, 2017/04/11 19:34:47]

Done.

+    boolean? singleUnified;

[Devlin, 2017/04/11 18:54:08]

singleUnified seems redundant to me - maybe singleDisplay or unifiedDisplay?

[stevenjb, 2017/04/11 19:34:47]

single = one result, unified = when in unified desktop mode.
'singleDisplay' is incorrect because multiple displays will be returned if not
in unified desktop mode.
'unifiedDisplay' is also misleading because we may not be in unified desktop
mode.

I don't think there is a good clear property name here. This is a restricted API
that only devs familiar with the concepts should be using.

+  };
+
   callback DisplayInfoCallback = void (DisplayUnitInfo[] displayInfo);
   callback DisplayLayoutCallback = void (DisplayLayout[] layouts);
   callback SetDisplayUnitInfoCallback = void();
   callback SetDisplayLayoutCallback = void();
   callback NativeTouchCalibrationCallback = void(boolean success);
 
   interface Functions {
-    // Get the information of all attached display devices.
-    static void getInfo(DisplayInfoCallback callback);
+    // Requests the information for all attached display devices.
+    // |flags|: See $(ref:GetInfoFlags).

[Devlin, 2017/04/11 18:54:08]

similar to the others, |flags| will already have a type that indicates what it
is.  Instead, say something like "The options used to determine which
information to return".

[stevenjb, 2017/04/11 19:34:47]

Done.

+    // |callback|: This will be invoked with an array of $(ref:DisplayUnitInfo).

[Devlin, 2017/04/11 18:54:08]

same as 238 (sorry, wrote these backwards)

[stevenjb, 2017/04/11 19:34:47]

Done.

+    static void getInfo(optional GetInfoFlags flags,
+                        DisplayInfoCallback callback);
 
-    // Get the layout info for all displays.
+    // Requests the layout info for all displays.
     // NOTE: This is only available to Chrome OS Kiosk apps and Web UI.
+    // |callback|: This will be invoked with an array of $(ref:DisplayLayout).

[Devlin, 2017/04/11 18:54:08]

The docs already say this by virtue of what the callback looks like.  Just say
something like "the callback to invoke with the results."

[stevenjb, 2017/04/11 19:34:47]

Done.

     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|.
@@ skipping 83 matching lines @@
     // display.
     // |id|: The display's unique identifier.
     static void clearTouchCalibration(DOMString id);
   };
 
   interface Events {
     // Fired when anything changes to the display configuration.
     static void onDisplayChanged();
   };
 };