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

2025-02-02 20:26:59 +01:00 · 2020-09-25 14:31:14 -04:00 · 2020-09-25 14:31:14 -04:00 · cae194f493
commit cae194f493
parent 4fbd247231
6 changed files with 98 additions and 77 deletions
--- a/include/capi/views/cef_display_capi.h
+++ b/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.
-// Methods must be called on the browser process UI thread unless otherwise
-// indicated.
+// values are in density independent pixel (DIP) coordinates unless otherwise
+// indicated. Methods must be called on the browser process UI thread unless
+// 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
-  // using this Display's device scale factor.
+  // Convert |point| from DIP coordinates to pixel coordinates using this
+  // 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)
-  // using this Display's device scale factor.
+  // Convert |point| from pixel coordinates to DIP coordinates using this
+  // 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
-  // are occupied for window manager toolbars, etc.
+  // Returns this Display's work area in DIP screen coordinates. This excludes
+  // 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
-// of density independent pixels (DIP).
+// |input_pixel_coords| to true (1) if |bounds| is in pixel screen coordinates
+// instead of DIP screen coordinates.
 ///
 CEF_EXPORT cef_display_t* cef_display_get_matching_bounds(
    const cef_rect_t* bounds,
--- a/include/capi/views/cef_view_capi.h
+++ b/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
-  // coordinates.
+  // Sets the bounds (size and position) of this View. |bounds| is in parent
+  // 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
-  // coordinates.
+  // Returns the bounds (size and position) of this View in parent 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.
-  // This View must belong to a Window when calling this function. Returns true
-  // (1) if the conversion is successful or false (0) otherwise. Use
-  // cef_display_t::convert_point_to_pixels() after calling this function if
+  // Convert |point| from this View's coordinate system to DIP screen
+  // coordinates. This View must belong to a Window when calling this function.
+  // Returns true (1) if the conversion is successful or false (0) otherwise.
+  // 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.
-  // This View must belong to a Window when calling this function. Returns true
-  // (1) if the conversion is successful or false (0) otherwise. Use
-  // cef_display_t::convert_point_from_pixels() before calling this function if
-  // conversion from display-specific pixel coordinates is necessary.
+  // Convert |point| to this View's coordinate system from DIP screen
+  // coordinates. This View must belong to a Window when calling this function.
+  // Returns true (1) if the conversion is successful or false (0) otherwise.
+  // Use cef_display_t::convert_point_from_pixels() before calling this function
+  // 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);
--- a/include/capi/views/cef_window_delegate_capi.h
+++ b/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
-  // function returns an NULL CefRect then get_preferred_size() will be called
-  // to retrieve the size, and the window will be placed on the default screen
-  // with origin (0,0).
+  // Return the initial bounds for |window| in density independent pixel (DIP)
+  // coordinates. If this function returns an NULL CefRect then
+  // get_preferred_size() will be called to retrieve the size, and the window
+  // 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,
--- a/include/views/cef_display.h
+++ b/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.
-// Methods must be called on the browser process UI thread unless otherwise
-// indicated.
+// values are in density independent pixel (DIP) coordinates unless otherwise
+// indicated. Methods must be called on the browser process UI thread unless
+// 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
-  // (DIP).
+  // |point| is in pixel screen coordinates instead of DIP screen coordinates.
  ///
  /*--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
-  // density independent pixels (DIP).
+  // |input_pixel_coords| to true if |bounds| is in pixel screen coordinates
+  // 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
-  // using this Display's device scale factor.
+  // Convert |point| from DIP coordinates to pixel coordinates using this
+  // Display's device scale factor.
  ///
  /*--cef()--*/
  virtual void ConvertPointToPixels(CefPoint& point) = 0;

  ///
-  // Convert |point| from pixel coordinates to density independent pixels (DIP)
-  // using this Display's device scale factor.
+  // Convert |point| from pixel coordinates to DIP coordinates using this
+  // 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
-  // are occupied for window manager toolbars, etc.
+  // Returns this Display's work area in DIP screen coordinates. This excludes
+  // areas of the display that are occupied with window manager toolbars, etc.
  ///
  /*--cef()--*/
  virtual CefRect GetWorkArea() = 0;
--- a/include/views/cef_view.h
+++ b/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
-  // coordinates.
+  // Sets the bounds (size and position) of this View. |bounds| is in parent
+  // 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
-  // coordinates.
+  // Returns the bounds (size and position) of this View in parent 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.
-  // This View must belong to a Window when calling this method. Returns true
-  // if the conversion is successful or false otherwise. Use
+  // Convert |point| from this View's coordinate system to DIP screen
+  // coordinates. This View must belong to a Window when calling this method.
+  // 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.
-  // This View must belong to a Window when calling this method. Returns true if
-  // the conversion is successful or false otherwise. Use
+  // Convert |point| to this View's coordinate system from DIP screen
+  // coordinates. This View must belong to a Window when calling this method.
+  // 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.
  ///
--- a/include/views/cef_window_delegate.h
+++ b/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
-  // method returns an empty CefRect then GetPreferredSize() will be called to
-  // retrieve the size, and the window will be placed on the default screen with
-  // origin (0,0).
+  // Return the initial bounds for |window| in density independent pixel (DIP)
+  // coordinates. If this method returns an empty CefRect then
+  // GetPreferredSize() will be called to retrieve the size, and the window will
+  // 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) {