CEF・Electron からの乗り換えガイド

作成者: BlinkGTK Project
対象の版: BlinkGTK 1.2.5-build2 (Chromium 156.0.8078.47)

English

CEF (Chromium Embedded Framework) や Electron で作ったアプリを、BlinkGTK に移すか
どうかを判断するためのガイドです。今の構成でやっていることごとに、BlinkGTK で
何を使うかを表にしました。BlinkGTK に対応するものが無い機能は、表の中と
「対応していない機能と違うところ」にはっきり書いています。

表に出てくる BlinkGTK の関数は、すべて配布物の公開ヘッダ blink_gtk/blink_gtk.h
にあるものです。

どんな方向けか

• CEF を C / C++ のアプリに組み込んでいて、GTK4 のアプリにしたい方
• Electron で作ったデスクトップアプリを、Linux 向けに GTK4 で作り直したい方
• 乗り換えるかどうかを、移す前に判断したい方

WebKitGTK から移る方は WebKitGTK からの移行ガイド
を読んでください。こちらは置き換えがほぼ 1 対 1 です。

先に確かめること

乗り換えの前に、次の 4 点が今のアプリの条件に合うかを確かめてください。

CEF や Electron のように 1 つのコードで Windows・macOS・Linux に配る構成が要件なら、
BlinkGTK は向きません。

考え方の違い

1. WebView は GTK のウィジェット 1 つです。 blink_web_view_new() が返すのは
   GtkWidget* です。GtkWindow や GtkBox に入れれば表示されます。CEF の
   CefWindowInfo や Electron の BrowserWindow のように、エンジンが窓を持つことはありません
2. ブラウザのプロセス構成をアプリが組み立てる必要はありません。 CEF の
   CefExecuteProcess() に当たる関数はありません。サブプロセス用の実行ファイルも
   アプリ側で用意しません。プロセスの起動と管理はライブラリの中で行います
3. ハンドラはクラスではなく関数とシグナルで受けます。 CEF の CefClient に
   各ハンドラのクラスを返す形ではなく、WebView ごとに関数を登録するか、
   GObject のシグナルに接続します
4. メインループは BlinkGTK のものを回します。 blink_gtk_run_main_loop() を使い、
   g_main_loop_run() や g_application_run() は使いません (後述)。
   GLib の g_timeout_add() と g_idle_add() はこのループの下でも動きます
5. アプリの処理とページの間はメッセージで結びます。 Electron の ipcMain /
   ipcRenderer に当たる双方向のメッセージがあります。ページの中に C の関数を
   直接見せる仕組み (CEF の CefV8Handler など) はありません

対応表

表の「BlinkGTK」の列は、公開ヘッダにある関数・シグナル名です。シグナルは
g_signal_connect() で接続します。

初期化と終了

リソースは、指定しなければ実行ファイルと同じディレクトリを探し、そこに無ければ
ライブラリの置き場所から探します。RPM / DEB で入れた場合は指定は要りません。

メインループ

g_application_run() で回すと、ビルドも起動もできるのにページが読み込まれません。
GtkApplication を使うときは必ず blink_gtk_application_run() を使ってください。

窓と WebView の作成

BLINK_WEB_VIEW() で BlinkWebView* に変換してから BlinkGTK の関数に渡します。
GTK の関数にはそのまま渡せます。

URL の読み込みとナビゲーション

load-changed の BLINK_LOAD_STARTED は、blink_web_view_load_uri() や
load_html() を呼んだときにだけ届きます。リンクのクリックや戻る・進むでは届きません。
詳しくは シグナル API を見てください。

ページとの通信 (JavaScript の実行とメッセージ)

メッセージで気を付けること:

• ページからアプリに届く data は Base64 のバイト列です。g_base64_decode() で戻します。
  アプリからページへは文字列がそのまま渡ります
• send_message_to_page() は送り先が無いと黙って捨てます。ページから「準備ができた」と
  知らせてもらってから送るのが確実です
• ページの addMessageHandler() の登録は、ページを移るたびに消えます。アプリの側の登録は残ります
• postMessage はページの中のどのスクリプトからも呼べます。届いた内容はアプリの側で検証してください

詳しくはアプリ連携 API の
「JS ↔︎ C メッセージング」を見てください。

独自スキームとリソースの置き方

スキームの応答で気を付けること:

• コールバックが受け取るのは URI だけです。応答の状態コード・リダイレクト・応答ヘッダを
  返す手段はありません
• コールバックはメインスレッドで同期に呼ばれます。重い処理は前もって済ませてください
• 登録はスキームごとにプロセス全体で 1 つです。別の WebView で同じスキームを登録すると、
  後から登録したものに置き換わります。コールバックの第 1 引数は登録したときの WebView で、
  要求を出した WebView ではありません。WebView ごとに内容を分けたいときは、
  app://reader/... と app://settings/... のように URI のホスト名やパスで区別してください
• URI をそのままファイルのパスにつながないでください。realpath() などで解決し、
  アプリの置き場所の下にあることを確かめてから開きます

開発者ツールとデバッグ

アプリの窓の中に開発者ツールを並べて出す機能はありません。開発者ツールは
別の Chrome / Chromium の窓で開きます。

その他のよく使う機能

配布 (パッケージと依存)

リンクは pkg-config を通してください。手で -lblinkgtk だけを書くと、
ビルドも起動もできるのにページが表示されないことがあります。理由と確かめ方は
組み込みガイド にあります。

アプリと一緒に配る場合は、THIRD_PARTY_NOTICES.html などのライセンス表記も
一緒に配る必要があります。ポータブルアプリ作成ガイドの
「ライセンス上の義務」を見てください。

最小の例 (C)

独自スキーム app:// でアプリ内の HTML を返し、ページのボタンからアプリへ
メッセージを送り、アプリから返事を返す例です。Electron の
ipcRenderer.send() と 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'>アプリに送る</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>";

/* app://main/... への要求ごとに呼ばれる。URI 以外の情報は渡らない */
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));
}

/* ページの postMessage('hello', ...) を受ける。data は 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);
}

/* execute_javascript の結果。JSON の文字列で、実行できなければ空文字列 */
static void on_title(const char* result, gpointer user_data) {
  (void)user_data;
  g_print("document.title = %s\n", result[0] ? result : "(未実行)");
}

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[]) {
  /* CefInitialize() に当たる。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);

  /* 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));

  /* CefRunMessageLoop() に当たる */
  int status = blink_gtk_run_main_loop();

  /* CefShutdown() に当たる */
  blink_gtk_shutdown();
  return status;
}

ビルドと実行:

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

Wayland のセッションで実行してください。ボタンを押すと、端末に hello: ping と出て、
ページに pong と表示されます。

対応していない機能と違うところ

次の機能は、BlinkGTK の公開 API に対応するものがありません。

ほかに、次の点が違います。

• 呼び出しはメインスレッドからだけです。 公開ヘッダの関数は GTK のメインスレッドから
  呼びます。コールバックもメインスレッドで呼ばれます
• 初期化の前に決めることがあります。 リソースの置き場所・描画方式・独自スキームの
  名前は、blink_gtk_init() の後では変えられません
• blink_web_view_get_uri() と get_title() の返り値は解放しません。 次に同じ関数を
  呼ぶと上書きされるので、持ち越すなら複製してください

足りない機能が乗り換えの妨げになる場合は、
不具合報告・要望 または
contact@blinkgtk.org までお知らせください。

次に読むページ

• アプリのビルド — インストールから最初の起動まで
• 組み込みガイド — リンクと実行時の要件
• アプリ連携 API — 独自スキーム・メッセージ・スクリプトの注入
• シグナル API — 読み込みの状態・ナビゲーションの判断・権限
• UI ハンドラ API — ダイアログ・ファイル選択・ダウンロード
• DevTools API
• 逆引きリファレンス — やりたいことから関数を探す
• Python で作る
• ポータブルアプリ作成ガイド
• WebKitGTK からの移行ガイド

変更履歴