:right-sidebar: True WebView =================================================================== .. currentmodule:: gi.repository.WebKit .. class:: WebView(**properties: ~typing.Any) :no-contents-entry: Superclasses: :class:`~gi.repository.WebKit.WebViewBase`, :class:`~gi.repository.Gtk.Widget`, :class:`~gi.repository.GObject.InitiallyUnowned`, :class:`~gi.repository.GObject.Object` Implemented Interfaces: :class:`~gi.repository.Gtk.Accessible`, :class:`~gi.repository.Gtk.Buildable`, :class:`~gi.repository.Gtk.ConstraintTarget` :Constructors: :: WebView(**properties) new() -> Gtk.Widget Constructors ------------ .. rst-class:: interim-class .. class:: WebView :no-index: .. classmethod:: new() -> ~gi.repository.Gtk.Widget Creates a new :obj:`~gi.repository.WebKit.WebView` with the default :obj:`~gi.repository.WebKit.WebContext`. Creates a new :obj:`~gi.repository.WebKit.WebView` with the default :obj:`~gi.repository.WebKit.WebContext` and no :obj:`~gi.repository.WebKit.UserContentManager` associated with it. See also webkit_web_view_new_with_context(), webkit_web_view_new_with_user_content_manager(), and webkit_web_view_new_with_settings(). Methods ------- .. rst-class:: interim-class .. class:: WebView :no-index: .. method:: call_async_javascript_function(body: str, length: int, arguments: ~gi.repository.GLib.Variant | None = None, world_name: str | None = None, source_uri: str | None = None, cancellable: ~gi.repository.Gio.Cancellable | None = None, callback: ~typing.Callable[[...], None] | None = None, *user_data: ~typing.Any) -> None Asynchronously call ``body`` with ``arguments`` in the script world with name ``world_name`` of the main frame current context in ``web_view``. The ``arguments`` values must be one of the following types, or contain only the following GVariant types: number, string and dictionary. The result of the operation can be a Promise that will be properly passed to the callback. If ``world_name`` is :const:`None`, the default world is used. Any value that is not :const:`None` is a distin ct world. The ``source_uri`` will be shown in exceptions and doesn't affect the behavior of the script. When not provided, the document URL is used. Note that if :obj:`~gi.repository.WebKit.Settings`:enable-javascript is :const:`False`, this method will do nothing. If you want to use this method but still prevent web content from executing its own JavaScript, then use :obj:`~gi.repository.WebKit.Settings`:enable-javascript-markup. When the operation is finished, ``callback`` will be called. You can then call :func:`~gi.repository.WebKit.WebView.call_async_javascript_function_finish` to get the result of the operation. This is an example that shows how to pass arguments to a JS function that returns a Promise that resolves with the passed argument: .. code-block:: c :dedent: static void web_view_javascript_finished (GObject *object, GAsyncResult *result, gpointer user_data) { JSCValue *value; GError *error = NULL; value = webkit_web_view_call_async_javascript_function_finish (WEBKIT_WEB_VIEW (object), result, &error); if (!value) { g_warning ("Error running javascript: ``%s``", error->message); g_error_free (error); return; } if (jsc_value_is_number (value)) { gint32 int_value = jsc_value_to_string (value); JSCException *exception = jsc_context_get_exception (jsc_value_get_context (value)); if (exception) g_warning ("Error running javascript: ``%s``", jsc_exception_get_message (exception)); else g_print ("Script result: ``%d``\n", int_value); g_free (str_value); } else { g_warning ("Error running javascript: unexpected return value"); } g_object_unref (value); } static void web_view_evaluate_promise (WebKitWebView *web_view) { GVariantDict dict; g_variant_dict_init (&dict, NULL); g_variant_dict_insert (&dict, "count", "u", 42); GVariant *args = g_variant_dict_end (&dict); const gchar *body = "return new Promise((resolve) => { resolve(count); });"; webkit_web_view_call_async_javascript_function (web_view, body, -1, arguments, NULL, NULL, NULL, web_view_javascript_finished, NULL); } .. versionadded:: 2.40 :param body: the function body :param length: length of ``body``, or -1 if ``body`` is a nul-terminated string :param arguments: a :obj:`~gi.repository.GLib.Variant` with format ``a{sv}`` storing the function arguments, or :const:`None` :param world_name: the name of a ``WebKitScriptWorld`` or :const:`None` to use the default :param source_uri: the source URI :param cancellable: a :obj:`~gi.repository.Gio.Cancellable` or :const:`None` to ignore :param callback: a :obj:`~gi.repository.Gio.AsyncReadyCallback` to call when the script finished :param user_data: the data to pass to callback function .. method:: call_async_javascript_function_finish(result: ~gi.repository.Gio.AsyncResult) -> ~gi.repository.JavaScriptCore.Value Finish an asynchronous operation started with :func:`~gi.repository.WebKit.WebView.call_async_javascript_function`. .. versionadded:: 2.40 :param result: a :obj:`~gi.repository.Gio.AsyncResult` .. method:: can_execute_editing_command(command: str, cancellable: ~gi.repository.Gio.Cancellable | None = None, callback: ~typing.Callable[[...], None] | None = None, *user_data: ~typing.Any) -> None Asynchronously check if it is possible to execute the given editing command. When the operation is finished, ``callback`` will be called. You can then call :func:`~gi.repository.WebKit.WebView.can_execute_editing_command_finish` to get the result of the operation. :param command: the command to check :param cancellable: a :obj:`~gi.repository.Gio.Cancellable` or :const:`None` to ignore :param callback: a :obj:`~gi.repository.Gio.AsyncReadyCallback` to call when the request is satisfied :param user_data: the data to pass to callback function .. method:: can_execute_editing_command_finish(result: ~gi.repository.Gio.AsyncResult) -> bool Finish an asynchronous operation started with :func:`~gi.repository.WebKit.WebView.can_execute_editing_command`. :param result: a :obj:`~gi.repository.Gio.AsyncResult` .. method:: can_go_back() -> bool Determines whether ``web_view`` has a previous history item. .. method:: can_go_forward() -> bool Determines whether ``web_view`` has a next history item. .. method:: can_show_mime_type(mime_type: str) -> bool Whether or not a MIME type can be displayed in ``web_view``. :param mime_type: a MIME type .. method:: download_uri(uri: str) -> ~gi.repository.WebKit.Download Requests downloading of the specified URI string for ``web_view``. :param uri: the URI to download .. method:: evaluate_javascript(script: str, length: int, world_name: str | None = None, source_uri: str | None = None, cancellable: ~gi.repository.Gio.Cancellable | None = None, callback: ~typing.Callable[[...], None] | None = None, *user_data: ~typing.Any) -> None Asynchronously evaluate ``script`` in the script world with name ``world_name`` of the main frame current context in ``web_view``. If ``world_name`` is :const:`None`, the default world is used. Any value that is not :const:`None` is a distinct world. The ``source_uri`` will be shown in exceptions and doesn't affect the behavior of the script. When not provided, the document URL is used. Note that if :obj:`~gi.repository.WebKit.Settings`:enable-javascript is :const:`False`, this method will do nothing. If you want to use this method but still prevent web content from executing its own JavaScript, then use :obj:`~gi.repository.WebKit.Settings`:enable-javascript-markup. When the operation is finished, ``callback`` will be called. You can then call :func:`~gi.repository.WebKit.WebView.evaluate_javascript_finish` to get the result of the operation. This is an example of using :func:`~gi.repository.WebKit.WebView.evaluate_javascript` with a script returning a string: .. code-block:: c :dedent: static void web_view_javascript_finished (GObject *object, GAsyncResult *result, gpointer user_data) { JSCValue *value; GError *error = NULL; value = webkit_web_view_evaluate_javascript_finish (WEBKIT_WEB_VIEW (object), result, &error); if (!value) { g_warning ("Error running javascript: ``%s``", error->message); g_error_free (error); return; } if (jsc_value_is_string (value)) { gchar *str_value = jsc_value_to_string (value); JSCException *exception = jsc_context_get_exception (jsc_value_get_context (value)); if (exception) g_warning ("Error running javascript: ``%s``", jsc_exception_get_message (exception)); else g_print ("Script result: ``%s``\n", str_value); g_free (str_value); } else { g_warning ("Error running javascript: unexpected return value"); } g_object_unref (value); } static void web_view_get_link_url (WebKitWebView *web_view, const gchar *link_id) { gchar *script = g_strdup_printf ("window.document.getElementById('``%s``').href;", link_id); webkit_web_view_evaluate_javascript (web_view, script, -1, NULL, NULL, NULL, web_view_javascript_finished, NULL); g_free (script); } .. versionadded:: 2.40 :param script: the script to evaluate :param length: length of ``script``, or -1 if ``script`` is a nul-terminated string :param world_name: the name of a ``WebKitScriptWorld`` or :const:`None` to use the default :param source_uri: the source URI :param cancellable: a :obj:`~gi.repository.Gio.Cancellable` or :const:`None` to ignore :param callback: a :obj:`~gi.repository.Gio.AsyncReadyCallback` to call when the script finished :param user_data: the data to pass to callback function .. method:: evaluate_javascript_finish(result: ~gi.repository.Gio.AsyncResult) -> ~gi.repository.JavaScriptCore.Value Finish an asynchronous operation started with :func:`~gi.repository.WebKit.WebView.evaluate_javascript`. .. versionadded:: 2.40 :param result: a :obj:`~gi.repository.Gio.AsyncResult` .. method:: execute_editing_command(command: str) -> None Request to execute the given ``command`` for ``web_view``. You can use :func:`~gi.repository.WebKit.WebView.can_execute_editing_command` to check whether it's possible to execute the command. :param command: the command to execute .. method:: execute_editing_command_with_argument(command: str, argument: str) -> None Request to execute the given ``command`` with ``argument`` for ``web_view``. You can use :func:`~gi.repository.WebKit.WebView.can_execute_editing_command` to check whether it's possible to execute the command. .. versionadded:: 2.10 :param command: the command to execute :param argument: the command argument .. method:: get_automation_presentation_type() -> ~gi.repository.WebKit.AutomationBrowsingContextPresentation Get the presentation type of :obj:`~gi.repository.WebKit.WebView` when created for automation. .. versionadded:: 2.28 .. method:: get_back_forward_list() -> ~gi.repository.WebKit.BackForwardList Obtains the :obj:`~gi.repository.WebKit.BackForwardList` associated with the given :obj:`~gi.repository.WebKit.WebView`. The :obj:`~gi.repository.WebKit.BackForwardList` is owned by the :obj:`~gi.repository.WebKit.WebView`. .. method:: get_background_color() -> ~gi.repository.Gdk.RGBA Gets the color that is used to draw the ``web_view`` background. Gets the color that is used to draw the ``web_view`` background before the actual contents are rendered. For more information see also :func:`~gi.repository.WebKit.WebView.set_background_color` .. versionadded:: 2.8 .. method:: get_camera_capture_state() -> ~gi.repository.WebKit.MediaCaptureState Get the camera capture state of a :obj:`~gi.repository.WebKit.WebView`. .. versionadded:: 2.34 .. method:: get_context() -> ~gi.repository.WebKit.WebContext Gets the web context of ``web_view``. .. method:: get_custom_charset() -> str Returns the current custom character encoding name of ``web_view``. .. method:: get_default_content_security_policy() -> str | None Gets the configured default Content-Security-Policy. .. versionadded:: 2.38 .. method:: get_display_capture_state() -> ~gi.repository.WebKit.MediaCaptureState Get the display capture state of a :obj:`~gi.repository.WebKit.WebView`. .. versionadded:: 2.34 .. method:: get_editor_state() -> ~gi.repository.WebKit.EditorState Gets the web editor state of ``web_view``. .. versionadded:: 2.10 .. method:: get_estimated_load_progress() -> float Gets the value of the :obj:`~gi.repository.WebKit.WebView`:estimated-load-progress property. You can monitor the estimated progress of a load operation by connecting to the notify::estimated-load-progress signal of ``web_view``. .. method:: get_favicon() -> ~gi.repository.Gdk.Texture Returns favicon currently associated to ``web_view``. Returns favicon currently associated to ``web_view``, if any. You can connect to notify::favicon signal of ``web_view`` to be notified when the favicon is available. .. method:: get_find_controller() -> ~gi.repository.WebKit.FindController Gets the :obj:`~gi.repository.WebKit.FindController`. Gets the :obj:`~gi.repository.WebKit.FindController` that will allow the caller to query the :obj:`~gi.repository.WebKit.WebView` for the text to look for. .. method:: get_input_method_context() -> ~gi.repository.WebKit.InputMethodContext | None Get the :obj:`~gi.repository.WebKit.InputMethodContext` currently in use by ``web_view``. Get the :obj:`~gi.repository.WebKit.InputMethodContext` currently in use by ``web_view``, or :const:`None` if no input method is being used. .. versionadded:: 2.28 .. method:: get_inspector() -> ~gi.repository.WebKit.WebInspector Get the :obj:`~gi.repository.WebKit.WebInspector` associated to ``web_view`` .. method:: get_is_muted() -> bool Gets the mute state of ``web_view``. .. versionadded:: 2.30 .. method:: get_is_web_process_responsive() -> bool Get whether the current web process of a :obj:`~gi.repository.WebKit.WebView` is responsive. .. versionadded:: 2.34 .. method:: get_main_resource() -> ~gi.repository.WebKit.WebResource Return the main resource of ``web_view``. .. method:: get_microphone_capture_state() -> ~gi.repository.WebKit.MediaCaptureState Get the microphone capture state of a :obj:`~gi.repository.WebKit.WebView`. .. versionadded:: 2.34 .. method:: get_network_session() -> ~gi.repository.WebKit.NetworkSession Get the :obj:`~gi.repository.WebKit.NetworkSession` associated to ``web_view``. .. versionadded:: 2.40 .. method:: get_page_id() -> int Get the identifier of the ``WebKitWebPage`` corresponding to the :obj:`~gi.repository.WebKit.WebView` .. method:: get_session_state() -> ~gi.repository.WebKit.WebViewSessionState Gets the current session state of ``web_view`` .. versionadded:: 2.12 .. method:: get_settings() -> ~gi.repository.WebKit.Settings Gets the :obj:`~gi.repository.WebKit.Settings` currently applied to ``web_view``. If no other :obj:`~gi.repository.WebKit.Settings` have been explicitly applied to ``web_view`` with :func:`~gi.repository.WebKit.WebView.set_settings`, the default :obj:`~gi.repository.WebKit.Settings` will be returned. This method always returns a valid :obj:`~gi.repository.WebKit.Settings` object. To modify any of the ``web_view`` settings, you can either create a new :obj:`~gi.repository.WebKit.Settings` object with :func:`~gi.repository.WebKit.Settings.new`, setting the desired preferences, and then replace the existing ``web_view`` settings with :func:`~gi.repository.WebKit.WebView.set_settings` or get the existing ``web_view`` settings and update it directly. :obj:`~gi.repository.WebKit.Settings` objects can be shared by multiple :obj:`~gi.repository.WebKit.WebView`s, so modifying the settings of a :obj:`~gi.repository.WebKit.WebView` would affect other :obj:`~gi.repository.WebKit.WebView`s using the same :obj:`~gi.repository.WebKit.Settings`. .. method:: get_snapshot(region: ~gi.repository.WebKit.SnapshotRegion, options: ~gi.repository.WebKit.SnapshotOptions, cancellable: ~gi.repository.Gio.Cancellable | None = None, callback: ~typing.Callable[[...], None] | None = None, *user_data: ~typing.Any) -> None Asynchronously retrieves a snapshot of ``web_view`` for ``region``. ``options`` specifies how the snapshot should be rendered. When the operation is finished, ``callback`` will be called. You must call :func:`~gi.repository.WebKit.WebView.get_snapshot_finish` to get the result of the operation. :param region: the :obj:`~gi.repository.WebKit.SnapshotRegion` for this snapshot :param options: :obj:`~gi.repository.WebKit.SnapshotOptions` for the snapshot :param cancellable: a :obj:`~gi.repository.Gio.Cancellable` :param callback: a :obj:`~gi.repository.Gio.AsyncReadyCallback` :param user_data: user data .. method:: get_snapshot_finish(result: ~gi.repository.Gio.AsyncResult) -> ~gi.repository.Gdk.Texture Finishes an asynchronous operation started with :func:`~gi.repository.WebKit.WebView.get_snapshot`. :param result: a :obj:`~gi.repository.Gio.AsyncResult` .. method:: get_title() -> str Gets the value of the :obj:`~gi.repository.WebKit.WebView`:title property. You can connect to notify::title signal of ``web_view`` to be notified when the title has been received. .. method:: get_tls_info() -> tuple[bool, ~gi.repository.Gio.TlsCertificate, ~gi.repository.Gio.TlsCertificateFlags] Retrieves the :obj:`~gi.repository.Gio.TlsCertificate` associated with the main resource of ``web_view``. Retrieves the :obj:`~gi.repository.Gio.TlsCertificate` associated with the main resource of ``web_view``, and the :obj:`~gi.repository.Gio.TlsCertificateFlags` showing what problems, if any, have been found with that certificate. If the connection is not HTTPS, this function returns :const:`False`. This function should be called after a response has been received from the server, so you can connect to :obj:`~gi.repository.WebKit.WebView`::load-changed and call this function when it's emitted with :const:`~gi.repository.WebKit.LoadEvent.COMMITTED` event. Note that this function provides no information about the security of the web page if the current :obj:`~gi.repository.WebKit.TLSErrorsPolicy` is :const:`~gi.repository.WebKit.TLSErrorsPolicy.IGNORE`, as subresources of the page may be controlled by an attacker. This function may safely be used to determine the security status of the current page only if the current :obj:`~gi.repository.WebKit.TLSErrorsPolicy` is :const:`~gi.repository.WebKit.TLSErrorsPolicy.FAIL`, in which case subresources that fail certificate verification will be blocked. .. method:: get_uri() -> str Returns the current active URI of ``web_view``. The active URI might change during a load operation: When nothing has been loaded yet on ``web_view`` the active URI is :const:`None`. When a new load operation starts the active URI is the requested URI: If the load operation was started by :func:`~gi.repository.WebKit.WebView.load_uri`, the requested URI is the given one. If the load operation was started by :func:`~gi.repository.WebKit.WebView.load_html`, the requested URI is "about:blank". If the load operation was started by :func:`~gi.repository.WebKit.WebView.load_alternate_html`, the requested URI is content URI provided. If the load operation was started by :func:`~gi.repository.WebKit.WebView.go_back` or :func:`~gi.repository.WebKit.WebView.go_forward`, the requested URI is the original URI of the previous/next item in the :obj:`~gi.repository.WebKit.BackForwardList` of ``web_view``. If the load operation was started by :func:`~gi.repository.WebKit.WebView.go_to_back_forward_list_item`, the requested URI is the opriginal URI of the given :obj:`~gi.repository.WebKit.BackForwardListItem`. If there is a server redirection during the load operation, the active URI is the redirected URI. When the signal :obj:`~gi.repository.WebKit.WebView`::load-changed is emitted with :const:`~gi.repository.WebKit.LoadEvent.REDIRECTED` event, the active URI is already updated to the redirected URI. When the signal :obj:`~gi.repository.WebKit.WebView`::load-changed is emitted with :const:`~gi.repository.WebKit.LoadEvent.COMMITTED` event, the active URI is the final one and it will not change unless a new load operation is started or a navigation action within the same page is performed. You can monitor the active URI by connecting to the notify::uri signal of ``web_view``. .. method:: get_user_content_manager() -> ~gi.repository.WebKit.UserContentManager Gets the user content manager associated to ``web_view``. .. versionadded:: 2.6 .. method:: get_web_extension_mode() -> ~gi.repository.WebKit.WebExtensionMode Get the view's :obj:`~gi.repository.WebKit.WebExtensionMode`. .. versionadded:: 2.38 .. method:: get_website_policies() -> ~gi.repository.WebKit.WebsitePolicies Gets the default website policies. Gets the default website policies set on construction in the ``web_view``. These can be overridden on a per-origin basis via the :obj:`~gi.repository.WebKit.WebView`::decide-policy signal handler. See also :func:`~gi.repository.WebKit.PolicyDecision.use_with_policies`. .. versionadded:: 2.30 .. method:: get_window_properties() -> ~gi.repository.WebKit.WindowProperties Get the :obj:`~gi.repository.WebKit.WindowProperties` object. Get the :obj:`~gi.repository.WebKit.WindowProperties` object containing the properties that the window containing ``web_view`` should have. .. method:: get_zoom_level() -> float Set the zoom level of ``web_view``. Get the zoom level of ``web_view``, i.e. the factor by which the view contents are scaled with respect to their original size. .. method:: go_back() -> None Loads the previous history item. You can monitor the load operation by connecting to :obj:`~gi.repository.WebKit.WebView`::load-changed signal. .. method:: go_forward() -> None Loads the next history item. You can monitor the load operation by connecting to :obj:`~gi.repository.WebKit.WebView`::load-changed signal. .. method:: go_to_back_forward_list_item(list_item: ~gi.repository.WebKit.BackForwardListItem) -> None Loads the specific history item ``list_item``. You can monitor the load operation by connecting to :obj:`~gi.repository.WebKit.WebView`::load-changed signal. :param list_item: a :obj:`~gi.repository.WebKit.BackForwardListItem` .. method:: is_controlled_by_automation() -> bool Get whether a :obj:`~gi.repository.WebKit.WebView` was created with :obj:`~gi.repository.WebKit.WebView`:is-controlled-by-automation property enabled. Only :obj:`~gi.repository.WebKit.WebView`s controlled by automation can be used in an automation session. .. versionadded:: 2.18 .. method:: is_editable() -> bool Gets whether the user is allowed to edit the HTML document. When ``web_view`` is not editable an element in the HTML document can only be edited if the CONTENTEDITABLE attribute has been set on the element or one of its parent elements. By default a :obj:`~gi.repository.WebKit.WebView` is not editable. .. versionadded:: 2.8 .. method:: is_loading() -> bool Gets the value of the :obj:`~gi.repository.WebKit.WebView`:is-loading property. You can monitor when a :obj:`~gi.repository.WebKit.WebView` is loading a page by connecting to notify::is-loading signal of ``web_view``. This is useful when you are interesting in knowing when the view is loading something but not in the details about the status of the load operation, for example to start a spinner when the view is loading a page and stop it when it finishes. .. method:: is_playing_audio() -> bool Gets the value of the :obj:`~gi.repository.WebKit.WebView`:is-playing-audio property. You can monitor when a page in a :obj:`~gi.repository.WebKit.WebView` is playing audio by connecting to the notify::is-playing-audio signal of ``web_view``. This is useful when the application wants to provide visual feedback when a page is producing sound. .. versionadded:: 2.8 .. method:: load_alternate_html(content: str, content_uri: str, base_uri: str | None = None) -> None Load the given ``content`` string for the URI ``content_uri``. This allows clients to display page-loading errors in the :obj:`~gi.repository.WebKit.WebView` itself. When this method is called from :obj:`~gi.repository.WebKit.WebView`::load-failed signal to show an error page, then the back-forward list is maintained appropriately. For everything else this method works the same way as :func:`~gi.repository.WebKit.WebView.load_html`. :param content: the new content to display as the main page of the ``web_view`` :param content_uri: the URI for the alternate page content :param base_uri: the base URI for relative locations or :const:`None` .. method:: load_bytes(bytes: ~gi.repository.GLib.Bytes, mime_type: str | None = None, encoding: str | None = None, base_uri: str | None = None) -> None Load the specified ``bytes`` into ``web_view`` using the given ``mime_type`` and ``encoding``. When ``mime_type`` is :const:`None`, it defaults to "text/html". When ``encoding`` is :const:`None`, it defaults to "UTF-8". When ``base_uri`` is :const:`None`, it defaults to "about:blank". You can monitor the load operation by connecting to :obj:`~gi.repository.WebKit.WebView`::load-changed signal. .. versionadded:: 2.6 :param bytes: input data to load :param mime_type: the MIME type of ``bytes``, or :const:`None` :param encoding: the character encoding of ``bytes``, or :const:`None` :param base_uri: the base URI for relative locations or :const:`None` .. method:: load_html(content: str, base_uri: str | None = None) -> None Load the given ``content`` string with the specified ``base_uri``. If ``base_uri`` is not :const:`None`, relative URLs in the ``content`` will be resolved against ``base_uri`` and absolute local paths must be children of the ``base_uri``. For security reasons absolute local paths that are not children of ``base_uri`` will cause the web process to terminate. If you need to include URLs in ``content`` that are local paths in a different directory than ``base_uri`` you can build a data URI for them. When ``base_uri`` is :const:`None`, it defaults to "about:blank". The mime type of the document will be "text/html". You can monitor the load operation by connecting to :obj:`~gi.repository.WebKit.WebView`::load-changed signal. :param content: The HTML string to load :param base_uri: The base URI for relative locations or :const:`None` .. method:: load_plain_text(plain_text: str) -> None Load the specified ``plain_text`` string into ``web_view``. The mime type of document will be "text/plain". You can monitor the load operation by connecting to :obj:`~gi.repository.WebKit.WebView`::load-changed signal. :param plain_text: The plain text to load .. method:: load_request(request: ~gi.repository.WebKit.URIRequest) -> None Requests loading of the specified :obj:`~gi.repository.WebKit.URIRequest`. You can monitor the load operation by connecting to :obj:`~gi.repository.WebKit.WebView`::load-changed signal. :param request: a :obj:`~gi.repository.WebKit.URIRequest` to load .. method:: load_uri(uri: str) -> None Requests loading of the specified URI string. You can monitor the load operation by connecting to :obj:`~gi.repository.WebKit.WebView`::load-changed signal. :param uri: an URI string .. method:: reload() -> None Reloads the current contents of ``web_view``. See also :func:`~gi.repository.WebKit.WebView.reload_bypass_cache`. .. method:: reload_bypass_cache() -> None Reloads the current contents of ``web_view`` without using any cached data. .. method:: restore_session_state(state: ~gi.repository.WebKit.WebViewSessionState) -> None Restore the ``web_view`` session state from ``state`` .. versionadded:: 2.12 :param state: a :obj:`~gi.repository.WebKit.WebViewSessionState` .. method:: save(save_mode: ~gi.repository.WebKit.SaveMode, cancellable: ~gi.repository.Gio.Cancellable | None = None, callback: ~typing.Callable[[...], None] | None = None, *user_data: ~typing.Any) -> None Asynchronously save the current web page. Asynchronously save the current web page associated to the :obj:`~gi.repository.WebKit.WebView` into a self-contained format using the mode specified in ``save_mode``. When the operation is finished, ``callback`` will be called. You can then call :func:`~gi.repository.WebKit.WebView.save_finish` to get the result of the operation. :param save_mode: the :obj:`~gi.repository.WebKit.SaveMode` specifying how the web page should be saved. :param cancellable: a :obj:`~gi.repository.Gio.Cancellable` or :const:`None` to ignore :param callback: a :obj:`~gi.repository.Gio.AsyncReadyCallback` to call when the request is satisfied :param user_data: the data to pass to callback function .. method:: save_finish(result: ~gi.repository.Gio.AsyncResult) -> ~gi.repository.Gio.InputStream Finish an asynchronous operation started with :func:`~gi.repository.WebKit.WebView.save`. :param result: a :obj:`~gi.repository.Gio.AsyncResult` .. method:: save_to_file(file: ~gi.repository.Gio.File, save_mode: ~gi.repository.WebKit.SaveMode, cancellable: ~gi.repository.Gio.Cancellable | None = None, callback: ~typing.Callable[[...], None] | None = None, *user_data: ~typing.Any) -> None Asynchronously save the current web page. Asynchronously save the current web page associated to the :obj:`~gi.repository.WebKit.WebView` into a self-contained format using the mode specified in ``save_mode`` and writing it to ``file``. When the operation is finished, ``callback`` will be called. You can then call :func:`~gi.repository.WebKit.WebView.save_to_file_finish` to get the result of the operation. :param file: the :obj:`~gi.repository.Gio.File` where the current web page should be saved to. :param save_mode: the :obj:`~gi.repository.WebKit.SaveMode` specifying how the web page should be saved. :param cancellable: a :obj:`~gi.repository.Gio.Cancellable` or :const:`None` to ignore :param callback: a :obj:`~gi.repository.Gio.AsyncReadyCallback` to call when the request is satisfied :param user_data: the data to pass to callback function .. method:: save_to_file_finish(result: ~gi.repository.Gio.AsyncResult) -> bool Finish an asynchronous operation started with :func:`~gi.repository.WebKit.WebView.save_to_file`. :param result: a :obj:`~gi.repository.Gio.AsyncResult` .. method:: send_message_to_page(message: ~gi.repository.WebKit.UserMessage, cancellable: ~gi.repository.Gio.Cancellable | None = None, callback: ~typing.Callable[[...], None] | None = None, *user_data: ~typing.Any) -> None Send ``message`` to the ``WebKitWebPage`` corresponding to ``web_view``. If ``message`` is floating, it's consumed. If you don't expect any reply, or you simply want to ignore it, you can pass :const:`None` as ``callback``. When the operation is finished, ``callback`` will be called. You can then call :func:`~gi.repository.WebKit.WebView.send_message_to_page_finish` to get the message reply. .. versionadded:: 2.28 :param message: a :obj:`~gi.repository.WebKit.UserMessage` :param cancellable: a :obj:`~gi.repository.Gio.Cancellable` or :const:`None` to ignore :param callback: (nullable): A :obj:`~gi.repository.Gio.AsyncReadyCallback` to call when the request is satisfied or :const:`None` :param user_data: the data to pass to callback function .. method:: send_message_to_page_finish(result: ~gi.repository.Gio.AsyncResult) -> ~gi.repository.WebKit.UserMessage Finish an asynchronous operation started with :func:`~gi.repository.WebKit.WebView.send_message_to_page`. .. versionadded:: 2.28 :param result: a :obj:`~gi.repository.Gio.AsyncResult` .. method:: set_background_color(rgba: ~gi.repository.Gdk.RGBA) -> None Sets the color that will be used to draw the ``web_view`` background. Sets the color that will be used to draw the ``web_view`` background before the actual contents are rendered. Note that if the web page loaded in ``web_view`` specifies a background color, it will take precedence over the ``rgba`` color. By default the ``web_view`` background color is opaque white. Note that the parent window must have a RGBA visual and :obj:`~gi.repository.Gtk.Widget`:app-paintable property set to :const:`True` for backgrounds colors to work. .. code-block:: c :dedent: static void browser_window_set_background_color (BrowserWindow *window, const GdkRGBA *rgba) { WebKitWebView *web_view; GdkScreen *screen = gtk_window_get_screen (GTK_WINDOW (window)); GdkVisual *rgba_visual = gdk_screen_get_rgba_visual (screen); if (!rgba_visual) return; gtk_widget_set_visual (GTK_WIDGET (window), rgba_visual); gtk_widget_set_app_paintable (GTK_WIDGET (window), TRUE); web_view = browser_window_get_web_view (window); webkit_web_view_set_background_color (web_view, rgba); } .. versionadded:: 2.8 :param rgba: a :obj:`~gi.repository.Gdk.RGBA` .. method:: set_camera_capture_state(state: ~gi.repository.WebKit.MediaCaptureState) -> None Set the camera capture state of a :obj:`~gi.repository.WebKit.WebView`. If :obj:`~gi.repository.WebKit.Settings`:enable-mediastream is :const:`False`, this method will have no visible effect. Once the state of the device has been set to :const:`~gi.repository.WebKit.MediaCaptureState.NONE` it cannot be changed anymore. The page can however request capture again using the mediaDevices API. .. versionadded:: 2.34 :param state: a :obj:`~gi.repository.WebKit.MediaCaptureState` .. method:: set_cors_allowlist(allowlist: ~typing.Sequence[str] | None = None) -> None Sets the ``allowlist`` for CORS. Sets the ``allowlist`` for which `Cross-Origin Resource Sharing `_ checks are disabled in ``web_view``. URI patterns must be of the form ``[protocol]://[host]/[path]``, each component may contain the wildcard character (``*``) to represent zero or more other characters. All three components are required and must not be omitted from the URI patterns. Disabling CORS checks permits resources from other origins to load allowlisted resources. It does not permit the allowlisted resources to load resources from other origins. If this function is called multiple times, only the allowlist set by the most recent call will be effective. .. versionadded:: 2.34 :param allowlist: an allowlist of URI patterns, or :const:`None` .. method:: set_custom_charset(charset: str | None = None) -> None Sets the current custom character encoding override of ``web_view``. The custom character encoding will override any text encoding detected via HTTP headers or META tags. Calling this method will stop any current load operation and reload the current page. Setting the custom character encoding to :const:`None` removes the character encoding override. :param charset: a character encoding name or :const:`None` .. method:: set_display_capture_state(state: ~gi.repository.WebKit.MediaCaptureState) -> None Set the display capture state of a :obj:`~gi.repository.WebKit.WebView`. If :obj:`~gi.repository.WebKit.Settings`:enable-mediastream is :const:`False`, this method will have no visible effect. Once the state of the device has been set to :const:`~gi.repository.WebKit.MediaCaptureState.NONE` it cannot be changed anymore. The page can however request capture again using the mediaDevices API. .. versionadded:: 2.34 :param state: a :obj:`~gi.repository.WebKit.MediaCaptureState` .. method:: set_editable(editable: bool) -> None Sets whether the user is allowed to edit the HTML document. If ``editable`` is :const:`True`, ``web_view`` allows the user to edit the HTML document. If ``editable`` is :const:`False`, an element in ``web_view``'s document can only be edited if the CONTENTEDITABLE attribute has been set on the element or one of its parent elements. By default a :obj:`~gi.repository.WebKit.WebView` is not editable. Normally, a HTML document is not editable unless the elements within the document are editable. This function provides a way to make the contents of a :obj:`~gi.repository.WebKit.WebView` editable without altering the document or DOM structure. .. versionadded:: 2.8 :param editable: a :obj:`~gi.repository.gboolean` indicating the editable state .. method:: set_input_method_context(context: ~gi.repository.WebKit.InputMethodContext | None = None) -> None Set the :obj:`~gi.repository.WebKit.InputMethodContext` to be used by ``web_view``. Set the :obj:`~gi.repository.WebKit.InputMethodContext` to be used by ``web_view``, or :const:`None` to not use any input method. Note that the same :obj:`~gi.repository.WebKit.InputMethodContext` can't be set on more than one :obj:`~gi.repository.WebKit.WebView` at the same time. .. versionadded:: 2.28 :param context: the :obj:`~gi.repository.WebKit.InputMethodContext` to set, or :const:`None` .. method:: set_is_muted(muted: bool) -> None Sets the mute state of ``web_view``. .. versionadded:: 2.30 :param muted: mute flag .. method:: set_microphone_capture_state(state: ~gi.repository.WebKit.MediaCaptureState) -> None Set the microphone capture state of a :obj:`~gi.repository.WebKit.WebView`. If :obj:`~gi.repository.WebKit.Settings`:enable-mediastream is :const:`False`, this method will have no visible effect. Once the state of the device has been set to :const:`~gi.repository.WebKit.MediaCaptureState.NONE` it cannot be changed anymore. The page can however request capture again using the mediaDevices API. .. versionadded:: 2.34 :param state: a :obj:`~gi.repository.WebKit.MediaCaptureState` .. method:: set_settings(settings: ~gi.repository.WebKit.Settings) -> None Sets the :obj:`~gi.repository.WebKit.Settings` to be applied to ``web_view``. The existing :obj:`~gi.repository.WebKit.Settings` of ``web_view`` will be replaced by ``settings``. New settings are applied immediately on ``web_view``. The same :obj:`~gi.repository.WebKit.Settings` object can be shared by multiple :obj:`~gi.repository.WebKit.WebView`s. :param settings: a :obj:`~gi.repository.WebKit.Settings` .. method:: set_zoom_level(zoom_level: float) -> None Set the zoom level of ``web_view``. Set the zoom level of ``web_view``, i.e. the factor by which the view contents are scaled with respect to their original size. :param zoom_level: the zoom level .. method:: stop_loading() -> None Stops any ongoing loading operation in ``web_view``. This method does nothing if no content is being loaded. If there is a loading operation in progress, it will be cancelled and :obj:`~gi.repository.WebKit.WebView`::load-failed signal will be emitted with :const:`~gi.repository.WebKit.NetworkError.CANCELLED` error. .. method:: terminate_web_process() -> None Terminates the web process associated to ``web_view``. When the web process gets terminated using this method, the :obj:`~gi.repository.WebKit.WebView`::web-process-terminated signal is emitted with :const:`~gi.repository.WebKit.WebProcessTerminationReason.TERMINATED_BY_API` as the reason for termination. .. versionadded:: 2.34 .. method:: try_close() -> None Tries to close the ``web_view``. This will fire the onbeforeunload event to ask the user for confirmation to close the page. If there isn't an onbeforeunload event handler or the user confirms to close the page, the :obj:`~gi.repository.WebKit.WebView`::close signal is emitted, otherwise nothing happens. .. versionadded:: 2.12 Properties ---------- .. rst-class:: interim-class .. class:: WebView :no-index: .. attribute:: props.automation_presentation_type :type: ~gi.repository.WebKit.AutomationBrowsingContextPresentation The :obj:`~gi.repository.WebKit.AutomationBrowsingContextPresentation` of :obj:`~gi.repository.WebKit.WebView`. This should only be used when creating a new :obj:`~gi.repository.WebKit.WebView` as a response to :obj:`~gi.repository.WebKit.AutomationSession`::create-web-view signal request. If the new WebView was added to a new tab of current browsing context window :const:`~gi.repository.WebKit.AutomationBrowsingContextPresentation.TAB` should be used. .. versionadded:: 2.28 .. attribute:: props.camera_capture_state :type: ~gi.repository.WebKit.MediaCaptureState Capture state of the camera device. Whenever the user grants a media-request sent by the web page, requesting video capture capabilities (`navigator.mediaDevices.getUserMedia({video: true})`) this property will be set to :const:`~gi.repository.WebKit.MediaCaptureState.ACTIVE`. The application can monitor this property and provide a visual indicator allowing to optionally deactivate or mute the capture device by setting this property respectively to :const:`~gi.repository.WebKit.MediaCaptureState.NONE` or :const:`~gi.repository.WebKit.MediaCaptureState.MUTED`. If the capture state of the device is set to :const:`~gi.repository.WebKit.MediaCaptureState.NONE` the web-page can still re-request the permission to the user. Permission desision caching is left to the application. .. versionadded:: 2.34 .. attribute:: props.default_content_security_policy :type: str The default Content-Security-Policy used by the webview as if it were set by an HTTP header. This applies to all content loaded including through navigation or via the various ``webkit_web_view_load_``\* APIs. However do note that many WebKit APIs bypass Content-Security-Policy in general such as :obj:`~gi.repository.WebKit.UserContentManager` and webkit_web_view_run_javascript(). Policies are additive so if a website sets its own policy it still applies on top of the policy set here. .. versionadded:: 2.38 .. attribute:: props.display_capture_state :type: ~gi.repository.WebKit.MediaCaptureState Capture state of the display device. Whenever the user grants a media-request sent by the web page, requesting screencasting capabilities (`navigator.mediaDevices.getDisplayMedia() this property will be set to :const:`~gi.repository.WebKit.MediaCaptureState.ACTIVE`. The application can monitor this property and provide a visual indicator allowing to optionally deactivate or mute the capture device by setting this property respectively to :const:`~gi.repository.WebKit.MediaCaptureState.NONE` or :const:`~gi.repository.WebKit.MediaCaptureState.MUTED`. If the capture state of the device is set to :const:`~gi.repository.WebKit.MediaCaptureState.NONE` the web-page can still re-request the permission to the user. Permission desision caching is left to the application. .. versionadded:: 2.34 .. attribute:: props.editable :type: bool Whether the pages loaded inside :obj:`~gi.repository.WebKit.WebView` are editable. For more information see :func:`~gi.repository.WebKit.WebView.set_editable`. .. versionadded:: 2.8 .. attribute:: props.estimated_load_progress :type: float An estimate of the percent completion for the current loading operation. This value will range from 0.0 to 1.0 and, once a load completes, will remain at 1.0 until a new load starts, at which point it will be reset to 0.0. The value is an estimate based on the total number of bytes expected to be received for a document, including all its possible subresources and child documents. .. attribute:: props.favicon :type: ~gi.repository.Gdk.Texture The favicon currently associated to the :obj:`~gi.repository.WebKit.WebView`. See :func:`~gi.repository.WebKit.WebView.get_favicon` for more details. .. attribute:: props.is_controlled_by_automation :type: bool Whether the :obj:`~gi.repository.WebKit.WebView` is controlled by automation. This should only be used when creating a new :obj:`~gi.repository.WebKit.WebView` as a response to :obj:`~gi.repository.WebKit.AutomationSession`::create-web-view signal request. .. versionadded:: 2.18 .. attribute:: props.is_loading :type: bool Whether the :obj:`~gi.repository.WebKit.WebView` is currently loading a page. This property becomes :const:`True` as soon as a new load operation is requested and before the :obj:`~gi.repository.WebKit.WebView`::load-changed signal is emitted with :const:`~gi.repository.WebKit.LoadEvent.STARTED` and at that point the active URI is the requested one. When the load operation finishes the property is set to :const:`False` before :obj:`~gi.repository.WebKit.WebView`::load-changed is emitted with :const:`~gi.repository.WebKit.LoadEvent.FINISHED`. .. attribute:: props.is_muted :type: bool Whether the :obj:`~gi.repository.WebKit.WebView` audio is muted. When :const:`True`, audio is silenced. It may still be playing, i.e. :obj:`~gi.repository.WebKit.WebView`:is-playing-audio may be :const:`True`. .. versionadded:: 2.30 .. attribute:: props.is_playing_audio :type: bool Whether the :obj:`~gi.repository.WebKit.WebView` is currently playing audio from a page. This property becomes :const:`True` as soon as web content starts playing any kind of audio. When a page is no longer playing any kind of sound, the property is set back to :const:`False`. .. versionadded:: 2.8 .. attribute:: props.is_web_process_responsive :type: bool Whether the web process currently associated to the :obj:`~gi.repository.WebKit.WebView` is responsive. .. versionadded:: 2.34 .. attribute:: props.microphone_capture_state :type: ~gi.repository.WebKit.MediaCaptureState Capture state of the microphone device. Whenever the user grants a media-request sent by the web page, requesting audio capture capabilities (`navigator.mediaDevices.getUserMedia({audio: true})`) this property will be set to :const:`~gi.repository.WebKit.MediaCaptureState.ACTIVE`. The application can monitor this property and provide a visual indicator allowing to optionally deactivate or mute the capture device by setting this property respectively to :const:`~gi.repository.WebKit.MediaCaptureState.NONE` or :const:`~gi.repository.WebKit.MediaCaptureState.MUTED`. If the capture state of the device is set to :const:`~gi.repository.WebKit.MediaCaptureState.NONE` the web-page can still re-request the permission to the user. Permission desision caching is left to the application. .. versionadded:: 2.34 .. attribute:: props.network_session :type: ~gi.repository.WebKit.NetworkSession The :obj:`~gi.repository.WebKit.NetworkSession` of the view .. versionadded:: 2.40 .. attribute:: props.page_id :type: int The identifier of the ``WebKitWebPage`` corresponding to the :obj:`~gi.repository.WebKit.WebView`. .. versionadded:: 2.28 .. attribute:: props.related_view :type: ~gi.repository.WebKit.WebView The related :obj:`~gi.repository.WebKit.WebView` used when creating the view to share the same web process and network session. This property is not readable because the related web view is only valid during the object construction. .. versionadded:: 2.4 .. attribute:: props.settings :type: ~gi.repository.WebKit.Settings The :obj:`~gi.repository.WebKit.Settings` of the view. .. versionadded:: 2.6 .. attribute:: props.title :type: str The main frame document title of this :obj:`~gi.repository.WebKit.WebView`. If the title has not been received yet, it will be :const:`None`. .. attribute:: props.uri :type: str The current active URI of the :obj:`~gi.repository.WebKit.WebView`. See :func:`~gi.repository.WebKit.WebView.get_uri` for more details. .. attribute:: props.user_content_manager :type: ~gi.repository.WebKit.UserContentManager The :obj:`~gi.repository.WebKit.UserContentManager` of the view. .. versionadded:: 2.6 .. attribute:: props.web_context :type: ~gi.repository.WebKit.WebContext The :obj:`~gi.repository.WebKit.WebContext` of the view. .. attribute:: props.web_extension_mode :type: ~gi.repository.WebKit.WebExtensionMode This configures ``web_view`` to treat the content as a WebExtension. Note that this refers to the web standard `WebExtensions `_ and not WebKitWebExtensions. In practice this limits the Content-Security-Policies that are allowed to be set. Some details can be found in `Chrome's documentation `_. .. versionadded:: 2.38 .. attribute:: props.website_policies :type: ~gi.repository.WebKit.WebsitePolicies The :obj:`~gi.repository.WebKit.WebsitePolicies` for the view. .. versionadded:: 2.30 .. attribute:: props.zoom_level :type: float The zoom level of the :obj:`~gi.repository.WebKit.WebView` content. See :func:`~gi.repository.WebKit.WebView.set_zoom_level` for more details. Signals ------- .. rst-class:: interim-class .. class:: WebView.signals :no-index: .. method:: authenticate(request: ~gi.repository.WebKit.AuthenticationRequest) -> bool This signal is emitted when the user is challenged with HTTP authentication. To let the application access or supply the credentials as well as to allow the client application to either cancel the request or perform the authentication, the signal will pass an instance of the :obj:`~gi.repository.WebKit.AuthenticationRequest` in the ``request`` argument. To handle this signal asynchronously you should keep a ref of the request and return :const:`True`. To disable HTTP authentication entirely, connect to this signal and simply return :const:`True`. The default signal handler will run a default authentication dialog asynchronously for the user to interact with. .. versionadded:: 2.2 :param request: a :obj:`~gi.repository.WebKit.AuthenticationRequest` .. method:: close() -> None Emitted when closing a :obj:`~gi.repository.WebKit.WebView` is requested. This occurs when a call is made from JavaScript's window.close function or after trying to close the ``web_view`` with :func:`~gi.repository.WebKit.WebView.try_close`. It is the owner's responsibility to handle this signal to hide or destroy the :obj:`~gi.repository.WebKit.WebView`, if necessary. .. method:: context_menu(context_menu: ~gi.repository.WebKit.ContextMenu, hit_test_result: ~gi.repository.WebKit.HitTestResult) -> bool Emitted when a context menu is about to be displayed to give the application a chance to customize the proposed menu, prevent the menu from being displayed, or build its own context menu. To customize the proposed menu you can use :func:`~gi.repository.WebKit.ContextMenu.prepend`, :func:`~gi.repository.WebKit.ContextMenu.append` or :func:`~gi.repository.WebKit.ContextMenu.insert` to add new :obj:`~gi.repository.WebKit.ContextMenuItem`s to ``context_menu``, :func:`~gi.repository.WebKit.ContextMenu.move_item` to reorder existing items, or :func:`~gi.repository.WebKit.ContextMenu.remove` to remove an existing item. The signal handler should return :const:`False`, and the menu represented by ``context_menu`` will be shown. To prevent the menu from being displayed you can just connect to this signal and return :const:`True` so that the proposed menu will not be shown. To build your own menu, you can remove all items from the proposed menu with :func:`~gi.repository.WebKit.ContextMenu.remove_all`, add your own items and return :const:`False` so that the menu will be shown. You can also ignore the proposed :obj:`~gi.repository.WebKit.ContextMenu`, build your own ``GtkMenu`` and return :const:`True` to prevent the proposed menu from being shown. If you just want the default menu to be shown always, simply don't connect to this signal because showing the proposed context menu is the default behaviour. If the signal handler returns :const:`False` the context menu represented by ``context_menu`` will be shown, if it return :const:`True` the context menu will not be shown. The proposed :obj:`~gi.repository.WebKit.ContextMenu` passed in ``context_menu`` argument is only valid during the signal emission. :param context_menu: the proposed :obj:`~gi.repository.WebKit.ContextMenu` :param hit_test_result: a :obj:`~gi.repository.WebKit.HitTestResult` .. method:: context_menu_dismissed() -> None Emitted after :obj:`~gi.repository.WebKit.WebView`::context-menu signal, if the context menu is shown, to notify that the context menu is dismissed. .. method:: create(navigation_action: ~gi.repository.WebKit.NavigationAction) -> ~gi.repository.Gtk.Widget Emitted when the creation of a new :obj:`~gi.repository.WebKit.WebView` is requested. If this signal is handled the signal handler should return the newly created :obj:`~gi.repository.WebKit.WebView`. The :obj:`~gi.repository.WebKit.NavigationAction` parameter contains information about the navigation action that triggered this signal. The new :obj:`~gi.repository.WebKit.WebView` must be related to ``web_view``, see :obj:`~gi.repository.WebKit.WebView`:related-view for more details. The new :obj:`~gi.repository.WebKit.WebView` should not be displayed to the user until the :obj:`~gi.repository.WebKit.WebView`::ready-to-show signal is emitted. :param navigation_action: a :obj:`~gi.repository.WebKit.NavigationAction` .. method:: decide_policy(decision: ~gi.repository.WebKit.PolicyDecision, decision_type: ~gi.repository.WebKit.PolicyDecisionType) -> bool This signal is emitted when WebKit is requesting the client to decide a policy decision, such as whether to navigate to a page, open a new window or whether or not to download a resource. The :obj:`~gi.repository.WebKit.NavigationPolicyDecision` passed in the ``decision`` argument is a generic type, but should be casted to a more specific type when making the decision. For example: .. code-block:: c :dedent: static gboolean decide_policy_cb (WebKitWebView *web_view, WebKitPolicyDecision *decision, WebKitPolicyDecisionType type) { switch (type) { case WEBKIT_POLICY_DECISION_TYPE_NAVIGATION_ACTION: { WebKitNavigationPolicyDecision *navigation_decision = WEBKIT_NAVIGATION_POLICY_DECISION (decision); // Make a policy decision here break; } case WEBKIT_POLICY_DECISION_TYPE_NEW_WINDOW_ACTION: { WebKitNavigationPolicyDecision *navigation_decision = WEBKIT_NAVIGATION_POLICY_DECISION (decision); // Make a policy decision here break; } case WEBKIT_POLICY_DECISION_TYPE_RESPONSE: WebKitResponsePolicyDecision *response = WEBKIT_RESPONSE_POLICY_DECISION (decision); // Make a policy decision here break; default: // Making no decision results in :func:`~gi.repository.WebKit.PolicyDecision.use` return FALSE; } return TRUE; } It is possible to make policy decision asynchronously, by simply calling :func:`~gi.repository.GObject.GObject.Object.ref` on the ``decision`` argument and returning :const:`True` to block the default signal handler. If the last reference is removed on a :obj:`~gi.repository.WebKit.PolicyDecision` and no decision has been made explicitly, :func:`~gi.repository.WebKit.PolicyDecision.use` will be the default policy decision. The default signal handler will simply call :func:`~gi.repository.WebKit.PolicyDecision.use`. Only the first policy decision chosen for a given :obj:`~gi.repository.WebKit.PolicyDecision` will have any affect. :param decision: the :obj:`~gi.repository.WebKit.PolicyDecision` :param decision_type: a :obj:`~gi.repository.WebKit.PolicyDecisionType` denoting the type of ``decision`` .. method:: enter_fullscreen() -> bool Emitted when JavaScript code calls element.webkitRequestFullScreen. If the signal is not handled the :obj:`~gi.repository.WebKit.WebView` will proceed to full screen its top level window. This signal can be used by client code to request permission to the user prior doing the full screen transition and eventually prepare the top-level window (e.g. hide some widgets that would otherwise be part of the full screen window). .. method:: insecure_content_detected(event: ~gi.repository.WebKit.InsecureContentEvent) -> None This signal is emitted when insecure content has been detected in a page loaded through a secure connection. This typically means that a external resource from an unstrusted source has been run or displayed, resulting in a mix of HTTPS and non-HTTPS content. You can check the ``event`` parameter to know exactly which kind of event has been detected (see :obj:`~gi.repository.WebKit.InsecureContentEvent`). :param event: the :obj:`~gi.repository.WebKit.InsecureContentEvent` .. method:: leave_fullscreen() -> bool Emitted when the :obj:`~gi.repository.WebKit.WebView` is about to restore its top level window out of its full screen state. This signal can be used by client code to restore widgets hidden during the :obj:`~gi.repository.WebKit.WebView`::enter-fullscreen stage for instance. .. method:: load_changed(load_event: ~gi.repository.WebKit.LoadEvent) -> None Emitted when a load operation in ``web_view`` changes. The signal is always emitted with :const:`~gi.repository.WebKit.LoadEvent.STARTED` when a new load request is made and :const:`~gi.repository.WebKit.LoadEvent.FINISHED` when the load finishes successfully or due to an error. When the ongoing load operation fails :obj:`~gi.repository.WebKit.WebView`::load-failed signal is emitted before :obj:`~gi.repository.WebKit.WebView`::load-changed is emitted with :const:`~gi.repository.WebKit.LoadEvent.FINISHED`. If a redirection is received from the server, this signal is emitted with :const:`~gi.repository.WebKit.LoadEvent.REDIRECTED` after the initial emission with :const:`~gi.repository.WebKit.LoadEvent.STARTED` and before :const:`~gi.repository.WebKit.LoadEvent.COMMITTED`. When the page content starts arriving the signal is emitted with :const:`~gi.repository.WebKit.LoadEvent.COMMITTED` event. You can handle this signal and use a switch to track any ongoing load operation. .. code-block:: c :dedent: static void web_view_load_changed (WebKitWebView *web_view, WebKitLoadEvent load_event, gpointer user_data) { switch (load_event) { case WEBKIT_LOAD_STARTED: // New load, we have now a provisional URI provisional_uri = webkit_web_view_get_uri (web_view); // Here we could start a spinner or update the // location bar with the provisional URI break; case WEBKIT_LOAD_REDIRECTED: redirected_uri = webkit_web_view_get_uri (web_view); break; case WEBKIT_LOAD_COMMITTED: // The load is being performed. Current URI is // the final one and it won't change unless a new // load is requested or a navigation within the // same page is performed uri = webkit_web_view_get_uri (web_view); break; case WEBKIT_LOAD_FINISHED: // Load finished, we can now stop the spinner break; } } :param load_event: the :obj:`~gi.repository.WebKit.LoadEvent` .. method:: load_failed(load_event: ~gi.repository.WebKit.LoadEvent, failing_uri: str, error: ~gi.repository.GLib.GError) -> bool Emitted when an error occurs during a load operation. If the error happened when starting to load data for a page ``load_event`` will be :const:`~gi.repository.WebKit.LoadEvent.STARTED`. If it happened while loading a committed data source ``load_event`` will be :const:`~gi.repository.WebKit.LoadEvent.COMMITTED`. Since a load error causes the load operation to finish, the signal WebKitWebView::load-changed will always be emitted with :const:`~gi.repository.WebKit.LoadEvent.FINISHED` event right after this one. By default, if the signal is not handled, a stock error page will be displayed. You need to handle the signal if you want to provide your own error page. :param load_event: the :obj:`~gi.repository.WebKit.LoadEvent` of the load operation :param failing_uri: the URI that failed to load :param error: the :obj:`~gi.repository.GLib.Error` that was triggered .. method:: load_failed_with_tls_errors(failing_uri: str, certificate: ~gi.repository.Gio.TlsCertificate, errors: ~gi.repository.Gio.TlsCertificateFlags) -> bool Emitted when a TLS error occurs during a load operation. To allow an exception for this ``certificate`` and the host of ``failing_uri`` use webkit_web_context_allow_tls_certificate_for_host(). To handle this signal asynchronously you should call :func:`~gi.repository.GObject.GObject.Object.ref` on ``certificate`` and return :const:`True`. If :const:`False` is returned, :obj:`~gi.repository.WebKit.WebView`::load-failed will be emitted. The load will finish regardless of the returned value. .. versionadded:: 2.6 :param failing_uri: the URI that failed to load :param certificate: a :obj:`~gi.repository.Gio.TlsCertificate` :param errors: a :obj:`~gi.repository.Gio.TlsCertificateFlags` with the verification status of ``certificate`` .. method:: mouse_target_changed(hit_test_result: ~gi.repository.WebKit.HitTestResult, modifiers: int) -> None This signal is emitted when the mouse cursor moves over an element such as a link, image or a media element. To determine what type of element the mouse cursor is over, a Hit Test is performed on the current mouse coordinates and the result is passed in the ``hit_test_result`` argument. The ``modifiers`` argument is a bitmask of :obj:`~gi.repository.Gdk.ModifierType` flags indicating the state of modifier keys. The signal is emitted again when the mouse is moved out of the current element with a new ``hit_test_result``. :param hit_test_result: a :obj:`~gi.repository.WebKit.HitTestResult` :param modifiers: a bitmask of :obj:`~gi.repository.Gdk.ModifierType` .. method:: permission_request(request: ~gi.repository.WebKit.PermissionRequest) -> bool This signal is emitted when WebKit is requesting the client to decide about a permission request, such as allowing the browser to switch to fullscreen mode, sharing its location or similar operations. A possible way to use this signal could be through a dialog allowing the user decide what to do with the request: .. code-block:: c :dedent: static gboolean permission_request_cb (WebKitWebView *web_view, WebKitPermissionRequest *request, GtkWindow *parent_window) { GtkWidget *dialog = gtk_message_dialog_new (parent_window, GTK_DIALOG_MODAL, GTK_MESSAGE_QUESTION, GTK_BUTTONS_YES_NO, "Allow Permission Request?"); gtk_widget_show (dialog); gint result = gtk_dialog_run (GTK_DIALOG (dialog)); switch (result) { case GTK_RESPONSE_YES: webkit_permission_request_allow (request); break; default: webkit_permission_request_deny (request); break; } gtk_widget_destroy (dialog); return TRUE; } It is possible to handle permission requests asynchronously, by simply calling :func:`~gi.repository.GObject.GObject.Object.ref` on the ``request`` argument and returning :const:`True` to block the default signal handler. If the last reference is removed on a :obj:`~gi.repository.WebKit.PermissionRequest` and the request has not been handled, :func:`~gi.repository.WebKit.PermissionRequest.deny` will be the default action. If the signal is not handled, the ``request`` will be completed automatically by the specific :obj:`~gi.repository.WebKit.PermissionRequest` that could allow or deny it. Check the documentation of classes implementing :obj:`~gi.repository.WebKit.PermissionRequest` interface to know their default action. :param request: the :obj:`~gi.repository.WebKit.PermissionRequest` .. method:: print_(print_operation: ~gi.repository.WebKit.PrintOperation) -> bool :param print_operation: .. method:: query_permission_state(query: ~gi.repository.WebKit.PermissionStateQuery) -> bool This signal allows the User-Agent to respond to permission requests for powerful features, as specified by the `Permissions W3C Specification `_. You can reply to the query using :func:`~gi.repository.WebKit.PermissionStateQuery.finish`. You can handle the query asynchronously by calling :func:`~gi.repository.WebKit.PermissionStateQuery.ref` on ``query`` and returning :const:`True`. If the last reference of ``query`` is removed and the query has not been handled, the query result will be set to ``%WEBKIT_QUERY_PERMISSION_PROMPT``. .. versionadded:: 2.40 :param query: the :obj:`~gi.repository.WebKit.PermissionStateQuery` .. method:: ready_to_show() -> None Emitted after :obj:`~gi.repository.WebKit.WebView`::create on the newly created :obj:`~gi.repository.WebKit.WebView` when it should be displayed to the user. When this signal is emitted all the information about how the window should look, including size, position, whether the location, status and scrollbars should be displayed, is already set on the :obj:`~gi.repository.WebKit.WindowProperties` of ``web_view``. See also :func:`~gi.repository.WebKit.WebView.get_window_properties`. .. method:: resource_load_started(resource: ~gi.repository.WebKit.WebResource, request: ~gi.repository.WebKit.URIRequest) -> None Emitted when a new resource is going to be loaded. The ``request`` parameter contains the :obj:`~gi.repository.WebKit.URIRequest` that will be sent to the server. You can monitor the load operation by connecting to the different signals of ``resource``. :param resource: a :obj:`~gi.repository.WebKit.WebResource` :param request: a :obj:`~gi.repository.WebKit.URIRequest` .. method:: run_as_modal() -> None Emitted after :obj:`~gi.repository.WebKit.WebView`::ready-to-show on the newly created :obj:`~gi.repository.WebKit.WebView` when JavaScript code calls window.showModalDialog. The purpose of this signal is to allow the client application to prepare the new view to behave as modal. Once the signal is emitted a new main loop will be run to block user interaction in the parent :obj:`~gi.repository.WebKit.WebView` until the new dialog is closed. .. method:: run_color_chooser(request: ~gi.repository.WebKit.ColorChooserRequest) -> bool This signal is emitted when the user interacts with a HTML element, requesting from WebKit to show a dialog to select a color. To let the application know the details of the color chooser, as well as to allow the client application to either cancel the request or perform an actual color selection, the signal will pass an instance of the :obj:`~gi.repository.WebKit.ColorChooserRequest` in the ``request`` argument. It is possible to handle this request asynchronously by increasing the reference count of the request. The default signal handler will asynchronously run a regular :obj:`~gi.repository.Gtk.ColorChooser` for the user to interact with. .. versionadded:: 2.8 :param request: a :obj:`~gi.repository.WebKit.ColorChooserRequest` .. method:: run_file_chooser(request: ~gi.repository.WebKit.FileChooserRequest) -> bool This signal is emitted when the user interacts with a HTML element, requesting from WebKit to show a dialog to select one or more files to be uploaded. To let the application know the details of the file chooser, as well as to allow the client application to either cancel the request or perform an actual selection of files, the signal will pass an instance of the :obj:`~gi.repository.WebKit.FileChooserRequest` in the ``request`` argument. The default signal handler will asynchronously run a regular ``GtkFileChooserDialog`` for the user to interact with. :param request: a :obj:`~gi.repository.WebKit.FileChooserRequest` .. method:: script_dialog(dialog: ~gi.repository.WebKit.ScriptDialog) -> bool Emitted when JavaScript code calls window.alert, window.confirm or window.prompt, or when onbeforeunload event is fired. The ``dialog`` parameter should be used to build the dialog. If the signal is not handled a different dialog will be built and shown depending on the dialog type: :const:`~gi.repository.WebKit.ScriptDialogType.ALERT`: message dialog with a single Close button. :const:`~gi.repository.WebKit.ScriptDialogType.CONFIRM`: message dialog with OK and Cancel buttons. :const:`~gi.repository.WebKit.ScriptDialogType.PROMPT`: message dialog with OK and Cancel buttons and a text entry with the default text. :const:`~gi.repository.WebKit.ScriptDialogType.BEFORE_UNLOAD_CONFIRM`: message dialog with Stay and Leave buttons. It is possible to handle the script dialog request asynchronously, by simply caling :func:`~gi.repository.WebKit.ScriptDialog.ref` on the ``dialog`` argument and calling :func:`~gi.repository.WebKit.ScriptDialog.close` when done. If the last reference is removed on a :obj:`~gi.repository.WebKit.ScriptDialog` and the dialog has not been closed, :func:`~gi.repository.WebKit.ScriptDialog.close` will be called. :param dialog: the :obj:`~gi.repository.WebKit.ScriptDialog` to show .. method:: show_notification(notification: ~gi.repository.WebKit.Notification) -> bool This signal is emitted when a notification should be presented to the user. The ``notification`` is kept alive until either: 1) the web page cancels it or 2) a navigation happens. The default handler will emit a notification using libnotify, if built with support for it. .. versionadded:: 2.8 :param notification: a :obj:`~gi.repository.WebKit.Notification` .. method:: show_option_menu(menu: ~gi.repository.WebKit.OptionMenu, rectangle: ~gi.repository.Gdk.Rectangle) -> bool This signal is emitted when a select element in ``web_view`` needs to display a dropdown menu. This signal can be used to show a custom menu, using ``menu`` to get the details of all items that should be displayed. The area of the element in the :obj:`~gi.repository.WebKit.WebView` is given as ``rectangle`` parameter, it can be used to position the menu. To handle this signal asynchronously you should keep a ref of the ``menu``. The default signal handler will pop up a ``GtkMenu``. .. versionadded:: 2.18 :param menu: the :obj:`~gi.repository.WebKit.OptionMenu` :param rectangle: the option element area .. method:: submit_form(request: ~gi.repository.WebKit.FormSubmissionRequest) -> None This signal is emitted when a form is about to be submitted. The ``request`` argument passed contains information about the text fields of the form. This is typically used to store login information that can be used later to pre-fill the form. The form will not be submitted until :func:`~gi.repository.WebKit.FormSubmissionRequest.submit` is called. It is possible to handle the form submission request asynchronously, by simply calling :func:`~gi.repository.GObject.GObject.Object.ref` on the ``request`` argument and calling :func:`~gi.repository.WebKit.FormSubmissionRequest.submit` when done to continue with the form submission. If the last reference is removed on a :obj:`~gi.repository.WebKit.FormSubmissionRequest` and the form has not been submitted, :func:`~gi.repository.WebKit.FormSubmissionRequest.submit` will be called. :param request: a :obj:`~gi.repository.WebKit.FormSubmissionRequest` .. method:: user_message_received(message: ~gi.repository.WebKit.UserMessage) -> bool This signal is emitted when a :obj:`~gi.repository.WebKit.UserMessage` is received from the ``WebKitWebPage`` corresponding to ``web_view``. 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`. If the last reference of ``message`` is removed and the message has not been replied to, the operation in the ``WebKitWebPage`` will finish with error :const:`~gi.repository.WebKit.UserMessageError.MESSAGE`. .. versionadded:: 2.28 :param message: the :obj:`~gi.repository.WebKit.UserMessage` received .. method:: web_process_terminated(reason: ~gi.repository.WebKit.WebProcessTerminationReason) -> None This signal is emitted when the web process terminates abnormally due to ``reason``. .. versionadded:: 2.20 :param reason: the a :obj:`~gi.repository.WebKit.WebProcessTerminationReason` Virtual Methods --------------- .. rst-class:: interim-class .. class:: WebView :no-index: .. method:: do_authenticate(request: ~gi.repository.WebKit.AuthenticationRequest) -> bool :param request: .. method:: do_close() -> None .. method:: do_context_menu(context_menu: ~gi.repository.WebKit.ContextMenu, hit_test_result: ~gi.repository.WebKit.HitTestResult) -> bool :param context_menu: :param hit_test_result: .. method:: do_context_menu_dismissed() -> None .. method:: do_decide_policy(decision: ~gi.repository.WebKit.PolicyDecision, type: ~gi.repository.WebKit.PolicyDecisionType) -> bool :param decision: :param type: .. method:: do_enter_fullscreen() -> bool .. method:: do_insecure_content_detected(event: ~gi.repository.WebKit.InsecureContentEvent) -> None :param event: .. method:: do_leave_fullscreen() -> bool .. method:: do_load_changed(load_event: ~gi.repository.WebKit.LoadEvent) -> None :param load_event: .. method:: do_load_failed(load_event: ~gi.repository.WebKit.LoadEvent, failing_uri: str, error: ~gi.repository.GLib.GError) -> bool :param load_event: :param failing_uri: :param error: .. method:: do_load_failed_with_tls_errors(failing_uri: str, certificate: ~gi.repository.Gio.TlsCertificate, errors: ~gi.repository.Gio.TlsCertificateFlags) -> bool :param failing_uri: :param certificate: :param errors: .. method:: do_mouse_target_changed(hit_test_result: ~gi.repository.WebKit.HitTestResult, modifiers: int) -> None :param hit_test_result: :param modifiers: .. method:: do_permission_request(permission_request: ~gi.repository.WebKit.PermissionRequest) -> bool :param permission_request: .. method:: do_print_(print_operation: ~gi.repository.WebKit.PrintOperation) -> bool :param print_operation: .. method:: do_query_permission_state(query: ~gi.repository.WebKit.PermissionStateQuery) -> bool :param query: .. method:: do_ready_to_show() -> None .. method:: do_resource_load_started(resource: ~gi.repository.WebKit.WebResource, request: ~gi.repository.WebKit.URIRequest) -> None :param resource: :param request: .. method:: do_run_as_modal() -> None .. method:: do_run_color_chooser(request: ~gi.repository.WebKit.ColorChooserRequest) -> bool :param request: .. method:: do_run_file_chooser(request: ~gi.repository.WebKit.FileChooserRequest) -> bool :param request: .. method:: do_script_dialog(dialog: ~gi.repository.WebKit.ScriptDialog) -> bool :param dialog: .. method:: do_show_notification(notification: ~gi.repository.WebKit.Notification) -> bool :param notification: .. method:: do_show_option_menu(menu: ~gi.repository.WebKit.OptionMenu, rectangle: ~gi.repository.Gdk.Rectangle) -> bool :param menu: :param rectangle: .. method:: do_submit_form(request: ~gi.repository.WebKit.FormSubmissionRequest) -> None :param request: .. method:: do_user_message_received(message: ~gi.repository.WebKit.UserMessage) -> bool :param message: .. method:: do_web_process_crashed() -> bool .. method:: do_web_process_terminated(reason: ~gi.repository.WebKit.WebProcessTerminationReason) -> None :param reason: Fields ------ .. rst-class:: interim-class .. class:: WebView :no-index: .. attribute:: parent_instance .. attribute:: priv