CefPreferenceManager

Header: cef_preference.h
Sections: CefPreferenceRegistrar, CefPreferenceManager (+1 more)
Category: System Utilities

Overview

Tasks, threads, parsers, streams, cookies, URL requests, scheme registration, and constant tables.

CefPreferenceRegistrar

Source File: include/cef_preference.h

Process / Thread Context: Browser Process / UI Thread, inside CefBrowserProcessHandler::OnRegisterCustomPreferences only.

Purpose: Scoped helper class that manages registration of custom preferences. A reference is handed to the client during OnRegisterCustomPreferences; calling AddPreference after that callback returns is not allowed (scope-limited lifetime, derives from CefBaseScoped).

Methods

bool AddPreference(const CefString& name, CefRefPtr<CefValue> default_value)

Parameters:

• name — preference name; should include an application-specific prefix followed by a period (e.g. "myapp.value") to avoid collisions with built-in Chromium preferences. default_value — default value; its data type is inferred (bool, int, double, string, dictionary, list) and is immutable after registration. The contents are copied.

Return Value: true on success; false if name is already registered or default_value has an invalid type.

Usage Instruction: Call only from inside CefBrowserProcessHandler::OnRegisterCustomPreferences. Once a preference is registered, its type cannot change, but its value can be modified later via CefPreferenceManager::SetPreference.

Threading Constraint: UI thread, restricted to the registrar's scope.

Usage Example

class MyApp : public CefBrowserProcessHandler {
  void OnRegisterCustomPreferences(CefPreferenceRegistrar registrar) override {
    // Register a custom preference with an application-prefixed name.
    CefRefPtr<CefValue> def = CefValue::Create();
    def->SetString("light");
    registrar.AddPreference("myapp.theme", def);

    CefRefPtr<CefValue> defInt = CefValue::Create();
    defInt->SetInt(42);
    registrar.AddPreference("myapp.window_width", defInt);
  }
};

CefPreferenceObserver (CEF_API_ADDED(13401))

Source File: include/cef_preference.h

Process / Thread Context: Browser Process / UI Thread (callbacks).

Purpose: Client-implemented callback interface for receiving notifications when preference values change. Registered with CefPreferenceManager::AddPreferenceObserver. The returned CefRegistration object controls the observer's lifetime.

Methods

void OnPreferenceChanged(const CefString& name)

Parameters:

• name — name of the preference that changed.

Return Value: None.

Usage Instruction: Retrieve the new value with CefPreferenceManager::GetPreference(name). The callback is invoked only on the UI thread.

Threading Constraint: Browser process UI thread only.

Usage Example

class ThemePrefObserver : public CefPreferenceObserver {
 public:
  void OnPreferenceChanged(const CefString& name) override {
    if (name == "myapp.theme") {
      auto mgr = CefPreferenceManager::GetGlobalPreferenceManager();
      CefRefPtr<CefValue> v = mgr->GetPreference(name);
      ApplyTheme(v->GetString());
    }
  }
};

CefRefPtr<CefRegistration> g_reg;
void StartObserving() {
  auto mgr = CefPreferenceManager::GetGlobalPreferenceManager();
  g_reg = mgr->AddPreferenceObserver("myapp.theme", new ThemePrefObserver);
}
void StopObserving() { g_reg = nullptr; }  // dropping the registration unregisters.

CefPreferenceManager

Source File: include/cef_preference.h

Process / Thread Context: Browser Process / UI Thread (for all instance methods unless otherwise noted).

Purpose: Library-provided interface to the global Chromium preference store (PrefService). Allows querying, setting, and observing preferences — both built-in Chromium preferences and custom preferences registered via CefPreferenceRegistrar.

Methods

static CefRefPtr<CefPreferenceManager> GetGlobalPreferenceManager()

Parameters:

• None.

Return Value: The singleton global preference manager.

Usage Instruction: Entry point for all preference lookups. Methods below are non-static instance methods.

Threading Constraint: Safe to call from any thread to obtain the pointer; instance methods are UI-thread only.

virtual bool HasPreference(const CefString& name)

Parameters:

• name — preference name.

Return Value: true if a preference with name exists.

Usage Instruction: Use to gate reads of optional preferences.

Threading Constraint: UI thread.

virtual CefRefPtr<CefValue> GetPreference(const CefString& name)

Parameters:

• name — preference name.

Return Value: A CefValue containing a copy of the underlying value, or NULL if the preference does not exist. Mutating the returned value does not modify the stored preference.

Usage Instruction: Always dereference on the UI thread; for thread safety, copy the underlying scalar out before leaving the UI thread.

Threading Constraint: UI thread.

virtual CefRefPtr<CefDictionaryValue> GetAllPreferences(bool include_defaults)

Parameters:

• include_defaults — if true, preferences currently at their default value are included; if false, only modified preferences are returned.

Return Value: Dictionary containing copies of all preferences.

Usage Instruction: Useful for serializing a snapshot (e.g., for diagnostics or migration).

Threading Constraint: UI thread.

virtual bool CanSetPreference(const CefString& name)

Parameters:

• name — preference name.

Return Value: true if the preference can be modified via SetPreference; false if it is read-only (e.g., forced by command line or policy).

Usage Instruction: Check before exposing a UI control for editing a preference.

Threading Constraint: UI thread.

virtual bool SetPreference(const CefString& name, CefRefPtr<CefValue> value, CefString& error)

Parameters:

• name — name of the preference to observe; empty string means all preferences (not recommended outside testing due to performance). observer — client-implemented observer.

Return Value: CefRegistration handle; the observer remains registered until this handle is destroyed.

Usage Instruction: Hold the returned CefRegistration in a member whose lifetime matches the desired observation window. Destroy it (release the ref) to unregister.

Threading Constraint: UI thread.

Usage Example

// Reading + writing preferences.
auto mgr = CefPreferenceManager::GetGlobalPreferenceManager();
if (mgr->HasPreference("myapp.theme")) {
  CefString err;
  CefRefPtr<CefValue> v = CefValue::Create();
  v->SetString("dark");
  if (!mgr->SetPreference("myapp.theme", v, err)) {
    LOG(ERROR) << "Failed to set theme: " << err;
  }
}

// Enumerate current Chrome variations for telemetry.
std::vector<CefString> variations;
CefPreferenceManager::GetChromeVariationsAsStrings(variations);
for (const auto& s : variations) DLOG(INFO) << s;