BlinkGTK GObject Signals API Reference

Version: 1.2.2-build6
Last updated: 2026-07-30
Language: English |

日本語

About this page

Reference for the eight GObject signals emitted by BlinkWebView: load
state, URL and title changes, new-window requests, messages from page JS,
and permission requests.

This page is written from measurements of the actual engine implementation.
The wiring status of each handler was re-checked against 1.2.2-build6.

Major correction from earlier editions (before 2026-07-30): previous
editions showed title-changed / uri-changed callbacks with a string
argument. Neither signal has any extra argument. Code written against
the old signatures receives user_data in the string-argument position —
a recipe for crashes and memory corruption. The signatures on this page
match the implementation.

Signal list (as implemented)

The property notifications notify::uri / notify::title /
notify::is-loading also work (when migrating from WebKitGTK, reusing
notify::uri / notify::title unchanged is the easiest path).

Three facts to know first

1. All engine-originated signals arrive on the GTK main thread (the
   Chromium UI thread is the GTK main loop). You may call GTK APIs from
   handlers. However, the signals that load_uri() fires synchronously (see
   below) run on whatever thread called the API — so call BlinkGTK APIs
   from the main thread.
2. title-changed / uri-changed carry no arguments. Read the values
   inside the handler with blink_web_view_get_title() /
   blink_web_view_get_uri().
3. Strings returned by getters live in an internal static buffer and are
   overwritten by the next call to the same getter. g_strdup() them if you
   keep them.

Basic form

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, not an argument */
    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

Signature

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

BlinkLoadEvent values (explicit — note the order)

typedef enum {
    BLINK_LOAD_STARTED    = 0,
    BLINK_LOAD_COMMITTED  = 1,
    BLINK_LOAD_FINISHED   = 2,
    BLINK_LOAD_REDIRECTED = 3   /* reserved — not emitted by the current runtime */
} BlinkLoadEvent;

• BLINK_LOAD_REDIRECTED is never emitted today (reserved for the
  future). Redirect tracking is not available
• The value order differs from past editions. Always compare by constant
  name (hard-coded numbers like if (ev == 3) will break)

What each value actually means

Firing patterns by operation (measured)

What is guaranteed at FINISHED

Right before FINISHED, the engine has finished applying injected stylesheets
(App Integration API) and the JS message
bridge (window.blinkgtk). Calling execute_javascript() from a FINISHED
handler can already use the bridge.

FINISHED means onload, though — not that dynamically-built content has
finished appearing (a paint-complete notification is not yet provided).

Stopping a loading spinner correctly

Stopping only on FINISHED can leave the spinner running forever:

• Non-committed failures (cancellations etc.) → also stop on load-failed
• Navigations that turn into downloads, or HTTP 204/205 responses, fire
  no signal at all (complete silence). Add a timeout backed by
  blink_web_view_is_loading() as a safety net

load-failed

Signature

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

The arguments come in (error_code, failing_uri) order. A callback in the
reverse order reads a pointer as an integer.

When it fires (important — counterintuitive)

The only condition is "a navigation that ended without committing, with a
net error". Consequences:

The real type of error_code

Values are raw negative Chromium net error codes (-3, -105, …). The
header's BlinkLoadError enum (BLINK_LOAD_ERROR_NETWORK etc.) is unused
by the current runtime — treat the argument as an int in C.

Full list: Chromium net_error_list.h.

Implementation pattern

static void on_load_failed(BlinkWebView *view, int error_code,
                           const char *failing_uri, gpointer user_data) {
    if (error_code == -3)   /* ERR_ABORTED: byproduct of normal use; ignore */
        return;
    const char *current = blink_web_view_get_uri(view);
    if (current && failing_uri && strcmp(current, failing_uri) != 0)
        return;             /* failure of something other than the shown page */
    g_message("load failed: %d %s", error_code, failing_uri);
}

uri-changed / title-changed

Signature (no extra arguments for either)

void user_function(BlinkWebView* web_view, gpointer user_data);

Read the values inside the handler with blink_web_view_get_uri() /
blink_web_view_get_title().

uri-changed behavior details

title-changed behavior details

new-window-requested

Signature

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

This is a notification — you cannot control it

It tells you that window.open() or <a target="_blank"> happened; you
cannot block it or open it elsewhere (no return value). The current engine
is single-window: by the time the signal fires it has already started
navigating this same WebView to the target URL.

• Do not call load_uri(url) from the handler — the engine has already
  started the same navigation; you would double-navigate. Use this signal
  for logging or for showing your own "open in new tab?" UI
• If you must divert to a different URL, defer with g_idle_add() (for
  target="_blank"-style requests the engine's own navigation wins over a
  synchronous call)
• Whether it was a popup, requested size, and user-gesture information are
  not currently passed
• Some "open in new tab" paths (e.g. middle click) never fire this signal
  at all (they open in the same view)
• What page JS sees from window.open(): normally a window that is
  immediately closed === true; with noopener, null. Connecting a
  handler changes none of this

message-received

Receives window.blinkgtk.postMessage() from page JS. Two arguments:
(name, data) — channel name and Base64 data. Full semantics (encodings,
multi-subscriber behavior, relation to the C-API handler) are documented in
the App Integration API.

Permission requests (permission-request)

Receives permission requests such as geolocation and notifications.

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);   /* allow notifications only */
    else
        blink_permission_request_deny(req);
    return TRUE;   /* handled */
}

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

Semantics

• The handler must call exactly one of blink_permission_request_allow() or
  blink_permission_request_deny(), exactly once, synchronously inside
  the signal handler. The BlinkPermissionRequest becomes invalid once
  the handler returns; deferred responses are not possible (returning TRUE
  without answering counts as denial; touching the handle afterwards is
  undefined)
• If you need user confirmation, deny this request, direct the user to your
  settings UI, and allow on a later request
• blink_permission_request_get_type_name() returns the kind: one of the 38
  names listed below, or "unknown". Do not allow everything without
  looking at the kind.
• If no handler returns TRUE, the request is denied (deny-by-default)
• This signal is C-only for now (the argument is a raw pointer, so language
  bindings cannot use it)

List of request kinds (v1.2.2-build6 and later)

What a reading application actually uses:

Network:

Input and devices:

"unknown" is returned only when Chromium gained a kind that BlinkGTK has
not caught up with yet. release/scripts/check-permission-type-names.sh
detects that state.

Separate profile and cache per view (v1.2.2-build6 and later)

Views created with blink_web_view_new() share one profile and cache within a
process. Opening the same URL in several views serves all but the first from
that shared cache, so the server sees a single request.

Use blink_web_view_new_with_profile() to separate them.

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

• The same name means the same profile; different names are separate
• Storage lives under profiles/<name> inside the process profile directory
• Names may contain letters, digits, - and _ only; anything else returns NULL
• Separated: HTTP cache, cookies, localStorage, IndexedDB
• Not separated: the renderer process pool and anything else the process shares
• The directory is created on first use and kept after blink_gtk_shutdown().
  Use a fresh name, or remove the directory, when a run must start cold
• What blink_gtk_get_profile_path() reports does not change
• The HTTP cache lives inside that profile (profiles/<name>/Cache).
  Views from blink_web_view_new() keep an in-memory cache
• The cache survives blink_gtk_shutdown(). The next run starts warm.
  Remove the profile directory first when a run must start cold

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+)

Completion notification for a live render-path switch (BlinkShift) requested
with blink_web_view_switch_render_path(). The switch is asynchronous; this
signal is the authoritative result (the function's return value only says
whether the request was accepted).

static void on_render_path_changed(BlinkWebView *view,
                                   const char *path_id,   /* "P1" / "P2" */
                                   const char *result,    /* see table */
                                   int gate_ms,           /* time taken, ms */
                                   int seq,               /* this swap's number */
                                   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 request was not accepted");
/* seq is assigned synchronously when the request is accepted, and the
 * completion signal carries the same number — so records taken before and
 * after a swap can be keyed to the exact swap they describe. Matching by
 * time proximity is unreliable when swaps run back to back. */

Meaning of result

Notes

• A request is accepted only after the first frame has been delivered, and
  only for supported path ids ("P1" / "P2"). On acceptance the function
  returns this swap's sequence number (>= 1); if rejected it returns 0 and
  no signal is emitted
• gate_ms measures from the request to the completion of the resume gate
  (render verification). Measured values are a few hundred ms — this feature
  exists to replace the 2-3 second process-restart approach
• The current path is available via blink_web_view_get_render_path()
  (updated only when result is "ok")

Emission order

Guaranteed by the implementation:

• Inside load_uri(): uri-changed → load-changed(STARTED) (synchronous,
  in this order)
• On commit: load-changed(COMMITTED) → notify::uri → uri-changed
• At onload: injected CSS / JS bridge applied → load-changed(FINISHED) →
  notify::is-loading

Not guaranteed:

• The order of title-changed relative to load-changed is undefined.
  title-changed after FINISHED is perfectly normal (including dynamic title
  changes)

Lifecycle and threading

• Engine-originated signals all arrive on the GTK main thread; handlers may
  call GTK APIs directly
• Call BlinkGTK APIs from the main thread. Signals fired synchronously
  by load_uri() etc. run on the calling thread (there is no thread check)
• Signals can still arrive while blink_gtk_shutdown() is in progress; at
  that point get_uri() / get_title() return NULL, so handlers must
  tolerate NULL (all examples on this page do)
• Getter strings live in a static buffer; g_strdup() anything you keep
• The GPU-mode BlinkWebViewEgl widget currently emits none of these
  signals (standard BlinkWebView only)

Practical pattern: updating browser 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);
        /* safety net for the silent cases (downloads, 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: byproduct of normal use */
    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);
}

Migrating from WebKitGTK

Known limitations

Related

• JS↔︎C messaging, injection, custom schemes: App Integration API
• Dialogs, file chooser, certificate errors: UI Handlers API
• Navigation operations (go_back etc.): Navigation API

Changelog