Changelog for webkitgtk: 2.52.5 -> 2.52.6 Source: Documentation/webkitgtk-6.0/migrating-to-webkitgtk-6.0.html, Documentation/webkitgtk-6.0/signal.BackForwardList.changed.html, Documentation/webkitgtk-6.0/signal.CookieManager.changed.html, Documentation/webkitgtk-6.0/signal.EditorState.changed.html, Documentation/webkitgtk-6.0/signal.FaviconDatabase.favicon-changed.html, Documentation/webkitgtk-6.0/signal.InputMethodContext.preedit-changed.html, Documentation/webkitgtk-6.0/signal.WebView.load-changed.html, Documentation/webkitgtk-6.0/signal.WebView.mouse-target-changed.html, Documentation/webkitgtk-6.0/vfunc.InputMethodContext.preedit_changed.html, Documentation/webkitgtk-6.0/vfunc.WebView.load_changed.html, Documentation/webkitgtk-6.0/vfunc.WebView.mouse_target_changed.html, Documentation/webkitgtk-web-process-extension-6.0/signal.WebEditor.selection-changed.html WebKit – 6.0: Migrating WebKitGTK Applications to GTK 4

Migrating WebKitGTK Applications to GTK 4

Migrating WebKitGTK Applications to GTK 4

This document contains guidance to application developers looking to migrate applications that use WebKitGTK from GTK 3 to GTK 4.

webkitgtk-6.0 is a new API version of WebKitGTK designed for use with GTK 4 and libsoup 3. This API version obsoletes webkit2gtk-4.0 and webkit2gtk-4.1, the GTK 3 API versions for libsoup 2 and libsoup 3, respectively. It also obsoletes webkit2gtk-5.0, which was an earlier unstable API version for GTK 4.

Upgrade to libsoup 3

libsoup 2 and libsoup 3 cannot be linked together. If your application currently uses webkit2gtk-4.0, you must first port to webkit2gtk-4.1 by eliminating use of libsoup 2. See Migrating from libsoup 2 for guidance on this. After first migrating to webkit2gtk-4.1, then it is time to start looking into webkitgtk-6.0.

Stop Using Deprecated APIs

All APIs that were previously deprecated in webkit2gtk-4.0 and webkit2gtk-4.1 have been removed. This includes the original JavaScriptCore API (e.g. JSContextRef and JSObjectRef), which has been replaced by the GObject-style JavaScriptCore API (e.g. JSCContext and JSCValue) that is available since 2.22. It also includes the entire GObject DOM API (e.g. WebKitDOMDocument), which has been removed without replacement. Use JavaScript to interact with and manipulate the DOM instead, perhaps via webkit_web_view_evaluate_javascript() or webkit_web_view_call_async_javascript_function() in the UI process, or jsc_value_object_invoke_method() in the web process.

Run your application with the environment variable G_ENABLE_DIAGNOSTIC=1 to notice use of deprecated signals and properties.

Upgrade to GTK 4

After successfully building your webkit2gtk-4.1 application without deprecation warnings, then it is time to attempt to upgrade to GTK 4 and webkitgtk-6.0. This is easier said than done, but the GTK 4 migration guide will help. Good luck.

Most Types Are Final

Only two types are now derivable:

  • WebKitWebView has been often subclassed to customize its behavior for an specific application. This possibility has been kept, as it has proved useful in the past.
  • WebKitInputMethodContext is specifically designed in a way that subclassing is required to make use of it.

The rest of the types are no longer derivable; they are defined with the G_TYPE_FLAG_FINAL flag set. Use composition instead of derivation.

Mandatory Web Process Sandbox

The webkit_web_context_set_sandbox_enabled() and webkit_web_context_get_sandbox_enabled() functions have been removed. The web process sandbox is now always enabled. If your application’s web process needs to access extra directories, use webkit_web_context_add_path_to_sandbox() to mount them in the sandbox.

Mandatory Process Swap on Cross-site Navigation

The WebKitWebContext:process-swap-on-cross-site-navigation-enabled property has been removed. Process swapping is now mandatory. Your application should be prepared for the web view’s web process to be replaced when navigating between different security origins. You can ensure that your application is prepared for this change before porting to GTK 4 by testing your application with the WebKitWebContext:process-swap-on-cross-site-navigation-enabled property enabled. This property was previously disabled by default.

Event Parameter Removed from Context Menu and Option Menu Signals

WebKitWebView::context-menu and WebKitWebView::show-option-menu no longer have a GdkEvent parameter. Adjust your signal handlers accordingly.

Changes to WebKitWebView Construction

webkit_web_view_new_with_context(), webkit_web_view_new_with_settings(), webkit_web_view_new_with_user_content_manager(), and webkit_web_view_new_with_related_view() have all been removed. You may directly use g_object_new() instead. webkit_web_view_new() remains.

Network Session API

WebKit now uses a single global network process for all web contexts, and different network sessions can be created and used in the same network process. All the networking APIs have been moved from WebKitWebContext and WebKitWebsiteDataManager to the new class WebKitNetworkSession. There’s a default global persistent session that you can get with webkit_network_session_get_default(). You can also create new sessions with webkit_network_session_new() for persistent sessions and webkit_network_session_new_ephemeral() for ephemeral sessions. It’s no longer possible to create a WebKitWebsiteDataManager; it’s now created by the WebKitNetworkSession automatically at construction time. The WebKitNetworkSession to be used must be passed to the WebKitWebView as a construct parameter. You can pass the same WebKitNetworkSession object to several web views to use the same session. The only exception is automation mode, which uses its own ephemeral session that is configured by the automation session capabilities. If you notice that your application uses WebKitWebContext or WebKitWebsiteDataManager APIs that no longer exist, look for replacement APIs in WebKitNetworkSession.

webkit_web_context_clear_cache() does not have a direct replacement, but you can use webkit_website_data_manager_clear() to achieve the same effect.

The WebKitWebContext::download-started signal has been removed. Use WebKitNetworkSession::download-started instead.

Favicon Database

WebKitFaviconDatabase is now owned by WebKitWebsiteDataManager instead of WebKitWebContext. Use webkit_website_data_manager_set_favicons_enabled() to enable the favicon database.

There is no replacement for webkit_web_context_set_favicon_database_directory(). Favicons will be stored in the base cache directory of the website data manager.

Hardware Acceleration Policy

WEBKIT_HARDWARE_ACCELERATION_POLICY_ON_DEMAND has been removed from WebKitHardwareAccelerationPolicy. You may still use webkit_settings_set_hardware_acceleration_policy() to enable or disable hardware acceleration.

Scrollbar Appearance

Because GTK 4 does not contain a foreign drawing API, it is no longer possible to draw scrollbars that match arbitrary GTK themes. Accordingly, the webkit_web_context_get_use_system_appearance_for_scrollbars and webkit_web_context_set_use_system_appearance_for_scrollbars APIs have been removed. WebKit will draw scrollbars that match the Adwaita GTK theme.

User Script Message Handlers

webkit_user_content_manager_register_script_message_handler_in_world() and webkit_user_content_manager_unregister_script_message_handler_in_world() have been removed. Instead, webkit_user_content_manager_register_script_message_handler() and webkit_user_content_manager_unregister_script_message_handler() have gained parameters to specify the script world to use.

Download Destination

webkit_download_set_destination(), webkit_download_get_destination(), WebKitDownload:destination, and WebKitDownload::created-destination now all use a filesystem path rather than a URI. All uses must be updated accordingly.

JavaScript Results

WebKitJavascriptResult has been removed. WebKitUserContentManager::script-message-received now directly returns a JSCValue instead.

Web Process Extension

WebKitWebExtension has been renamed to WebKitWebProcessExtension to avoid confusion with WebExtensions, which are unrelated. This affects many methods and signals of other objects as well, e.g. WebKitWebContext::initialize-web-process-extensions. The name of your extension’s entry point must now be webkit_web_process_extension_initialize() or webkit_web_process_extension_initialize_with_user_data().

Beware that as of WebKitGTK 2.40, the entire web process API may unfortunately be removed in the future. For more information on why, see this mailing list thread.

WebKit.BackForwardList::changed

Signal

WebKitBackForwardList::changed

Declaration 

void
changed (
  WebKitBackForwardList* self,
  WebKitBackForwardListItem* item_added,
  gpointer items_removed,
  gpointer user_data
)

Description [src]

This signal is emitted when back_forward_list changes. This happens when the current item is updated, a new item is added or one or more items are removed. Note that both item_added and items_removed can NULL when only the current item is updated. Items are only removed when the list is cleared or the maximum items limit is reached.

Default handler:

The default handler is called after the handlers added via g_signal_connect().

Parameters

item_added

Type: WebKitBackForwardListItem

The WebKitBackForwardListItem added or NULL.

The argument can be NULL.
The data is owned by the caller of the function.
items_removed

Type: gpointer

A GList of WebKitBackForwardListItems.

The argument can be NULL.
The data is owned by the caller of the function.
WebKit.CookieManager::changed

Signal

WebKitCookieManager::changed

Declaration 

void
changed (
  WebKitCookieManager* self,
  gpointer user_data
)

Description [src]

This signal is emitted when cookies are added, removed or modified.

Default handler:

The default handler is called after the handlers added via g_signal_connect().

WebKit.EditorState::changed

Signal

WebKitEditorState::changed

since: 2.44

Declaration 

void
changed (
  WebKitEditorState* self,
  gpointer user_data
)

Description [src]

Emitted when the WebKitEdtorState is changed.

Default handler:

The default handler is called after the handlers added via g_signal_connect().

Available since: 2.44
WebKit.FaviconDatabase::favicon-changed

Signal

WebKitFaviconDatabase::favicon-changed

Declaration 

void
favicon_changed (
  WebKitFaviconDatabase* self,
  gchar* page_uri,
  gchar* favicon_uri,
  gpointer user_data
)

Description [src]

This signal is emitted when the favicon URI of page_uri has been changed to favicon_uri in the database. You can connect to this signal and call webkit_favicon_database_get_favicon() to get the favicon. If you are interested in the favicon of a WebKitWebView it’s easier to use the WebKitWebView:favicon property. See webkit_web_view_get_favicon() for more details.

Default handler:

The default handler is called after the handlers added via g_signal_connect().

Parameters

page_uri

Type: gchar*

The URI of the Web page containing the icon.

The data is owned by the caller of the function.
The value is a NUL terminated UTF-8 string.
favicon_uri

Type: gchar*

The URI of the favicon.

The data is owned by the caller of the function.
The value is a NUL terminated UTF-8 string.
WebKit.InputMethodContext::preedit-changed

Signal

WebKitInputMethodContext::preedit-changed

since: 2.28

Declaration 

void
preedit_changed (
  WebKitInputMethodContext* self,
  gpointer user_data
)

Description [src]

Emitted whenever the preedit sequence currently being entered has changed. It is also emitted at the end of a preedit sequence, in which case webkit_input_method_context_get_preedit() returns the empty string.

Default handler:

The default handler is called after the handlers added via g_signal_connect().

Available since: 2.28
WebKit.WebView::load-changed

Signal

WebKitWebView::load-changed

Declaration 

void
load_changed (
  WebKitWebView* self,
  WebKitLoadEvent load_event,
  gpointer user_data
)

Description [src]

Emitted when a load operation in web_view changes. The signal is always emitted with WEBKIT_LOAD_STARTED when a new load request is made and WEBKIT_LOAD_FINISHED when the load finishes successfully or due to an error. When the ongoing load operation fails WebKitWebView::load-failed signal is emitted before WebKitWebView::load-changed is emitted with WEBKIT_LOAD_FINISHED. If a redirection is received from the server, this signal is emitted with WEBKIT_LOAD_REDIRECTED after the initial emission with WEBKIT_LOAD_STARTED and before WEBKIT_LOAD_COMMITTED. When the page content starts arriving the signal is emitted with WEBKIT_LOAD_COMMITTED event.

You can handle this signal and use a switch to track any ongoing load operation.

static void web_view_load_changed (WebKitWebView  *web_view,
                                   WebKitLoadEvent load_event,
                                   gpointer        user_data)
{
    switch (load_event) {
    case WEBKIT_LOAD_STARTED:
        // New load, we have now a provisional URI
        provisional_uri = webkit_web_view_get_uri (web_view);
        // Here we could start a spinner or update the
        // location bar with the provisional URI
        break;
    case WEBKIT_LOAD_REDIRECTED:
        redirected_uri = webkit_web_view_get_uri (web_view);
        break;
    case WEBKIT_LOAD_COMMITTED:
        // The load is being performed. Current URI is
        // the final one and it won't change unless a new
        // load is requested or a navigation within the
        // same page is performed
        uri = webkit_web_view_get_uri (web_view);
        break;
    case WEBKIT_LOAD_FINISHED:
        // Load finished, we can now stop the spinner
        break;
    }
}
Default handler:

The default handler is called after the handlers added via g_signal_connect().

Parameters

load_event

Type: WebKitLoadEvent

The WebKitLoadEvent.

WebKit.WebView::mouse-target-changed

Signal

WebKitWebView::mouse-target-changed

Declaration 

void
mouse_target_changed (
  WebKitWebView* self,
  WebKitHitTestResult* hit_test_result,
  guint modifiers,
  gpointer user_data
)

Description [src]

This signal is emitted when the mouse cursor moves over an element such as a link, image or a media element. To determine what type of element the mouse cursor is over, a Hit Test is performed on the current mouse coordinates and the result is passed in the hit_test_result argument. The modifiers argument is a bitmask of GdkModifierType flags indicating the state of modifier keys. The signal is emitted again when the mouse is moved out of the current element with a new hit_test_result.

Default handler:

The default handler is called after the handlers added via g_signal_connect().

Parameters

hit_test_result

Type: WebKitHitTestResult

A WebKitHitTestResult.

The data is owned by the caller of the function.
modifiers

Type: guint

A bitmask of GdkModifierType.

WebKit.InputMethodContext.preedit_changed

Virtual Method

WebKitInputMethodContextpreedit_changed

Declaration [src] 

void
preedit_changed (
  WebKitInputMethodContext* context
)

Description

No description available.

WebKit.WebView.load_changed

Virtual Method

WebKitWebViewload_changed

Declaration [src] 

void
load_changed (
  WebKitWebView* web_view,
  WebKitLoadEvent load_event
)

Description

No description available.

Parameters

load_event

Type: WebKitLoadEvent

No description available.

WebKit.WebView.mouse_target_changed

Virtual Method

WebKitWebViewmouse_target_changed

Declaration [src] 

void
mouse_target_changed (
  WebKitWebView* web_view,
  WebKitHitTestResult* hit_test_result,
  guint modifiers
)

Description

No description available.

Parameters

hit_test_result

Type: WebKitHitTestResult

No description available.

The data is owned by the caller of the method.
modifiers

Type: guint

No description available.

WebKitWebProcessExtension.WebEditor::selection-changed

Signal

WebKitWebProcessExtensionWebEditor::selection-changed

since: 2.10

Declaration 

void
selection_changed (
  WebKitWebEditor* self,
  gpointer user_data
)

Description [src]

This signal is emitted for every selection change inside a WebKitWebPage as well as for every caret position change as the caret is a collapsed selection.

Default handler:

The default handler is called after the handlers added via g_signal_connect().

Available since: 2.10