Skip to content

Commit f5f678d

Browse files
cztomczakcztomczak
committed
Update API docs and create a log of CEF changes in regards v66 update
1 parent 9306e89 commit f5f678d

File tree

11 files changed

+353
-204
lines changed

11 files changed

+353
-204
lines changed

‎api/ApplicationSettings.md‎

Lines changed: 9 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -107,10 +107,15 @@ Example values that can be set in Win7 DPI settings (Control Panel Appearance an
107107
### background_color
108108

109109
(int)
110-
Opaque background color used for accelerated content. By default the
111-
background color will be white. Only the RGB compontents of the specified
112-
value will be used. The alpha component must greater than 0 to enable use
113-
of the background color but will be otherwise ignored.
110+
Description from upstream CEF:
111+
> Background color used for the browser before a document is loaded and when
112+
> no document color is specified. The alpha component must be either fully
113+
> opaque (0xFF) or fully transparent (0x00). If the alpha component is fully
114+
> opaque then the RGB components will be used as the background color. If the
115+
> alpha component is fully transparent for a windowed browser then the
116+
> default value of opaque white be used. If the alpha component is fully
117+
> transparent for a windowless (off-screen) browser then transparent painting
118+
> will be enabled.
114119
115120
32-bit ARGB color value, not premultiplied. The color components are always
116121
in a known order. Equivalent to the `SkColor` type.

‎api/Browser.md‎

Lines changed: 13 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -313,15 +313,24 @@ Calling javascript from native code synchronously is not possible in CEF 3. It i
313313

314314
| Parameter | Type |
315315
| --- | --- |
316-
| searchID | int |
316+
| searchId | int |
317317
| searchText | string |
318318
| forward | bool |
319319
| matchCase | bool |
320320
| findNext | bool |
321321
| __Return__ | void |
322322

323-
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.
323+
Description from upstream CEF:
324324

325+
> Search for |searchText|. |identifier| must be a unique ID and these IDs
326+
> must strictly increase so that newer requests always have greater IDs than
327+
> older requests. If |identifier| is zero or less than the previous ID value
328+
> then it will be automatically assigned a new valid ID. |forward| indicates
329+
> whether to search forward or backward within the page. |matchCase|
330+
> indicates whether the search should be case-sensitive. |findNext| indicates
331+
> whether this is the first request or a follow-up. The CefFindHandler
332+
> instance, if any, returned via CefClient::GetFindHandler will be called to
333+
> report find results.
325334
326335
### GetClientCallback
327336

@@ -493,7 +502,8 @@ Returns an inner or outer window handle for the browser. If the browser was crea
493502
| --- | --- |
494503
| __Return__ | int |
495504

496-
Returns the globally unique identifier for this browser.
505+
Returns the globally unique identifier for this browser. This value is also
506+
used as the tabId for extension APIs.
497507

498508

499509
### GetZoomLevel

‎api/BrowserSettings.md‎

Lines changed: 9 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -77,12 +77,15 @@ empty then "en-US,en" will be used.
7777
### background_color
7878

7979
(int)
80-
Opaque background color used for the browser before a document is loaded
81-
and when no document color is specified. By default the background color
82-
will be the same as CefSettings.background_color. Only the RGB compontents
83-
of the specified value will be used. The alpha component must greater than
84-
0 to enable use of the background color but will be otherwise ignored.
85-
80+
Description from upstream CEF:
81+
> Background color used for the browser before a document is loaded and when
82+
> no document color is specified. The alpha component must be either fully
83+
> opaque (0xFF) or fully transparent (0x00). If the alpha component is fully
84+
> opaque then the RGB components will be used as the background color. If the
85+
> alpha component is fully transparent for a windowed browser then the
86+
> CefSettings.background_color value will be used. If the alpha component is
87+
> fully transparent for a windowless (off-screen) browser then transparent
88+
> painting will be enabled.
8689
8790
### databases_disabled
8891

‎api/DragData.md‎

Lines changed: 7 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -81,10 +81,12 @@ Return the text/html fragment that is being dragged.
8181
| --- | --- |
8282
| __Return__ | [Image](Image.md) |
8383

84-
Linux-only currently (#251).
84+
Description from upstream CEF:
85+
> Get the image representation of drag data. May return NULL if no image
86+
> representation is available.
8587
86-
Get image representation of drag data. Check with HasImage() first,
87-
otherwise if there is no image an exception is thrown.
88+
Check with HasImage() first, otherwise if there is no image an exception
89+
is thrown.
8890

8991

9092
### GetImageHotspot
@@ -93,9 +95,7 @@ otherwise if there is no image an exception is thrown.
9395
| --- | --- |
9496
| __Return__ | [Image](Image.md) |
9597

96-
Linux-only currently (#251).
97-
98-
Get image hotspot (drag start location relative to image dimensions).
98+
Get the image hotspot (drag start location relative to image dimensions).
9999

100100

101101
### HasImage
@@ -104,7 +104,5 @@ Get image hotspot (drag start location relative to image dimensions).
104104
| --- | --- |
105105
| __Return__ | bool |
106106

107-
Linux-only currently (#251).
108-
109-
Whether image representation of drag data is available.
107+
Returns true if an image representation of drag data is available.
110108

‎api/LifespanHandler.md‎

Lines changed: 21 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -36,24 +36,27 @@ Table of contents:
3636
| no_javascript_access_out | list[bool] |
3737
| __Return__ | bool |
3838

39-
Called on the IO thread before a new popup browser is created. The
40-
|browser| and |frame| values represent the source of the popup request. The
41-
|target_url| and |target_frame_name| values indicate where the popup
42-
browser should navigate and may be empty if not specified with the request.
43-
The |target_disposition| value indicates where the user intended to open
44-
the popup (e.g. current tab, new tab, etc). The |user_gesture| value will
45-
be true if the popup was opened via explicit user gesture (e.g. clicking a
46-
link) or false if the popup opened automatically (e.g. via the
47-
DomContentLoaded event). The |popup_features| structure contains additional
48-
information about the requested popup window. To allow creation of the
49-
popup browser optionally modify |windowInfo|, |client|, |browserSettings| and
50-
|no_javascript_access| and return false. To cancel creation of the popup
51-
browser return true. The |client| and |settings| values will default to the
52-
source browser's values. If the |no_javascript_access| value is set to
53-
false the new browser will not be scriptable and may not be hosted in the
54-
same renderer process as the source browser. Any modifications to
55-
|window_info| will be ignored if the parent browser is wrapped in a
56-
CefBrowserView.
39+
Description from upstream CEF:
40+
> Called on the UI thread before a new popup browser is created. The
41+
> |browser| and |frame| values represent the source of the popup request. The
42+
> |target_url| and |target_frame_name| values indicate where the popup
43+
> browser should navigate and may be empty if not specified with the request.
44+
> The |target_disposition| value indicates where the user intended to open
45+
> the popup (e.g. current tab, new tab, etc). The |user_gesture| value will
46+
> be true if the popup was opened via explicit user gesture (e.g. clicking a
47+
> link) or false if the popup opened automatically (e.g. via the
48+
> DomContentLoaded event). The |popup_features| structure contains additional
49+
> information about the requested popup window. To allow creation of the
50+
> popup browser optionally modify |windowInfo|, |client|, |browserSettings| and
51+
> |no_javascript_access| and return false. To cancel creation of the popup
52+
> browser return true. The |client| and |settings| values will default to the
53+
> source browser's values. If the |no_javascript_access| value is set to
54+
> false the new browser will not be scriptable and may not be hosted in the
55+
> same renderer process as the source browser. Any modifications to
56+
> |window_info| will be ignored if the parent browser is wrapped in a
57+
> CefBrowserView. Popup browser creation will be canceled if the parent
58+
> browser is destroyed before the popup browser creation completes (indicated
59+
> by a call to OnAfterCreated for the popup browser).
5760
5861
Note that if you return True and create the popup window yourself, then
5962
the popup window and parent window will not be able to script each other.

‎api/Request.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -170,6 +170,9 @@ Available flags (access via `cefpython.Request.Flags["xxx"]`):
170170

171171
* **None** - Default behavior.
172172
* **SkipCache** - If set the cache will be skipped when handling the request.
173+
Setting this value is equivalent to specifying the "Cache-Control: no-cache"
174+
request header. Setting this value in combination with UR_FLAG_ONLY_FROM_CACHE
175+
will cause the request to fail.
173176
* **AllowCachedCredentials** - If set user name, password, and cookies may be
174177
sent with the request, and cookies may be saved from the response.
175178
* **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"]`):
185188
| __Return__ | void |
186189

187190
Set the flags used in combination with [WebRequest](WebRequest.md).
191+
See GetFlags() for possible values.
188192

189193

190194
### GetFirstPartyForCookies

‎api/WindowInfo.md‎

Lines changed: 5 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -58,13 +58,14 @@ CefRenderHandler interface. The |parent| value will be used to identify
5858
monitor info and to act as the parent window for dialogs, context menus,
5959
etc. If |parent| is not provided then the main screen monitor will be used
6060
and some functionality that requires a parent window may not function
61-
correctly. If |transparent| is true a transparent background color will be
62-
used (RGBA=0x00000000). If |transparent| is false the background will be
63-
white and opaque. In order to create windowless browsers the
61+
correctly. In order to create windowless browsers the
6462
CefSettings.windowless_rendering_enabled value must be set to true.
63+
Transparent painting is enabled by default but can be disabled by setting
64+
CefBrowserSettings.background_color to an opaque value.
6565

6666
Call this method to disable windowed rendering and to use
67-
[RenderHandler](RenderHandler.md). See the Panda3D and Kivy examples.
67+
[RenderHandler](RenderHandler.md). See the pysdl2, screenshot, panda3d
68+
and kivy examples.
6869

6970
In order to create windowless browsers the
7071
ApplicationSettings.[windowless_rendering_enabled](ApplicationSettings.md#windowless_rendering_enabled)
@@ -73,12 +74,3 @@ value must be set to true.
7374
You can pass 0 as `parentWindowHandle`, but then some things like
7475
context menus and plugins may not display correctly.
7576

76-
77-
### SetTransparentPainting
78-
79-
| Parameter | Type |
80-
| --- | --- |
81-
| transparentPainting | bool |
82-
| __Return__ | void |
83-
84-
This method is intended for use with off-screen rendering only.

‎api/cefpython.md‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -240,16 +240,16 @@ Post a task for execution on the thread associated with this task runner. Execut
240240
An example usage is in the wxpython.py example on Windows, in implementation of LifespanHandler.OnBeforePopup().
241241

242242
List of threads in the Browser process:
243-
* 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.
243+
* 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.
244244
* cef.TID_DB: Used to interact with the database.
245-
* cef.TID_FILE: Used to interact with the file system.
246-
* cef.TID_FILE_USER_BLOCKING: Used for file system operations that block user interactions. Responsiveness of this thread affects users.
245+
* 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.
246+
* 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.
247247
* cef.TID_PROCESS_LAUNCHER: Used to launch and terminate browser processes.
248248
* cef.TID_CACHE: Used to handle slow HTTP cache operations.
249-
* cef.TID_IO: Used to process IPC and network messages.
249+
* 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.
250250

251251
List of threads in the Renderer process:
252-
* cef.TID_RENDERER: The main thread in the renderer. Used for all webkit and V8 interaction.
252+
* 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).
253253

254254

255255
### PostDelayedTask

‎src/cef_v32..v51_changes.txt‎

Lines changed: 139 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,139 @@
1+
Changes in v31..v51.
2+
Not all changes are listed here.
3+
4+
CefEnableHighDPISupport()
5+
6+
CefRequestContext
7+
NEW BROWSER SETTINGS that can be get/set using request context:
8+
* GetAllPreferences - all preferences for browser's request context
9+
* SetPreference
10+
* many more methods has/get/canset...
11+
_cef_request_context_settings_t:
12+
cache_path
13+
persist_session_cookies
14+
persist_user_preferences
15+
ignore_certificate_errors
16+
PurgePluginListCache
17+
GetDefaultCookieManager
18+
GetCachePath
19+
IsSharingWith - possible to create new context that shares
20+
storage with another context
21+
more methods...
22+
23+
CefRequestContextHandler
24+
OnBeforePluginLoad
25+
26+
CefBrowserSettings
27+
windowless_frame_rate - **OSR**
28+
29+
CefBrowserHost
30+
GetNavigationEntries
31+
PrintToPDF
32+
ParentWindowWillClose() - REMOVED, update .py examples
33+
SetWindowVisibility()
34+
ShowDevTools(WindowInfo, CefClient, BrowserSettings, inspect_element_at)
35+
CloseDevTools [DONE]
36+
ReplaceMisspelling
37+
AddWordToDictionary
38+
Invalidate
39+
NotifyMoveOrResizeStarted() - call in WM_MOVE, WM_MOVING, WM_SIZING on Win
40+
GetWindowlessFrameRate - **OSR**
41+
SetWindowlessFrameRate - **OSR**
42+
DragTargetDragEnter
43+
DragTargetDragOver
44+
DragTargetDragLeave
45+
DragTargetDrop
46+
DragSourceEndedAt
47+
DragSourceSystemDragEnded
48+
HasDevTools
49+
DownloadImage
50+
HasView
51+
52+
CefRequestHandler
53+
OnOpenURLFromTab
54+
OnBeforeResourceLoad - new arg CefRequestCallback
55+
OnResourceResponse
56+
GetResourceResponseFilter - easy way to alter response, no need for the
57+
complicated wxpython-response.py example (Issue #229)
58+
OnResourceLoadComplete
59+
OnCertificateError - new args: browser and ssl_info.
60+
No more need to set it using
61+
cefpython.SetGlobalClientCallback()
62+
OnRenderViewReady
63+
64+
Support for handling onbeforeunload in LifespanHandler::DoClose with
65+
the use of Browser.TryCloseBrowser() or Browser.CloseBrowser.
66+
67+
CefRequest
68+
SetReferrer
69+
GetReferrerURL
70+
GetReferrerPolicy
71+
GetIdentifier
72+
73+
CefResponse
74+
GetError
75+
SetError
76+
77+
CEF exposes Views/Aura framework as an alternative API
78+
for client applications. This can be a replacement for
79+
WinAPI/GTK/X11/Cocoa UI frameworks. See for more info:
80+
https://bitbucket.org/chromiumembedded/cef/issues/1749
81+
82+
CefPrintHandler - Linux only
83+
CefPrintSettings
84+
85+
CefDisplayHandler
86+
OnFaviconURLChange
87+
OnFullscreenModeChange
88+
89+
CefRenderHandler
90+
OnCursorChange - new args: type and custom_cursor_info
91+
StartDragging
92+
UpdateDragCursor
93+
OnScrollOffsetChanged - new args: x,y
94+
95+
96+
In upstream cefclient:
97+
1. g_signal_connect(G_OBJECT(window_), "configure-event",
98+
G_CALLBACK(&RootWindowGtk::WindowConfigure), this);
99+
browser->GetHost()->NotifyMoveOrResizeStarted();
100+
2. g_signal_connect(G_OBJECT(window_), "focus-in-event",
101+
G_CALLBACK(&RootWindowGtk::WindowFocusIn), this);
102+
self->browser_window_->SetFocus(true);
103+
104+
When window is minimized set browser size to 0x0 to reduce resource usage.
105+
See cefclient:
106+
- on Windows see https://github.com/cztomczak/phpdesktop/issues/179
107+
- on Linux see root_window_gtk.cc > WindowState
108+
109+
CefContextMenuHandler
110+
RunContextMenu
111+
CefContextMenuParams
112+
GetMisspelledWord
113+
GetDictionarySuggestions
114+
IsSpellCheckEnabled
115+
IsCustomMenu
116+
IsPepperMenu
117+
118+
CefCompletionCallback - added to many cookie functions to run asynchronously
119+
on the IO thread
120+
121+
include/cef_parser.h - url/css/json/etc parsers
122+
123+
CefResourceBundle
124+
CefResponseFilter
125+
126+
CefValue
127+
128+
cef_get_current_platform_thread_id()
129+
cef_get_current_platform_thread_handle()
130+
131+
cef_get_xdisplay();
132+
133+
include/cef_ssl_info.h
134+
include/wrapper/cef_helpers.h - CefDeleteOnThread() free object on
135+
the specified thread
136+
include/wrapper/cef_resource_manager.h
137+
138+
CefPostData
139+
HasExcludedElements

0 commit comments

Comments
 (0)