CEF C++ Documentation

Appearance

CefRenderHandler ​

Header: cef_render_handler.h
Category: Browser Handlers

Overview ​

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

CefRenderHandler ​

Source File: include/cef_render_handler.h

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

Methods ​

CefRefPtr<CefAccessibilityHandler> GetAccessibilityHandler() ​

Parameters:

  • None.

Return Value: Returns the user's CefAccessibilityHandler (or nullptr to use the default implementation).

Usage Instruction: Override to supply a custom accessibility handler. Default returns nullptr.

Threading Constraint: Called on the UI thread.

bool GetRootScreenRect(CefRefPtr<CefBrowser> browser, CefRect& rect) ​

Parameters:

  • browser: The OSR browser.
  • rect: (Out) View rectangle in screen DIP coordinates. Must always be non-empty.

Return Value: None.

Usage Instruction: This is the most fundamental OSR callback — the browser needs to know how big its drawing surface is. Populate with the on-screen rectangle (origin and size in DIPs) of where the browser will be composited.

Threading Constraint: Called on the UI thread.

bool GetScreenPoint(CefRefPtr<CefBrowser> browser, int viewX, int viewY, int& screenX, int& screenY) ​

Parameters:

  • browser: The OSR browser.

Return Value: Return true if the requested coordinates were provided; otherwise false.

Usage Instruction: Used for popup placement and tooltip positioning.

Threading Constraint: Called on the UI thread.

bool GetScreenInfo(CefRefPtr<CefBrowser> browser, CefScreenInfo& screen_info) ​

Parameters:

  • browser: The OSR browser.
  • screen_info: (Out) CefScreenInfo structure containing device scale factor, screen rect, and available rect.

Return Value: Return true if screen_info was modified; otherwise false.

Usage Instruction: If the screen-info rectangle is left empty, the rectangle from GetViewRect is used. If still empty/invalid, popups may not be drawn correctly. Populate device_scale_factor for HiDPI rendering.

Threading Constraint: Called on the UI thread.

void OnPopupShow(CefRefPtr<CefBrowser> browser, bool show) ​

Parameters:

  • browser: The OSR browser.
  • show: true to show the popup widget; false to hide.

Return Value: None.

Usage Instruction: The browser wants to show/hide a popup (e.g. a <select> dropdown). The client is responsible for compositing the popup on top of the view (or hiding it).

Threading Constraint: Called on the UI thread.

void OnPopupSize(CefRefPtr<CefBrowser> browser, const CefRect& rect) ​

Parameters:

  • browser: The OSR browser.
  • type: PET_VIEW for the main view, PET_POPUP for the popup widget.
  • dirtyRects: Set of rectangles (in pixel coordinates) that need to be repainted.
  • buffer: Pixel data for the whole image (not just dirty rects). width*height*4 bytes, BGRA, upper-left origin. Scaled relative to view coordinates based on CefScreenInfo.device_scale_factor from GetScreenInfo.

Return Value: None.

Usage Instruction: This is the core OSR paint callback. The client must copy buffer to a texture, bitmap, or window surface. Only called when CefWindowInfo::shared_texture_enabled == false.

Threading Constraint: Called on the UI thread.

void OnAcceleratedPaint(CefRefPtr<CefBrowser> browser, PaintElementType type, const RectList& dirtyRects, const CefAcceleratedPaintInfo& info) ​

Parameters:

  • browser: The OSR browser.
  • type: PET_VIEW or PET_POPUP.
  • dirtyRects: Set of dirty rectangles in pixel coordinates.
  • info: CefAcceleratedPaintInfo containing the shared handle. On Windows, a HANDLE to a texture openable with D3D11 OpenSharedResource1 or D3D12 OpenSharedHandle. On macOS, an IOSurface* openable with Metal/OpenGL. On Linux, several planes each with an fd to the underlying system native buffer.

Return Value: None.

Usage Instruction: Called when an element has been rendered to a shared texture. The implementation uses a pool; the handle may differ each frame and cannot be cached or accessed outside this callback. Reopen it each call and copy its contents to a texture owned by the client. The contents of info are released back to the pool after this callback returns.

Threading Constraint: Called on the UI thread.

void GetTouchHandleSize(CefRefPtr<CefBrowser> browser, cef_horizontal_alignment_t orientation, CefSize& size) ​

Parameters:

  • browser: The OSR browser.
  • orientation: cef_horizontal_alignment_t (left or right) of the touch handle being queried.
  • size: (Out) Size of the touch handle in DIPs.

Return Value: None.

Usage Instruction: Used when the client is rendering touch selection handles; return the desired visual size of the handle.

Threading Constraint: Called on the UI thread.

void OnTouchHandleStateChanged(CefRefPtr<CefBrowser> browser, const CefTouchHandleState& state) ​

Parameters:

  • browser: The OSR browser.
  • state: New CefTouchHandleState for the touch handle(s).

Return Value: None.

Usage Instruction: The client is responsible for rendering the touch handles in OSR mode; update their visibility/position/state here.

Threading Constraint: Called on the UI thread.

bool StartDragging(CefRefPtr<CefBrowser> browser, CefRefPtr<CefDragData> drag_data, DragOperationsMask allowed_ops, int x, int y) ​

Parameters:

  • browser: The OSR browser.
  • drag_data: Contextual info about the dragged content.
  • allowed_ops: Bitmask of allowed drag operations (none, move, copy, link).

Return Value: Return false to abort the drag operation (and do NOT call any CefBrowserHost::DragSource*Ended* methods afterward). Return true to handle the drag operation; then call CefBrowserHost::DragSourceEndedAt and CefBrowserHost::DragSourceSystemDragEnded (synchronously or asynchronously) to inform the web view that the drag has ended.

Usage Instruction: OS message loops that run a system drag loop are allowed within this call. The client typically initiates a system drag-and-drop operation here.

Threading Constraint: Called on the UI thread.

void UpdateDragCursor(CefRefPtr<CefBrowser> browser, DragOperation operation) ​

Parameters:

  • browser: The OSR browser.
  • operation: cef_drag_operations_mask_t describing the allowed operation (none, move, copy, link).

Return Value: None.

Usage Instruction: Called when the web view wants to update the mouse cursor during a drag-and-drop operation (e.g. cursor changes to a "copy" cursor when over a valid drop target). Update your OS cursor accordingly.

Threading Constraint: Called on the UI thread.

void OnScrollOffsetChanged(CefRefPtr<CefBrowser> browser, double x, double y) ​

Parameters:

  • browser: The OSR browser.

Return Value: None.

Usage Instruction: Use to update scroll indicators or synchronize an external scroller.

Threading Constraint: Called on the UI thread.

void OnImeCompositionRangeChanged(CefRefPtr<CefBrowser> browser, const CefRange& selected_range, const RectList& character_bounds) ​

Parameters:

  • browser: The OSR browser.
  • selected_range: Range of characters that have been selected (for IME composition).
  • character_bounds: Bounds of each character, in view coordinates.

Return Value: None.

Usage Instruction: Use to position an IME candidate window in your custom UI.

Threading Constraint: Called on the UI thread.

void OnTextSelectionChanged(CefRefPtr<CefBrowser> browser, const CefString& selected_text, const CefRange& selected_range) ​

Parameters:

  • browser: The OSR browser.
  • selected_text: Currently selected text (may be empty).
  • selected_range: Character range of the selection.

Return Value: None.

Usage Instruction: Use to update a "copy" menu item's enabled state or to mirror selected text in a host UI.

Threading Constraint: Called on the UI thread.

void OnVirtualKeyboardRequested(CefRefPtr<CefBrowser> browser, TextInputMode input_mode) ​

Parameters:

  • browser: The OSR browser.
  • input_mode: cef_text_input_mode_t describing the kind of keyboard to open. If CEF_TEXT_INPUT_MODE_NONE, hide any existing keyboard for this browser.

Return Value: None.

Usage Instruction: Use to show/hide a custom on-screen keyboard (especially relevant on touch devices in OSR mode).

Threading Constraint: Called on the UI thread.

Usage Example ​

cpp
#include "include/cef_render_handler.h"
#include "include/cef_client.h"

class MyRenderHandler : public CefRenderHandler {
 public:
  // --- Required (pure virtual) ---
  void GetViewRect(CefRefPtr<CefBrowser> browser, CefRect& rect) override {
    rect = view_rect_;  // current on-screen rect in DIPs (must be non-empty)
  }

  void OnPaint(CefRefPtr<CefBrowser> browser,
               PaintElementType type,
               const RectList& dirtyRects,
               const void* buffer,
               int width,
               int height) override {
    // Copy BGRA buffer to your texture/bitmap (width*height*4 bytes).
    // type == PET_VIEW for main view, PET_POPUP for popup overlay.
  }

  // --- Optional overrides ---
  CefRefPtr<CefAccessibilityHandler> GetAccessibilityHandler() override {
    return nullptr;  // use default
  }

  bool GetRootScreenRect(CefRefPtr<CefBrowser> browser, CefRect& rect) override {
    return false;  // fall back to GetViewRect
  }

  bool GetScreenPoint(CefRefPtr<CefBrowser> browser,
                      int viewX, int viewY,
                      int& screenX, int& screenY) override {
    // Map view coords to screen coords using view_rect_ origin.
    screenX = view_rect_.x + viewX;
    screenY = view_rect_.y + viewY;
    return true;
  }

  bool GetScreenInfo(CefRefPtr<CefBrowser> browser,
                     CefScreenInfo& screen_info) override {
    screen_info.device_scale_factor = 1.0;
    screen_info.rect = view_rect_;
    screen_info.available_rect = view_rect_;
    return true;
  }

  void OnPopupShow(CefRefPtr<CefBrowser> browser, bool show) override {}
  void OnPopupSize(CefRefPtr<CefBrowser> browser, const CefRect& rect) override {
    popup_rect_ = rect;
  }

  void OnAcceleratedPaint(CefRefPtr<CefBrowser> browser,
                          PaintElementType type,
                          const RectList& dirtyRects,
                          const CefAcceleratedPaintInfo& info) override {
    // Re-open shared handle, copy to client-owned texture; never cache.
  }

  void GetTouchHandleSize(CefRefPtr<CefBrowser> browser,
                          cef_horizontal_alignment_t orientation,
                          CefSize& size) override {}
  void OnTouchHandleStateChanged(CefRefPtr<CefBrowser> browser,
                                 const CefTouchHandleState& state) override {}

  bool StartDragging(CefRefPtr<CefBrowser> browser,
                     CefRefPtr<CefDragData> drag_data,
                     DragOperationsMask allowed_ops,
                     int x, int y) override {
    return false;  // abort drag
  }

  void UpdateDragCursor(CefRefPtr<CefBrowser> browser,
                        DragOperation operation) override {}

  void OnScrollOffsetChanged(CefRefPtr<CefBrowser> browser,
                             double x, double y) override {}

  void OnImeCompositionRangeChanged(CefRefPtr<CefBrowser> browser,
                                    const CefRange& selected_range,
                                    const RectList& character_bounds) override {}

  void OnTextSelectionChanged(CefRefPtr<CefBrowser> browser,
                              const CefString& selected_text,
                              const CefRange& selected_range) override {}

  void OnVirtualKeyboardRequested(CefRefPtr<CefBrowser> browser,
                                  TextInputMode input_mode) override {}

 private:
  CefRect view_rect_ = CefRect(0, 0, 800, 600);
  CefRect popup_rect_;
  IMPLEMENT_REFCOUNTING(MyRenderHandler);
};

class MyClient : public CefClient {
 public:
  CefRefPtr<CefRenderHandler> GetRenderHandler() override {
    return new MyRenderHandler();
  }
};

Derived from the CEF C++ headers — © Marshall A. Greenblatt, Google Inc. & contributors (BSD-style license). Not an official CEF project.

Documentation curated & hosted by Ernest Tech House · owned by Pease Ernest