WebContext
Superclasses: Object
Manages aspects common to all :obj:`~gi.repository.WebKit.WebView`<!– –>s
The WebContext
manages all aspects common to all
:obj:`~gi.repository.WebKit.WebView`<!– –>s.
You can define the CacheModel
with
set_cache_model()
, depending on the needs of
your application. You can access the SecurityManager
to specify
the behaviour of your application regarding security using
get_security_manager()
.
It is also possible to change your preferred language or enable
spell checking, using set_preferred_languages()
,
set_spell_checking_languages()
and
set_spell_checking_enabled()
.
You can use register_uri_scheme()
to register
custom URI schemes, and manage several other settings.
TLS certificate validation failure is now treated as a transport
error by default. To handle TLS failures differently, you can
connect to WebView
::load-failed-with-tls-errors.
Alternatively, you can use webkit_web_context_set_tls_errors_policy()
to set the policy IGNORE
; however, this is
not appropriate for Internet applications.
Constructors
- class WebContext
- classmethod new() WebContext
Create a new
WebContext
.Added in version 2.8.
Methods
- class WebContext
- add_path_to_sandbox(path: str, read_only: bool) None
Adds a path to be mounted in the sandbox.
path
must exist before any web process has been created; otherwise, it will be silently ignored. It is a fatal error to add paths after a web process has been spawned.Paths under
/sys
,/proc
, and/dev
are invalid. Attempting to add all of/
is not valid. Since 2.40, adding the user’s entire home directory or /home is also not valid.See also webkit_web_context_set_sandbox_enabled()
Added in version 2.26.
- Parameters:
path – an absolute path to mount in the sandbox
read_only – if
True
the path will be read-only
- get_cache_model() CacheModel
Returns the current cache model.
For more information about this value check the documentation of the function
set_cache_model()
.
- get_default() WebContext
Gets the default web context.
- get_geolocation_manager() GeolocationManager
Get the
GeolocationManager
ofcontext
.Added in version 2.26.
- get_network_session_for_automation() NetworkSession | None
Get the
NetworkSession
used for automation sessions started incontext
.Added in version 2.40.
- get_security_manager() SecurityManager
Get the
SecurityManager
ofcontext
.
- get_spell_checking_languages() list[str]
Get the the list of spell checking languages.
Get the the list of spell checking languages associated with
context
, orNone
if no languages have been previously set.See
set_spell_checking_languages()
for more details on the format of the languages in the list.
- get_time_zone_override() str
Get the
WebContext
:time-zone-override property.Added in version 2.38.
- initialize_notification_permissions(allowed_origins: list[SecurityOrigin], disallowed_origins: list[SecurityOrigin]) None
Sets initial desktop notification permissions for the
context
.allowed_origins
anddisallowed_origins
must each beList
ofSecurityOrigin
objects representing origins that will, respectively, either always or never have permission to show desktop notifications. NoWebKitNotificationPermissionRequest
will ever be generated for any of the security origins represented inallowed_origins
ordisallowed_origins
. This function is necessary because some webpages proactively check whether they have permission to display notifications without ever creating a permission request.This function only affects web processes that have not already been created. The best time to call it is when handling
WebContext
::initialize-notification-permissions so as to ensure that new web processes receive the most recent set of permissions.Added in version 2.16.
- is_automation_allowed() bool
Get whether automation is allowed in
context
.See also
set_automation_allowed()
.Added in version 2.18.
- register_uri_scheme(scheme: str, callback: Callable[[...], None], *user_data: Any) None
Register
scheme
incontext
.Register
scheme
incontext
, so that when an URI request withscheme
is made in theWebContext
, theURISchemeRequestCallback
registered will be called with aURISchemeRequest
. It is possible to handle URI scheme requests asynchronously, by callingref()
on theURISchemeRequest
and callingfinish()
later when the data of the request is available orfinish_error()
in case of error.static void about_uri_scheme_request_cb (WebKitURISchemeRequest *request, gpointer user_data) { GInputStream *stream; gsize stream_length; const gchar *path = webkit_uri_scheme_request_get_path (request); if (!g_strcmp0 (path, "memory")) { // Create a GInputStream with the contents of memory about page, and set its length to stream_length } else if (!g_strcmp0 (path, "applications")) { // Create a GInputStream with the contents of applications about page, and set its length to stream_length } else if (!g_strcmp0 (path, "example")) { gchar *contents = g_strdup_printf ("<html><body><p>Example about page</p></body></html>"); stream_length = strlen (contents); stream = g_memory_input_stream_new_from_data (contents, stream_length, g_free); } else { GError *error = g_error_new (ABOUT_HANDLER_ERROR, ABOUT_HANDLER_ERROR_INVALID, "Invalid about:``%s`` page.", path); webkit_uri_scheme_request_finish_error (request, error); g_error_free (error); return; } webkit_uri_scheme_request_finish (request, stream, stream_length, "text/html"); g_object_unref (stream); }
- Parameters:
scheme – the network scheme to register
callback – a
URISchemeRequestCallback
user_data – data to pass to callback function
- send_message_to_all_extensions(message: UserMessage) None
Send
message
to all web process extensions associated tocontext
.If
message
is floating, it’s consumed.Added in version 2.28.
- Parameters:
message – a
UserMessage
- set_automation_allowed(allowed: bool) None
Set whether automation is allowed in
context
.When automation is enabled the browser could be controlled by another process by requesting an automation session. When a new automation session is requested the signal
WebContext
::automation-started is emitted. Automation is disabled by default, so you need to explicitly call this method passingTrue
to enable it.Note that only one
WebContext
can have automation enabled, so this will do nothing if there’s anotherWebContext
with automation already enabled.Added in version 2.18.
- Parameters:
allowed – value to set
- set_cache_model(cache_model: CacheModel) None
Specifies a usage model for WebViews.
Specifies a usage model for WebViews, which WebKit will use to determine its caching behavior. All web views follow the cache model. This cache model determines the RAM and disk space to use for caching previously viewed content .
Research indicates that users tend to browse within clusters of documents that hold resources in common, and to revisit previously visited documents. WebKit and the frameworks below it include built-in caches that take advantage of these patterns, substantially improving document load speed in browsing situations. The WebKit cache model controls the behaviors of all of these caches, including various WebCore caches.
Browsers can improve document load speed substantially by specifying
WEB_BROWSER
. Applications without a browsing interface can reduce memory usage substantially by specifyingDOCUMENT_VIEWER
. The default value isWEB_BROWSER
.- Parameters:
cache_model – a
CacheModel
- set_preferred_languages(languages: Sequence[str] | None = None) None
Set the list of preferred languages.
Set the list of preferred languages, sorted from most desirable to least desirable. The list will be used in the following ways:
Determining how to build the
Accept-Language
HTTP header that will be included in the network requests started by theWebContext
.Setting the values of
navigator.language
andnavigator.languages
.The first item in the list sets the default locale for JavaScript
Intl
functions.
- Parameters:
languages – a
None
-terminated list of language identifiers
- set_spell_checking_enabled(enabled: bool) None
Enable or disable the spell checking feature.
- Parameters:
enabled – Value to be set
- set_spell_checking_languages(languages: Sequence[str]) None
Set the list of spell checking languages to be used for spell checking.
The locale string typically is in the form lang_COUNTRY, where lang is an ISO-639 language code, and COUNTRY is an ISO-3166 country code. For instance, sv_FI for Swedish as written in Finland or pt_BR for Portuguese as written in Brazil.
You need to call this function with a valid list of languages at least once in order to properly enable the spell checking feature in WebKit.
- Parameters:
languages – a
None
-terminated list of spell checking languages
- set_web_process_extensions_directory(directory: str) None
Set the directory where WebKit will look for web process extensions.
This method must be called before loading anything in this context, otherwise it will not have any effect. You can connect to
WebContext
::initialize-web-process-extensions to call this method before anything is loaded.- Parameters:
directory – the directory to add
- set_web_process_extensions_initialization_user_data(user_data: Variant) None
Set user data to be passed to Web Extensions on initialization.
The data will be passed to the
WebKitWebProcessExtensionInitializeWithUserDataFunction
. This method must be called before loading anything in this context, otherwise it will not have any effect. You can connect toWebContext
::initialize-web-process-extensions to call this method before anything is loaded.Added in version 2.4.
- Parameters:
user_data – a
Variant
Properties
- class WebContext
- props.memory_pressure_settings: MemoryPressureSettings
The
MemoryPressureSettings
applied to the web processes created by this context.Added in version 2.34.
- props.time_zone_override: str
The timezone override for this web context. Setting this property provides a better alternative to configure the timezone information for all webviews managed by the WebContext. The other, less optimal, approach is to globally set the TZ environment variable in the process before creating the context. However this approach might not be very convenient and can have side-effects in your application.
The expected values for this property are defined in the IANA timezone database. See this wikipedia page for instance, https://en.wikipedia.org/wiki/List_of_tz_database_time_zones.
Added in version 2.38.
Signals
- class WebContext.signals
- automation_started(session: AutomationSession) None
This signal is emitted when a new automation request is made. Note that it will never be emitted if automation is not enabled in
context
, seeset_automation_allowed()
for more details.Added in version 2.18.
- Parameters:
session – the
AutomationSession
associated with this event
- initialize_notification_permissions() None
This signal is emitted when a
WebContext
needs to set initial notification permissions for a web process. It is emitted when a new web process is about to be launched, and signals the most appropriate moment to useinitialize_notification_permissions()
. If no notification permissions have changed since the last time this signal was emitted, then there is no need to callinitialize_notification_permissions()
again.Added in version 2.16.
- initialize_web_process_extensions() None
This signal is emitted when a new web process is about to be launched. It signals the most appropriate moment to use
set_web_process_extensions_initialization_user_data()
andset_web_process_extensions_directory()
.Added in version 2.4.
- user_message_received(message: UserMessage) bool
This signal is emitted when a
UserMessage
is received from a web process extension. You can reply to the message usingsend_reply()
.You can handle the user message asynchronously by calling
ref()
onmessage
and returningTrue
.Added in version 2.28.
- Parameters:
message – the
UserMessage
received