WebKit.UserContentManager

Subclasses:

None

Methods

Inherited:

GObject.Object (37)

Structs:

GObject.ObjectClass (5)

class	new ()
	add_filter (filter)
	add_script (script)
	add_style_sheet (stylesheet)
	register_script_message_handler (name, world_name)
	register_script_message_handler_with_reply (name, world_name)
	remove_all_filters ()
	remove_all_scripts ()
	remove_all_style_sheets ()
	remove_filter (filter)
	remove_filter_by_id (filter_id)
	remove_script (script)
	remove_style_sheet (stylesheet)
	unregister_script_message_handler (name, world_name)

Virtual Methods

Inherited:

GObject.Object (7)

Properties

None

Signals

Inherited:

GObject.Object (1)

Name	Short Description
script-message-received	This signal is emitted when JavaScript in a web view calls <code>window.webkit.messageHandlers.<name>.postMessage()</code>, after registering <code><name></code> using WebKit.UserContentManager.register_script_message_handler()
script-message-with-reply-received	This signal is emitted when JavaScript in a web view calls <code>window.webkit.messageHandlers.<name>.postMessage()</code>, after registering <code><name></code> using WebKit.UserContentManager.register_script_message_handler_with_reply() The given reply can be used to send a return value with WebKit.ScriptMessageReply.return_value() or an error message with WebKit.ScriptMessageReply.return_error_message().

Fields

Inherited:

GObject.Object (1)

Class Details

class WebKit.UserContentManager(**kwargs)

Bases:

GObject.Object

Abstract:

No

Structure:

WebKit.UserContentManagerClass

Manages user-defined content which affects web pages.

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

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

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

New in version 2.6.

classmethod new()

Returns:

A WebKit.UserContentManager

Return type:

WebKit.UserContentManager

Creates a new user content manager.

New in version 2.6.

add_filter(filter)

Parameters:

filter (WebKit.UserContentFilter) – A WebKit.UserContentFilter

Adds a WebKit.UserContentFilter to the given WebKit.UserContentManager.

The same WebKit.UserContentFilter can be reused with multiple WebKit.UserContentManager instances.

Filters need to be saved and loaded from WebKit.UserContentFilterStore.

New in version 2.24.

add_script(script)

Parameters:

script (WebKit.UserScript) – A WebKit.UserScript

Adds a WebKit.UserScript to the given WebKit.UserContentManager.

The same WebKit.UserScript can be reused with multiple WebKit.UserContentManager instances.

New in version 2.6.

add_style_sheet(stylesheet)

Parameters:

stylesheet (WebKit.UserStyleSheet) – A WebKit.UserStyleSheet

Adds a WebKit.UserStyleSheet to the given WebKit.UserContentManager.

The same WebKit.UserStyleSheet can be reused with multiple WebKit.UserContentManager instances.

New in version 2.6.

register_script_message_handler(name, world_name)

Parameters:

• name (str) – Name of the script message channel

• world_name (str or None) – the name of a #WebKitScriptWorld

Returns:

True if message handler was registered successfully, or False otherwise.

Return type:

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 WebKit.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:

``c 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 WebKit.UserContentManager.unregister_script_message_handler().

New in version 2.40.

register_script_message_handler_with_reply(name, world_name)

Parameters:

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

• world_name (str) –

Returns:

True if message handler was registered successfully, or False otherwise.

Return type:

bool

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

Different from WebKit.UserContentManager.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 WebKit.UserContentManager.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 WebKit.UserContentManager.unregister_script_message_handler().

New in version 2.40.

remove_all_filters()

Removes all content filters from the given WebKit.UserContentManager.

New in version 2.24.

remove_all_scripts()

Removes all user scripts from the given WebKit.UserContentManager

See also WebKit.UserContentManager.remove_script().

New in version 2.6.

remove_all_style_sheets()

Removes all user style sheets from the given WebKit.UserContentManager.

New in version 2.6.

remove_filter(filter)

Parameters:

filter (WebKit.UserContentFilter) – A WebKit.UserContentFilter

Removes a filter from the given WebKit.UserContentManager.

New in version 2.24.

remove_filter_by_id(filter_id)

Parameters:

filter_id (str) – Filter identifier

Removes a filter by the given identifier.

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

New in version 2.26.

remove_script(script)

Parameters:

script (WebKit.UserScript) – A WebKit.UserScript

Removes a WebKit.UserScript from the given WebKit.UserContentManager.

See also WebKit.UserContentManager.remove_all_scripts().

New in version 2.32.

remove_style_sheet(stylesheet)

Parameters:

stylesheet (WebKit.UserStyleSheet) – A WebKit.UserStyleSheet

Removes a WebKit.UserStyleSheet from the given WebKit.UserContentManager.

See also WebKit.UserContentManager.remove_all_style_sheets().

New in version 2.32.

unregister_script_message_handler(name, world_name)

Parameters:

• name (str) – Name of the script message channel

• world_name (str or None) – the name of a #WebKitScriptWorld

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 WebKit.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 WebKit.UserContentManager.register_script_message_handler().

New in version 2.40.

Signal Details

WebKit.UserContentManager.signals.script_message_received(user_content_manager, value)

Signal Name:

script-message-received

Flags:

RUN_LAST, DETAILED

Parameters:

• user_content_manager (WebKit.UserContentManager) – The object which received the signal

• value (JavaScriptCore.Value) – the value received from the JavaScript world.

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

New in version 2.8.

WebKit.UserContentManager.signals.script_message_with_reply_received(user_content_manager, value, reply)

Signal Name:

script-message-with-reply-received

Flags:

RUN_LAST, DETAILED

Parameters:

• user_content_manager (WebKit.UserContentManager) – The object which received the signal

• value (JavaScriptCore.Value) – the value received from the JavaScript world.

• reply (WebKit.ScriptMessageReply) – the WebKit.ScriptMessageReply to send the reply to the script message.

Returns:

True to stop other handlers from being invoked for the event. False to propagate the event further.

Return type:

bool

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

The given reply can be used to send a return value with WebKit.ScriptMessageReply.return_value() or an error message with WebKit.ScriptMessageReply.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 GObject.Object.ref() on the reply and returning True.

New in version 2.40.