CefApp

Header: cef_app.h
Sections: CefScopedSetNestableTasksAllowed, CefApp (+1 more)
Category: Core APIs

Overview

Foundational interfaces: process bootstrap, browser lifecycle, frames, DOM, requests, and data objects.

Free Functions — Process Bootstrap & Message Loop

Source File: include/cef_app.h

Process / Thread Context: CEF UI thread.

Purpose: "Set to true before calling OS APIs on the CEF UI thread that will enter a native message loop. Set to false after exiting the native message loop." Re-enables nested Chromium task processing during native modal loops (MessageBox, GetSaveFileName, drag/resize). On Windows, prefer CefSetOSModalLoop for top-menu/printer cases.

CefScopedSetNestableTasksAllowed

Source File: include/cef_app.h

Process / Thread Context: CEF UI thread (same as CefSetNestableTasksAllowed).

Purpose: "Scoped helper for calling CefSetNestableTasksAllowed." A stack object whose constructor calls CefSetNestableTasksAllowed(true) and destructor calls CefSetNestableTasksAllowed(false). Available only when __cplusplus is defined and API ≥ 14100.

Usage Example

// On the UI thread, calling a Windows modal API:
{
  CefScopedSetNestableTasksAllowed allow;  // CefSetNestableTasksAllowed(true)
  ::MessageBoxW(hwnd, L"Hello", L"CEF", MB_OK);  // CEF tasks can run nested
}  // dtor -> CefSetNestableTasksAllowed(false)

CefApp

Source File: include/cef_app.h

Process / Thread Context: Per the class comment, "Implement this interface to provide handler implementations. Methods will be called by the process and/or thread indicated." Each method's comment specifies its own context.

Purpose: Top-level process-wide handler object. A single CefRefPtr<CefApp> is passed to both CefExecuteProcess and CefInitialize. The same CefApp instance can be used in every process (browser, renderer, GPU, etc.) — CEF routes calls to the appropriate methods per process. It exposes hooks for command-line preprocessing, custom scheme registration, and three sub-handler getters (resource bundle, browser-process, render-process).

Methods

virtual void OnBeforeCommandLineProcessing(const CefString& process_type, CefRefPtr<CefCommandLine> command_line)

Parameters:

• process_type: Empty string for the browser process; otherwise the secondary process type (e.g. "renderer", "gpu-process").
• command_line: The CefCommandLine that will be used by the process. "Do not keep a reference to the CefCommandLine object passed to this method."

Return Value: void.

Usage Instruction: Modify the command line in place. cef_settings_t.command_line_args_disabled can produce an empty starting object. Settings-derived arguments are already applied before this callback. The header warns: "Be cautious when using this method to modify command-line arguments for non-browser processes as this may result in undefined behavior including crashes."

Threading Constraint: Not explicitly stated per method, but called before the process starts processing. Header says class-level "Methods will be called by the process and/or thread indicated."

virtual void OnRegisterCustomSchemes(CefRawPtr<CefSchemeRegistrar> registrar)

Parameters:

• registrar: Raw pointer to a CefSchemeRegistrar. "Do not keep a reference to the |registrar| object."

Return Value: void.

Usage Instruction: Register custom URI schemes here. "This method is called on the main thread for each process and the registered schemes should be the same across all processes."

Threading Constraint: Main thread of each process.

virtual CefRefPtr<CefResourceBundleHandler> GetResourceBundleHandler()

Parameters:

• none.

Return Value: The resource-bundle handler, or nullptr to load resources from pack files (default).

Usage Instruction: Return a handler to override resource pack loading.

Threading Constraint: "This method is called by the browser and render processes on multiple threads."

virtual CefRefPtr<CefBrowserProcessHandler> GetBrowserProcessHandler()

Parameters:

• none.

Return Value: The browser-process handler, or nullptr.

Usage Instruction: Return your CefBrowserProcessHandler subclass. CEF will call its methods on the browser process.

Threading Constraint: "This method is called on multiple threads in the browser process."

virtual CefRefPtr<CefRenderProcessHandler> GetRenderProcessHandler()

Parameters:

• none.

Return Value: The render-process handler, or nullptr.

Usage Instruction: Return your CefRenderProcessHandler subclass. Only relevant in render processes; called in others but the result is ignored.

Threading Constraint: "This method is called on the render process main thread."

Usage Example

#include "include/cef_app.h"

class MyApp : public CefApp,
              public CefBrowserProcessHandler,
              public CefRenderProcessHandler {
 public:
  // --- CefApp ---
  void OnBeforeCommandLineProcessing(
      const CefString& process_type,
      CefRefPtr<CefCommandLine> command_line) override {
    command_line->AppendSwitch("disable-gpu");
  }

  CefRefPtr<CefBrowserProcessHandler> GetBrowserProcessHandler() override {
    return this;  // we are also the browser-process handler
  }
  CefRefPtr<CefRenderProcessHandler> GetRenderProcessHandler() override {
    return this;  // and the render-process handler
  }

  // --- CefBrowserProcessHandler ---
  void OnContextInitialized() override { /* create browsers here */ }

  // --- CefRenderProcessHandler ---
  void OnWebKitInitialized() override { /* inject V8 extensions */ }

 private:
  IMPLEMENT_REFCOUNTING(MyApp);
};

int main(int argc, char** argv) {
  CefMainArgs args(argc, argv);
  CefRefPtr<CefApp> app = new MyApp();
  // Secondary processes block here and return their exit code:
  if (CefExecuteProcess(args, app, nullptr) >= 0) return 0;

  CefSettings settings;
  // populate settings...
  if (!CefInitialize(args, settings, app, nullptr)) return CefGetExitCode();

  CefRunMessageLoop();
  CefShutdown();
  return 0;
}

See Also

• cef_browser_process_handler
• cef_render_process_handler