extensions/common/api/system_display.idl - chromium/src - Git at Google

 // 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 Point {
     // The x-coordinate of the point.
     long x;

     // The y-coordinate of the point.
     long y;
   };

   dictionary TouchCalibrationPair {
     // The coordinates of the display point.
     Point displayPoint;

     // The coordinates of the touch point corresponding to the display point.
     Point touchPoint;
   };

   dictionary TouchCalibrationPairQuad {
     // First pair of touch and display point required for touch calibration.
     TouchCalibrationPair pair1;

     // Second pair of touch and display point required for touch calibration.
     TouchCalibrationPair pair2;

     // Third pair of touch and display point required for touch calibration.
     TouchCalibrationPair pair3;

     // Fourth pair of touch and display point required for touch calibration.
     TouchCalibrationPair pair4;
   };

   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;

     // True if this display has a touch input device associated with it.
     boolean hasTouchSupport;
   };

   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();
   callback NativeTouchCalibrationCallback = void(boolean success);

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

     // Displays the native touch calibration UX for the display with |id| as
     // display id. This will show an overlay on the screen with required
     // instructions on how to proceed. The callback will be invoked in case of
     // successful calibraion only. If the calibration fails, this will throw an
     // error.
     // |id|: The display's unique identifier.
     // |callback|: Optional callback to inform the caller that the touch
     //      calibration has ended. The argument of the callback informs if the
     //      calibration was a success or not.
     static void showNativeTouchCalibration(
         DOMString id, optional NativeTouchCalibrationCallback callback);

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

     // Sets the touch calibration pairs for a display. These |pairs| would be
     // 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 completeCustomTouchCalibration(TouchCalibrationPairQuad pairs,
                                                Bounds bounds);

     // Resets the touch calibration for the display and brings it back to its
     // default state by clearing any touch calibration data associated with the
     // 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();
   };
 };
	// 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 Point {
	// The x-coordinate of the point.
	long x;

	// The y-coordinate of the point.
	long y;
	};

	dictionary TouchCalibrationPair {
	// The coordinates of the display point.
	Point displayPoint;

	// The coordinates of the touch point corresponding to the display point.
	Point touchPoint;
	};

	dictionary TouchCalibrationPairQuad {
	// First pair of touch and display point required for touch calibration.
	TouchCalibrationPair pair1;

	// Second pair of touch and display point required for touch calibration.
	TouchCalibrationPair pair2;

	// Third pair of touch and display point required for touch calibration.
	TouchCalibrationPair pair3;

	// Fourth pair of touch and display point required for touch calibration.
	TouchCalibrationPair pair4;
	};

	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;

	// True if this display has a touch input device associated with it.
	boolean hasTouchSupport;
	};

	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();
	callback NativeTouchCalibrationCallback = void(boolean success);

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

	// Displays the native touch calibration UX for the display with \|id\| as
	// display id. This will show an overlay on the screen with required
	// instructions on how to proceed. The callback will be invoked in case of
	// successful calibraion only. If the calibration fails, this will throw an
	// error.
	// \|id\|: The display's unique identifier.
	// \|callback\|: Optional callback to inform the caller that the touch
	// calibration has ended. The argument of the callback informs if the
	// calibration was a success or not.
	static void showNativeTouchCalibration(
	DOMString id, optional NativeTouchCalibrationCallback callback);

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

	// Sets the touch calibration pairs for a display. These \|pairs\| would be
	// 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 completeCustomTouchCalibration(TouchCalibrationPairQuad pairs,
	Bounds bounds);

	// Resets the touch calibration for the display and brings it back to its
	// default state by clearing any touch calibration data associated with the
	// 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();
	};
	};