From cae194f493328a9890b27533ce1dc661e0d4b042 Mon Sep 17 00:00:00 2001 From: Marshall Greenblatt Date: Fri, 25 Sep 2020 14:31:14 -0400 Subject: [PATCH] Improve documentation related to views screen coordinates (see issue #2980) --- include/capi/views/cef_display_capi.h | 29 ++++++----- include/capi/views/cef_view_capi.h | 52 +++++++++++-------- include/capi/views/cef_window_delegate_capi.h | 12 +++-- include/views/cef_display.h | 28 +++++----- include/views/cef_view.h | 44 +++++++++------- include/views/cef_window_delegate.h | 10 ++-- 6 files changed, 98 insertions(+), 77 deletions(-) diff --git a/include/capi/views/cef_display_capi.h b/include/capi/views/cef_display_capi.h index 89bb5ad92..afccd81c0 100644 --- 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, diff --git a/include/capi/views/cef_view_capi.h b/include/capi/views/cef_view_capi.h index e50c73d9d..7cfd5b8ef 100644 --- 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); diff --git a/include/capi/views/cef_window_delegate_capi.h b/include/capi/views/cef_window_delegate_capi.h index d6d0c6382..a2ec8a584 100644 --- 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, diff --git a/include/views/cef_display.h b/include/views/cef_display.h index de3e7ab82..80b28f49c 100644 --- 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 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 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; diff --git a/include/views/cef_view.h b/include/views/cef_view.h index eed14f317..509e3c0ce 100644 --- a/include/views/cef_view.h +++ b/include/views/cef_view.h @@ -174,71 +174,79 @@ class CefView : public CefBaseRefCounted { virtual CefRefPtr 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. /// diff --git a/include/views/cef_window_delegate.h b/include/views/cef_window_delegate.h index 74e45b080..b167096eb 100644 --- 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 window) {