Improve documentation related to views screen coordinates (see issue #2980)

include/capi/views/cef_display_capi.h

@@ -33,7 +33,7 @@
 // by hand. See the translator.README.txt file in the tools directory for
 // more information.
 //
-// $hash=422243fda6e1404222aca7bdd4e7b84b961a9626$
+// $hash=652ac7a90c6cd10b1cbc6ae99a549c03f36c794e$
 //
 
 #ifndef CEF_INCLUDE_CAPI_VIEWS_CEF_DISPLAY_CAPI_H_
@@ -50,9 +50,9 @@ extern "C" {
 // This structure typically, but not always, corresponds to a physical display
 // connected to the system. A fake Display may exist on a headless system, or a
 // Display may correspond to a remote, virtual display. All size and position
-// values are in density independent pixels (DIP) unless otherwise indicated.
+// values are in density independent pixel (DIP) coordinates unless otherwise
-// Methods must be called on the browser process UI thread unless otherwise
+// indicated. Methods must be called on the browser process UI thread unless
-// indicated.
+// otherwise indicated.
 ///
 typedef struct _cef_display_t {
   ///
@@ -74,27 +74,28 @@ typedef struct _cef_display_t {
   float(CEF_CALLBACK* get_device_scale_factor)(struct _cef_display_t* self);
 
   ///
-  // Convert |point| from density independent pixels (DIP) to pixel coordinates
+  // Convert |point| from DIP coordinates to pixel coordinates using this
-  // using this Display's device scale factor.
+  // Display's device scale factor.
   ///
   void(CEF_CALLBACK* convert_point_to_pixels)(struct _cef_display_t* self,
                                               cef_point_t* point);
 
   ///
-  // Convert |point| from pixel coordinates to density independent pixels (DIP)
+  // Convert |point| from pixel coordinates to DIP coordinates using this
-  // using this Display's device scale factor.
+  // Display's device scale factor.
   ///
   void(CEF_CALLBACK* convert_point_from_pixels)(struct _cef_display_t* self,
                                                 cef_point_t* point);
 
   ///
-  // Returns this Display's bounds. This is the full size of the display.
+  // Returns this Display's bounds in DIP screen coordinates. This is the full
+  // size of the display.
   ///
   cef_rect_t(CEF_CALLBACK* get_bounds)(struct _cef_display_t* self);
 
   ///
-  // Returns this Display's work area. This excludes areas of the display that
+  // Returns this Display's work area in DIP screen coordinates. This excludes
-  // are occupied for window manager toolbars, etc.
+  // areas of the display that are occupied with window manager toolbars, etc.
   ///
   cef_rect_t(CEF_CALLBACK* get_work_area)(struct _cef_display_t* self);
 
@@ -111,7 +112,7 @@ CEF_EXPORT cef_display_t* cef_display_get_primary();
 
 ///
 // Returns the Display nearest |point|. Set |input_pixel_coords| to true (1) if
-// |point| is in pixel coordinates instead of density independent pixels (DIP).
+// |point| is in pixel screen coordinates instead of DIP screen coordinates.
 ///
 CEF_EXPORT cef_display_t* cef_display_get_nearest_point(
     const cef_point_t* point,
@@ -119,8 +120,8 @@ CEF_EXPORT cef_display_t* cef_display_get_nearest_point(
 
 ///
 // Returns the Display that most closely intersects |bounds|.  Set
-// |input_pixel_coords| to true (1) if |bounds| is in pixel coordinates instead
+// |input_pixel_coords| to true (1) if |bounds| is in pixel screen coordinates
-// of density independent pixels (DIP).
+// instead of DIP screen coordinates.
 ///
 CEF_EXPORT cef_display_t* cef_display_get_matching_bounds(
     const cef_rect_t* bounds,

include/capi/views/cef_view_capi.h

@@ -33,7 +33,7 @@
 // by hand. See the translator.README.txt file in the tools directory for
 // more information.
 //
-// $hash=45b421dfcf8ee7cf61b1991a336bc65d33fbe10a$
+// $hash=55be3e44016d9861bb8e9270b52f2bf45c8a53f5$
 //
 
 #ifndef CEF_INCLUDE_CAPI_VIEWS_CEF_VIEW_CAPI_H_
@@ -176,64 +176,72 @@ typedef struct _cef_view_t {
                                                      int id);
 
   ///
-  // Sets the bounds (size and position) of this View. Position is in parent
+  // Sets the bounds (size and position) of this View. |bounds| is in parent
-  // coordinates.
+  // coordinates, or DIP screen coordinates if there is no parent.
   ///
   void(CEF_CALLBACK* set_bounds)(struct _cef_view_t* self,
                                  const cef_rect_t* bounds);
 
   ///
-  // Returns the bounds (size and position) of this View. Position is in parent
+  // Returns the bounds (size and position) of this View in parent coordinates,
-  // coordinates.
+  // or DIP screen coordinates if there is no parent.
   ///
   cef_rect_t(CEF_CALLBACK* get_bounds)(struct _cef_view_t* self);
 
   ///
-  // Returns the bounds (size and position) of this View. Position is in screen
+  // Returns the bounds (size and position) of this View in DIP screen
   // coordinates.
   ///
   cef_rect_t(CEF_CALLBACK* get_bounds_in_screen)(struct _cef_view_t* self);
 
   ///
-  // Sets the size of this View without changing the position.
+  // Sets the size of this View without changing the position. |size| in parent
+  // coordinates, or DIP screen coordinates if there is no parent.
   ///
   void(CEF_CALLBACK* set_size)(struct _cef_view_t* self,
                                const cef_size_t* size);
 
   ///
-  // Returns the size of this View.
+  // Returns the size of this View in parent coordinates, or DIP screen
+  // coordinates if there is no parent.
   ///
   cef_size_t(CEF_CALLBACK* get_size)(struct _cef_view_t* self);
 
   ///
   // Sets the position of this View without changing the size. |position| is in
-  // parent coordinates.
+  // parent coordinates, or DIP screen coordinates if there is no parent.
   ///
   void(CEF_CALLBACK* set_position)(struct _cef_view_t* self,
                                    const cef_point_t* position);
 
   ///
-  // Returns the position of this View. Position is in parent coordinates.
+  // Returns the position of this View. Position is in parent coordinates, or
+  // DIP screen coordinates if there is no parent.
   ///
   cef_point_t(CEF_CALLBACK* get_position)(struct _cef_view_t* self);
 
   ///
   // Returns the size this View would like to be if enough space is available.
+  // Size is in parent coordinates, or DIP screen coordinates if there is no
+  // parent.
   ///
   cef_size_t(CEF_CALLBACK* get_preferred_size)(struct _cef_view_t* self);
 
   ///
-  // Size this View to its preferred size.
+  // Size this View to its preferred size. Size is in parent coordinates, or DIP
+  // screen coordinates if there is no parent.
   ///
   void(CEF_CALLBACK* size_to_preferred_size)(struct _cef_view_t* self);
 
   ///
-  // Returns the minimum size for this View.
+  // Returns the minimum size for this View. Size is in parent coordinates, or
+  // DIP screen coordinates if there is no parent.
   ///
   cef_size_t(CEF_CALLBACK* get_minimum_size)(struct _cef_view_t* self);
 
   ///
-  // Returns the maximum size for this View.
+  // Returns the maximum size for this View. Size is in parent coordinates, or
+  // DIP screen coordinates if there is no parent.
   ///
   cef_size_t(CEF_CALLBACK* get_maximum_size)(struct _cef_view_t* self);
 
@@ -327,21 +335,21 @@ typedef struct _cef_view_t {
   cef_color_t(CEF_CALLBACK* get_background_color)(struct _cef_view_t* self);
 
   ///
-  // Convert |point| from this View's coordinate system to that of the screen.
+  // Convert |point| from this View's coordinate system to DIP screen
-  // This View must belong to a Window when calling this function. Returns true
+  // coordinates. This View must belong to a Window when calling this function.
-  // (1) if the conversion is successful or false (0) otherwise. Use
+  // Returns true (1) if the conversion is successful or false (0) otherwise.
-  // cef_display_t::convert_point_to_pixels() after calling this function if
+  // Use cef_display_t::convert_point_to_pixels() after calling this function if
   // further conversion to display-specific pixel coordinates is desired.
   ///
   int(CEF_CALLBACK* convert_point_to_screen)(struct _cef_view_t* self,
                                              cef_point_t* point);
 
   ///
-  // Convert |point| to this View's coordinate system from that of the screen.
+  // Convert |point| to this View's coordinate system from DIP screen
-  // This View must belong to a Window when calling this function. Returns true
+  // coordinates. This View must belong to a Window when calling this function.
-  // (1) if the conversion is successful or false (0) otherwise. Use
+  // Returns true (1) if the conversion is successful or false (0) otherwise.
-  // cef_display_t::convert_point_from_pixels() before calling this function if
+  // Use cef_display_t::convert_point_from_pixels() before calling this function
-  // conversion from display-specific pixel coordinates is necessary.
+  // if conversion from display-specific pixel coordinates is necessary.
   ///
   int(CEF_CALLBACK* convert_point_from_screen)(struct _cef_view_t* self,
                                                cef_point_t* point);

include/capi/views/cef_window_delegate_capi.h

@@ -33,7 +33,7 @@
 // by hand. See the translator.README.txt file in the tools directory for
 // more information.
 //
-// $hash=734a13cd5ad9b0af1b29e1e91b406dd5e6740dc4$
+// $hash=fee25d300df47c6143b935d0f99d543ea888f55c$
 //
 
 #ifndef CEF_INCLUDE_CAPI_VIEWS_CEF_WINDOW_DELEGATE_CAPI_H_
@@ -88,10 +88,12 @@ typedef struct _cef_window_delegate_t {
       int* can_activate_menu);
 
   ///
-  // Return the initial bounds for |window| in screen coordinates. If this
+  // Return the initial bounds for |window| in density independent pixel (DIP)
-  // function returns an NULL CefRect then get_preferred_size() will be called
+  // coordinates. If this function returns an NULL CefRect then
-  // to retrieve the size, and the window will be placed on the default screen
+  // get_preferred_size() will be called to retrieve the size, and the window
-  // with origin (0,0).
+  // will be placed on the screen with origin (0,0). This function can be used
+  // in combination with cef_view_t::get_bounds_in_screen() to restore the
+  // previous window bounds.
   ///
   cef_rect_t(CEF_CALLBACK* get_initial_bounds)(
       struct _cef_window_delegate_t* self,

include/views/cef_display.h

@@ -46,9 +46,9 @@
 // This class typically, but not always, corresponds to a physical display
 // connected to the system. A fake Display may exist on a headless system, or a
 // Display may correspond to a remote, virtual display. All size and position
-// values are in density independent pixels (DIP) unless otherwise indicated.
+// values are in density independent pixel (DIP) coordinates unless otherwise
-// Methods must be called on the browser process UI thread unless otherwise
+// indicated. Methods must be called on the browser process UI thread unless
-// indicated.
+// otherwise indicated.
 ///
 /*--cef(source=library)--*/
 class CefDisplay : public CefBaseRefCounted {
@@ -61,8 +61,7 @@ class CefDisplay : public CefBaseRefCounted {
 
   ///
   // Returns the Display nearest |point|. Set |input_pixel_coords| to true if
-  // |point| is in pixel coordinates instead of density independent pixels
+  // |point| is in pixel screen coordinates instead of DIP screen coordinates.
-  // (DIP).
   ///
   /*--cef()--*/
   static CefRefPtr<CefDisplay> GetDisplayNearestPoint(const CefPoint& point,
@@ -70,8 +69,8 @@ class CefDisplay : public CefBaseRefCounted {
 
   ///
   // Returns the Display that most closely intersects |bounds|.  Set
-  // |input_pixel_coords| to true if |bounds| is in pixel coordinates instead of
+  // |input_pixel_coords| to true if |bounds| is in pixel screen coordinates
-  // density independent pixels (DIP).
+  // instead of DIP screen coordinates.
   ///
   /*--cef()--*/
   static CefRefPtr<CefDisplay> GetDisplayMatchingBounds(
@@ -108,28 +107,29 @@ class CefDisplay : public CefBaseRefCounted {
   virtual float GetDeviceScaleFactor() = 0;
 
   ///
-  // Convert |point| from density independent pixels (DIP) to pixel coordinates
+  // Convert |point| from DIP coordinates to pixel coordinates using this
-  // using this Display's device scale factor.
+  // Display's device scale factor.
   ///
   /*--cef()--*/
   virtual void ConvertPointToPixels(CefPoint& point) = 0;
 
   ///
-  // Convert |point| from pixel coordinates to density independent pixels (DIP)
+  // Convert |point| from pixel coordinates to DIP coordinates using this
-  // using this Display's device scale factor.
+  // Display's device scale factor.
   ///
   /*--cef()--*/
   virtual void ConvertPointFromPixels(CefPoint& point) = 0;
 
   ///
-  // Returns this Display's bounds. This is the full size of the display.
+  // Returns this Display's bounds in DIP screen coordinates. This is the full
+  // size of the display.
   ///
   /*--cef()--*/
   virtual CefRect GetBounds() = 0;
 
   ///
-  // Returns this Display's work area. This excludes areas of the display that
+  // Returns this Display's work area in DIP screen coordinates. This excludes
-  // are occupied for window manager toolbars, etc.
+  // areas of the display that are occupied with window manager toolbars, etc.
   ///
   /*--cef()--*/
   virtual CefRect GetWorkArea() = 0;

include/views/cef_view.h

@@ -174,71 +174,79 @@ class CefView : public CefBaseRefCounted {
   virtual CefRefPtr<CefView> GetViewForID(int id) = 0;
 
   ///
-  // Sets the bounds (size and position) of this View. Position is in parent
+  // Sets the bounds (size and position) of this View. |bounds| is in parent
-  // coordinates.
+  // coordinates, or DIP screen coordinates if there is no parent.
   ///
   /*--cef()--*/
   virtual void SetBounds(const CefRect& bounds) = 0;
 
   ///
-  // Returns the bounds (size and position) of this View. Position is in parent
+  // Returns the bounds (size and position) of this View in parent coordinates,
-  // coordinates.
+  // or DIP screen coordinates if there is no parent.
   ///
   /*--cef()--*/
   virtual CefRect GetBounds() = 0;
 
   ///
-  // Returns the bounds (size and position) of this View. Position is in screen
+  // Returns the bounds (size and position) of this View in DIP screen
   // coordinates.
   ///
   /*--cef()--*/
   virtual CefRect GetBoundsInScreen() = 0;
 
   ///
-  // Sets the size of this View without changing the position.
+  // Sets the size of this View without changing the position. |size| in
+  // parent coordinates, or DIP screen coordinates if there is no parent.
   ///
   /*--cef()--*/
   virtual void SetSize(const CefSize& size) = 0;
 
   ///
-  // Returns the size of this View.
+  // Returns the size of this View in parent coordinates, or DIP screen
+  // coordinates if there is no parent.
   ///
   /*--cef()--*/
   virtual CefSize GetSize() = 0;
 
   ///
   // Sets the position of this View without changing the size. |position| is in
-  // parent coordinates.
+  // parent coordinates, or DIP screen coordinates if there is no parent.
   ///
   /*--cef()--*/
   virtual void SetPosition(const CefPoint& position) = 0;
 
   ///
-  // Returns the position of this View. Position is in parent coordinates.
+  // Returns the position of this View. Position is in parent coordinates, or
+  // DIP screen coordinates if there is no parent.
   ///
   /*--cef()--*/
   virtual CefPoint GetPosition() = 0;
 
   ///
   // Returns the size this View would like to be if enough space is available.
+  // Size is in parent coordinates, or DIP screen coordinates if there is no
+  // parent.
   ///
   /*--cef()--*/
   virtual CefSize GetPreferredSize() = 0;
 
   ///
-  // Size this View to its preferred size.
+  // Size this View to its preferred size. Size is in parent coordinates, or
+  // DIP screen coordinates if there is no parent.
   ///
   /*--cef()--*/
   virtual void SizeToPreferredSize() = 0;
 
   ///
-  // Returns the minimum size for this View.
+  // Returns the minimum size for this View. Size is in parent coordinates, or
+  // DIP screen coordinates if there is no parent.
   ///
   /*--cef()--*/
   virtual CefSize GetMinimumSize() = 0;
 
   ///
-  // Returns the maximum size for this View.
+  // Returns the maximum size for this View. Size is in parent coordinates, or
+  // DIP screen coordinates if there is no parent.
   ///
   /*--cef()--*/
   virtual CefSize GetMaximumSize() = 0;
@@ -345,9 +353,9 @@ class CefView : public CefBaseRefCounted {
   virtual cef_color_t GetBackgroundColor() = 0;
 
   ///
-  // Convert |point| from this View's coordinate system to that of the screen.
+  // Convert |point| from this View's coordinate system to DIP screen
-  // This View must belong to a Window when calling this method. Returns true
+  // coordinates. This View must belong to a Window when calling this method.
-  // if the conversion is successful or false otherwise. Use
+  // Returns true if the conversion is successful or false otherwise. Use
   // CefDisplay::ConvertPointToPixels() after calling this method if further
   // conversion to display-specific pixel coordinates is desired.
   ///
@@ -355,9 +363,9 @@ class CefView : public CefBaseRefCounted {
   virtual bool ConvertPointToScreen(CefPoint& point) = 0;
 
   ///
-  // Convert |point| to this View's coordinate system from that of the screen.
+  // Convert |point| to this View's coordinate system from DIP screen
-  // This View must belong to a Window when calling this method. Returns true if
+  // coordinates. This View must belong to a Window when calling this method.
-  // the conversion is successful or false otherwise. Use
+  // Returns true if the conversion is successful or false otherwise. Use
   // CefDisplay::ConvertPointFromPixels() before calling this method if
   // conversion from display-specific pixel coordinates is necessary.
   ///

include/views/cef_window_delegate.h

@@ -79,10 +79,12 @@ class CefWindowDelegate : public CefPanelDelegate {
   }
 
   ///
-  // Return the initial bounds for |window| in screen coordinates. If this
+  // Return the initial bounds for |window| in density independent pixel (DIP)
-  // method returns an empty CefRect then GetPreferredSize() will be called to
+  // coordinates. If this method returns an empty CefRect then
-  // retrieve the size, and the window will be placed on the default screen with
+  // GetPreferredSize() will be called to retrieve the size, and the window will
-  // origin (0,0).
+  // be placed on the screen with origin (0,0). This method can be used in
+  // combination with CefView::GetBoundsInScreen() to restore the previous
+  // window bounds.
   ///
   /*--cef()--*/
   virtual CefRect GetInitialBounds(CefRefPtr<CefWindow> window) {