BlinkGTK GObject Signals API リファレンス

バージョン: 1.2.5-build5
最終更新: 2026-07-30
言語: 日本語 |

English

このページについて

BlinkWebView が発する GObject シグナル 8 本のリファレンスです。ページの
ロード状態・URL・タイトルの変化、新規ウィンドウ要求、JS からのメッセージ、
権限要求を受け取れます。

本ページはエンジン実装を実測して書かれています。ハンドラやシグナルの状況は
全体は 2026-08-04 時点 (1.2.0-build2) で確認し、その後に追加・変更した行は、行ごとに版を書いています。

旧版 (2026-07-29 以前) からの重大な訂正: 旧版は title-changed /
uri-changed のコールバックに文字列引数があるかのように記載していましたが、
両シグナルに引数はありません。旧版のシグネチャどおりに書くと
user_data が文字列引数の位置に入り、クラッシュやメモリ破壊の原因に
なります。本ページのシグネチャが実装どおりの正です。

シグナル一覧 (実装どおり)

GtkWidget 由来のプロパティ通知 notify::uri / notify::title /
notify::is-loading も使えます。

WebKitGTK からの移行では、notify::uri / notify::title をそのまま流用するのが
最も簡単です。

まず知っておく 3 つの事実

1. エンジン発のシグナルは全て GTK メインスレッドで届きます (Chromium の
   UI スレッド = GTK メインループ)。ハンドラから GTK API を直接呼べます。
   一方、load_uri() が同期発火するシグナル (下記) は「API を呼んだ
   スレッド」で走るため、BlinkGTK API はメインスレッドから呼んでください。
2. title-changed / uri-changed に引数はありません。 値はハンドラ内で
   blink_web_view_get_title() / blink_web_view_get_uri() から取ります。
3. getter が返す文字列は内部の静的バッファで、次に同じ getter を呼ぶと
   上書きされます。保持するなら g_strdup() してください。

基本形

static void on_title_changed(BlinkWebView *view, gpointer user_data) {
    GtkWindow *win = GTK_WINDOW(user_data);
    const char *title = blink_web_view_get_title(view);   /* 引数でなく getter */
    gtk_window_set_title(win, title ? title : "BlinkGTK");
}

static void on_uri_changed(BlinkWebView *view, gpointer user_data) {
    GtkEditable *entry = GTK_EDITABLE(user_data);
    const char *uri = blink_web_view_get_uri(view);
    gtk_editable_set_text(entry, uri ? uri : "");
}

g_signal_connect(view, "title-changed", G_CALLBACK(on_title_changed), win);
g_signal_connect(view, "uri-changed", G_CALLBACK(on_uri_changed), entry);

load-changed

シグネチャ

void user_function(BlinkWebView* web_view,
                   BlinkLoadEvent load_event,
                   gpointer user_data);

BlinkLoadEvent の値 (明示値 — 順序に注意)

typedef enum {
    BLINK_LOAD_STARTED    = 0,
    BLINK_LOAD_COMMITTED  = 1,
    BLINK_LOAD_FINISHED   = 2,
    BLINK_LOAD_REDIRECTED = 3   /* 予約 — 現在のランタイムは発火しません */
} BlinkLoadEvent;

• BLINK_LOAD_REDIRECTED は現在発火しません (将来のための予約値)。
  リダイレクトの追跡はできません
• 過去の版と値の並びが異なります。必ず定数名で比較してください
  (数値直書きの if (ev == 3) などは壊れます)

各値の実際の意味

操作別の発火パターン (実測)

FINISHED 時点で保証されること

FINISHED の直前に、エンジンは注入 CSS (アプリ連携 API)
と JS メッセージブリッジ (window.blinkgtk) のセットアップを済ませています。
FINISHED ハンドラの中から execute_javascript() を呼べばブリッジは使えます。

ただし FINISHED は onload であり、ページが動的に組み立てるコンテンツの完成
までは意味しません (描画完成の通知は現在未提供です)。

スピナー (読み込み中表示) の正しい止め方

1.2.5 からは notify::is-loading で切り替えるのが確実です。 読み込みの開始と終了のたびに
通知が来て、blink_web_view_is_loading() の値が変わっています。STARTED が来ない操作
(戻る・再読み込み) や、FINISHED が来ない応答 (load_uri() で開いた HTTP 204) でも来ることを
確かめています (ダウンロードでは試していません)。1.2.4 までは、読み込みの終わりに
FALSE の通知が来ませんでした。

load-changed だけで切り替える場合は、FINISHED だけで止めると永久スピナーになるケースがあります:

• コミットされない失敗 (キャンセル等) → load-failed で止める
• ダウンロードになったナビゲーション → どのシグナルも来ません (完全に無音)。
  HTTP 204・205 の応答も無音と書いていましたが、load_uri() で開いた 204 では
  load-failed に中断の -3 が届くことを 1.2.5 で確かめました (リンクからの 204 は試していません)。blink_web_view_is_loading() を保険にした
  タイムアウトを併用してください

/* FINISHED または load-failed で止め、無音ケースはタイムアウトで拾う */

load-failed

シグネチャ

void user_function(BlinkWebView* web_view,
                   int error_code,
                   const char* failing_uri,
                   gpointer user_data);

引数は (error_code, failing_uri) の順です。 逆順で書いたコールバックは
ポインタを整数として読み、クラッシュや文字化けの原因になります。

いつ発火するか (重要 — 直感と異なります)

発火条件は「コミットされずに終わったナビゲーション + net エラーあり」
だけです。帰結:

error_code の実際の型

値は Chromium の net エラーコードの生の負値です (-3, -105, …)。
ヘッダの BlinkLoadError enum (BLINK_LOAD_ERROR_NETWORK 等) は現在の
ランタイムでは使われません — C では int として扱ってください。

完全なリストは Chromium net_error_list.h を参照してください。

実装パターン

static void on_load_failed(BlinkWebView *view, int error_code,
                           const char *failing_uri, gpointer user_data) {
    if (error_code == -3)   /* ERR_ABORTED: 正常操作の副産物。無視が基本 */
        return;
    const char *current = blink_web_view_get_uri(view);
    if (current && failing_uri && strcmp(current, failing_uri) != 0)
        return;             /* iframe など、表示中ページ以外の失敗 */
    g_message("load failed: %d %s", error_code, failing_uri);
}

uri-changed / title-changed

シグネチャ (両方とも追加引数なし)

void user_function(BlinkWebView* web_view, gpointer user_data);

値はハンドラ内で blink_web_view_get_uri() / blink_web_view_get_title()
で取得します。

uri-changed の動作の詳細

title-changed の動作の詳細

new-window-requested

シグネチャ

void user_function(BlinkWebView* web_view,
                   const char* url,
                   gpointer user_data);

これは「通知」です — 制御は decide-navigation で

window.open() や <a target="_blank"> が起きたことを知らせるシグナルで、
このシグナルでは、開かせない・別の場所に開く、という制御はできません (戻り値なし)。
制御するには、v1.2.3-build2 以降の decide-navigation を使います。
decide-navigation がハンドラで決めた場合、このシグナルは出ません。
現在のエンジンはシングルウィンドウ動作で、シグナル発火の時点で既に同じ
WebView を対象 URL へナビゲートし始めています。

• ハンドラ内で load_uri(url) を呼ばないでください — エンジンが既に
  同じ遷移を始めているため二重ナビゲーションになります。用途はログ・
  「新しいタブで開く UI を自前で出す」等の通知処理に留めるのが安全です
• どうしても別 URL に差し替えたい場合は g_idle_add() で遅延させて
  ください (target="_blank" 系ではエンジンの遷移が同期呼び出しに勝つため)
• ポップアップか通常タブか・サイズ指定・ユーザー操作起因かの情報は
  現在渡りません
• 中クリックなど「新しいタブで開く」系の一部経路ではこのシグナル自体が
  来ません (同じ view で開かれます)
• ページ側から見た window.open() の戻り値: 通常は「直後に閉じられた
  ウィンドウ」(closed === true)、noopener 指定時は null です。
  ハンドラの接続有無で変わりません

decide-navigation (v1.2.3-build2 以降)

ページが始めた移動と新しいウィンドウの行き先を、アプリが決めます。
本の中の外部リンクをシステムのブラウザで開く、target="_blank" を別のビューで開く、
意図しないサイトへの移動を止める、といった用途です。

static gboolean on_decide(BlinkWebView *view, BlinkNavigationDecision *d, gpointer user_data) {
    const char *uri = blink_navigation_decision_get_uri(d);
    if (blink_navigation_decision_get_decision_type(d) == BLINK_NAVIGATION_DECISION_NEW_WINDOW) {
        GtkWidget *nv = blink_navigation_decision_create_view(d);  /* opener を保つ */
        GtkWidget *win = gtk_window_new();
        gtk_window_set_child(GTK_WINDOW(win), nv);
        gtk_window_present(GTK_WINDOW(win));
        return TRUE;
    }
    if (!g_str_has_prefix(uri, "https://example.org/")) {
        blink_navigation_decision_open_external(d);  /* 本の外はシステムのブラウザで */
        return TRUE;
    }
    return FALSE;  /* 既定の動作に任せる */
}
g_signal_connect(view, "decide-navigation", G_CALLBACK(on_decide), NULL);

何が届くか

• 主フレームでページが始めた移動: リンク、フォーム送信、スクリプトによる移動
  (blink_navigation_decision_get_decision_type() が BLINK_NAVIGATION_DECISION_NAVIGATION)
• window.open()、target="_blank" など新しいウィンドウ
  (BLINK_NAVIGATION_DECISION_NEW_WINDOW)
• 届かないもの: アプリの blink_web_view_load_uri() で始めた移動、サブフレーム (iframe) の移動、
  リダイレクト

答え方 (どれか 1 つを 1 回)

• 後から答える: blink_navigation_decision_ref() で参照を持って TRUE を返し、答えたあとで
  blink_navigation_decision_unref() します。同じビュー内の移動は、答えが出るまで止まって待ちます
• ハンドラが無い・FALSE を返した: 既定の動作です。同じビュー内は進み、新しいウィンドウは
  今のビューで開いて new-window-requested を出します (v1.2.3-build1 までと同じ)
• TRUE を返して答えずに手放した: 同じビュー内は進み、新しいウィンドウは開きません

判断材料

• blink_navigation_decision_get_uri(): 行き先
• blink_navigation_decision_get_disposition(): ページが求めた開き方 (今のビュー / 新しいタブ /
  ポップアップ / 新しいウィンドウ)
• blink_navigation_decision_is_user_gesture(): 利用者の操作で始まったか
• blink_navigation_decision_get_initiator_origin(): 始めたページのオリジン。分からなければ NULL

確かめた範囲

release/scripts/check-navigation-decision.sh で、次を確かめています (software 経路)。

• ハンドラ無しは v1.2.3-build1 までと同じ動作
• ignore で、新しいウィンドウも同じビュー内のリンクも止まる
• create_view で新しいビューが作られ、開いた先のページから window.opener.postMessage() が届く。
  新しいビューに内容が描かれる (GTK が描いた結果の画素で確認)
• 後から (500 ms 後) open_external すると、既定のハンドラに URI が渡り、ビューは動かない

EGL 経路 (BLINKGTK_GPU_MODE=egl) で、create_view の新しいビューに内容が出るかは確かめていません。

message-received

ページ JS の window.blinkgtk.postMessage() を受けるシグナルです。
引数は (name, data) の 2 つ (チャネル名と Base64 データ)。詳細な
セマンティクス (エンコーディング・多重購読・C API 版ハンドラとの関係) は
アプリ連携 API にまとめてあります。

権限要求 (permission-request)

位置情報・通知などの権限要求を受けるシグナルです。

static gboolean on_permission(BlinkWebView *view,
                              BlinkPermissionRequest *req,
                              gpointer user_data) {
    const char *kind = blink_permission_request_get_type_name(req);
    if (g_strcmp0(kind, "notifications") == 0)
        blink_permission_request_allow(req);   /* 通知だけ許可 */
    else
        blink_permission_request_deny(req);
    return TRUE;   /* 処理した */
}

g_signal_connect(view, "permission-request", G_CALLBACK(on_permission), NULL);

仕様

• ハンドラは blink_permission_request_allow() か blink_permission_request_deny() のどちらか一方で答えます。2 回目以降の呼び出しは無視されます
• その場で答える場合: ハンドラの中で allow / deny を呼び、TRUE を返します。BlinkPermissionRequest はハンドラから戻ると無効になります
• 後から答える場合 (1.2.3-build2 以降): blink_permission_request_ref() で参照を取って TRUE を返します。ダイアログなどで読者の答えを得てから allow / deny を呼び、最後に blink_permission_request_unref() を呼びます。答えないまま最後の参照を外す、ビューを破棄する、主フレームが別のページへ移る、のいずれかで拒否として片付きます
• 参照を取らずに TRUE を返し、答えずに戻ると拒否扱いです (1.2.3-build1 までと同じ)
• ハンドラが TRUE を返さなければ要求は拒否されます (deny-by-default)
• 要求元が分かります (1.2.3-build2 以降): blink_permission_request_get_origin() は要求したフレームのオリジン ("https://example.org" など) を返します。blink_permission_request_get_embedding_origin() は最上位のページのオリジンを返します。一度に複数の種別を求められたときは blink_permission_request_get_type_names() で全部を得られます (get_type_name() は先頭の 1 つだけ)
• 決定を覚えられます (1.2.3-build2 以降): allow / deny の前に blink_permission_request_set_remember(req, TRUE) を呼ぶと、その種別・要求元・最上位のページの組で決定を覚えます。次からはシグナルを出さずに同じ答えを返します。navigator.permissions.query() も覚えた決定を返します。覚えた決定はビューのプロファイルのディレクトリ (BlinkGTK Permissions.json) に書かれ、アプリを起こし直しても残ります。名前の無い既定のプロファイルも同じです。オフザレコードではメモリだけに置きます
• 覚えた決定の読み書き: blink_web_view_get_permission_state() / blink_web_view_set_permission_state()。削除: blink_web_view_clear_permission_states()
• blink_permission_request_get_type_name() が要求種別を返します (下表の 38 種のいずれか、または "unknown")。種別を見ずに一律 allow しないでください
• このシグナルは C 専用です (引数が生ポインタのため、言語バインディングからは現在利用できません)

/* 後から答える例 (1.2.3-build2 以降) */
static void on_answer(gboolean allow, gpointer data) {
    BlinkPermissionRequest *req = data;
    blink_permission_request_set_remember(req, TRUE);   /* 次回から聞かない */
    if (allow) blink_permission_request_allow(req);
    else       blink_permission_request_deny(req);
    blink_permission_request_unref(req);
}

static gboolean on_permission(BlinkWebView *view, BlinkPermissionRequest *req,
                              gpointer user_data) {
    if (g_strcmp0(blink_permission_request_get_type_name(req), "screen-wake-lock") != 0) {
        blink_permission_request_deny(req);
        return TRUE;
    }
    blink_permission_request_ref(req);
    ask_reader(blink_permission_request_get_origin(req), on_answer, req);  /* ダイアログを出す */
    return TRUE;
}

要求種別の一覧 (v1.2.2-build6 以降)

読書アプリが実際に使うもの:

ネットワーク:

入出力・機器:

"unknown" が返るのは、Chromium 側に新しい種別が増えて BlinkGTK が
追随していない場合だけです。 その状態は
release/scripts/check-permission-type-names.sh が検出します。

カメラとマイク (v1.2.3-build2 以降)

ページが getUserMedia({audio: true, video: true}) を呼ぶと、permission-request が
1 回だけ届きます。このとき blink_permission_request_get_type_names() は、
"audio-capture" と "video-capture" の両方を返します。許可すればトラックが使えるようになり、拒否すれば
ページには NotAllowedError が返ります。覚えた決定があれば、シグナルを出さずにそれに従います。

• 使う機器は、ページが機器の ID を指定していればその機器、指定が無ければ最初に見つかった機器です
• v1.2.3-build1 までは、この経路が無く、ページには常に NotSupportedError が返っていました
• 確かめたのは偽の機器 (--use-fake-device-for-media-stream) での動作です。実機のカメラ・マイクと、
  機器が 1 つも無いときにページへ返るエラーの種類は確かめていません

view ごとに profile / cache を分ける (v1.2.2-build6 以降)

blink_web_view_new() で作った view は、1 プロセス内で profile と cache を
共有します。同じ URL を複数の view で開くと、2 つ目以降はキャッシュに当たり、
サーバへの要求は 1 回に畳まれます。

分けたい場合は blink_web_view_new_with_profile() を使います。

GtkWidget *a = blink_web_view_new_with_profile("tab1");
GtkWidget *b = blink_web_view_new_with_profile("tab2");

• 同じ名前なら同じ profile、違う名前なら別々になります
• 置き場は プロセスの profile の下の profiles/<name>
• 名前に使えるのは 英数字と - _ のみ。それ以外は NULL が返ります
• 分かれるもの: HTTP キャッシュ / cookie / localStorage / IndexedDB
• 分かれないもの: 描画プロセスの共用など、プロセスが共有しているもの
• ディレクトリは最初の使用時に作られ、blink_gtk_shutdown() 後も残ります。
  毎回まっさらにしたい場合は名前を変えるか、ディレクトリを消してください
• blink_gtk_get_profile_path() が返す値は変わりません (プロセスの profile)
• HTTP キャッシュはこの profile の下 (profiles/<name>/Cache) に置かれます。
  既定の view (blink_web_view_new()) はメモリ上のままです
• キャッシュは blink_gtk_shutdown() 後も残ります。 次の実行は温まった
  状態から始まります。毎回まっさらから始めたい場合は、profile ディレクトリを
  消してから起動してください

API

const char* blink_permission_request_get_type_name(BlinkPermissionRequest* request);
void        blink_permission_request_allow(BlinkPermissionRequest* request);
void        blink_permission_request_deny(BlinkPermissionRequest* request);

render-path-changed (v1.2.0-build9 以降)

blink_web_view_switch_render_path() で要求した描画経路のライブ切替
(BlinkShift) の完了通知です。切替は非同期です。切替が成功したかどうかは、
このシグナルで受け取ってください (関数の返り値が示すのは「要求を受け付けたか」だけです)。

static void on_render_path_changed(BlinkWebView *view,
                                   const char *path_id,   /* "P1" / "P2" */
                                   const char *result,    /* 下表 */
                                   int gate_ms,           /* 切替に要した ms */
                                   int seq,               /* この swap の通し番号 */
                                   gpointer user_data) {
    g_print("render path -> %s (%s, %d ms, seq=%d)\n",
            path_id, result, gate_ms, seq);
}

g_signal_connect(view, "render-path-changed",
                 G_CALLBACK(on_render_path_changed), NULL);
int seq = blink_web_view_switch_render_path(view, "P2");
if (seq == 0)
    g_warning("switch 要求が受理されなかった");
/* seq は要求受理時に同期で確定します。完了 signal の seq 引数に同じ番号が
 * 載るため、swap の前後で採った記録 (ページ位置など) を「当の swap」に
 * 鍵付けできます。連続 swap では時刻の近さでの突き合わせは当てになりません */

result の意味

仕様

• 要求が受理される条件: 最初のフレーム配送後であること、対応 path_id
  ("P1" / "P2") であること。受理されると swap の通し番号 (>= 1) が返り、
  受理されない場合は 0 が返ってシグナルは発火しません
• gate_ms は要求から描画確認 (resume gate) 完了までの時間です。実測は
  数百 ms 程度 (プロセス再起動方式の 2〜3 秒に対する短縮が目的の機能です)
• 現在の経路は blink_web_view_get_render_path() で取れます (result が
  "ok" のときのみ更新されます)

発火順序

実装で保証される順序:

• load_uri() 内: uri-changed → load-changed(STARTED) (この順・同期)
• コミット時: load-changed(COMMITTED) → notify::uri → uri-changed
• onload 時: 注入 CSS / JS ブリッジ適用 → load-changed(FINISHED) →
  notify::is-loading

保証されない順序:

• title-changed と load-changed の前後関係は不定です。FINISHED の後に
  title-changed が来ることも普通にあります (動的タイトル変更を含む)

ライフサイクルとスレッド

• エンジン発のシグナルは全て GTK メインスレッドで届きます。ハンドラ内から
  GTK API を直接呼べます
• BlinkGTK の API はメインスレッドから呼んでください。load_uri() 等が
  同期発火するシグナルは呼び出したスレッドで走ります (スレッド検査は
  ありません)
• blink_gtk_shutdown() の進行中にもシグナルが届くことがあります。その
  時点では get_uri() / get_title() が NULL を返すため、ハンドラは
  NULL を許容してください (本ページの例はすべて NULL チェック付きです)
• getter の返す文字列は静的バッファです。ハンドラの外に持ち出すなら
  g_strdup() してください
• GPU モード egl の BlinkWebViewEgl ウィジェットは現在このページの
  シグナルを発火しません (標準の BlinkWebView のみ)

実用パターン: ブラウザ UI の更新

#include <blink_gtk/blink_gtk.h>
#include <gtk/gtk.h>
#include <string.h>

typedef struct {
    GtkWidget *window;
    GtkWidget *url_entry;
    GtkWidget *spinner;
    guint      spinner_timeout;
} BrowserUI;

static gboolean stop_spinner_fallback(gpointer data) {
    BrowserUI *ui = data;
    gtk_widget_set_visible(ui->spinner, FALSE);
    ui->spinner_timeout = 0;
    return G_SOURCE_REMOVE;
}

static void on_load_changed(BlinkWebView *view, BlinkLoadEvent ev,
                            gpointer user_data) {
    BrowserUI *ui = user_data;
    if (ev == BLINK_LOAD_STARTED) {
        gtk_widget_set_visible(ui->spinner, TRUE);
        /* 無音ケース (ダウンロード化・204) の保険 */
        if (ui->spinner_timeout)
            g_source_remove(ui->spinner_timeout);
        ui->spinner_timeout =
            g_timeout_add_seconds(30, stop_spinner_fallback, ui);
    } else if (ev == BLINK_LOAD_FINISHED) {
        gtk_widget_set_visible(ui->spinner, FALSE);
        if (ui->spinner_timeout) {
            g_source_remove(ui->spinner_timeout);
            ui->spinner_timeout = 0;
        }
    }
}

static void on_load_failed(BlinkWebView *view, int error_code,
                           const char *failing_uri, gpointer user_data) {
    BrowserUI *ui = user_data;
    gtk_widget_set_visible(ui->spinner, FALSE);
    if (error_code == -3)
        return;   /* ERR_ABORTED は正常操作の副産物 */
    g_message("load failed: %d %s", error_code,
              failing_uri ? failing_uri : "");
}

static void on_uri_changed(BlinkWebView *view, gpointer user_data) {
    BrowserUI *ui = user_data;
    const char *uri = blink_web_view_get_uri(view);
    gtk_editable_set_text(GTK_EDITABLE(ui->url_entry), uri ? uri : "");
}

static void on_title_changed(BlinkWebView *view, gpointer user_data) {
    BrowserUI *ui = user_data;
    const char *title = blink_web_view_get_title(view);
    char *t = g_strdup_printf("%s - MyBrowser",
                              (title && *title) ? title : "(untitled)");
    gtk_window_set_title(GTK_WINDOW(ui->window), t);
    g_free(t);
}

static void setup_signals(BlinkWebView *view, BrowserUI *ui) {
    g_signal_connect(view, "load-changed", G_CALLBACK(on_load_changed), ui);
    g_signal_connect(view, "load-failed", G_CALLBACK(on_load_failed), ui);
    g_signal_connect(view, "uri-changed", G_CALLBACK(on_uri_changed), ui);
    g_signal_connect(view, "title-changed", G_CALLBACK(on_title_changed), ui);
}

WebKitGTK からの移行

制限事項まとめ

関連

• JS↔︎C メッセージング・注入・カスタムスキーム: アプリ連携 API
• ダイアログ・ファイル選択・証明書エラー: UI ハンドラ API
• ナビゲーション操作 (go_back 等): Navigation API

変更履歴