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 | None = None) → 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 – the name of a WebKitScriptWorld

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

See also remove_script().

Added in version 2.6.

remove_all_style_sheets() → None#

Removes all user style sheets from the given UserContentManager.

Added in version 2.6.

remove_filter(filter: UserContentFilter) → None#

Removes a filter from the given UserContentManager.

Since 2.24

Parameters:

filter – A UserContentFilter

remove_filter_by_id(filter_id: str) → None#

Removes a filter by the given identifier.

Removes a filter from the given UserContentManager given the identifier of a UserContentFilter as returned by get_identifier().

Added in version 2.26.

Parameters:

filter_id – Filter identifier

remove_script(script: UserScript) → None#

Removes a UserScript from the given UserContentManager.

See also remove_all_scripts().

Added in version 2.32.

Parameters:

script – A UserScript

remove_style_sheet(stylesheet: UserStyleSheet) → None#

Removes a UserStyleSheet from the given UserContentManager.

See also remove_all_style_sheets().

Added in version 2.32.

Parameters:

stylesheet – A UserStyleSheet

unregister_script_message_handler(name: str, world_name: str | None = None) → None#

Unregisters a previously registered message handler in script world with name world_name. If None is passed as the world_name, the default world will be used.

Note that this does not disconnect handlers for the UserContentManager::script-message-received signal; they will be kept connected, but the signal will not be emitted unless the handler name is registered again.

See also register_script_message_handler().

Added in version 2.40.

Parameters:

  • name – Name of the script message channel

  • world_name – the name of a WebKitScriptWorld

Signals#

class UserContentManager.signals
script_message_received(value: Value) → None#

The type of the None singleton.

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 type of the None singleton.

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.