CefLifeSpanHandler

Header: cef_life_span_handler.h
Category: Browser Handlers

Overview

User-implemented handler interfaces returned from CefClient and registered with CefBrowserHost.

CefLifeSpanHandler

Source File: include/cef_life_span_handler.h

Process / Thread Context: Browser Process / UI Thread (class-level comment:

Purpose: User-implemented interface to handle events related to browser

Methods

bool OnBeforePopup(CefRefPtr<CefBrowser> browser, CefRefPtr<CefFrame> frame, int popup_id, const CefString& target_url, const CefString& target_frame_name, WindowOpenDisposition target_disposition, bool user_gesture, const CefPopupFeatures& popupFeatures, CefWindowInfo& windowInfo, CefRefPtr<CefClient>& client, CefBrowserSettings& settings, CefRefPtr<CefDictionaryValue>& extra_info, bool* no_javascript_access)

Parameters:

• browser: The opener browser (source of the popup request).
• frame: The opener frame (source frame in the opener browser).
• popup_id: Unique identifier for the popup within the context of the opener browser.
• target_url: URL the popup should navigate to; may be empty.
• target_frame_name: Target frame name; may be empty.
• target_disposition: Where the user intended to open the popup (current tab, new tab, etc.).
• user_gesture: true if opened via explicit user gesture (e.g. clicking a link); false if opened automatically (e.g. on DOMContentLoaded).
• popupFeatures: Additional popup window information.
• windowInfo: (In/out) CefWindowInfo describing the parent / popup window; user may modify. Ignored if the parent is wrapped in a CefBrowserView.
• client: (In/out) CefRefPtr<CefClient> to attach; defaults to the source browser's client; user may replace.
• settings: (In/out) CefBrowserSettings for the new popup; defaults to source browser's; user may modify.
• extra_info: (In/out) CefRefPtr<CefDictionaryValue> forwarded to CefRenderProcessHandler::OnBrowserCreated() in the renderer process.
• no_javascript_access: (Out) If set to false, the new browser will not be scriptable and may not share the source renderer process.

Return Value: Return true to cancel creation of the popup browser. Return false (after optionally modifying windowInfo, client, settings, extra_info, no_javascript_access) to allow creation to proceed. If creation succeeds, OnAfterCreated is called for the new popup; if it fails (and the opener still exists), OnBeforePopupAborted is called for the opener.

Usage Instruction: Use to intercept window.open() / target=_blank navigations; customize popup window geometry, client, or settings; block unwanted popups; or pass extra info to the renderer process for the new browser. If you return false without setting a parent window handle (native-hosted) or without implementing CefBrowserViewDelegate::OnPopupBrowserViewCreated (Views), a default popup window is created.

Threading Constraint: Called on the UI thread.

void OnBeforePopupAborted(CefRefPtr<CefBrowser> browser, int popup_id)

Parameters:

• browser: The opener (source) browser.
• popup_id: The same popup_id value that was passed to OnBeforePopup for this popup.

Return Value: None.

Usage Instruction: Called only when a popup was allowed in OnBeforePopup but creation failed before OnAfterCreated ran. Use it to clear any client state associated with the pending popup. Note: OnBeforeClose of the opener may have already fired (e.g. opener is closing during popup creation); in that case CefBrowserHost::IsValid will return false here.

Threading Constraint: Called on the UI thread.

void OnBeforeDevToolsPopup(CefRefPtr<CefBrowser> browser, CefWindowInfo& windowInfo, CefRefPtr<CefClient>& client, CefBrowserSettings& settings, CefRefPtr<CefDictionaryValue>& extra_info, bool* use_default_window)

Parameters:

• browser: The source browser that triggered the DevTools popup.
• windowInfo: (In/out) CefWindowInfo; modifications ignored if parent is Views-hosted.
• client: (In/out) CefRefPtr<CefClient>; defaults to source browser's.
• settings: (In/out) CefBrowserSettings; defaults to source browser's.
• extra_info: (In/out) CefRefPtr<CefDictionaryValue>; existing object is read-only but may be replaced; forwarded to the renderer's OnBrowserCreated.
• use_default_window: (Out) For Views-hosted source browsers, set to true to force a native default window rather than a Views-hosted DevTools popup.

Return Value: None.

Usage Instruction: Use to customize DevTools popup window, client, settings, or to pass extra info to the renderer. DevTools popups can also be blocked entirely by returning true from CefCommandHandler::OnChromeCommand for IDC_DEV_TOOLS. Only used with Chrome style.

Threading Constraint: Called on the UI thread.

void OnAfterCreated(CefRefPtr<CefBrowser> browser)

Parameters:

• browser: The newly created browser. It is now safe to perform actions on it.

Return Value: None.

Usage Instruction: This is the canonical "browser is ready" hook. Store the CefRefPtr<CefBrowser> in your client/state object here (so you can call methods on it later). Note that CefFrameHandler callbacks for initial main frame creation arrive before this callback.

Threading Constraint: Called on the UI thread (implicit from class comment).

bool DoClose(CefRefPtr<CefBrowser> browser)

Parameters:

• browser: The Alloy-style browser that is ready to be closed. JavaScript unload handlers have already executed (or should be ignored).

Return Value: Return false to send the standard close notification to the browser's top-level parent window (windowed rendering) — e.g. WM_CLOSE on Windows, performClose: on macOS, delete_event on Linux, or CefWindowDelegate::CanClose() from Views — or to destroy the browser object immediately (off-screen rendering). Return true to suppress the standard notification; in that case you must still complete the close yourself by calling [Try]CloseBrowser() or proceeding with window/view tear-down.

Usage Instruction: This is the close-customization hook. With windowed rendering the standard pattern is: app's top-level window close handler calls CefBrowserHost::TryCloseBrowser() or CloseBrowser(false), JavaScript onbeforeunload runs (can be overridden via CefJSDialogHandler::OnBeforeUnloadDialog), DoClose() fires, and you typically return false. With off-screen rendering there is no internal window and returning false destroys the browser immediately. For non-standard close notifications, send your own from here and return true.

Threading Constraint: Called on the UI thread. Not called if the host window/view has already been destroyed (e.g. parent tear-down).

void OnBeforeClose(CefRefPtr<CefBrowser> browser)

Parameters:

• browser: The browser that is about to be destroyed.

Return Value: None.

Usage Instruction: This is the canonical "browser is gone" hook. Release all references to the browser object here; do not call any methods other than IsValid, GetIdentifier, or IsSame after this callback returns. The application should only exit after OnBeforeClose has been called for all existing browsers. Any in-progress network requests are aborted; CefResourceRequestHandler callbacks for those may still arrive on the IO thread after this callback.

Threading Constraint: Called on the UI thread.

Usage Example

#include "include/cef_life_span_handler.h"
#include "include/cef_client.h"

class MyLifeSpanHandler : public CefLifeSpanHandler {
 public:
  MyLifeSpanHandler() = default;

  bool OnBeforePopup(CefRefPtr<CefBrowser> browser,
                     CefRefPtr<CefFrame> frame,
                     int popup_id,
                     const CefString& target_url,
                     const CefString& target_frame_name,
                     WindowOpenDisposition target_disposition,
                     bool user_gesture,
                     const CefPopupFeatures& popupFeatures,
                     CefWindowInfo& windowInfo,
                     CefRefPtr<CefClient>& client,
                     CefBrowserSettings& settings,
                     CefRefPtr<CefDictionaryValue>& extra_info,
                     bool* no_javascript_access) override {
    // Block all popups.
    return true;
  }

  void OnAfterCreated(CefRefPtr<CefBrowser> browser) override {
    browser_ = browser;  // store for later use
  }

  bool DoClose(CefRefPtr<CefBrowser> browser) override {
    // Allow standard close handling.
    return false;
  }

  void OnBeforeClose(CefRefPtr<CefBrowser> browser) override {
    browser_ = nullptr;
    // If this was the last browser, exit the message loop:
    // CefQuitMessageLoop();
  }

 private:
  CefRefPtr<CefBrowser> browser_;
  IMPLEMENT_REFCOUNTING(MyLifeSpanHandler);
  DISALLOW_COPY_AND_ASSIGN(MyLifeSpanHandler);
};

// Returned from CefClient:
class MyClient : public CefClient {
 public:
  CefRefPtr<CefLifeSpanHandler> GetLifeSpanHandler() override {
    return new MyLifeSpanHandler();
  }
};

See Also

• cef_browser
• cef_client
• cef_frame_handler