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
JSObjectRef), which has been replaced by the GObject-style
available since 2.22. It also includes the entire GObject DOM API (e.g.
to interact with and manipulate the DOM instead, perhaps via
JSC.ValueObject.invoke_method in the web process.
Run your application with the environment variable
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:
WebKitWebViewhas been often subclassed to customize its behavior for an specific application. This possibility has been kept, as it has proved useful in the past.
WebKitInputMethodContextis 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
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.WebContext.add_path_to_sandbox to mount them in the sandbox.
Mandatory Process Swap on Cross-site Navigation
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
enabled. This property was previously disabled by default.
Event Parameter Removed from Context Menu and Option Menu Signals
WebKit.WebView::context-menu and WebKit.WebView::show-option-menu
no longer have a
GdkEvent parameter. Adjust your signal handlers accordingly.
Changes to WebKitWebView Construction
webkit_web_view_new_with_related_view() have all been removed. You
may directly use
g_object_new() instead. WebKit.WebView.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 WebKit.WebContext and WebKit.WebsiteDataManager to the new class WebKit.NetworkSession. There’s a default global persistent session that you can get with WebKit.NetworkSession.get_default. You can also create new sessions with WebKit.NetworkSession.new for persistent sessions and WebKit.NetworkSession.new_ephemeral for ephemeral sessions. It’s no longer possible to create a WebKit.WebsiteDataManager; it’s now created by the WebKit.NetworkSession automatically at construction time. The WebKit.NetworkSession to be used must be passed to the WebKit.WebView as a construct parameter. You can pass the same WebKit.NetworkSession 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 WebKit.WebContext or WebKit.WebsiteDataManager APIs that no longer exist, look for replacement APIs in WebKit.NetworkSession.
webkit_web_context_clear_cache() does not have a direct replacement, but you
can use WebKit.WebsiteDataManager.clear to achieve the same effect.
WebKitWebContext::download-started signal has been removed. Use
WebKit.FaviconDatabase is now owned by WebKit.WebsiteDataManager instead of WebKit.WebContext. Use WebKit.WebsiteDataManager.set_favicons_enabled to enable the favicon database.
There is no replacement for
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
WebKit.HardwareAccelerationPolicy. You may still use
WebKit.Settings.set_hardware_acceleration_policy to enable or disable
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_set_use_system_appearance_for_scrollbars APIs have been
removed. WebKit will draw scrollbars that match the Adwaita GTK theme.
User Script Message Handlers
been removed. Instead, WebKit.UserContentManager.register_script_message_handler
and WebKit.UserContentManager.unregister_script_message_handler have
gained parameters to specify the script world to use.
WebKit.Download.set_destination, WebKit.Download.get_destination, WebKit.Download:destination, and WebKit.Download::created-destination now all use a filesystem path rather than a URI. All uses must be updated accordingly.
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. WebKit.WebContext::initialize-web-process-extensions.
The name of your extension’s entry point must now be
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.