pascal/CEF4Delphi
1
0
Fork 0
mirror of https://github.com/salvadordf/CEF4Delphi.git synced 2025-06-22 22:17:48 +02:00
Code Issues Actions 1 Releases Activity

Update to CEF 130.1.2

Browse Source
This commit is contained in:
Salvador Díaz Fau
2024-10-19 19:07:53 +02:00
parent 52bff28f3b
commit 0aebca3630
25 changed files with 1173 additions and 1622 deletions
Download Patch File Download Diff File Expand all files Collapse all files

75
docs/html/uCEFInterfaces.ICefLifeSpanHandler.html
View File

@ -109,23 +109,82 @@
</tr>
<tr><td colspan="2">
<p>
Called when a browser has received a request to close. This may result directly from a call to ICefBrowserHost.*CloseBrowser or indirectly if the browser is parented to a top-level window created by CEF and the user attempts to close that window (by clicking the 'X', for example). The DoClose function will be called after the JavaScript 'onunload' event has been fired.
<p>An application should handle top-level owner window close notifications by calling ICefBrowserHost.TryCloseBrowser or ICefBrowserHost.CloseBrowser(false) instead of allowing the window to close immediately (see the examples below). This gives CEF an opportunity to process the 'onbeforeunload' event and optionally cancel the close before DoClose is called.
<p>When windowed rendering is enabled CEF will internally create a window or view to host the browser. In that case returning false (0) from DoClose() will send the standard close notification to the browser's top-level owner window (e.g. WM_CLOSE on Windows, performClose: on OS X, &quot;delete_event&quot; on Linux or ICefWindowDelegate.CanClose callback from Views). If the browser's host window/view has already been destroyed (via view hierarchy tear-down, for example) then DoClose() will not be called for that browser since is no longer possible to cancel the close.
<p>Called when an Alloy style browser is ready to be closed, meaning that the close has already been initiated and that JavaScript unload handlers have already executed or should be ignored. This may result directly from a call to TChromiumCore.[Try]CloseBrowser() or indirectly if the browser's top-level parent window was created by CEF and the user attempts to close that window (by clicking the 'X', for example). TChromiumCore.OnClose will not be called if the browser's host window/view has already been destroyed (via parent window/view hierarchy tear-down, for example), as it is no longer possible to customize the close behavior at that point.
<p>When windowed rendering is disabled returning false (0) from DoClose() will cause the browser object to be destroyed immediately.
<p>An application should handle top-level parent window close notifications by calling TChromiumCore.TryCloseBrowser() or TChromiumCore.CloseBrowser(false) instead of allowing the window to close immediately (see the examples below). This gives CEF an opportunity to process JavaScript unload handlers and optionally cancel the close before TChromiumCore.OnClose is called.
<p>If the browser's top-level owner window requires a non-standard close notification then send that notification from DoClose() and return true (1).
<p>When windowed rendering is enabled CEF will create an internal child window/view to host the browser. In that case returning false (0) from TChromiumCore.OnClose will send the standard close notification to the browser's top- level parent window (e.g. WM_CLOSE on Windows, performClose: on OS X, &quot;delete_event&quot; on Linux or TCEFWindowComponent.OnCanClose callback from Views).
<p>The ICefLifeSpanHandler.OnBeforeClose function will be called after DoClose() (if DoClose() is called) and immediately before the browser object is destroyed. The application should only exit after OnBeforeClose() has been called for all existing browsers.
<p>When windowed rendering is disabled there is no internal window/view and returning false (0) from TChromiumCore.OnClose will cause the browser object to be destroyed immediately.
<p>If the browser's top-level parent window requires a non-standard close notification then send that notification from TChromiumCore.OnClose and return true (1). You are still required to complete the browser close as soon as possible (either by calling TChromiumCore.[Try]CloseBrowser() or by proceeding with window/view hierarchy tear-down), otherwise the browser will be left in a partially closed state that interferes with proper functioning. Top-level windows created on the browser process UI thread can alternately call TChromiumCore.IsReadyToBeClosed() in the close handler to check close status instead of relying on custom TChromiumCore.OnClose handling. See documentation on that function for additional details.
<p>The TChromiumCore.OnBeforeClose event will be called after TChromiumCore.OnClose (if TChromiumCore.OnClose is called) and immediately before the browser object is destroyed. The application should only exit after TChromiumCore.OnBeforeClose has been called for all existing browsers.
<p>The below examples describe what should happen during window close when the browser is parented to an application-provided top-level window.
<p>Example 1: Using ICefBrowserHost.TryCloseBrowser(). This is recommended for clients using standard close handling and windows created on the browser process UI thread. 1. User clicks the window close button which sends a close notification to the application's top-level window. 2. Application's top-level window receives the close notification and calls TryCloseBrowser() (which internally calls CloseBrowser(false)). TryCloseBrowser() returns false so the client cancels the window close. 3. JavaScript 'onbeforeunload' handler executes and shows the close confirmation dialog (which can be overridden via ICefJSDialogHandler.OnBeforeUnloadDialog()). 4. User approves the close. 5. JavaScript 'onunload' handler executes. 6. CEF sends a close notification to the application's top-level window (because DoClose() returned false by default). 7. Application's top-level window receives the close notification and calls TryCloseBrowser(). TryCloseBrowser() returns true so the client allows the window close. 8. Application's top-level window is destroyed. 9. Application's OnBeforeClose() handler is called and the browser object is destroyed. 10. Application exits by calling cef_quit_message_loop() if no other browsers exist.
<p>Example 1: Using TChromiumCore.TryCloseBrowser(). This is recommended for clients using standard close handling and windows created on the browser process UI thread.
<p>Example 2: Using ICefBrowserHost::CloseBrowser(false) and implementing the DoClose() callback. This is recommended for clients using non-standard close handling or windows that were not created on the browser process UI thread. 1. User clicks the window close button which sends a close notification to the application's top-level window. 2. Application's top-level window receives the close notification and: A. Calls ICefBrowserHost.CloseBrowser(false). B. Cancels the window close. 3. JavaScript 'onbeforeunload' handler executes and shows the close confirmation dialog (which can be overridden via ICefJSDialogHandler.OnBeforeUnloadDialog()). 4. User approves the close. 5. JavaScript 'onunload' handler executes. 6. Application's DoClose() handler is called. Application will: A. Set a flag to indicate that the next close attempt will be allowed. B. Return false. 7. CEF sends an close notification to the application's top-level window. 8. Application's top-level window receives the close notification and allows the window to close based on the flag from #6B. 9. Application's top-level window is destroyed. 10. Application's OnBeforeClose() handler is called and the browser object is destroyed. 11. Application exits by calling cef_quit_message_loop() if no other browsers exist. </p>
<p></p>
<pre class="preformatted">
1. User clicks the window close button which sends a close notification
to the application's top-level window.
2. Application's top-level window receives the close notification and
calls TChromiumCore.TryCloseBrowser() (similar to calling TChromiumCore.CloseBrowser(false)).
TChromiumCore.TryCloseBrowser() returns false so the client cancels the window
close.
3. JavaScript 'onbeforeunload' handler executes and shows the close
confirmation dialog (which can be overridden via TChromiumCore.OnBeforeUnloadDialog).
4. User approves the close.
5. JavaScript 'onunload' handler executes.
6. Application's TChromiumCore.OnClose handler is called and returns false (0) by
default.
7. CEF sends a close notification to the application's top-level window
(because TChromiumCore.OnClose returned false).
8. Application's top-level window receives the close notification and
calls TryCloseBrowser(). TryCloseBrowser() returns true so the client
allows the window close.
9. Application's top-level window is destroyed, triggering destruction
of the child browser window.
10. Application's TChromiumCore.OnBeforeClose handler is called and the browser object
is destroyed.
11. Application exits by calling TCefApplicationCore.QuitMessageLoop if no other browsers
exist.</pre>
<p>
<p>Example 2: Using TChromiumCore.CloseBrowser(false) and implementing the TChromiumCore.OnClose event. This is recommended for clients using non-standard close handling or windows that were not created on the browser process UI thread.
<p></p>
<pre class="preformatted">
1. User clicks the window close button which sends a close notification
to the application's top-level window.
2. Application's top-level window receives the close notification and:
A. Calls ICefBrowserHost.CloseBrowser(false).
B. Cancels the window close.
3. JavaScript 'onbeforeunload' handler executes and shows the close
confirmation dialog (which can be overridden via TChromiumCore.OnBeforeUnloadDialog).
4. User approves the close.
5. JavaScript 'onunload' handler executes.
6. Application's TChromiumCore.OnClose handler is called. Application will:
A. Set a flag to indicate that the next top-level window close attempt
will be allowed.
B. Return false.
7. CEF sends a close notification to the application's top-level window
(because TChromiumCore.OnClose returned false).
8. Application's top-level window receives the close notification and
allows the window to close based on the flag from #6A.
9. Application's top-level window is destroyed, triggering destruction
of the child browser window.
10. Application's TChromiumCore.OnBeforeClose handler is called and the browser object
is destroyed.
11. Application exits by calling TCefApplicationCore.QuitMessageLoop if no other browsers exist.</pre>
<p> </p>
</td></tr>
</table>
<table class="detail wide_list">