CefDisplayHandler

Header: cef_display_handler.h
Category: Browser Handlers

Overview

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

CefDisplayHandler

Source File: include/cef_display_handler.h

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

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

Methods

void OnAddressChange(CefRefPtr<CefBrowser> browser, CefRefPtr<CefFrame> frame, const CefString& url)

Parameters:

• browser: The browser whose frame's address changed.
• frame: The frame whose address changed.
• url: The new URL.

Return Value: None.

Usage Instruction: Use to update the address bar / location indicator.

Threading Constraint: Called on the UI thread.

void OnTitleChange(CefRefPtr<CefBrowser> browser, const CefString& title)

Parameters:

• browser: The browser whose page title changed.
• title: The new page title (may be empty).

Return Value: None.

Usage Instruction: Use to update the host window's title bar.

Threading Constraint: Called on the UI thread.

void OnFaviconURLChange(CefRefPtr<CefBrowser> browser, const std::vector<CefString>& icon_urls)

Parameters:

• browser: The browser whose page icon URLs changed.
• icon_urls: The list of favicon URLs the page now advertises (may be empty).

Return Value: None.

Usage Instruction: Use to fetch and display the page favicon. Note these are URLs of icons declared in the document — the client is responsible for fetching/caching the image data.

Threading Constraint: Called on the UI thread.

void OnFullscreenModeChange(CefRefPtr<CefBrowser> browser, bool fullscreen)

Parameters:

• browser: The browser whose fullscreen state changed.
• fullscreen: true if entering fullscreen, false if exiting.

Return Value: None.

Usage Instruction: Triggered when web content toggles fullscreen via the Fullscreen API. With Alloy style, the client is responsible for triggering the actual fullscreen transition (e.g. call CefWindow::SetFullscreen when using Views). With Chrome style, the transition is triggered automatically. CefWindowDelegate::OnWindowFullscreenTransition is called during the transition for notification.

Threading Constraint: Called on the UI thread.

bool OnTooltip(CefRefPtr<CefBrowser> browser, CefString& text)

Parameters:

• browser: The browser about to display a tooltip.
• text: (In/out) The tooltip text the browser would display. May be modified.

Return Value: Return true to handle display of the tooltip yourself (suppress default). Return false (optionally after modifying text) to let the browser display the (possibly modified) tooltip. When window rendering is disabled (off-screen rendering), the application is responsible for drawing tooltips and the return value is ignored.

Usage Instruction: Use to translate, sanitize, or rewrite tooltip text, or to draw custom tooltips in OSR mode.

Threading Constraint: Called on the UI thread.

void OnStatusMessage(CefRefPtr<CefBrowser> browser, const CefString& value)

Parameters:

• browser: The browser receiving the status message.
• value: The status text (e.g. from window.status or link hover).

Return Value: None.

Usage Instruction: Use to update a status bar / link-hover indicator.

Threading Constraint: Called on the UI thread.

bool OnConsoleMessage(CefRefPtr<CefBrowser> browser, cef_log_severity_t level, const CefString& message, const CefString& source, int line)

Parameters:

• browser: The browser that produced the console message.
• level: cef_log_severity_t severity (INFO, WARNING, ERROR, etc.).
• message: The console message text.
• source: The source URL that produced the message (may be empty).
• line: The line number in source (may be 0).

Return Value: Return true to stop the message from being output to the default console. Return false to allow default output (and let your code process it in addition).

Usage Instruction: Use to redirect console output to your log system, or filter noisy messages.

Threading Constraint: Called on the UI thread.

bool OnAutoResize(CefRefPtr<CefBrowser> browser, const CefSize& new_size)

Parameters:

• browser: The browser that auto-resized.
• new_size: Desired size in DIP coordinates.

Return Value: Return true if the resize was handled (you adjusted the host). Return false for default handling.

Usage Instruction: Only called when auto-resize is enabled via CefBrowserHost::SetAutoResizeEnabled. Use to resize your host window to fit the page's preferred size.

Threading Constraint: Called on the UI thread.

void OnLoadingProgressChange(CefRefPtr<CefBrowser> browser, double progress)

Parameters:

• browser: The browser whose loading progress changed.
• progress: Overall page loading progress, ranging from 0.0 to 1.0.

Return Value: None.

Usage Instruction: Use to update a progress bar.

Threading Constraint: Called on the UI thread.

bool OnCursorChange(CefRefPtr<CefBrowser> browser, CefCursorHandle cursor, cef_cursor_type_t type, const CefCursorInfo& custom_cursor_info)

Parameters:

• browser: The browser whose cursor changed.
• cursor: OS-specific cursor handle.
• type: cef_cursor_type_t enum describing the cursor.
• custom_cursor_info: CefCursorInfo populated with custom cursor information when type == CT_CUSTOM.

Return Value: Return true if the cursor change was handled (you set your own cursor). Return false for default handling.

Usage Instruction: Mostly relevant for off-screen rendering (windowless) browsers where the application owns the cursor. In windowed rendering the browser sets the OS cursor itself.

Threading Constraint: Called on the UI thread.

void OnMediaAccessChange(CefRefPtr<CefBrowser> browser, bool has_video_access, bool has_audio_access)

Parameters:

• browser: The browser requesting its root window's screen rect.
• rect: (Out) Root window rectangle in screen DIP coordinates.

Return Value: Return true if rect was provided. Return false to use the root window bounds on Windows, or the browser content bounds on Linux.

Usage Instruction: Only called for windowed browsers on Windows and Linux. Used by OnContentsBoundsChange / OnCursorChange / screen-info calculations. See also CefBrowserHost::NotifyScreenInfoChanged.

Threading Constraint: Called on the UI thread. (API added at CEF 13700; guarded by #if CEF_API_ADDED(13700).)

Usage Example

#include "include/cef_display_handler.h"
#include "include/cef_client.h"

class MyDisplayHandler : public CefDisplayHandler {
 public:
  void OnAddressChange(CefRefPtr<CefBrowser> browser,
                       CefRefPtr<CefFrame> frame,
                       const CefString& url) override {
    // Update URL bar to |url|.
  }

  void OnTitleChange(CefRefPtr<CefBrowser> browser,
                     const CefString& title) override {
    // Set host window title to |title|.
  }

  void OnFaviconURLChange(CefRefPtr<CefBrowser> browser,
                          const std::vector<CefString>& icon_urls) override {
    // Fetch first icon_urls entry and update favicon UI.
  }

  void OnFullscreenModeChange(CefRefPtr<CefBrowser> browser,
                              bool fullscreen) override {
    // Alloy: call CefWindow::SetFullscreen on the containing window.
  }

  bool OnTooltip(CefRefPtr<CefBrowser> browser, CefString& text) override {
    // Return false to allow default tooltip.
    return false;
  }

  void OnStatusMessage(CefRefPtr<CefBrowser> browser,
                       const CefString& value) override {
    // Update status bar.
  }

  bool OnConsoleMessage(CefRefPtr<CefBrowser> browser,
                        cef_log_severity_t level,
                        const CefString& message,
                        const CefString& source,
                        int line) override {
    // Forward to your logger; return true to suppress default output.
    return false;
  }

  bool OnAutoResize(CefRefPtr<CefBrowser> browser,
                    const CefSize& new_size) override {
    return false;  // default handling
  }

  void OnLoadingProgressChange(CefRefPtr<CefBrowser> browser,
                                double progress) override {
    // Update progress bar (0.0 to 1.0).
  }

  bool OnCursorChange(CefRefPtr<CefBrowser> browser,
                      CefCursorHandle cursor,
                      cef_cursor_type_t type,
                      const CefCursorInfo& custom_cursor_info) override {
    return false;  // default
  }

  void OnMediaAccessChange(CefRefPtr<CefBrowser> browser,
                           bool has_video_access,
                           bool has_audio_access) override {
    // Toggle recording indicator.
  }

#if CEF_API_ADDED(13700)
  bool OnContentsBoundsChange(CefRefPtr<CefBrowser> browser,
                              const CefRect& new_bounds) override {
    return false;  // default handling (Views-hosted Chrome style only)
  }

  bool GetRootWindowScreenRect(CefRefPtr<CefBrowser> browser,
                               CefRect& rect) override {
    return false;  // use defaults
  }
#endif

  IMPLEMENT_REFCOUNTING(MyDisplayHandler);
};

class MyClient : public CefClient {
 public:
  CefRefPtr<CefDisplayHandler> GetDisplayHandler() override {
    return new MyDisplayHandler();
  }
};