:right-sidebar: True WebContext =================================================================== .. currentmodule:: gi.repository.WebKit .. class:: WebContext(**properties: ~typing.Any) :no-contents-entry: Superclasses: :class:`~gi.repository.GObject.Object` Manages aspects common to all :obj:`~gi.repository.WebKit.WebView`\s The :obj:`~gi.repository.WebKit.WebContext` manages all aspects common to all :obj:`~gi.repository.WebKit.WebView`\s. You can define the :obj:`~gi.repository.WebKit.CacheModel` with :func:`~gi.repository.WebKit.WebContext.set_cache_model`, depending on the needs of your application. You can access the :obj:`~gi.repository.WebKit.SecurityManager` to specify the behaviour of your application regarding security using :func:`~gi.repository.WebKit.WebContext.get_security_manager`. It is also possible to change your preferred language or enable spell checking, using :func:`~gi.repository.WebKit.WebContext.set_preferred_languages`, :func:`~gi.repository.WebKit.WebContext.set_spell_checking_languages` and :func:`~gi.repository.WebKit.WebContext.set_spell_checking_enabled`. You can use :func:`~gi.repository.WebKit.WebContext.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 :obj:`~gi.repository.WebKit.WebView`\::load-failed-with-tls-errors. Alternatively, you can use webkit_web_context_set_tls_errors_policy() to set the policy :const:`~gi.repository.WebKit.TLSErrorsPolicy.IGNORE`; however, this is not appropriate for Internet applications. Constructors ------------ .. rst-class:: interim-class .. class:: WebContext :no-index: .. classmethod:: new() -> ~gi.repository.WebKit.WebContext Create a new :obj:`~gi.repository.WebKit.WebContext`\. .. versionadded:: 2.8 Methods ------- .. rst-class:: interim-class .. class:: WebContext :no-index: .. method:: 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() .. versionadded:: 2.26 :param path: an absolute path to mount in the sandbox :param read_only: if :const:`True` the path will be read-only .. method:: get_cache_model() -> ~gi.repository.WebKit.CacheModel Returns the current cache model. For more information about this value check the documentation of the function :func:`~gi.repository.WebKit.WebContext.set_cache_model`. .. classmethod:: get_default() -> ~gi.repository.WebKit.WebContext Gets the default web context. .. method:: get_geolocation_manager() -> ~gi.repository.WebKit.GeolocationManager Get the :obj:`~gi.repository.WebKit.GeolocationManager` of ``context``\. .. versionadded:: 2.26 .. method:: get_network_session_for_automation() -> ~gi.repository.WebKit.NetworkSession | None Get the :obj:`~gi.repository.WebKit.NetworkSession` used for automation sessions started in ``context``\. .. versionadded:: 2.40 .. method:: get_security_manager() -> ~gi.repository.WebKit.SecurityManager Get the :obj:`~gi.repository.WebKit.SecurityManager` of ``context``\. .. method:: get_spell_checking_enabled() -> bool Get whether spell checking feature is currently enabled. .. method:: 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``\, or :const:`None` if no languages have been previously set. See :func:`~gi.repository.WebKit.WebContext.set_spell_checking_languages` for more details on the format of the languages in the list. .. method:: get_time_zone_override() -> str Get the :obj:`~gi.repository.WebKit.WebContext`\:time-zone-override property. .. versionadded:: 2.38 .. method:: initialize_notification_permissions(allowed_origins: list[~gi.repository.WebKit.SecurityOrigin], disallowed_origins: list[~gi.repository.WebKit.SecurityOrigin]) -> None Sets initial desktop notification permissions for the ``context``\. ``allowed_origins`` and ``disallowed_origins`` must each be :obj:`~gi.repository.GLib.List` of :obj:`~gi.repository.WebKit.SecurityOrigin` objects representing origins that will, respectively, either always or never have permission to show desktop notifications. No ``WebKitNotificationPermissionRequest`` will ever be generated for any of the security origins represented in ``allowed_origins`` or ``disallowed_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 :obj:`~gi.repository.WebKit.WebContext`\::initialize-notification-permissions so as to ensure that new web processes receive the most recent set of permissions. .. versionadded:: 2.16 :param allowed_origins: a :obj:`~gi.repository.GLib.List` of security origins :param disallowed_origins: a :obj:`~gi.repository.GLib.List` of security origins .. method:: is_automation_allowed() -> bool Get whether automation is allowed in ``context``\. See also :func:`~gi.repository.WebKit.WebContext.set_automation_allowed`. .. versionadded:: 2.18 .. method:: register_uri_scheme(scheme: str, callback: ~typing.Callable[[~gi.repository.WebKit.URISchemeRequest, ~typing.Any], None], user_data: ~typing.Any = None) -> None Register ``scheme`` in ``context``\. Register ``scheme`` in ``context``\, so that when an URI request with ``scheme`` is made in the :obj:`~gi.repository.WebKit.WebContext`\, the :obj:`~gi.repository.WebKit.URISchemeRequestCallback` registered will be called with a :obj:`~gi.repository.WebKit.URISchemeRequest`\. It is possible to handle URI scheme requests asynchronously, by calling :func:`~gi.repository.GObject.GObject.Object.ref` on the :obj:`~gi.repository.WebKit.URISchemeRequest` and calling :func:`~gi.repository.WebKit.URISchemeRequest.finish` later when the data of the request is available or :func:`~gi.repository.WebKit.URISchemeRequest.finish_error` in case of error. .. code-block:: c :dedent: 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 ("

Example about page

"); 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); } :param scheme: the network scheme to register :param callback: a :obj:`~gi.repository.WebKit.URISchemeRequestCallback` :param user_data: data to pass to callback function .. method:: send_message_to_all_extensions(message: ~gi.repository.WebKit.UserMessage) -> None Send ``message`` to all web process extensions associated to ``context``\. If ``message`` is floating, it's consumed. .. versionadded:: 2.28 :param message: a :obj:`~gi.repository.WebKit.UserMessage` .. method:: 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 :obj:`~gi.repository.WebKit.WebContext`\::automation-started is emitted. Automation is disabled by default, so you need to explicitly call this method passing :const:`True` to enable it. Note that only one :obj:`~gi.repository.WebKit.WebContext` can have automation enabled, so this will do nothing if there's another :obj:`~gi.repository.WebKit.WebContext` with automation already enabled. .. versionadded:: 2.18 :param allowed: value to set .. method:: set_cache_model(cache_model: ~gi.repository.WebKit.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 :const:`~gi.repository.WebKit.CacheModel.WEB_BROWSER`. Applications without a browsing interface can reduce memory usage substantially by specifying :const:`~gi.repository.WebKit.CacheModel.DOCUMENT_VIEWER`. The default value is :const:`~gi.repository.WebKit.CacheModel.WEB_BROWSER`. :param cache_model: a :obj:`~gi.repository.WebKit.CacheModel` .. method:: set_preferred_languages(languages: list[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 the :obj:`~gi.repository.WebKit.WebContext`\. - Setting the values of ``navigator.language`` and ``navigator.languages``\. - The first item in the list sets the default locale for JavaScript ``Intl`` functions. :param languages: a :const:`None`-terminated list of language identifiers .. method:: set_spell_checking_enabled(enabled: bool) -> None Enable or disable the spell checking feature. :param enabled: Value to be set .. method:: set_spell_checking_languages(languages: list[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. :param languages: a :const:`None`-terminated list of spell checking languages .. method:: 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 :obj:`~gi.repository.WebKit.WebContext`\::initialize-web-process-extensions to call this method before anything is loaded. :param directory: the directory to add .. method:: set_web_process_extensions_initialization_user_data(user_data: ~gi.repository.GLib.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 to :obj:`~gi.repository.WebKit.WebContext`\::initialize-web-process-extensions to call this method before anything is loaded. .. versionadded:: 2.4 :param user_data: a :obj:`~gi.repository.GLib.Variant` Properties ---------- .. rst-class:: interim-class .. class:: WebContext :no-index: .. attribute:: props.memory_pressure_settings :type: ~gi.repository.WebKit.MemoryPressureSettings The type of the None singleton. .. versionadded:: 2.34 .. attribute:: props.time_zone_override :type: str The type of the None singleton. .. versionadded:: 2.38 Signals ------- .. rst-class:: interim-class .. class:: WebContext.signals :no-index: .. method:: automation_started(session: ~gi.repository.WebKit.AutomationSession) -> None The type of the None singleton. .. versionadded:: 2.18 :param session: the :obj:`~gi.repository.WebKit.AutomationSession` associated with this event .. method:: initialize_notification_permissions() -> None The type of the None singleton. .. versionadded:: 2.16 .. method:: initialize_web_process_extensions() -> None The type of the None singleton. .. versionadded:: 2.4 .. method:: user_message_received(message: ~gi.repository.WebKit.UserMessage) -> bool The type of the None singleton. .. versionadded:: 2.28 :param message: the :obj:`~gi.repository.WebKit.UserMessage` received