views: Add support for absolute positioned overlay views.

To test: Run `cefclient.exe --use-views --hide-frame --hide-controls` Add `--enable-chrome-runtime` for the same behavior using the Chrome location bar instead of a text field.
2025-06-05 21:39:12 +02:00 · 2021-08-27 21:55:15 -04:00
parent 6f6072b857
commit 4a44e16a09
96 changed files with 3875 additions and 230 deletions
--- a/include/capi/cef_i18n_util_capi.h
+++ b/include/capi/cef_i18n_util_capi.h
@@ -0,0 +1,58 @@
+// Copyright (c) 2021 Marshall A. Greenblatt. All rights reserved.
+//
+// Redistribution and use in source and binary forms, with or without
+// modification, are permitted provided that the following conditions are
+// met:
+//
+//    * Redistributions of source code must retain the above copyright
+// notice, this list of conditions and the following disclaimer.
+//    * Redistributions in binary form must reproduce the above
+// copyright notice, this list of conditions and the following disclaimer
+// in the documentation and/or other materials provided with the
+// distribution.
+//    * Neither the name of Google Inc. nor the name Chromium Embedded
+// Framework nor the names of its contributors may be used to endorse
+// or promote products derived from this software without specific prior
+// written permission.
+//
+// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+//
+// ---------------------------------------------------------------------------
+//
+// This file was generated by the CEF translator tool and should not edited
+// by hand. See the translator.README.txt file in the tools directory for
+// more information.
+//
+// $hash=bf890f7b8e8edd423d71ad5a4d5bd43d81f1eb01$
+//
+
+#ifndef CEF_INCLUDE_CAPI_CEF_I18N_UTIL_CAPI_H_
+#define CEF_INCLUDE_CAPI_CEF_I18N_UTIL_CAPI_H_
+#pragma once
+
+#include "include/capi/cef_base_capi.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+///
+// Returns true (1) if the application text direction is right-to-left.
+///
+CEF_EXPORT int cef_is_rtl();
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif  // CEF_INCLUDE_CAPI_CEF_I18N_UTIL_CAPI_H_
--- a/include/capi/views/cef_overlay_controller_capi.h
+++ b/include/capi/views/cef_overlay_controller_capi.h
@@ -0,0 +1,216 @@
+// Copyright (c) 2021 Marshall A. Greenblatt. All rights reserved.
+//
+// Redistribution and use in source and binary forms, with or without
+// modification, are permitted provided that the following conditions are
+// met:
+//
+//    * Redistributions of source code must retain the above copyright
+// notice, this list of conditions and the following disclaimer.
+//    * Redistributions in binary form must reproduce the above
+// copyright notice, this list of conditions and the following disclaimer
+// in the documentation and/or other materials provided with the
+// distribution.
+//    * Neither the name of Google Inc. nor the name Chromium Embedded
+// Framework nor the names of its contributors may be used to endorse
+// or promote products derived from this software without specific prior
+// written permission.
+//
+// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+//
+// ---------------------------------------------------------------------------
+//
+// This file was generated by the CEF translator tool and should not edited
+// by hand. See the translator.README.txt file in the tools directory for
+// more information.
+//
+// $hash=60a15cb1c2e77544c20a3aafef1db736f07a5fb8$
+//
+
+#ifndef CEF_INCLUDE_CAPI_VIEWS_CEF_OVERLAY_CONTROLLER_CAPI_H_
+#define CEF_INCLUDE_CAPI_VIEWS_CEF_OVERLAY_CONTROLLER_CAPI_H_
+#pragma once
+
+#include "include/capi/cef_base_capi.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+struct _cef_view_t;
+struct _cef_window_t;
+
+///
+// Controller for an overlay that contains a contents View added via
+// cef_window_t::AddOverlayView. Methods exposed by this controller should be
+// called in preference to functions of the same name exposed by the contents
+// View unless otherwise indicated. Methods must be called on the browser
+// process UI thread unless otherwise indicated.
+///
+typedef struct _cef_overlay_controller_t {
+  ///
+  // Base structure.
+  ///
+  cef_base_ref_counted_t base;
+
+  ///
+  // Returns true (1) if this object is valid.
+  ///
+  int(CEF_CALLBACK* is_valid)(struct _cef_overlay_controller_t* self);
+
+  ///
+  // Returns true (1) if this object is the same as |that| object.
+  ///
+  int(CEF_CALLBACK* is_same)(struct _cef_overlay_controller_t* self,
+                             struct _cef_overlay_controller_t* that);
+
+  ///
+  // Returns the contents View for this overlay.
+  ///
+  struct _cef_view_t*(CEF_CALLBACK* get_contents_view)(
+      struct _cef_overlay_controller_t* self);
+
+  ///
+  // Returns the top-level Window hosting this overlay. Use this function
+  // instead of calling get_window() on the contents View.
+  ///
+  struct _cef_window_t*(CEF_CALLBACK* get_window)(
+      struct _cef_overlay_controller_t* self);
+
+  ///
+  // Returns the docking mode for this overlay.
+  ///
+  cef_docking_mode_t(CEF_CALLBACK* get_docking_mode)(
+      struct _cef_overlay_controller_t* self);
+
+  ///
+  // Destroy this overlay.
+  ///
+  void(CEF_CALLBACK* destroy)(struct _cef_overlay_controller_t* self);
+
+  ///
+  // Sets the bounds (size and position) of this overlay. This will set the
+  // bounds of the contents View to match and trigger a re-layout if necessary.
+  // |bounds| is in parent coordinates and any insets configured on this overlay
+  // will be ignored. Use this function only for overlays created with a docking
+  // mode value of CEF_DOCKING_MODE_CUSTOM. With other docking modes modify the
+  // insets of this overlay and/or layout of the contents View and call
+  // size_to_preferred_size() instead to calculate the new size and re-position
+  // the overlay if necessary.
+  ///
+  void(CEF_CALLBACK* set_bounds)(struct _cef_overlay_controller_t* self,
+                                 const cef_rect_t* bounds);
+
+  ///
+  // Returns the bounds (size and position) of this overlay in parent
+  // coordinates.
+  ///
+  cef_rect_t(CEF_CALLBACK* get_bounds)(struct _cef_overlay_controller_t* self);
+
+  ///
+  // Returns the bounds (size and position) of this overlay in DIP screen
+  // coordinates.
+  ///
+  cef_rect_t(CEF_CALLBACK* get_bounds_in_screen)(
+      struct _cef_overlay_controller_t* self);
+
+  ///
+  // Sets the size of this overlay without changing the position. This will set
+  // the size of the contents View to match and trigger a re-layout if
+  // necessary. |size| is in parent coordinates and any insets configured on
+  // this overlay will be ignored. Use this function only for overlays created
+  // with a docking mode value of CEF_DOCKING_MODE_CUSTOM. With other docking
+  // modes modify the insets of this overlay and/or layout of the contents View
+  // and call size_to_preferred_size() instead to calculate the new size and re-
+  // position the overlay if necessary.
+  ///
+  void(CEF_CALLBACK* set_size)(struct _cef_overlay_controller_t* self,
+                               const cef_size_t* size);
+
+  ///
+  // Returns the size of this overlay in parent coordinates.
+  ///
+  cef_size_t(CEF_CALLBACK* get_size)(struct _cef_overlay_controller_t* self);
+
+  ///
+  // Sets the position of this overlay without changing the size. |position| is
+  // in parent coordinates and any insets configured on this overlay will be
+  // ignored. Use this function only for overlays created with a docking mode
+  // value of CEF_DOCKING_MODE_CUSTOM. With other docking modes modify the
+  // insets of this overlay and/or layout of the contents View and call
+  // size_to_preferred_size() instead to calculate the new size and re-position
+  // the overlay if necessary.
+  ///
+  void(CEF_CALLBACK* set_position)(struct _cef_overlay_controller_t* self,
+                                   const cef_point_t* position);
+
+  ///
+  // Returns the position of this overlay in parent coordinates.
+  ///
+  cef_point_t(CEF_CALLBACK* get_position)(
+      struct _cef_overlay_controller_t* self);
+
+  ///
+  // Sets the insets for this overlay. |insets| is in parent coordinates. Use
+  // this function only for overlays created with a docking mode value other
+  // than CEF_DOCKING_MODE_CUSTOM.
+  ///
+  void(CEF_CALLBACK* set_insets)(struct _cef_overlay_controller_t* self,
+                                 const cef_insets_t* insets);
+
+  ///
+  // Returns the insets for this overlay in parent coordinates.
+  ///
+  cef_insets_t(CEF_CALLBACK* get_insets)(
+      struct _cef_overlay_controller_t* self);
+
+  ///
+  // Size this overlay to its preferred size and trigger a re-layout if
+  // necessary. The position of overlays created with a docking mode value of
+  // CEF_DOCKING_MODE_CUSTOM will not be modified by calling this function. With
+  // other docking modes this function may re-position the overlay if necessary
+  // to accommodate the new size and any insets configured on the contents View.
+  ///
+  void(CEF_CALLBACK* size_to_preferred_size)(
+      struct _cef_overlay_controller_t* self);
+
+  ///
+  // Sets whether this overlay is visible. Overlays are hidden by default. If
+  // this overlay is hidden then it and any child Views will not be drawn and,
+  // if any of those Views currently have focus, then focus will also be
+  // cleared. Painting is scheduled as needed.
+  ///
+  void(CEF_CALLBACK* set_visible)(struct _cef_overlay_controller_t* self,
+                                  int visible);
+
+  ///
+  // Returns whether this overlay is visible. A View may be visible but still
+  // not drawn in a Window if any parent Views are hidden. Call is_drawn() to
+  // determine whether this overlay and all parent Views are visible and will be
+  // drawn.
+  ///
+  int(CEF_CALLBACK* is_visible)(struct _cef_overlay_controller_t* self);
+
+  ///
+  // Returns whether this overlay is visible and drawn in a Window. A View is
+  // drawn if it and all parent Views are visible. To determine if the
+  // containing Window is visible to the user on-screen call is_visible() on the
+  // Window.
+  ///
+  int(CEF_CALLBACK* is_drawn)(struct _cef_overlay_controller_t* self);
+} cef_overlay_controller_t;
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif  // CEF_INCLUDE_CAPI_VIEWS_CEF_OVERLAY_CONTROLLER_CAPI_H_
--- 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=9881a00ef237b6972f14c071544387fc90fe18f1$
+// $hash=84b29a8dcdadffae5466ac16e7aafd80471a0abd$
 //

 #ifndef CEF_INCLUDE_CAPI_VIEWS_CEF_VIEW_CAPI_H_
@@ -220,6 +220,19 @@ typedef struct _cef_view_t {
  ///
  cef_point_t(CEF_CALLBACK* get_position)(struct _cef_view_t* self);

+  ///
+  // Sets the insets for this View. |insets| is in parent coordinates, or DIP
+  // screen coordinates if there is no parent.
+  ///
+  void(CEF_CALLBACK* set_insets)(struct _cef_view_t* self,
+                                 const cef_insets_t* insets);
+
+  ///
+  // Returns the insets for this View in parent coordinates, or DIP screen
+  // coordinates if there is no parent.
+  ///
+  cef_insets_t(CEF_CALLBACK* get_insets)(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
--- a/include/capi/views/cef_view_delegate_capi.h
+++ b/include/capi/views/cef_view_delegate_capi.h
@@ -33,7 +33,7 @@
 // by hand. See the translator.README.txt file in the tools directory for
 // more information.
 //
-// $hash=a060cb3c53317d758e7f6b4a275288cd08f086e7$
+// $hash=c8707f30655dc83c5f329d1dc22b14e9e06f4e76$
 //

 #ifndef CEF_INCLUDE_CAPI_VIEWS_CEF_VIEW_DELEGATE_CAPI_H_
@@ -121,6 +121,13 @@ typedef struct _cef_view_delegate_t {
                                        struct _cef_view_t* view,
                                        int added);

+  ///
+  // Called when the layout of |view| has changed.
+  ///
+  void(CEF_CALLBACK* on_layout_changed)(struct _cef_view_delegate_t* self,
+                                        struct _cef_view_t* view,
+                                        const cef_rect_t* new_bounds);
+
  ///
  // Called when |view| gains focus.
  ///
--- a/include/capi/views/cef_window_capi.h
+++ b/include/capi/views/cef_window_capi.h
@@ -33,7 +33,7 @@
 // by hand. See the translator.README.txt file in the tools directory for
 // more information.
 //
-// $hash=15f88e3521ca96947fe8b1f91f251eb3405fb293$
+// $hash=0f5dad3572a20ee7395cb861b5c970cff382b61c$
 //

 #ifndef CEF_INCLUDE_CAPI_VIEWS_CEF_WINDOW_CAPI_H_
@@ -43,6 +43,7 @@
 #include "include/capi/cef_image_capi.h"
 #include "include/capi/cef_menu_model_capi.h"
 #include "include/capi/views/cef_display_capi.h"
+#include "include/capi/views/cef_overlay_controller_capi.h"
 #include "include/capi/views/cef_panel_capi.h"
 #include "include/capi/views/cef_window_delegate_capi.h"

@@ -197,6 +198,40 @@ typedef struct _cef_window_t {
  struct _cef_image_t*(CEF_CALLBACK* get_window_app_icon)(
      struct _cef_window_t* self);

+  ///
+  // Add a View that will be overlayed on the Window contents with absolute
+  // positioning and high z-order. Positioning is controlled by |docking_mode|
+  // as described below. The returned cef_overlay_controller_t object is used to
+  // control the overlay. Overlays are hidden by default.
+  //
+  // With CEF_DOCKING_MODE_CUSTOM:
+  //   1. The overlay is initially hidden, sized to |view|'s preferred size, and
+  //      positioned in the top-left corner.
+  //   2. Optionally change the overlay position and/or size by calling
+  //      CefOverlayController methods.
+  //   3. Call CefOverlayController::SetVisible(true) to show the overlay.
+  //   4. The overlay will be automatically re-sized if |view|'s layout changes.
+  //      Optionally change the overlay position and/or size when
+  //      OnLayoutChanged is called on the Window's delegate to indicate a
+  //      change in Window bounds.
+  //
+  // With other docking modes:
+  //   1. The overlay is initially hidden, sized to |view|'s preferred size, and
+  //      positioned based on |docking_mode|.
+  //   2. Call CefOverlayController::SetVisible(true) to show the overlay.
+  //   3. The overlay will be automatically re-sized if |view|'s layout changes
+  //      and re-positioned as appropriate when the Window resizes.
+  //
+  // Overlays created by this function will receive a higher z-order then any
+  // child Views added previously. It is therefore recommended to call this
+  // function last after all other child Views have been added so that the
+  // overlay displays as the top-most child of the Window.
+  ///
+  struct _cef_overlay_controller_t*(CEF_CALLBACK* add_overlay_view)(
+      struct _cef_window_t* self,
+      struct _cef_view_t* view,
+      cef_docking_mode_t docking_mode);
+
  ///
  // Show a menu with contents |menu_model|. |screen_point| specifies the menu
  // position in screen coordinates. |anchor_position| specifies how the menu
--- a/include/cef_api_hash.h
+++ b/include/cef_api_hash.h
@@ -42,13 +42,13 @@
 // way that may cause binary incompatibility with other builds. The universal
 // hash value will change if any platform is affected whereas the platform hash
 // values will change only if that particular platform is affected.
-#define CEF_API_HASH_UNIVERSAL "5625e3ce80d2bbf5b5a39f8655d96c215f7685ee"
+#define CEF_API_HASH_UNIVERSAL "e32fc367fb311d2d68f097d42a75357a3e339fdd"
 #if defined(OS_WIN)
-#define CEF_API_HASH_PLATFORM "c20e4ffc24e6267b61774f49237d0f30a581f370"
+#define CEF_API_HASH_PLATFORM "e40f20dc24610956c9e2768f4c9535502d68f70e"
 #elif defined(OS_MAC)
-#define CEF_API_HASH_PLATFORM "65731bc654ec6e1dbd48d6ff2336c4c8573f7d35"
+#define CEF_API_HASH_PLATFORM "cb578fa9c253d93944f63d9bdc7a8f9e0a417bae"
 #elif defined(OS_LINUX)
-#define CEF_API_HASH_PLATFORM "4e35b9cc9735c63ac9f16fbbb49a4b8e2307f23a"
+#define CEF_API_HASH_PLATFORM "10b47123ea31edcf4a978a36e4ee2aa5bc755b2d"
 #endif

 #ifdef __cplusplus
--- a/include/cef_i18n_util.h
+++ b/include/cef_i18n_util.h
@@ -0,0 +1,49 @@
+// Copyright (c) 2021 Marshall A. Greenblatt. All rights reserved.
+//
+// Redistribution and use in source and binary forms, with or without
+// modification, are permitted provided that the following conditions are
+// met:
+//
+//    * Redistributions of source code must retain the above copyright
+// notice, this list of conditions and the following disclaimer.
+//    * Redistributions in binary form must reproduce the above
+// copyright notice, this list of conditions and the following disclaimer
+// in the documentation and/or other materials provided with the
+// distribution.
+//    * Neither the name of Google Inc. nor the name Chromium Embedded
+// Framework nor the names of its contributors may be used to endorse
+// or promote products derived from this software without specific prior
+// written permission.
+//
+// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+//
+// ---------------------------------------------------------------------------
+//
+// The contents of this file must follow a specific format in order to
+// support the CEF translator tool. See the translator.README.txt file in the
+// tools directory for more information.
+//
+
+#ifndef CEF_INCLUDE_CEF_I18N_UTIL_H_
+#define CEF_INCLUDE_CEF_I18N_UTIL_H_
+#pragma once
+
+#include "include/cef_base.h"
+
+///
+// Returns true if the application text direction is right-to-left.
+///
+/*--cef()--*/
+bool CefIsRTL();
+
+#endif  // CEF_INCLUDE_CEF_I18N_UTIL_H_
--- a/include/internal/cef_types.h
+++ b/include/internal/cef_types.h
@@ -3198,6 +3198,17 @@ typedef enum {
  CEF_CTT_LOCATION,
 } cef_chrome_toolbar_type_t;

+///
+// Docking modes supported by CefWindow::AddOverlay.
+///
+typedef enum {
+  CEF_DOCKING_MODE_TOP_LEFT = 1,
+  CEF_DOCKING_MODE_TOP_RIGHT,
+  CEF_DOCKING_MODE_BOTTOM_LEFT,
+  CEF_DOCKING_MODE_BOTTOM_RIGHT,
+  CEF_DOCKING_MODE_CUSTOM,
+} cef_docking_mode_t;
+
 #ifdef __cplusplus
 }
 #endif
--- a/include/views/cef_overlay_controller.h
+++ b/include/views/cef_overlay_controller.h
@@ -0,0 +1,209 @@
+// Copyright (c) 2021 Marshall A. Greenblatt. All rights reserved.
+//
+// Redistribution and use in source and binary forms, with or without
+// modification, are permitted provided that the following conditions are
+// met:
+//
+//    * Redistributions of source code must retain the above copyright
+// notice, this list of conditions and the following disclaimer.
+//    * Redistributions in binary form must reproduce the above
+// copyright notice, this list of conditions and the following disclaimer
+// in the documentation and/or other materials provided with the
+// distribution.
+//    * Neither the name of Google Inc. nor the name Chromium Embedded
+// Framework nor the names of its contributors may be used to endorse
+// or promote products derived from this software without specific prior
+// written permission.
+//
+// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+//
+// ---------------------------------------------------------------------------
+//
+// The contents of this file must follow a specific format in order to
+// support the CEF translator tool. See the translator.README.txt file in the
+// tools directory for more information.
+//
+
+#ifndef CEF_INCLUDE_VIEWS_CEF_OVERLAY_CONTROLLER_H_
+#define CEF_INCLUDE_VIEWS_CEF_OVERLAY_CONTROLLER_H_
+#pragma once
+
+#include "include/cef_base.h"
+
+class CefView;
+class CefWindow;
+
+///
+// Controller for an overlay that contains a contents View added via
+// CefWindow::AddOverlayView. Methods exposed by this controller should be
+// called in preference to methods of the same name exposed by the contents View
+// unless otherwise indicated. Methods must be called on the browser process UI
+// thread unless otherwise indicated.
+///
+/*--cef(source=library)--*/
+class CefOverlayController : public CefBaseRefCounted {
+ public:
+  ///
+  // Returns true if this object is valid.
+  ///
+  /*--cef()--*/
+  virtual bool IsValid() = 0;
+
+  ///
+  // Returns true if this object is the same as |that| object.
+  ///
+  /*--cef()--*/
+  virtual bool IsSame(CefRefPtr<CefOverlayController> that) = 0;
+
+  ///
+  // Returns the contents View for this overlay.
+  ///
+  /*--cef()--*/
+  virtual CefRefPtr<CefView> GetContentsView() = 0;
+
+  ///
+  // Returns the top-level Window hosting this overlay. Use this method instead
+  // of calling GetWindow() on the contents View.
+  ///
+  /*--cef()--*/
+  virtual CefRefPtr<CefWindow> GetWindow() = 0;
+
+  ///
+  // Returns the docking mode for this overlay.
+  ///
+  /*--cef(default_retval=CEF_DOCKING_MODE_TOP_LEFT)--*/
+  virtual cef_docking_mode_t GetDockingMode() = 0;
+
+  ///
+  // Destroy this overlay.
+  ///
+  /*--cef()--*/
+  virtual void Destroy() = 0;
+
+  ///
+  // Sets the bounds (size and position) of this overlay. This will set the
+  // bounds of the contents View to match and trigger a re-layout if necessary.
+  // |bounds| is in parent coordinates and any insets configured on this overlay
+  // will be ignored. Use this method only for overlays created with a docking
+  // mode value of CEF_DOCKING_MODE_CUSTOM. With other docking modes modify the
+  // insets of this overlay and/or layout of the contents View and call
+  // SizeToPreferredSize() instead to calculate the new size and re-position the
+  // overlay if necessary.
+  ///
+  /*--cef()--*/
+  virtual void SetBounds(const CefRect& bounds) = 0;
+
+  ///
+  // Returns the bounds (size and position) of this overlay in parent
+  // coordinates.
+  ///
+  /*--cef()--*/
+  virtual CefRect GetBounds() = 0;
+
+  ///
+  // Returns the bounds (size and position) of this overlay in DIP screen
+  // coordinates.
+  ///
+  /*--cef()--*/
+  virtual CefRect GetBoundsInScreen() = 0;
+
+  ///
+  // Sets the size of this overlay without changing the position. This will set
+  // the size of the contents View to match and trigger a re-layout if
+  // necessary. |size| is in parent coordinates and any insets configured on
+  // this overlay will be ignored. Use this method only for overlays created
+  // with a docking mode value of CEF_DOCKING_MODE_CUSTOM. With other docking
+  // modes modify the insets of this overlay and/or layout of the contents View
+  // and call SizeToPreferredSize() instead to calculate the new size and
+  // re-position the overlay if necessary.
+  ///
+  /*--cef()--*/
+  virtual void SetSize(const CefSize& size) = 0;
+
+  ///
+  // Returns the size of this overlay in parent coordinates.
+  ///
+  /*--cef()--*/
+  virtual CefSize GetSize() = 0;
+
+  ///
+  // Sets the position of this overlay without changing the size. |position| is
+  // in parent coordinates and any insets configured on this overlay will
+  // be ignored. Use this method only for overlays created with a docking mode
+  // value of CEF_DOCKING_MODE_CUSTOM. With other docking modes modify the
+  // insets of this overlay and/or layout of the contents View and call
+  // SizeToPreferredSize() instead to calculate the new size and re-position the
+  // overlay if necessary.
+  ///
+  /*--cef()--*/
+  virtual void SetPosition(const CefPoint& position) = 0;
+
+  ///
+  // Returns the position of this overlay in parent coordinates.
+  ///
+  /*--cef()--*/
+  virtual CefPoint GetPosition() = 0;
+
+  ///
+  // Sets the insets for this overlay. |insets| is in parent coordinates. Use
+  // this method only for overlays created with a docking mode value other than
+  // CEF_DOCKING_MODE_CUSTOM.
+  ///
+  /*--cef()--*/
+  virtual void SetInsets(const CefInsets& insets) = 0;
+
+  ///
+  // Returns the insets for this overlay in parent coordinates.
+  ///
+  /*--cef()--*/
+  virtual CefInsets GetInsets() = 0;
+
+  ///
+  // Size this overlay to its preferred size and trigger a re-layout if
+  // necessary. The position of overlays created with a docking mode value of
+  // CEF_DOCKING_MODE_CUSTOM will not be modified by calling this method. With
+  // other docking modes this method may re-position the overlay if necessary to
+  // accommodate the new size and any insets configured on the contents View.
+  ///
+  /*--cef()--*/
+  virtual void SizeToPreferredSize() = 0;
+
+  ///
+  // Sets whether this overlay is visible. Overlays are hidden by default. If
+  // this overlay is hidden then it and any child Views will not be drawn and,
+  // if any of those Views currently have focus, then focus will also be
+  // cleared. Painting is scheduled as needed.
+  ///
+  /*--cef()--*/
+  virtual void SetVisible(bool visible) = 0;
+
+  ///
+  // Returns whether this overlay is visible. A View may be visible but still
+  // not drawn in a Window if any parent Views are hidden. Call IsDrawn() to
+  // determine whether this overlay and all parent Views are visible and will be
+  // drawn.
+  ///
+  /*--cef()--*/
+  virtual bool IsVisible() = 0;
+
+  ///
+  // Returns whether this overlay is visible and drawn in a Window. A View is
+  // drawn if it and all parent Views are visible. To determine if the
+  // containing Window is visible to the user on-screen call IsVisible() on the
+  // Window.
+  ///
+  /*--cef()--*/
+  virtual bool IsDrawn() = 0;
+};
+
+#endif  // CEF_INCLUDE_VIEWS_CEF_OVERLAY_CONTROLLER_H_
--- a/include/views/cef_view.h
+++ b/include/views/cef_view.h
@@ -222,6 +222,20 @@ class CefView : public CefBaseRefCounted {
  /*--cef()--*/
  virtual CefPoint GetPosition() = 0;

+  ///
+  // Sets the insets for this View. |insets| is in parent coordinates, or DIP
+  // screen coordinates if there is no parent.
+  ///
+  /*--cef()--*/
+  virtual void SetInsets(const CefInsets& insets) = 0;
+
+  ///
+  // Returns the insets for this View in parent coordinates, or DIP screen
+  // coordinates if there is no parent.
+  ///
+  /*--cef()--*/
+  virtual CefInsets GetInsets() = 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
--- a/include/views/cef_view_delegate.h
+++ b/include/views/cef_view_delegate.h
@@ -108,9 +108,16 @@ class CefViewDelegate : public virtual CefBaseRefCounted {
  ///
  // Called when |view| is added or removed from the CefWindow.
  ///
-  /*--cef(optional_param=window)--*/
+  /*--cef()--*/
  virtual void OnWindowChanged(CefRefPtr<CefView> view, bool added) {}

+  ///
+  // Called when the layout of |view| has changed.
+  ///
+  /*--cef()--*/
+  virtual void OnLayoutChanged(CefRefPtr<CefView> view,
+                               const CefRect& new_bounds) {}
+
  ///
  // Called when |view| gains focus.
  ///
--- a/include/views/cef_window.h
+++ b/include/views/cef_window.h
@@ -41,6 +41,7 @@
 #include "include/cef_image.h"
 #include "include/cef_menu_model.h"
 #include "include/views/cef_display.h"
+#include "include/views/cef_overlay_controller.h"
 #include "include/views/cef_panel.h"
 #include "include/views/cef_window_delegate.h"

@@ -211,6 +212,40 @@ class CefWindow : public CefPanel {
  /*--cef()--*/
  virtual CefRefPtr<CefImage> GetWindowAppIcon() = 0;

+  ///
+  // Add a View that will be overlayed on the Window contents with absolute
+  // positioning and high z-order. Positioning is controlled by |docking_mode|
+  // as described below. The returned CefOverlayController object is used to
+  // control the overlay. Overlays are hidden by default.
+  //
+  // With CEF_DOCKING_MODE_CUSTOM:
+  //   1. The overlay is initially hidden, sized to |view|'s preferred size, and
+  //      positioned in the top-left corner.
+  //   2. Optionally change the overlay position and/or size by calling
+  //      CefOverlayController methods.
+  //   3. Call CefOverlayController::SetVisible(true) to show the overlay.
+  //   4. The overlay will be automatically re-sized if |view|'s layout changes.
+  //      Optionally change the overlay position and/or size when
+  //      OnLayoutChanged is called on the Window's delegate to indicate a
+  //      change in Window bounds.
+  //
+  // With other docking modes:
+  //   1. The overlay is initially hidden, sized to |view|'s preferred size, and
+  //      positioned based on |docking_mode|.
+  //   2. Call CefOverlayController::SetVisible(true) to show the overlay.
+  //   3. The overlay will be automatically re-sized if |view|'s layout changes
+  //      and re-positioned as appropriate when the Window resizes.
+  //
+  // Overlays created by this method will receive a higher z-order then any
+  // child Views added previously. It is therefore recommended to call this
+  // method last after all other child Views have been added so that the overlay
+  // displays as the top-most child of the Window.
+  ///
+  /*--cef()--*/
+  virtual CefRefPtr<CefOverlayController> AddOverlayView(
+      CefRefPtr<CefView> view,
+      cef_docking_mode_t docking_mode) = 0;
+
  ///
  // Show a menu with contents |menu_model|. |screen_point| specifies the menu
  // position in screen coordinates. |anchor_position| specifies how the menu