UserContentManager

Added in version 2.6.

class UserContentManager(**properties: Any)

Superclasses: Object

Manages user-defined content which affects web pages.

Using a UserContentManager user CSS style sheets can be set to be injected in the web pages loaded by a WebView, by add_style_sheet().

To use a UserContentManager, it must be created using new(), and then used to construct a WebView. User style sheets can be created with new().

User style sheets can be added and removed at any time, but they will affect the web pages loaded afterwards.

Constructors

class UserContentManager

classmethod new() → UserContentManager: Creates a new user content manager.

Added in version 2.6.

Methods

class UserContentManager

add_filter(filter: UserContentFilter) → None

Adds a UserContentFilter to the given UserContentManager.

The same UserContentFilter can be reused with multiple UserContentManager instances.

Filters need to be saved and loaded from UserContentFilterStore.

Added in version 2.24.

Parameters:: filter – A UserContentFilter

add_script(script: UserScript) → None

Adds a UserScript to the given UserContentManager.

The same UserScript can be reused with multiple UserContentManager instances.

Added in version 2.6.

Parameters:: script – A UserScript

add_style_sheet(stylesheet: UserStyleSheet) → None

Adds a UserStyleSheet to the given UserContentManager.

The same UserStyleSheet can be reused with multiple UserContentManager instances.

Added in version 2.6.

Parameters:: stylesheet – A UserStyleSheet

register_script_message_handler(name: str, world_name: str | None = None) → bool

Registers a new user script message handler in script world.

After it is registered, scripts can use window.webkit.messageHandlers.<name>.postMessage(value) to send messages. Those messages are received by connecting handlers to the UserContentManager::script-message-received signal. The handler name is used as the detail of the signal. To avoid race conditions between registering the handler name, and starting to receive the signals, it is recommended to connect to the signal before registering the handler name:

WebKitWebView *view = webkit_web_view_new ();
WebKitUserContentManager *manager = webkit_web_view_get_user_content_manager ();
g_signal_connect (manager, "script-message-received::foobar",
                  G_CALLBACK (handle_script_message), NULL);
webkit_user_content_manager_register_script_message_handler (manager, "foobar");

Registering a script message handler will fail if the requested name has been already registered before.

If None is passed as the world_name, the default world will be used.

The registered handler can be unregistered by using unregister_script_message_handler().

Added in version 2.40.

Parameters:

name – Name of the script message channel
world_name – the name of a WebKitScriptWorld

register_script_message_handler_with_reply(name: str, world_name: str) → bool

Registers a new user script message handler in script world with name world_name.

Different from register_script_message_handler(), when using this function to register the handler, the connected signal is script-message-with-reply-received, and a reply provided by the user is expected. Otherwise, the user will receive a default undefined value.

If None is passed as the world_name, the default world will be used. See register_script_message_handler() for full description.

Registering a script message handler will fail if the requested name has been already registered before.

The registered handler can be unregistered by using unregister_script_message_handler().

Added in version 2.40.

Parameters:

name – Name of the script message channel world_name (nullable): the name of a WebKitScriptWorld
world_name

remove_all_filters() → None: Removes all content filters from the given UserContentManager.

Added in version 2.24.

remove_all_scripts() → None

Removes all user scripts from the given UserContentManager

Signals

class UserContentManager.signals

script_message_received(value: Value) → None

This signal is emitted when JavaScript in a web view calls <code>window.webkit.messageHandlers.<name>.postMessage()</code>, after registering <code><name></code> using register_script_message_handler()

Added in version 2.8.

Parameters:: value – the value received from the JavaScript world.

script_message_with_reply_received(value: Value, reply: ScriptMessageReply) → bool

The given reply can be used to send a return value with return_value() or an error message with return_error_message(). If none of them are called, an automatic reply with an undefined value will be sent.

It is possible to handle the reply asynchronously, by simply calling ref() on the reply and returning True.

Added in version 2.40.

Parameters:

value – the value received from the JavaScript world.
reply – the ScriptMessageReply to send the reply to the script message.