Switching from CEF or Electron to BlinkGTK

Author: BlinkGTK Project
Applies to: BlinkGTK 1.2.5-build2 (Chromium 156.0.8078.47)

日本語

This guide helps you decide whether to move an application built with CEF
(Chromium Embedded Framework) or Electron to BlinkGTK. For each thing your
current setup does, the tables show what to use in BlinkGTK. Where BlinkGTK has
no equivalent, the tables and the section "Features without an equivalent, and
other differences" say so plainly.

Every BlinkGTK function in the tables is declared in the public header shipped
with the packages, blink_gtk/blink_gtk.h.

Who this is for

• You embed CEF in a C or C++ application and want it to become a GTK4 application
• You built a desktop application with Electron and want to rebuild it for Linux with GTK4
• You want to judge whether to switch before you start moving code

If you are coming from WebKitGTK, read the
WebKitGTK migration guide instead. There the
replacements are nearly one to one.

Check these first

Before switching, check that the following four points fit your application.

If you need one code base that ships to Windows, macOS and Linux, as CEF and
Electron allow, BlinkGTK is not a good fit.

How the model differs

1. The web view is a single GTK widget. blink_web_view_new() returns a
   GtkWidget*. Put it in a GtkWindow or a GtkBox and it is shown. The engine
   never owns the window, unlike CEF's CefWindowInfo or Electron's BrowserWindow
2. Your application does not assemble the browser's process layout. There is
   no function corresponding to CEF's CefExecuteProcess(), and you do not provide
   a separate executable for subprocesses. The library starts and manages its
   processes itself
3. Handlers are functions and signals, not classes. Instead of returning handler
   classes from a CefClient, you register functions per web view or connect to
   GObject signals
4. You run BlinkGTK's main loop. Use blink_gtk_run_main_loop(), not
   g_main_loop_run() or g_application_run() (see below). GLib's g_timeout_add()
   and g_idle_add() still work under this loop
5. Your application and the page talk through messages. There are two-way
   messages comparable to Electron's ipcMain / ipcRenderer. There is no way to
   expose C functions directly to the page (such as CEF's CefV8Handler)

Mapping tables

The "BlinkGTK" column lists functions and signal names from the public header.
Connect to signals with g_signal_connect().

Initialization and shutdown

If you do not set the resource location, BlinkGTK looks next to the executable
first, then near the library. With the RPM or DEB packages no setting is needed.

Main loop

If you run the loop with g_application_run(), the application builds and starts
but pages never load. When you use GtkApplication, always use
blink_gtk_application_run().

Windows and web views

Convert to BlinkWebView* with BLINK_WEB_VIEW() before passing the view to
BlinkGTK functions. GTK functions take it as it is.

Loading URLs and navigation

BLINK_LOAD_STARTED from load-changed arrives only when you call
blink_web_view_load_uri() or load_html(). It does not arrive for link clicks
or back and forward. See the Signals API for details.

Talking to the page (running JavaScript and messages)

Points to watch with messages:

• data sent from the page reaches the application as Base64 bytes. Decode it
  with g_base64_decode(). From the application to the page, the string is passed as it is
• send_message_to_page() silently drops the message when nobody listens yet. The
  reliable way is to have the page tell you it is ready before you send
• addMessageHandler() registrations in the page are lost on every navigation. The
  registrations on the application side stay
• Any script in the page can call postMessage. Validate what arrives in the application

See "JS ↔︎ C messaging"
in the App integration API for details.

Custom schemes and where to put your resources

Points to watch with scheme handlers:

• The callback receives only the URI. There is no way to return a status code,
  a redirect or response headers
• The callback runs synchronously on the main thread. Prepare heavy work in advance
• There is one registration per scheme for the whole process. Registering the same scheme
  from another web view replaces the earlier registration. The callback's first argument is
  the web view that registered the scheme, not the one that made the request. To serve
  different content to different web views, tell them apart by the host or path of the URI,
  such as app://reader/... and app://settings/...
• Do not join the URI straight onto a file path. Resolve it with realpath() or similar
  and check that it is under your application's directory before opening it

Developer tools and debugging

There is no way to show the developer tools inside your application's window.
They open in a separate Chrome or Chromium window.

Other common features

Distribution (packages and dependencies)

Link through pkg-config. If you only write -lblinkgtk by hand, the
application can build and start but show no page. The reason and how to check
are in the integration guide.

When you ship BlinkGTK together with your application, you must also include the
license notices such as THIRD_PARTY_NOTICES.html. See
"License obligations"
in the portable application guide.

Minimal example (C)

This example serves the application's own HTML over the app:// scheme,
sends a message from a button in the page to the application, and sends an answer
back. It corresponds to Electron's ipcRenderer.send() combined with webContents.send().

/* cef-electron-migration.c */
#include <blink_gtk/blink_gtk.h>
#include <gtk/gtk.h>
#include <string.h>

static const char page_html[] =
    "<!doctype html><meta charset='utf-8'><title>sample</title>"
    "<button id='b'>Send to the application</button><p id='out'></p>"
    "<script>"
    "window.blinkgtk.addMessageHandler('reply', function (data) {"
    "  document.getElementById('out').textContent = data;"
    "});"
    "document.getElementById('b').onclick = function () {"
    "  window.blinkgtk.postMessage('hello', 'ping');"
    "};"
    "</script>";

/* Called for each request to app://main/... Only the URI is passed in */
static GBytes* on_app_scheme(BlinkWebView* view, const char* uri,
                             char** out_mime, gpointer user_data) {
  (void)view; (void)uri; (void)user_data;
  *out_mime = g_strdup("text/html");
  return g_bytes_new_static(page_html, strlen(page_html));
}

/* Receives postMessage('hello', ...) from the page. data is Base64 */
static void on_hello(const char* name, const guint8* data, gsize length,
                     gpointer user_data) {
  BlinkWebView* view = BLINK_WEB_VIEW(user_data);
  gchar* encoded = g_strndup((const gchar*)data, length);
  gsize decoded_len = 0;
  guchar* decoded = g_base64_decode(encoded, &decoded_len);
  g_print("%s: %.*s\n", name, (int)decoded_len, (const char*)decoded);
  blink_web_view_send_message_to_page(view, "reply", "pong");
  g_free(decoded);
  g_free(encoded);
}

/* Result of execute_javascript: a JSON string, or empty if it could not run */
static void on_title(const char* result, gpointer user_data) {
  (void)user_data;
  g_print("document.title = %s\n", result[0] ? result : "(not run)");
}

static void on_load_changed(BlinkWebView* view, BlinkLoadEvent event,
                            gpointer user_data) {
  (void)user_data;
  if (event == BLINK_LOAD_FINISHED)
    blink_web_view_execute_javascript(view, "document.title", on_title, NULL);
}

static gboolean on_close(GtkWindow* window, gpointer user_data) {
  (void)window; (void)user_data;
  blink_gtk_quit_main_loop();
  return FALSE;
}

int main(int argc, char* argv[]) {
  /* Corresponds to CefInitialize(). Call it before GTK */
  if (!blink_gtk_init(&argc, &argv)) {
    g_printerr("blink_gtk_init() failed\n");
    return 1;
  }

  GtkWidget* window = gtk_window_new();
  gtk_window_set_title(GTK_WINDOW(window), "BlinkGTK");
  gtk_window_set_default_size(GTK_WINDOW(window), 800, 600);
  g_signal_connect(window, "close-request", G_CALLBACK(on_close), NULL);

  /* Corresponds to CreateBrowser() / new BrowserWindow() */
  GtkWidget* web_view = blink_web_view_new();
  gtk_window_set_child(GTK_WINDOW(window), web_view);
  BlinkWebView* view = BLINK_WEB_VIEW(web_view);

  blink_web_view_register_custom_scheme_full(view, "app", on_app_scheme, NULL);
  blink_web_view_register_message_handler(view, "hello", on_hello, view);
  g_signal_connect(web_view, "load-changed", G_CALLBACK(on_load_changed), NULL);

  blink_web_view_load_uri(view, "app://main/index.html");
  gtk_window_present(GTK_WINDOW(window));

  /* Corresponds to CefRunMessageLoop() */
  int status = blink_gtk_run_main_loop();

  /* Corresponds to CefShutdown() */
  blink_gtk_shutdown();
  return status;
}

Build and run:

cc cef-electron-migration.c -o cef-electron-migration $(pkg-config --cflags --libs blinkgtk-0.1)
./cef-electron-migration

Run it in a Wayland session. When you press the button, the terminal prints
hello: ping and the page shows pong.

Features without an equivalent, and other differences

BlinkGTK's public API has no equivalent for the following.

Other differences:

• Calls come from the main thread only. Call the functions in the public header
  from the GTK main thread. Callbacks are also called on the main thread
• Some things are fixed before initialization. The resource location, the
  rendering mode and custom scheme names cannot be changed after blink_gtk_init()
• Do not free what blink_web_view_get_uri() and get_title() return. The next
  call to the same function overwrites it, so copy it if you keep it

If a missing feature stops you from switching, tell us through
bug reports and requests or at
contact@blinkgtk.org.

What to read next

• Building an application — from installation to the first run
• Integration guide — linking and runtime requirements
• App integration API — custom schemes, messages, script injection
• Signals API — load state, navigation decisions, permissions
• UI handlers API — dialogs, file choosers, downloads
• DevTools API
• How-to index — find functions by what you want to do
• Building in Python
• Portable application guide
• WebKitGTK migration guide

Change history