Updates touch calibration API and plumbs through the native touch calibration method

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 258 matching lines @@
     // 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);
 
-    // Starts touch calibration for a display. This will show an overlay on the
-    // screen and initialize the UX for touch calibration. If touch calibration
-    // for display |id| is already in progress this will throw an error.
+    // Starts native touch calibration for a display. This will show an overlay
+    // on the screen and initialize the UX for touch calibration. If another
+    // native touch calibration is already in progress this will throw an error.
     // |id|: The display's unique identifier.
-    static void touchCalibrationStart(DOMString id);
+    static void startNativeTouchCalibration(DOMString id);

[stevenjb, 2017/01/18 21:58:05]

If startNativeTouchCalibration doesn't require a complete() call, we should name
this something like showNativeTouchCalibration() and clarify the comment.

It would also be helpful to provide a completion callback when the native UI is
dismissed, is that possible?

[malaykeshav, 2017/01/19 01:30:51]

Renamed to showNativeTouchCalibration() and added a callback when the native UI
is dismissed.

+
+    // Starts custom touch calibration for a display. This should be called when
+    // using a custom UX for collecting calibration data. If another touch
+    // calibration is already in progress this will throw an error.
+    // |id|: The display's unique identifier.
+    static void startCustomTouchCalibration(DOMString id);

[stevenjb, 2017/01/18 21:01:35]

I find having multiple 'start' methods confusing. It is unclear what happens if
both are called.

Also, what is the expected flow with startNativeTouchCalibration? There is no
equivalent 'complete'. What triggers removal of the overlay?

Does it make sense to make 'native/custom' a parameter to startTouchCalibarion?

[malaykeshav, 2017/01/19 01:30:51]

Acknowledged.

 
     // Sets the touch calibration pairs for a display. These |pairs| would be
-    // used to calibrate the touch screen for display |id|. If touch calibration
-    // for display |id| is in progress this will do nothing.
-    // |id|: The display's unique identifier.
+    // used to calibrate the touch screen for display with |id| called in
+    // startCustomTouchCalibration(). Always call |startCustomTouchCalibration|
+    // before calling this method. If another touch calibration is already in
+    // progress this will throw an error.
     // |pairs|: The pairs of point used to calibrate the display.
     // |bounds|: Bounds of the display when the touch calibration was performed.
     //     |bounds.left| and |bounds.top| values are ignored.
-    static void touchCalibrationSet(DOMString id,
-                                    TouchCalibrationPairQuad pairs,
-                                    Bounds bounds);
+    static void completeCustomTouchCalibration(TouchCalibrationPairQuad pairs,
+                                               Bounds bounds);
 
     // Resets the touch calibration for the display and removes the saved
     // calibration data.
     // |id|: The display's unique identifier.
-    static void touchCalibrationReset(DOMString id);
+    static void resetTouchCalibration(DOMString id);

[stevenjb, 2017/01/18 21:58:05]

resetCustomTouchCalibration?

[malaykeshav, 2017/01/19 01:30:51]

This resets any stored touch calibration data and has nothing to do with the UX.

[stevenjb, 2017/01/19 17:19:01]

Hmm. Unfortunately this is different behavior from overscanCalibrationReset,
which resets to the last saved value during calibration. That one should
probably be named 'cancel', but changing that is risky.

Maybe name this 'clearTouchCalibration' since it is removing all saved
calibration data?

[malaykeshav, 2017/01/19 23:49:06]

Done

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