CefFrameHandler

Header: cef_frame_handler.h
Category: Browser Handlers

Overview

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

CefFrameHandler

Source File: include/cef_frame_handler.h

Process / Thread Context: Browser Process / UI Thread (class comment: "The

Purpose: User-implemented interface to handle events related to

Methods

void OnFrameCreated(CefRefPtr<CefBrowser> browser, CefRefPtr<CefFrame> frame)

Parameters:

• browser: The browser that owns the new frame.
• frame: The newly created frame object. This is the first notification that references this frame.

Return Value: None.

Usage Instruction: Any commands that require transport to the renderer (e.g. LoadRequest, SendProcessMessage, GetSource) will be queued until the frame is attached (or discarded before OnFrameDestroyed if it never attaches). Use this hook to register per-frame client-side state.

Threading Constraint: Called on the UI thread.

void OnFrameDestroyed(CefRefPtr<CefBrowser> browser, CefRefPtr<CefFrame> frame)

Parameters:

• browser: The browser that owns the frame.
• frame: The frame being destroyed. CefFrame::IsValid() will return false for frame. If called during browser destruction and after CefLifeSpanHandler::OnBeforeClose(), then CefBrowser::IsValid() will return false for browser.

Return Value: None.

Usage Instruction: This is the last notification that references frame. Drop any per-frame state here. Any queued commands not yet sent are discarded before this callback.

Threading Constraint: Called on the UI thread.

void OnFrameAttached(CefRefPtr<CefBrowser> browser, CefRefPtr<CefFrame> frame, bool reattached)

Parameters:

• browser: The browser that owns the frame.
• frame: The frame that has just become routable.
• reattached: true if the frame was re-attached after exiting the BackForwardCache or after a recoverable connection error.

Return Value: None.

Usage Instruction: Use to begin issuing commands to the frame — queued commands have now been dispatched. This method is not called for temporary frames created during cross-origin navigation.

Threading Constraint: Called on the UI thread.

void OnFrameDetached(CefRefPtr<CefBrowser> browser, CefRefPtr<CefFrame> frame)

Parameters:

• browser: The browser that owns the frame.
• frame: The frame that lost its renderer connection. CefFrame::IsValid() will return false if destruction is happening synchronously. During browser destruction after OnBeforeClose, CefBrowser::IsValid() returns false.

Return Value: None.

Usage Instruction: Triggers: frame destruction, BackForwardCache entry, or a rare connection error. If the same frame later exits BackForwardCache or recovers, a follow-up OnFrameAttached will fire. Sub-frame detach notifications are sent before main-frame detach during destruction. Not called for temporary cross-origin frames.

Threading Constraint: Called on the UI thread.

void OnMainFrameChanged(CefRefPtr<CefBrowser> browser, CefRefPtr<CefFrame> old_frame, CefRefPtr<CefFrame> new_frame)

Parameters:

• browser: The browser whose main frame changed.
• old_frame: NULL when a main frame is assigned for the first time; non-NULL otherwise.
• new_frame: NULL when the main frame is removed for the last time (final destruction); non-NULL otherwise. Both non-NULL during cross-origin navigation or re-navigation after renderer termination.

Return Value: None.

Usage Instruction: Triggers: (a) initial browser creation, (b) final browser destruction, (c) cross-origin navigation, (d) re-navigation after renderer process termination (e.g. after crashes). Called after OnFrameCreated for new_frame and/or after OnFrameDestroyed for old_frame. Use to track the "current" main frame for top-level state.

Threading Constraint: Called on the UI thread.

Usage Example

#include "include/cef_frame_handler.h"
#include "include/cef_client.h"

class MyFrameHandler : public CefFrameHandler {
 public:
  void OnFrameCreated(CefRefPtr<CefBrowser> browser,
                      CefRefPtr<CefFrame> frame) override {
    // Initialize per-frame state. Commands sent here are queued.
  }

  void OnFrameAttached(CefRefPtr<CefBrowser> browser,
                       CefRefPtr<CefFrame> frame,
                       bool reattached) override {
    // Safe to send commands to the frame now.
    if (frame->IsMain() && !reattached) {
      frame->ExecuteJavaScript("console.log('frame ready')", "", 0);
    }
  }

  void OnFrameDetached(CefRefPtr<CefBrowser> browser,
                       CefRefPtr<CefFrame> frame) override {
    // Stop sending commands; renderer connection lost.
  }

  void OnFrameDestroyed(CefRefPtr<CefBrowser> browser,
                        CefRefPtr<CefFrame> frame) override {
    // Final cleanup for this frame.
  }

  void OnMainFrameChanged(CefRefPtr<CefBrowser> browser,
                          CefRefPtr<CefFrame> old_frame,
                          CefRefPtr<CefFrame> new_frame) override {
    // Track the active main frame (e.g. update URL bar).
    main_frame_ = new_frame;
  }

 private:
  CefRefPtr<CefFrame> main_frame_;
  IMPLEMENT_REFCOUNTING(MyFrameHandler);
};

class MyClient : public CefClient {
 public:
  CefRefPtr<CefFrameHandler> GetFrameHandler() override {
    return new MyFrameHandler();
  }
};