:right-sidebar: True WebContext =================================================================== .. currentmodule:: gi.repository.WebKit .. class:: WebContext(**properties: ~typing.Any) :no-contents-entry: Superclasses: :class:`~gi.repository.GObject.Object` :Constructors: :: WebContext(**properties) new() -> WebKit.WebContext 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`. .. method:: 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[[...], None], *user_data: ~typing.Any) -> 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: ~typing.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 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: ~typing.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. :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 :obj:`~gi.repository.WebKit.MemoryPressureSettings` applied to the web processes created by this context. .. versionadded:: 2.34 .. attribute:: props.time_zone_override :type: 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. .. versionadded:: 2.38 Signals ------- .. rst-class:: interim-class .. class:: WebContext.signals :no-index: .. method:: automation_started(session: ~gi.repository.WebKit.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``, see :func:`~gi.repository.WebKit.WebContext.set_automation_allowed` for more details. .. versionadded:: 2.18 :param session: the :obj:`~gi.repository.WebKit.AutomationSession` associated with this event .. method:: initialize_notification_permissions() -> None This signal is emitted when a :obj:`~gi.repository.WebKit.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 use :func:`~gi.repository.WebKit.WebContext.initialize_notification_permissions`. If no notification permissions have changed since the last time this signal was emitted, then there is no need to call :func:`~gi.repository.WebKit.WebContext.initialize_notification_permissions` again. .. versionadded:: 2.16 .. method:: 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 :func:`~gi.repository.WebKit.WebContext.set_web_process_extensions_initialization_user_data` and :func:`~gi.repository.WebKit.WebContext.set_web_process_extensions_directory`. .. versionadded:: 2.4 .. method:: user_message_received(message: ~gi.repository.WebKit.UserMessage) -> bool This signal is emitted when a :obj:`~gi.repository.WebKit.UserMessage` is received from a web process extension. You can reply to the message using :func:`~gi.repository.WebKit.UserMessage.send_reply`. You can handle the user message asynchronously by calling :func:`~gi.repository.GObject.GObject.Object.ref` on ``message`` and returning :const:`True`. .. versionadded:: 2.28 :param message: the :obj:`~gi.repository.WebKit.UserMessage` received