Update API docs and create a log of CEF changes in regards v66 update

api/ApplicationSettings.md

@@ -107,10 +107,15 @@ Example values that can be set in Win7 DPI settings (Control Panel Appearance an
 ### background_color
 
 (int)
-Opaque background color used for accelerated content. By default the
-background color will be white. Only the RGB compontents of the specified
-value will be used. The alpha component must greater than 0 to enable use
-of the background color but will be otherwise ignored.
+Description from upstream CEF:
+> Background color used for the browser before a document is loaded and when
+> no document color is specified. The alpha component must be either fully
+> opaque (0xFF) or fully transparent (0x00). If the alpha component is fully
+> opaque then the RGB components will be used as the background color. If the
+> alpha component is fully transparent for a windowed browser then the
+> default value of opaque white be used. If the alpha component is fully
+> transparent for a windowless (off-screen) browser then transparent painting
+> will be enabled.
 
 32-bit ARGB color value, not premultiplied. The color components are always
 in a known order. Equivalent to the `SkColor` type.

api/Browser.md

@@ -313,15 +313,24 @@ Calling javascript from native code synchronously is not possible in CEF 3. It i
 
 | Parameter | Type |
 | --- | --- |
-| searchID | int |
+| searchId | int |
 | searchText | string |
 | forward | bool |
 | matchCase | bool |
 | findNext | bool |
 | __Return__ | void |
 
-Search for |searchText|. |searchID| can be custom, it is so that you can  have multiple searches running simultaneously. |forward| indicates whether to search forward or backward within the page. |matchCase| indicates whether the search should be case-sensitive. |findNext| indicates whether this is the first request or a follow-up. The CefFindHandler instance, if any, returned via CefClient::GetFindHandler will be called to report find results.
+Description from upstream CEF:
 
+> Search for |searchText|. |identifier| must be a unique ID and these IDs
+> must strictly increase so that newer requests always have greater IDs than
+> older requests. If |identifier| is zero or less than the previous ID value
+> then it will be automatically assigned a new valid ID. |forward| indicates
+> whether to search forward or backward within the page. |matchCase|
+> indicates whether the search should be case-sensitive. |findNext| indicates
+> whether this is the first request or a follow-up. The CefFindHandler
+> instance, if any, returned via CefClient::GetFindHandler will be called to
+> report find results.
 
 ### GetClientCallback
 
@@ -493,7 +502,8 @@ Returns an inner or outer window handle for the browser. If the browser was crea
 | --- | --- |
 | __Return__ | int |
 
-Returns the globally unique identifier for this browser.
+Returns the globally unique identifier for this browser. This value is also
+used as the tabId for extension APIs.
 
 
 ### GetZoomLevel

api/BrowserSettings.md

@@ -77,12 +77,15 @@ empty then "en-US,en" will be used.
 ### background_color
 
 (int)
-Opaque background color used for the browser before a document is loaded
-and when no document color is specified. By default the background color
-will be the same as CefSettings.background_color. Only the RGB compontents
-of the specified value will be used. The alpha component must greater than
-0 to enable use of the background color but will be otherwise ignored.
-
+Description from upstream CEF:
+> Background color used for the browser before a document is loaded and when
+> no document color is specified. The alpha component must be either fully
+> opaque (0xFF) or fully transparent (0x00). If the alpha component is fully
+> opaque then the RGB components will be used as the background color. If the
+> alpha component is fully transparent for a windowed browser then the
+> CefSettings.background_color value will be used. If the alpha component is
+> fully transparent for a windowless (off-screen) browser then transparent
+> painting will be enabled.
 
 ### databases_disabled
 

api/DragData.md

@@ -81,10 +81,12 @@ Return the text/html fragment that is being dragged.
 | --- | --- |
 | __Return__ | [Image](Image.md) |
 
-Linux-only currently (#251).
+Description from upstream CEF:
+> Get the image representation of drag data. May return NULL if no image
+> representation is available.
 
-Get image representation of drag data. Check with HasImage() first,
-otherwise if there is no image an exception is thrown.
+Check with HasImage() first, otherwise if there is no image an exception
+is thrown.
 
 
 ### GetImageHotspot
@@ -93,9 +95,7 @@ otherwise if there is no image an exception is thrown.
 | --- | --- |
 | __Return__ | [Image](Image.md) |
 
-Linux-only currently (#251).
-
-Get image hotspot (drag start location relative to image dimensions).
+Get the image hotspot (drag start location relative to image dimensions).
 
 
 ### HasImage
@@ -104,7 +104,5 @@ Get image hotspot (drag start location relative to image dimensions).
 | --- | --- |
 | __Return__ | bool |
 
-Linux-only currently (#251).
-
-Whether image representation of drag data is available.
+Returns true if an image representation of drag data is available.
 

api/LifespanHandler.md

@@ -36,24 +36,27 @@ Table of contents:
 | no_javascript_access_out | list[bool] |
 | __Return__ | bool |
 
-Called on the IO thread before a new popup browser is created. The
-|browser| and |frame| values represent the source of the popup request. The
-|target_url| and |target_frame_name| values indicate where the popup
-browser should navigate and may be empty if not specified with the request.
-The |target_disposition| value indicates where the user intended to open
-the popup (e.g. current tab, new tab, etc). The |user_gesture| value will
-be true if the popup was opened via explicit user gesture (e.g. clicking a
-link) or false if the popup opened automatically (e.g. via the
-DomContentLoaded event). The |popup_features| structure contains additional
-information about the requested popup window. To allow creation of the
-popup browser optionally modify |windowInfo|, |client|, |browserSettings| and
-|no_javascript_access| and return false. To cancel creation of the popup
-browser return true. The |client| and |settings| values will default to the
-source browser's values. If the |no_javascript_access| value is set to
-false the new browser will not be scriptable and may not be hosted in the
-same renderer process as the source browser. Any modifications to
-|window_info| will be ignored if the parent browser is wrapped in a
-CefBrowserView.
+Description from upstream CEF:
+> Called on the UI thread before a new popup browser is created. The
+> |browser| and |frame| values represent the source of the popup request. The
+> |target_url| and |target_frame_name| values indicate where the popup
+> browser should navigate and may be empty if not specified with the request.
+> The |target_disposition| value indicates where the user intended to open
+> the popup (e.g. current tab, new tab, etc). The |user_gesture| value will
+> be true if the popup was opened via explicit user gesture (e.g. clicking a
+> link) or false if the popup opened automatically (e.g. via the
+> DomContentLoaded event). The |popup_features| structure contains additional
+> information about the requested popup window. To allow creation of the
+> popup browser optionally modify |windowInfo|, |client|, |browserSettings| and
+> |no_javascript_access| and return false. To cancel creation of the popup
+> browser return true. The |client| and |settings| values will default to the
+> source browser's values. If the |no_javascript_access| value is set to
+> false the new browser will not be scriptable and may not be hosted in the
+> same renderer process as the source browser. Any modifications to
+> |window_info| will be ignored if the parent browser is wrapped in a
+> CefBrowserView. Popup browser creation will be canceled if the parent
+> browser is destroyed before the popup browser creation completes (indicated
+> by a call to OnAfterCreated for the popup browser).
 
 Note that if you return True and create the popup window yourself, then
 the popup window and parent window will not be able to script each other.

api/Request.md

@@ -170,6 +170,9 @@ Available flags (access via `cefpython.Request.Flags["xxx"]`):
 
 * **None** - Default behavior.
 * **SkipCache** - If set the cache will be skipped when handling the request.
+  Setting this value is equivalent to specifying the "Cache-Control: no-cache"
+  request header. Setting this value in combination with UR_FLAG_ONLY_FROM_CACHE
+  will cause the request to fail.
 * **AllowCachedCredentials** - If set user name, password, and cookies may be
       sent with the request, and cookies may be saved from the response.
 * **ReportUploadProgress** - If set upload progress events will be generated when a request has a body.
@@ -185,6 +188,7 @@ Available flags (access via `cefpython.Request.Flags["xxx"]`):
 | __Return__ | void |
 
 Set the flags used in combination with [WebRequest](WebRequest.md).
+See GetFlags() for possible values.
 
 
 ### GetFirstPartyForCookies

api/WindowInfo.md

@@ -58,13 +58,14 @@ CefRenderHandler interface. The |parent| value will be used to identify
 monitor info and to act as the parent window for dialogs, context menus,
 etc. If |parent| is not provided then the main screen monitor will be used
 and some functionality that requires a parent window may not function
-correctly. If |transparent| is true a transparent background color will be
-used (RGBA=0x00000000). If |transparent| is false the background will be
-white and opaque. In order to create windowless browsers the
+correctly. In order to create windowless browsers the
 CefSettings.windowless_rendering_enabled value must be set to true.
+Transparent painting is enabled by default but can be disabled by setting
+CefBrowserSettings.background_color to an opaque value.
 
 Call this method to disable windowed rendering and to use
-[RenderHandler](RenderHandler.md). See the Panda3D and Kivy examples.
+[RenderHandler](RenderHandler.md). See the pysdl2, screenshot, panda3d
+and kivy examples.
 
 In order to create windowless browsers the
 ApplicationSettings.[windowless_rendering_enabled](ApplicationSettings.md#windowless_rendering_enabled)
@@ -73,12 +74,3 @@ value must be set to true.
 You can pass 0 as `parentWindowHandle`, but then some things like
 context menus and plugins may not display correctly.
 
-
-### SetTransparentPainting
-
-| Parameter | Type |
-| --- | --- |
-| transparentPainting | bool |
-| __Return__ | void |
-
-This method is intended for use with off-screen rendering only.

api/cefpython.md

@@ -240,16 +240,16 @@ Post a task for execution on the thread associated with this task runner. Execut
 An example usage is in the wxpython.py example on Windows, in implementation of LifespanHandler.OnBeforePopup().
 
 List of threads in the Browser process:
-* cef.TID_UI: The main thread in the browser. This will be the same as the main application thread if cefpython.Initialize() is called with a ApplicationSettings.multi_threaded_message_loop value of false.
+* cef.TID_UI: The main thread in the browser. This will be the same as the main application thread if cefpython.Initialize() is called with a ApplicationSettings.multi_threaded_message_loop value of false. Do not perform blocking tasks on this thread. All tasks posted after CefBrowserProcessHandler::OnContextInitialized() and before CefShutdown() are guaranteed to run. This thread will outlive all other CEF threads.
 * cef.TID_DB: Used to interact with the database.
-* cef.TID_FILE: Used to interact with the file system.
-* cef.TID_FILE_USER_BLOCKING: Used for file system operations that block user interactions. Responsiveness of this thread affects users.
+* cef.TID_FILE: Used for blocking tasks (e.g. file system access) where the user won't notice if the task takes an arbitrarily long time to complete. All tasks posted after CefBrowserProcessHandler::OnContextInitialized() and before CefShutdown() are guaranteed to run.
+* cef.TID_FILE_USER_BLOCKING: Used for blocking tasks (e.g. file system access) that affect UI immediately after a user interaction. All tasks posted after CefBrowserProcessHandler::OnContextInitialized() and before CefShutdown() are guaranteed to run. Example: Generating data shown in the UI immediately after a click.
 * cef.TID_PROCESS_LAUNCHER: Used to launch and terminate browser processes.
 * cef.TID_CACHE: Used to handle slow HTTP cache operations.
-* cef.TID_IO: Used to process IPC and network messages.
+* cef.TID_IO: Used to process IPC and network messages. Do not perform blocking tasks on this thread. All tasks posted after CefBrowserProcessHandler::OnContextInitialized() and before CefShutdown() are guaranteed to run.
 
 List of threads in the Renderer process:
-* cef.TID_RENDERER: The main thread in the renderer. Used for all webkit and V8 interaction.
+* cef.TID_RENDERER: Tasks may be posted to this thread after CefRenderProcessHandler::OnRenderThreadCreated but are not guaranteed to run before sub-process termination (sub-processes may be killed at any time without warning).
 
 
 ### PostDelayedTask

src/cef_v32..v51_changes.txt

@@ -0,0 +1,139 @@
+Changes in v31..v51.
+Not all changes are listed here.
+
+CefEnableHighDPISupport()
+
+CefRequestContext
+    NEW BROWSER SETTINGS that can be get/set using request context:
+        * GetAllPreferences - all preferences for browser's request context
+        * SetPreference
+        * many more methods has/get/canset...
+    _cef_request_context_settings_t:
+        cache_path
+        persist_session_cookies
+        persist_user_preferences
+        ignore_certificate_errors
+    PurgePluginListCache
+    GetDefaultCookieManager
+    GetCachePath
+    IsSharingWith - possible to create new context that shares
+                    storage with another context
+    more methods...
+
+CefRequestContextHandler
+    OnBeforePluginLoad
+
+CefBrowserSettings
+    windowless_frame_rate - **OSR**
+
+CefBrowserHost
+    GetNavigationEntries
+    PrintToPDF
+    ParentWindowWillClose() - REMOVED, update .py examples
+    SetWindowVisibility()
+    ShowDevTools(WindowInfo, CefClient, BrowserSettings, inspect_element_at)
+    CloseDevTools [DONE]
+    ReplaceMisspelling
+    AddWordToDictionary
+    Invalidate
+    NotifyMoveOrResizeStarted() - call in WM_MOVE, WM_MOVING, WM_SIZING on Win
+    GetWindowlessFrameRate - **OSR**
+    SetWindowlessFrameRate - **OSR**
+    DragTargetDragEnter
+    DragTargetDragOver
+    DragTargetDragLeave
+    DragTargetDrop
+    DragSourceEndedAt
+    DragSourceSystemDragEnded
+    HasDevTools
+    DownloadImage
+    HasView
+
+CefRequestHandler
+    OnOpenURLFromTab
+    OnBeforeResourceLoad - new arg CefRequestCallback
+    OnResourceResponse
+    GetResourceResponseFilter - easy way to alter response, no need for the
+                         complicated wxpython-response.py example (Issue #229)
+    OnResourceLoadComplete
+    OnCertificateError - new args: browser and ssl_info.
+                         No more need to set it using
+                         cefpython.SetGlobalClientCallback()
+    OnRenderViewReady
+
+Support for handling onbeforeunload in LifespanHandler::DoClose with
+the use of Browser.TryCloseBrowser() or Browser.CloseBrowser.
+
+CefRequest
+    SetReferrer
+    GetReferrerURL
+    GetReferrerPolicy
+    GetIdentifier
+
+CefResponse
+    GetError
+    SetError
+
+CEF exposes Views/Aura framework as an alternative API
+for client applications. This can be a replacement for
+WinAPI/GTK/X11/Cocoa UI frameworks. See for more info:
+https://bitbucket.org/chromiumembedded/cef/issues/1749
+
+CefPrintHandler - Linux only
+CefPrintSettings
+
+CefDisplayHandler
+    OnFaviconURLChange
+    OnFullscreenModeChange
+
+CefRenderHandler
+    OnCursorChange - new args: type and custom_cursor_info
+    StartDragging
+    UpdateDragCursor
+    OnScrollOffsetChanged - new args: x,y
+
+
+In upstream cefclient:
+1. g_signal_connect(G_OBJECT(window_), "configure-event",
+                    G_CALLBACK(&RootWindowGtk::WindowConfigure), this);
+   browser->GetHost()->NotifyMoveOrResizeStarted();
+2. g_signal_connect(G_OBJECT(window_), "focus-in-event",
+                    G_CALLBACK(&RootWindowGtk::WindowFocusIn), this);
+   self->browser_window_->SetFocus(true);
+
+When window is minimized set browser size to 0x0 to reduce resource usage.
+See cefclient:
+- on Windows see https://github.com/cztomczak/phpdesktop/issues/179
+- on Linux see root_window_gtk.cc > WindowState
+
+CefContextMenuHandler
+    RunContextMenu
+CefContextMenuParams
+    GetMisspelledWord
+    GetDictionarySuggestions
+    IsSpellCheckEnabled
+    IsCustomMenu
+    IsPepperMenu
+
+CefCompletionCallback - added to many cookie functions to run asynchronously
+                        on the IO thread
+
+include/cef_parser.h - url/css/json/etc parsers
+
+CefResourceBundle
+CefResponseFilter
+
+CefValue
+
+cef_get_current_platform_thread_id()
+cef_get_current_platform_thread_handle()
+
+cef_get_xdisplay();
+
+include/cef_ssl_info.h
+include/wrapper/cef_helpers.h - CefDeleteOnThread() free object on
+                                the specified thread
+include/wrapper/cef_resource_manager.h
+
+CefPostData
+    HasExcludedElements