BlinkGTK C API Reference

Author: BlinkGTK Development Team
Date: 2026-03-07
Target Version: v1.1.0 and later
Changelog: Initial version (input event API added)

How this page fits in (updated 2026-07-30)

This page collects the common policies (thread safety, NULL guards, memory
management) and the complete function index (generated from the header).
For how to use each API, with full code examples, see the
per-topic pages; to find a function by goal, see
How do I…?. Every API named here is mechanically
verified to exist in the bundled header and shared library.

Overview

The BlinkGTK C API is defined in blink_gtk/blink_gtk.h.
Following the same design philosophy as WebKitGTK, it provides APIs that can be used directly from C.

Include path setup:

pkg-config --cflags blinkgtk-0.1

#include <blink_gtk/blink_gtk.h>

Thread Safety Policy

Every public BlinkGTK function must be called from the GTK main thread only.
Calling one from a worker or background thread is undefined behaviour.
If you need to drive the view from another thread, dispatch to the main thread
with g_idle_add().

/* Calling safely from a worker thread */
static gboolean load_on_main_thread(gpointer data) {
    const char* uri = (const char*)data;
    blink_web_view_load_uri(BLINK_WEB_VIEW(g_web_view), uri);
    return G_SOURCE_REMOVE;
}

/* inside the worker thread */
g_idle_add(load_on_main_thread, "https://example.com");

NULL Guard Policy

Since v1.1.0 every public function checks its arguments with
g_return_if_fail() / g_return_val_if_fail(). Passing NULL prints a GLib
warning and returns safely — it does not crash.

/* What happens when NULL is passed */
blink_web_view_load_uri(BLINK_WEB_VIEW(NULL), "https://example.com");
/* Output: (process:PID): BlinkGTK-CRITICAL **: blink_web_view_load_uri: assertion 'web_view != NULL' failed */

Note that this makes mistakes survivable, not invisible: the call does
nothing, so a missing page or an unchanged setting is the symptom you will see.
Read the warnings on stderr when something silently fails to happen.

Type Definitions

BlinkWebView

typedef GtkWidget BlinkWebView;

A typedef for GtkWidget. The central type in BlinkGTK, representing a web content display widget powered by the Blink rendering engine.

BlinkLoadEvent

typedef enum {
  BLINK_LOAD_STARTED,     /* A new load has started */
  BLINK_LOAD_REDIRECTED,  /* The load has been redirected */
  BLINK_LOAD_COMMITTED,   /* The load has been committed */
  BLINK_LOAD_FINISHED     /* The load has finished */
} BlinkLoadEvent;

BlinkLoadError

typedef enum {
  BLINK_LOAD_ERROR_NETWORK,      /* Network error */
  BLINK_LOAD_ERROR_CANCELLED,    /* Load was cancelled */
  BLINK_LOAD_ERROR_INVALID_URL   /* Invalid URL */
} BlinkLoadError;

Initialization and Shutdown API

blink_gtk_init(&argc, &argv)

gboolean blink_gtk_init(int* argc, char*** argv);

Initializes BlinkGTK. Must be called before creating any BlinkGTK widgets.

Parameter	Type	Description
`argc`	`int*`	Address of `argc` from `main()` (may be NULL)
`argv`	`char***`	Address of `argv` from `main()` (may be NULL)

Returns: TRUE if initialization succeeded, FALSE otherwise.

Thread safety: Must be called from the main thread only.

Example:

int main(int argc, char* argv[]) {
    if (!blink_gtk_init(&argc, &argv)) {
        g_critical("BlinkGTK initialization failed");
        return 1;
    }
    /* ... */
}

blink_gtk_run_main_loop()

int blink_gtk_run_main_loop(void);

Starts the Chromium main loop. Blocks until blink_gtk_quit_main_loop() is called.

Returns: Exit code (normally 0).

Note: Uses Chromium's base::RunLoop rather than GTK's g_application_run().

blink_gtk_quit_main_loop()

void blink_gtk_quit_main_loop(void);

Quits the main loop started by blink_gtk_run_main_loop().

blink_gtk_shutdown()

void blink_gtk_shutdown(void);

Shuts down BlinkGTK. Call when the application is closing.

Note: From v1.1.0 onward, internally calls _exit(0) to avoid the DiscardableSharedMemoryManager DCHECK.

BlinkWebView Constructor API

blink_web_view_new()

BlinkWebView* blink_web_view_new(void);

Creates a new BlinkWebView widget.

Returns: A new BlinkWebView widget (caller owns the reference).

Returns NULL if: blink_gtk_init(&argc, &argv) was not called, or initialization failed.

Example:

BlinkWebView* web_view = BLINK_WEB_VIEW(blink_web_view_new());
if (!web_view) {
    g_critical("Failed to create BlinkWebView");
    blink_gtk_shutdown();
    return 1;
}
g_object_ref_sink(web_view);  /* Convert floating reference to owned reference */

blink_web_view_load_uri()

void blink_web_view_load_uri(BlinkWebView* web_view, const char* uri);

Requests loading of the specified URI in the BlinkWebView.

Parameter	Type	Description
`web_view`	`BlinkWebView*`	The target BlinkWebView
`uri`	`const char*`	URI string to load

Supported URI schemes:

https:// / http:// — Standard web pages
file:// — Local files

Loading inline HTML:

To display inline HTML, use blink_web_view_load_html() instead of data: URLs
(data:URL to load_html() migration).

blink_web_view_load_uri(BLINK_WEB_VIEW(web_view), "https://www.google.com");

/* data:URL to load_html() migration — use load_html() for inline HTML */
blink_web_view_load_html(BLINK_WEB_VIEW(web_view),
    "<!DOCTYPE html><html><body style='margin:0'>"
    "<div style='display:block;background:#0000ff;width:800px;height:200px'>BLUE</div>"
    "</body></html>", NULL);

Note: With blink_web_view_load_html(), plain HTML can be passed directly without
data: URL encoding (e.g., %23). CSS color values like #ffe work as-is.
Always include DOCTYPE. Without it, the browser enters quirks mode and div elements are treated as inline elements (measured).

blink_web_view_go_back()

void blink_web_view_go_back(BlinkWebView* web_view);

Loads the previous history item.

blink_web_view_go_forward()

void blink_web_view_go_forward(BlinkWebView* web_view);

Loads the next history item.

blink_web_view_reload()

void blink_web_view_reload(BlinkWebView* web_view);

Reloads the current page.

blink_web_view_stop()

void blink_web_view_stop(BlinkWebView* web_view);

Stops any ongoing load operation.

blink_web_view_can_go_back()

gboolean blink_web_view_can_go_back(BlinkWebView* web_view);

Returns: TRUE if there is a previous history item.

blink_web_view_can_go_forward()

gboolean blink_web_view_can_go_forward(BlinkWebView* web_view);

Returns: TRUE if there is a next history item.

blink_web_view_load_html()

void blink_web_view_load_html(BlinkWebView* web_view,
                              const char* html,
                              const char* base_uri);

Since v1.1.0 — loads an HTML string directly. Compatible with WebKitGTK's
webkit_web_view_load_html().

Parameter	Type	Description
`web_view`	`BlinkWebView*`	Target view
`html`	`const char*`	HTML string to load
`base_uri`	`const char*`	Base URI used to resolve relative URLs (may be NULL)

When base_uri is NULL, about:blank is used as the base URI, which means
relative paths (images, stylesheets) will not resolve. Pass a real base URI when
your HTML refers to other files.

/* Basic use */
blink_web_view_load_html(BLINK_WEB_VIEW(web_view),
    "<!DOCTYPE html><html><body><h1>Hello</h1></body></html>",
    NULL);

/* With a base URI so that relative image paths resolve */
blink_web_view_load_html(BLINK_WEB_VIEW(web_view),
    "<img src=\"cover.png\">",
    "file:///home/user/book/");

Content Information API

blink_web_view_get_uri()

const char* blink_web_view_get_uri(BlinkWebView* web_view);

Returns: The current active URI (no transfer, may be NULL).

blink_web_view_get_title()

const char* blink_web_view_get_title(BlinkWebView* web_view);

Returns: The current page title (no transfer, may be NULL).

blink_web_view_get_estimated_load_progress()

gdouble blink_web_view_get_estimated_load_progress(BlinkWebView* web_view);

Returns: Load progress from 0.0 to 1.0 (1.0 = complete).

blink_web_view_is_loading()

gboolean blink_web_view_is_loading(BlinkWebView* web_view);

Returns: TRUE if currently loading content.

WebPreferences Getter API

Each setter has a matching getter. They read back the value currently in effect,
which is useful when your UI has to reflect state it did not set itself.

gboolean     blink_web_view_get_javascript_enabled(BlinkWebView* web_view);
gboolean     blink_web_view_get_images_enabled(BlinkWebView* web_view);
gboolean     blink_web_view_get_local_storage_enabled(BlinkWebView* web_view);
int          blink_web_view_get_default_font_size(BlinkWebView* web_view);
const char*  blink_web_view_get_default_encoding(BlinkWebView* web_view);

Function	Returns	Default
`blink_web_view_get_javascript_enabled()`	`TRUE` if JavaScript runs	`TRUE`
`blink_web_view_get_images_enabled()`	`TRUE` if images load	`TRUE`
`blink_web_view_get_local_storage_enabled()`	`TRUE` if localStorage is available	`TRUE`
`blink_web_view_get_default_font_size()`	Default font size in px	`16`
`blink_web_view_get_default_encoding()`	Default character encoding	`"UTF-8"`

The string returned by blink_web_view_get_default_encoding() is owned by the
view — do not free it, and copy it if you need it to outlive the next setter call.

if (!blink_web_view_get_javascript_enabled(BLINK_WEB_VIEW(view))) {
    g_print("JavaScript is off for this view\n");
}

Screenshot API

blink_web_view_capture_screenshot()

gboolean blink_web_view_capture_screenshot(BlinkWebView* web_view,
                                           const char* filename);

Captures the current rendering frame and saves it as a PNG file.

Parameter	Type	Description
`web_view`	`BlinkWebView*`	The target BlinkWebView
`filename`	`const char*`	File path to save (`.png` extension recommended)

Returns: TRUE if capture was initiated successfully.

Note: This is asynchronous. The file may not be written immediately.

Recommended timing: Wait at least 30 seconds after navigation before capturing.
Renderer initialization takes approximately 25 seconds (measured).

Example:

/* Take screenshot 30 seconds after navigation */
static gboolean take_screenshot(gpointer data) {
    BlinkWebView* view = (BlinkWebView*)data;
    blink_web_view_capture_screenshot(BLINK_WEB_VIEW(view), "/tmp/blinkgtk_screenshot.png");
    return G_SOURCE_REMOVE;
}
g_timeout_add_seconds(30, take_screenshot, web_view);

blink_web_view_capture_screenshot_async()

typedef void (*BlinkScreenshotCallback)(BlinkWebView* web_view,
                                        gboolean success,
                                        const char* filename,
                                        gpointer user_data);

void blink_web_view_capture_screenshot_async(BlinkWebView* web_view,
                                             const char* filename,
                                             BlinkScreenshotCallback callback,
                                             gpointer user_data);

Since v1.1.0 — the asynchronous form of
blink_web_view_capture_screenshot(). The callback runs on the GTK main thread
when the capture finishes.

Parameter	Type	Description
`web_view`	`BlinkWebView*`	Target view
`filename`	`const char*`	Destination path (`.png` recommended)
`callback`	`BlinkScreenshotCallback`	Called on completion
`user_data`	`gpointer`	Passed through to the callback

The callback receives success = FALSE when the capture failed; filename is
still the path you asked for, so you can report it. Use the asynchronous form
when you do not want to block the main loop while the frame is captured.

Testing and Debugging API

blink_web_view_inject_test_input()

void blink_web_view_inject_test_input(BlinkWebView* web_view,
                                      double mouse_x,
                                      double mouse_y);

v1.1.0 and later — Injects test input events directly into the Renderer.

Sends a mouse click (left button Down/Up) and keyboard event ('A' Down/Up)
to the Renderer via ForwardMouseEvent() / ForwardKeyboardEvent().

Parameter	Type	Description
`web_view`	`BlinkWebView*`	The target BlinkWebView
`mouse_x`	`double`	X coordinate for mouse click (pixels)
`mouse_y`	`double`	Y coordinate for mouse click (pixels)

Note: This API is for debugging and testing only. It bypasses the GTK gesture
event pipeline to test Chromium's input routing directly.

Example:

/* Test input 10 seconds after page load */
static gboolean test_input(gpointer data) {
    BlinkWebView* view = (BlinkWebView*)data;
    /* Send mouse click at (400, 100) + key 'A' */
    blink_web_view_inject_test_input(BLINK_WEB_VIEW(view), 400.0, 100.0);
    return G_SOURCE_REMOVE;
}
g_timeout_add_seconds(10, test_input, web_view);

Complete Sample Program

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

static BlinkWebView* g_web_view = NULL;

static gboolean quit_timer(gpointer data) {
    printf("Auto-quit after 45 seconds\n");
    blink_gtk_quit_main_loop();
    return G_SOURCE_REMOVE;
}

static gboolean screenshot_timer(gpointer data) {
    if (g_web_view) {
        blink_web_view_capture_screenshot(BLINK_WEB_VIEW(g_web_view), "/tmp/blinkgtk.png");
        printf("Screenshot captured\n");
    }
    return G_SOURCE_REMOVE;
}

int main(int argc, char* argv[]) {
    /* Initialize */
    if (!blink_gtk_init(&argc, &argv)) {
        fprintf(stderr, "Failed to initialize BlinkGTK\n");
        return 1;
    }

    /* Create BlinkWebView */
    g_web_view = BLINK_WEB_VIEW(blink_web_view_new());
    if (!g_web_view) {
        fprintf(stderr, "Failed to create BlinkWebView\n");
        blink_gtk_shutdown();
        return 1;
    }
    g_object_ref_sink(g_web_view);

    /* data:URL to load_html() migration — load inline HTML */
    blink_web_view_load_html(BLINK_WEB_VIEW(g_web_view),
        "<!DOCTYPE html><html>"
        "<body style='background:#00ff00'>Hello BlinkGTK</body></html>", NULL);

    /* Set timers */
    g_timeout_add_seconds(30, screenshot_timer, NULL);  /* Screenshot after 30s */
    g_timeout_add_seconds(45, quit_timer, NULL);         /* Quit after 45s */

    /* Run main loop */
    int status = blink_gtk_run_main_loop();

    /* Cleanup */
    if (g_web_view) {
        g_object_unref(g_web_view);
        g_web_view = NULL;
    }
    blink_gtk_shutdown();

    return status;
}

Signals

BlinkWebView emits GObject signals for load state, title and URI changes,
new-window requests and messages from page JavaScript.
They are documented in full in Signals API — including the exact
handler signature for each one, which is easy to get wrong
(title-changed does not pass the title; read it with
blink_web_view_get_title()).

Environment Variables

Rendering path, GPU mode and diagnostics are selected with environment
variables rather than API calls, so that they can be changed without
rebuilding the application. See
Environment Variables for the supported list.

blink-web-view-ja.md - BlinkWebView widget details
navigation-api-ja.md - Navigation API details
signals-api-ja.md - Signal reference

This document is created and maintained by the BlinkGTK Development Team.

Three functions that exist in the shipped header blink_gtk.h (mechanically
verified as of 2026-07-28).

blink_web_view_get_cookies()

typedef void (*BlinkCookieCallback)(const char* cookies, gpointer user_data);

void blink_web_view_get_cookies(BlinkWebView* web_view,
                                const char* url,
                                BlinkCookieCallback callback,
                                gpointer user_data);

Asynchronously retrieves the cookies for a URL. The callback receives a string in
"a=1; b=2" form.

blink_web_view_set_cookie()

typedef void (*BlinkSetCookieCallback)(gboolean success, gpointer user_data);

void blink_web_view_set_cookie(BlinkWebView* web_view,
                               const char* url,
                               const char* cookie_line,
                               BlinkSetCookieCallback callback,
                               gpointer user_data);

cookie_line uses the same syntax as the Set-Cookie header, for example
"session=abc123; Path=/; Max-Age=3600".

The cookie is validated before being stored. If the line cannot be parsed, or
the cookie store rejects it, the callback receives FALSE. callback may be
NULL.

static void on_set(gboolean success, gpointer user_data) {
    g_print("cookie: %s\n", success ? "OK" : "rejected");
}

blink_web_view_set_cookie(BLINK_WEB_VIEW(web_view),
                          "https://example.com",
                          "session=abc123; Path=/; Max-Age=3600",
                          on_set, NULL);

blink_web_view_delete_all_cookies()

void blink_web_view_delete_all_cookies(BlinkWebView* web_view);

Deletes all cookies in the browser context.

Deprecated APIs

These still work, but do not use them in new code. The compiler will warn
you.

blink_web_view_load_url()

Use blink_web_view_load_uri() instead.
It carries G_DEPRECATED_FOR(blink_web_view_load_uri).

blink_web_view_get_url()

Use blink_web_view_get_uri() instead.
It carries G_DEPRECATED_FOR(blink_web_view_get_uri).

There is no hurry to rewrite existing code. If we ever schedule their removal,
we will say so in the release notes first.

Complete function index

The 79 functions in blink_gtk.h that you would actually call. Where a dedicated page
exists it is linked; otherwise the entry says "this page".

Function	Details
`blink_web_view_new_container()`	this page
`blink_gtk_init()`	app-integration-api-en.md
`blink_gtk_run_main_loop()`	app-integration-api-en.md
`blink_gtk_quit_main_loop()`	this page
`blink_gtk_shutdown()`	this page
`blink_gtk_set_devtools_locale()`	devtools-api-en.md
`blink_gtk_get_devtools_locale()`	devtools-api-en.md
`blink_gtk_set_icu_data_path()`	this page
`blink_gtk_set_resources_path()`	this page
`blink_web_view_new()`	app-integration-api-en.md
`blink_web_view_new_with_gpu_mode()`	settings-api-en.md
`blink_web_view_get_gpu_mode()`	settings-api-en.md
`blink_web_view_load_uri()`	app-integration-api-en.md
`blink_web_view_load_html()`	signals-api-en.md
`blink_web_view_get_uri()`	this page
`blink_web_view_get_title()`	this page
`blink_web_view_go_back()`	navigation-api-en.md
`blink_web_view_go_forward()`	navigation-api-en.md
`blink_web_view_reload()`	navigation-api-en.md
`blink_web_view_stop()`	navigation-api-en.md
`blink_web_view_can_go_back()`	navigation-api-en.md
`blink_web_view_can_go_forward()`	navigation-api-en.md
`blink_web_view_get_estimated_load_progress()`	this page
`blink_web_view_is_loading()`	this page
`blink_web_view_capture_screenshot()`	this page
`blink_web_view_capture_screenshot_async()`	this page
`blink_web_view_inject_test_input()`	this page
`blink_web_view_set_content_policy()`	settings-api-en.md
`blink_web_view_get_content_policy()`	settings-api-en.md
`blink_web_view_execute_javascript()`	app-integration-api-en.md
`blink_web_view_set_canvas_size()`	this page
`blink_web_view_set_zoom_level()`	page-search-zoom-en.md
`blink_web_view_get_zoom_level()`	page-search-zoom-en.md
`blink_web_view_set_javascript_dialog_handler()`	ui-handlers-api-en.md
`blink_web_view_set_file_chooser_handler()`	ui-handlers-api-en.md
`blink_web_view_file_chooser_response()`	ui-handlers-api-en.md
`blink_web_view_set_download_handler()`	ui-handlers-api-en.md
`blink_web_view_set_certificate_error_handler()`	ui-handlers-api-en.md
`blink_web_view_set_javascript_enabled()`	navigation-api-en.md
`blink_web_view_set_images_enabled()`	settings-api-en.md
`blink_web_view_set_local_storage_enabled()`	settings-api-en.md
`blink_web_view_set_default_font_size()`	page-search-zoom-en.md
`blink_web_view_set_default_encoding()`	this page
`blink_web_view_get_javascript_enabled()`	settings-api-en.md
`blink_web_view_get_images_enabled()`	settings-api-en.md
`blink_web_view_get_local_storage_enabled()`	settings-api-en.md
`blink_web_view_get_default_font_size()`	this page
`blink_web_view_get_default_encoding()`	this page
`blink_web_view_find_in_page()`	page-search-zoom-en.md
`blink_web_view_stop_finding()`	page-search-zoom-en.md
`blink_web_view_get_cookies()`	this page
`blink_web_view_delete_all_cookies()`	this page
`blink_permission_request_get_type_name()`	signals-api-en.md
`blink_permission_request_allow()`	signals-api-en.md
`blink_permission_request_deny()`	signals-api-en.md
`blink_web_view_set_cookie()`	this page
`blink_web_view_set_user_agent()`	settings-api-en.md
`blink_web_view_get_user_agent()`	settings-api-en.md
`blink_web_view_set_auth_handler()`	ui-handlers-api-en.md
`blink_web_view_auth_response()`	ui-handlers-api-en.md
`blink_web_view_register_custom_scheme()`	app-integration-api-en.md
`blink_web_view_register_custom_scheme_full()`	app-integration-api-en.md
`blink_web_view_inject_user_script()`	app-integration-api-en.md
`blink_web_view_inject_user_stylesheet()`	app-integration-api-en.md
`blink_web_view_remove_all_user_scripts()`	app-integration-api-en.md
`blink_web_view_print_to_pdf()`	this page
`blink_web_view_set_fullscreen_handler()`	this page
`blink_web_view_exit_fullscreen()`	this page
`blink_web_view_is_fullscreen()`	this page
`blink_web_view_open_devtools()`	devtools-api-en.md
`blink_web_view_close_devtools()`	devtools-api-en.md
`blink_web_view_get_devtools_url()`	devtools-api-en.md
`blink_web_view_queue_draw()`	this page
`blink_web_view_set_frame_data()`	this page
`blink_web_view_register_message_handler()`	app-integration-api-en.md
`blink_web_view_unregister_message_handler()`	app-integration-api-en.md
`blink_web_view_send_message_to_page()`	app-integration-api-en.md
`blink_gtk_get_version()`	this page
`blink_gtk_get_chromium_version()`	this page

BlinkGTK C API Reference

Overview

Thread Safety Policy

NULL Guard Policy

Type Definitions

BlinkWebView

BlinkLoadEvent

BlinkLoadError

Initialization and Shutdown API

blink_gtk_init(&argc, &argv)

blink_gtk_run_main_loop()

blink_gtk_quit_main_loop()

blink_gtk_shutdown()

BlinkWebView Constructor API

blink_web_view_new()

Navigation API

blink_web_view_load_uri()

blink_web_view_go_back()

blink_web_view_go_forward()

blink_web_view_reload()

blink_web_view_stop()

blink_web_view_can_go_back()

blink_web_view_can_go_forward()

blink_web_view_load_html()

Content Information API

blink_web_view_get_uri()

blink_web_view_get_title()

blink_web_view_get_estimated_load_progress()

blink_web_view_is_loading()

WebPreferences Getter API

Screenshot API

blink_web_view_capture_screenshot()

blink_web_view_capture_screenshot_async()

Testing and Debugging API

blink_web_view_inject_test_input()

Complete Sample Program

Signals

Environment Variables

Related Documentation

Cookie API

blink_web_view_get_cookies()

blink_web_view_set_cookie()

blink_web_view_delete_all_cookies()

Deprecated APIs

blink_web_view_load_url()

blink_web_view_get_url()

Complete function index