bcarrella/cef
1
0
Fork 0
mirror of https://bitbucket.org/chromiumembedded/cef synced 2025-02-02 20:26:59 +01:00
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
Marshall Greenblatt 2020-09-25 14:31:14 -04:00
parent 4fbd247231
commit cae194f493
6 changed files with 98 additions and 77 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

29
include/capi/views/cef_display_capi.h
View File

@ -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,

52
include/capi/views/cef_view_capi.h
View File

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

12
include/capi/views/cef_window_delegate_capi.h
View File

@ -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,

28
include/views/cef_display.h
View File

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

44
include/views/cef_view.h
View File

@ -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.
///

10
include/views/cef_window_delegate.h
View File

@ -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) {