UserContentManager
Added in version 2.6.
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 givenUserContentManager
.The same
UserContentFilter
can be reused with multipleUserContentManager
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 givenUserContentManager
.The same
UserScript
can be reused with multipleUserContentManager
instances.Added in version 2.6.
- Parameters:
script – A
UserScript
- add_style_sheet(stylesheet: UserStyleSheet) None
Adds a
UserStyleSheet
to the givenUserContentManager
.The same
UserStyleSheet
can be reused with multipleUserContentManager
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 theUserContentManager
::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 theworld_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 theworld_name
, the default world will be used. Seeregister_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 aWebKitScriptWorld
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
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 aUserContentFilter
as returned byget_identifier()
.Added in version 2.26.
- Parameters:
filter_id – Filter identifier
- remove_script(script: UserScript) None
Removes a
UserScript
from the givenUserContentManager
.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 givenUserContentManager
.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
. IfNone
is passed as theworld_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
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
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_with_reply()
The given
reply
can be used to send a return value withreturn_value()
or an error message withreturn_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 thereply
and returningTrue
.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.