WebView#

class WebView(**properties: Any)#

Superclasses: WebViewBase, Widget, InitiallyUnowned, Object

Implemented Interfaces: Accessible, Buildable, ConstraintTarget

The central class of the WPE WebKit and WebKitGTK APIs.

WebView is the central class of the WPE WebKit and WebKitGTK APIs. It is responsible for managing the drawing of the content and forwarding of events. You can load any URI into the WebView or a data string. With Settings you can control various aspects of the rendering and loading of the content.

Note that in WebKitGTK, WebView is scrollable by itself, so you don’t need to embed it in a ScrolledWindow.

Constructors#

class WebView

classmethod new() → Widget#

Creates a new WebView with the default WebContext.

Creates a new WebView with the default WebContext and no 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#

class WebView

async call_async_javascript_function(self, body: str, length: int, arguments: Variant | None = None, world_name: str | None = None, source_uri: str | None = None) → Value#

This is the awaitable version of call_async_javascript_function().

Added in version 2.40.

Parameters:

body – the function body
length – length of body, or -1 if body is a nul-terminated string
arguments – a Variant with format a{sv} storing the function arguments, or None
world_name – the name of a WebKitScriptWorld or None to use the default
source_uri – the source URI

call_async_javascript_function(body: str, length: int, arguments: Variant | None = None, world_name: str | None = None, source_uri: str | None = None, cancellable: Cancellable | None = None, callback: Callable[[Object | None, AsyncResult, Any], None] | None = None, user_data: Any = None) → 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 None, the default world is used. Any value that is not 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 Settings:enable-javascript is 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 Settings:enable-javascript-markup.

When the operation is finished, callback will be called. You can then call 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:

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);
}

Added in version 2.40.

Parameters:

body – the function body
length – length of body, or -1 if body is a nul-terminated string
arguments – a Variant with format a{sv} storing the function arguments, or None
world_name – the name of a WebKitScriptWorld or None to use the default
source_uri – the source URI
cancellable – a Cancellable or None to ignore
callback – a AsyncReadyCallback to call when the script finished
user_data – the data to pass to callback function

call_async_javascript_function_finish(result: AsyncResult) → Value#

Finish an asynchronous operation started with call_async_javascript_function().

Added in version 2.40.

Parameters:: result – a AsyncResult

async can_execute_editing_command(self, command: str) → bool#

This is the awaitable version of can_execute_editing_command().

Parameters:: command – the command to check

can_execute_editing_command(command: str, cancellable: Cancellable | None = None, callback: Callable[[Object | None, AsyncResult, Any], None] | None = None, user_data: Any = None) → 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 can_execute_editing_command_finish() to get the result of the operation.

Parameters:

command – the command to check
cancellable – a Cancellable or None to ignore
callback – a AsyncReadyCallback to call when the request is satisfied
user_data – the data to pass to callback function

can_execute_editing_command_finish(result: AsyncResult) → bool#

Finish an asynchronous operation started with can_execute_editing_command().

Parameters:: result – a AsyncResult

can_go_back() → bool#: Determines whether web_view has a previous history item.

can_go_forward() → bool#: Determines whether web_view has a next history item.

can_show_mime_type(mime_type: str) → bool#

Whether or not a MIME type can be displayed in web_view.

Parameters:: mime_type – a MIME type

do_authenticate(self, request: AuthenticationRequest) → bool#

Parameters:: request

do_close(self) → None#

do_context_menu(self, context_menu: ContextMenu, hit_test_result: HitTestResult) → bool#

Parameters:

context_menu
hit_test_result

do_context_menu_dismissed(self) → None#

do_decide_policy(self, decision: PolicyDecision, type: PolicyDecisionType) → bool#

Parameters:

decision
type

do_enter_fullscreen(self) → bool#

do_insecure_content_detected(self, event: InsecureContentEvent) → None#

Parameters:: event

do_leave_fullscreen(self) → bool#

do_load_changed(self, load_event: LoadEvent) → None#

Parameters:: load_event

do_load_failed(self, load_event: LoadEvent, failing_uri: str, error: GError) → bool#

Parameters:

load_event
failing_uri
error

do_load_failed_with_tls_errors(self, failing_uri: str, certificate: TlsCertificate, errors: TlsCertificateFlags) → bool#

Parameters:

failing_uri
certificate
errors

do_mouse_target_changed(self, hit_test_result: HitTestResult, modifiers: int) → None#

Parameters:

hit_test_result
modifiers

do_permission_request(self, permission_request: PermissionRequest) → bool#

Parameters:: permission_request

do_print_(self, print_operation: PrintOperation) → bool#

Parameters:: print_operation

do_query_permission_state(self, query: PermissionStateQuery) → bool#

Parameters:: query

do_ready_to_show(self) → None#

do_resource_load_started(self, resource: WebResource, request: URIRequest) → None#

Parameters:

resource
request

do_run_as_modal(self) → None#

do_run_color_chooser(self, request: ColorChooserRequest) → bool#

Parameters:: request

do_run_file_chooser(self, request: FileChooserRequest) → bool#

Parameters:: request

do_script_dialog(self, dialog: ScriptDialog) → bool#

Parameters:: dialog

do_show_notification(self, notification: Notification) → bool#

Parameters:: notification

do_show_option_menu(self, menu: OptionMenu, rectangle: Rectangle) → bool#

Parameters:

menu
rectangle

do_submit_form(self, request: FormSubmissionRequest) → None#

Parameters:: request

do_user_message_received(self, message: UserMessage) → bool#

Parameters:: message

do_web_process_crashed(self) → bool#

do_web_process_terminated(self, reason: WebProcessTerminationReason) → None#

Parameters:: reason

download_uri(uri: str) → Download#

Requests downloading of the specified URI string for web_view.

Parameters:: uri – the URI to download

async evaluate_javascript(self, script: str, length: int, world_name: str | None = None, source_uri: str | None = None) → Value#

This is the awaitable version of evaluate_javascript().

Added in version 2.40.

Parameters:

script – the script to evaluate
length – length of script, or -1 if script is a nul-terminated string
world_name – the name of a WebKitScriptWorld or None to use the default
source_uri – the source URI

evaluate_javascript(script: str, length: int, world_name: str | None = None, source_uri: str | None = None, cancellable: Cancellable | None = None, callback: Callable[[Object | None, AsyncResult, Any], None] | None = None, user_data: Any = None) → 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 None, the default world is used. Any value that is not 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.

When the operation is finished, callback will be called. You can then call evaluate_javascript_finish() to get the result of the operation.

This is an example of using evaluate_javascript() with a script returning a string:

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);
}

Added in version 2.40.

Parameters:

script – the script to evaluate
length – length of script, or -1 if script is a nul-terminated string
world_name – the name of a WebKitScriptWorld or None to use the default
source_uri – the source URI
cancellable – a Cancellable or None to ignore
callback – a AsyncReadyCallback to call when the script finished
user_data – the data to pass to callback function

evaluate_javascript_finish(result: AsyncResult) → Value#

Finish an asynchronous operation started with evaluate_javascript().

Added in version 2.40.

Parameters:: result – a AsyncResult

execute_editing_command(command: str) → None#

Request to execute the given command for web_view.

You can use can_execute_editing_command() to check whether it’s possible to execute the command.

Parameters:: command – the command to execute

execute_editing_command_with_argument(command: str, argument: str) → None#

Request to execute the given command with argument for web_view.

You can use can_execute_editing_command() to check whether it’s possible to execute the command.

Added in version 2.10.

Parameters:

command – the command to execute
argument – the command argument

get_automation_presentation_type() → AutomationBrowsingContextPresentation#: Get the presentation type of WebView when created for automation.

Added in version 2.28.

get_back_forward_list() → BackForwardList#

Obtains the BackForwardList associated with the given WebView.

The BackForwardList is owned by the WebView.

get_background_color() → 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 set_background_color()

Added in version 2.8.

get_camera_capture_state() → MediaCaptureState#: Get the camera capture state of a WebView.

Added in version 2.34.

get_context() → WebContext#: Gets the web context of web_view.

get_custom_charset() → str#: Returns the current custom character encoding name of web_view.

get_default_content_security_policy() → str | None#: Gets the configured default Content-Security-Policy.

Added in version 2.38.

get_display_capture_state() → MediaCaptureState#: Get the display capture state of a WebView.

Added in version 2.34.

get_editor_state() → EditorState#: Gets the web editor state of web_view.

Added in version 2.10.

get_estimated_load_progress() → float#

Gets the value of the 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.

get_favicon() → 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.

get_find_controller() → FindController#

Gets the FindController.

Gets the FindController that will allow the caller to query the WebView for the text to look for.

get_input_method_context() → InputMethodContext | None#

Get the InputMethodContext currently in use by web_view.

Get the InputMethodContext currently in use by web_view, or None if no input method is being used.

Added in version 2.28.

get_inspector() → WebInspector#: Get the WebInspector associated to web_view

get_is_muted() → bool#: Gets the mute state of web_view.

Added in version 2.30.

get_is_web_process_responsive() → bool#: Get whether the current web process of a WebView is responsive.

Added in version 2.34.

get_main_resource() → WebResource#: Return the main resource of web_view.

get_microphone_capture_state() → MediaCaptureState#: Get the microphone capture state of a WebView.

Added in version 2.34.

get_network_session() → NetworkSession#: Get the NetworkSession associated to web_view.

Added in version 2.40.

get_page_id() → int#: Get the identifier of the WebKitWebPage corresponding to the WebView

get_session_state() → WebViewSessionState#: Gets the current session state of web_view

Added in version 2.12.

get_settings() → Settings#

Gets the Settings currently applied to web_view.

If no other Settings have been explicitly applied to web_view with set_settings(), the default Settings will be returned. This method always returns a valid Settings object. To modify any of the web_view settings, you can either create a new Settings object with new(), setting the desired preferences, and then replace the existing web_view settings with set_settings() or get the existing web_view settings and update it directly. Settings objects can be shared by multiple WebView<!– –>s, so modifying the settings of a WebView would affect other WebView<!– –>s using the same Settings.

async get_snapshot(self, region: SnapshotRegion, options: SnapshotOptions) → Texture#

This is the awaitable version of get_snapshot().

Parameters:

region – the SnapshotRegion for this snapshot
options – SnapshotOptions for the snapshot

get_snapshot(region: SnapshotRegion, options: SnapshotOptions, cancellable: Cancellable | None = None, callback: Callable[[Object | None, AsyncResult, Any], None] | None = None, user_data: Any = None) → 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 get_snapshot_finish() to get the result of the operation.

Parameters:

region – the SnapshotRegion for this snapshot
options – SnapshotOptions for the snapshot
cancellable – a Cancellable
callback – a AsyncReadyCallback
user_data – user data

get_snapshot_finish(result: AsyncResult) → Texture#

Finishes an asynchronous operation started with get_snapshot(), producing an image of the snapshot using the BGRA8888 pixel format.

Parameters:: result – a AsyncResult

get_theme_color() → tuple[bool, RGBA]#: Gets the theme color that is specified by the content in the web_view. If the web_view doesn’t have a theme color it will fill the rgba with transparent black content.

Added in version 2.50.

get_title() → str#

Gets the value of the WebView:title property.

You can connect to notify::title signal of web_view to be notified when the title has been received.

get_tls_info() → tuple[bool, TlsCertificate, TlsCertificateFlags]#

Retrieves the TlsCertificate associated with the main resource of web_view.

Retrieves the TlsCertificate associated with the main resource of web_view, and the TlsCertificateFlags showing what problems, if any, have been found with that certificate. If the connection is not HTTPS, this function returns False. This function should be called after a response has been received from the server, so you can connect to WebView::load-changed and call this function when it’s emitted with COMMITTED event.

Note that this function provides no information about the security of the web page if the current TLSErrorsPolicy is 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 TLSErrorsPolicy is FAIL, in which case subresources that fail certificate verification will be blocked.

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 None.

</para></listitem> <listitem><para>

When a new load operation starts the active URI is the requested URI: <itemizedlist> <listitem><para>

If the load operation was started by load_uri(), the requested URI is the given one.

</para></listitem> <listitem><para>

If the load operation was started by load_html(), the requested URI is “about:blank”.

</para></listitem> <listitem><para>

If the load operation was started by load_alternate_html(), the requested URI is content URI provided.

</para></listitem> <listitem><para>

If the load operation was started by go_back() or go_forward(), the requested URI is the original URI of the previous/next item in the BackForwardList of web_view.

</para></listitem> <listitem><para>

If the load operation was started by go_to_back_forward_list_item(), the requested URI is the opriginal URI of the given BackForwardListItem.

</para></listitem> </itemizedlist>

</para></listitem> <listitem><para>

If there is a server redirection during the load operation, the active URI is the redirected URI. When the signal WebView::load-changed is emitted with REDIRECTED event, the active URI is already updated to the redirected URI.

</para></listitem> <listitem><para>

When the signal WebView::load-changed is emitted with 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.

</para></listitem> </orderedlist>

You can monitor the active URI by connecting to the notify::uri signal of web_view.

get_user_content_manager() → UserContentManager#: Gets the user content manager associated to web_view.

Added in version 2.6.

get_web_extension_mode() → WebExtensionMode#: Get the view’s WebExtensionMode.

Added in version 2.38.

get_website_policies() → 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 WebView::decide-policy signal handler.

Properties#

class WebView

props.automation_presentation_type: AutomationBrowsingContextPresentation#: The AutomationBrowsingContextPresentation of WebView. This should only be used when creating a new WebView as a response to AutomationSession::create-web-view signal request. If the new WebView was added to a new tab of current browsing context window TAB should be used.

Added in version 2.28.

props.camera_capture_state: 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 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 NONE or MUTED.

If the capture state of the device is set to NONE the web-page can still re-request the permission to the user. Permission desision caching is left to the application.

Added in version 2.34.

props.default_content_security_policy: 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 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.

Added in version 2.38.

props.display_capture_state: 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 NONE or MUTED.

If the capture state of the device is set to NONE the web-page can still re-request the permission to the user. Permission desision caching is left to the application.

Added in version 2.34.

props.editable: bool#: Whether the pages loaded inside WebView are editable. For more information see set_editable().

Added in version 2.8.

props.estimated_load_progress: 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.

props.favicon: Texture#: The favicon currently associated to the WebView. See get_favicon() for more details.

props.is_controlled_by_automation: bool#

Whether the WebView is controlled by automation tools (e.g. WebDriver, Selenium). This is required for views returned as a response to AutomationSession::create-web-view signal, alongside any view you want to control during an automation session.

As a %G_PARAM_CONSTRUCT_ONLY, you need to set it during construction and it can’t be modified.

If WebView:related-view is also passed during construction, WebView:is-controlled-by-automation ignores its own parameter and inherits directly from the related view WebView:is-controlled-by-automation property. This is the recommended way when creating new views as a response to the WebView::create signal. For example, as response to JavaScript window.open() calls during an automation session.

Added in version 2.18.

props.is_immersive_mode_enabled: bool#: Whether the WebView is in immersive mode.

Added in version 2.52.

props.is_loading: bool#: Whether the WebView is currently loading a page. This property becomes True as soon as a new load operation is requested and before the WebView::load-changed signal is emitted with STARTED and at that point the active URI is the requested one. When the load operation finishes the property is set to False before WebView::load-changed is emitted with FINISHED.

props.is_muted: bool#: Whether the WebView audio is muted. When True, audio is silenced. It may still be playing, i.e. WebView:is-playing-audio may be True.

Added in version 2.30.

props.is_playing_audio: bool#: Whether the WebView is currently playing audio from a page. This property becomes 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 False.

Added in version 2.8.

props.is_web_process_responsive: bool#: Whether the web process currently associated to the WebView is responsive.

Added in version 2.34.

props.microphone_capture_state: 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 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 NONE or MUTED.

If the capture state of the device is set to NONE the web-page can still re-request the permission to the user. Permission desision caching is left to the application.

Added in version 2.34.

props.network_session: NetworkSession#: The NetworkSession of the view

Added in version 2.40.

props.page_id: int#: The identifier of the WebKitWebPage corresponding to the WebView.

Added in version 2.28.

props.related_view: WebView#: The related 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.

Added in version 2.4.

props.settings: Settings#: The Settings of the view.

Added in version 2.6.

props.theme_color: RGBA#: The theme color of the WebView’s current page.

Added in version 2.50.

props.title: str#: The main frame document title of this WebView. If the title has not been received yet, it will be None.

props.uri: str#: The current active URI of the WebView. See get_uri() for more details.

props.user_content_manager: UserContentManager#: The UserContentManager of the view.

Added in version 2.6.

props.web_context: WebContext#: The WebContext of the view.

props.web_extension_mode: 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.

Added in version 2.38.

props.website_policies: WebsitePolicies#: The WebsitePolicies for the view.

Added in version 2.30.

props.zoom_level: float#: The zoom level of the WebView content. See set_zoom_level() for more details.

Signals#

class WebView.signals

authenticate(request: 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 AuthenticationRequest in the request argument. To handle this signal asynchronously you should keep a ref of the request and return True. To disable HTTP authentication entirely, connect to this signal and simply return True.

The default signal handler will run a default authentication dialog asynchronously for the user to interact with.

Added in version 2.2.

Parameters:: request – a AuthenticationRequest

close() → None#: Emitted when closing a WebView is requested. This occurs when a call is made from JavaScript’s <function>window.close</function> function or after trying to close the web_view with try_close(). It is the owner’s responsibility to handle this signal to hide or destroy the WebView, if necessary.

context_menu(context_menu: ContextMenu, hit_test_result: 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. <itemizedlist> <listitem><para>

To customize the proposed menu you can use prepend(), append() or insert() to add new ContextMenuItem<!– –>s to context_menu, move_item() to reorder existing items, or remove() to remove an existing item. The signal handler should return False, and the menu represented by context_menu will be shown.

</para></listitem> <listitem><para>

To prevent the menu from being displayed you can just connect to this signal and return True so that the proposed menu will not be shown.

</para></listitem> <listitem><para>

To build your own menu, you can remove all items from the proposed menu with remove_all(), add your own items and return False so that the menu will be shown. You can also ignore the proposed ContextMenu, build your own GtkMenu and return True to prevent the proposed menu from being shown.

</para></listitem> <listitem><para>

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.

</para></listitem> </itemizedlist>

If the signal handler returns False the context menu represented by context_menu will be shown, if it return True the context menu will not be shown.

The proposed ContextMenu passed in context_menu argument is only valid during the signal emission.

Parameters:

context_menu – the proposed ContextMenu
hit_test_result – a HitTestResult

context_menu_dismissed() → None#: Emitted after WebView::context-menu signal, if the context menu is shown, to notify that the context menu is dismissed.

create(navigation_action: NavigationAction) → Widget#

Emitted when the creation of a new WebView is requested. If this signal is handled the signal handler should return the newly created WebView.

The NavigationAction parameter contains information about the navigation action that triggered this signal.

The new WebView must be related to web_view, see WebView:related-view for more details.

The new WebView should not be displayed to the user until the WebView::ready-to-show signal is emitted.

For creating views as response to automation tools requests, see the AutomationSession::create-web-view signal.

Parameters:: navigation_action – a NavigationAction

decide_policy(decision: PolicyDecision, decision_type: 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 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:

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 webkit_policy_decision_use()
        return FALSE;
    }
    return TRUE;
}

It is possible to make policy decision asynchronously, by simply calling ref() on the decision argument and returning True to block the default signal handler. If the last reference is removed on a PolicyDecision and no decision has been made explicitly, use() will be the default policy decision. The default signal handler will simply call use(). Only the first policy decision chosen for a given PolicyDecision will have any affect.

Parameters:

decision – the PolicyDecision
decision_type – a PolicyDecisionType denoting the type of decision

enter_fullscreen() → bool#: Emitted when JavaScript code calls <function>element.webkitRequestFullScreen</function>. If the signal is not handled the 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).

insecure_content_detected(event: InsecureContentEvent) → None#

Prior to 2.46, this signal was emitted when insecure content was loaded in a secure content. Since 2.46, this signal is generally no longer emitted.

Deprecated since version 2.46: Please do not use it in newly written code

Parameters:: event – the InsecureContentEvent

leave_fullscreen() → bool#: Emitted when the 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 WebView::enter-fullscreen stage for instance.

load_changed(load_event: LoadEvent) → None#

Emitted when a load operation in web_view changes. The signal is always emitted with STARTED when a new load request is made and FINISHED when the load finishes successfully or due to an error. When the ongoing load operation fails WebView::load-failed signal is emitted before WebView::load-changed is emitted with FINISHED. If a redirection is received from the server, this signal is emitted with REDIRECTED after the initial emission with STARTED and before COMMITTED. When the page content starts arriving the signal is emitted with COMMITTED event.

You can handle this signal and use a switch to track any ongoing load operation.

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;
    }
}

Parameters:: load_event – the LoadEvent

load_failed(load_event: LoadEvent, failing_uri: str, error: 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 STARTED. If it happened while loading a committed data source load_event will be COMMITTED. Since a load error causes the load operation to finish, the signal WebKitWebView::load-changed will always be emitted with 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.

Parameters:

load_event – the LoadEvent of the load operation
failing_uri – the URI that failed to load
error – the Error that was triggered

load_failed_with_tls_errors(failing_uri: str, certificate: TlsCertificate, errors: 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 ref() on certificate and return True.

If False is returned, WebView::load-failed will be emitted. The load will finish regardless of the returned value.

Added in version 2.6.

Parameters:

failing_uri – the URI that failed to load
certificate – a TlsCertificate
errors – a TlsCertificateFlags with the verification status of certificate

mouse_target_changed(hit_test_result: 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 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.

Parameters:

hit_test_result – a HitTestResult
modifiers – a bitmask of ModifierType

permission_request(request: 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:

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 ref() on the request argument and returning True to block the default signal handler. If the last reference is removed on a PermissionRequest and the request has not been handled, deny() will be the default action.

If the signal is not handled, the request will be completed automatically by the specific PermissionRequest that could allow or deny it. Check the documentation of classes implementing PermissionRequest interface to know their default action.

Parameters:: request – the PermissionRequest

print_(print_operation: PrintOperation) → bool#

Parameters:: print_operation

query_permission_state(query: 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 finish().

You can handle the query asynchronously by calling ref() on query and returning 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.

Added in version 2.40.

Parameters:: query – the PermissionStateQuery

ready_to_show() → None#: Emitted after WebView::create on the newly created 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 WindowProperties of web_view. See also get_window_properties().

resource_load_started(resource: WebResource, request: URIRequest) → None#

Emitted when a new resource is going to be loaded. The request parameter contains the URIRequest that will be sent to the server. You can monitor the load operation by connecting to the different signals of resource.

Parameters:

resource – a WebResource
request – a URIRequest

run_as_modal() → None#: Emitted after WebView::ready-to-show on the newly created WebView when JavaScript code calls <function>window.showModalDialog</function>. 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 WebView until the new dialog is closed.

run_color_chooser(request: ColorChooserRequest) → bool#

This signal is emitted when the user interacts with a <input type=’color’ /> 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 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 ColorChooser for the user to interact with.

Added in version 2.8.

Parameters:: request – a ColorChooserRequest

run_file_chooser(request: FileChooserRequest) → bool#

This signal is emitted when the user interacts with a <input type=’file’ /> 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 FileChooserRequest in the request argument.

The default signal handler will asynchronously run a regular GtkFileChooserDialog for the user to interact with.

Parameters:: request – a FileChooserRequest

script_dialog(dialog: ScriptDialog) → bool#

Emitted when JavaScript code calls <function>window.alert</function>, <function>window.confirm</function> or <function>window.prompt</function>, or when <function>onbeforeunload</function> 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: <itemizedlist> <listitem><para>

ALERT: message dialog with a single Close button.

</para></listitem> <listitem><para>

CONFIRM: message dialog with OK and Cancel buttons.

</para></listitem> <listitem><para>

PROMPT: message dialog with OK and Cancel buttons and a text entry with the default text.

</para></listitem> <listitem><para>

BEFORE_UNLOAD_CONFIRM: message dialog with Stay and Leave buttons.

</para></listitem> </itemizedlist>

It is possible to handle the script dialog request asynchronously, by simply caling ref() on the dialog argument and calling close() when done. If the last reference is removed on a ScriptDialog and the dialog has not been closed, close() will be called.

Parameters:: dialog – the ScriptDialog to show

show_notification(notification: 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.

Added in version 2.8.

Parameters:: notification – a Notification

show_option_menu(menu: OptionMenu, rectangle: 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 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.

Added in version 2.18.

Parameters:

menu – the OptionMenu
rectangle – the option element area

submit_form(request: 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 submit() is called.

It is possible to handle the form submission request asynchronously, by simply calling ref() on the request argument and calling submit() when done to continue with the form submission. If the last reference is removed on a FormSubmissionRequest and the form has not been submitted, submit() will be called.

Parameters:: request – a FormSubmissionRequest

user_message_received(message: UserMessage) → bool#

This signal is emitted when a UserMessage is received from the WebKitWebPage corresponding to web_view. You can reply to the message using send_reply().

You can handle the user message asynchronously by calling ref() on message and returning 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 MESSAGE.

Added in version 2.28.

Parameters:: message – the UserMessage received

web_process_terminated(reason: WebProcessTerminationReason) → None#

This signal is emitted when the web process terminates abnormally due to reason.

Added in version 2.20.

Parameters:: reason – the a WebProcessTerminationReason

Virtual Methods#

class WebView

do_authenticate(request: AuthenticationRequest) → bool#

Parameters:: request

do_close() → None#

do_context_menu(context_menu: ContextMenu, hit_test_result: HitTestResult) → bool#

Parameters:

context_menu
hit_test_result

do_context_menu_dismissed() → None#

do_decide_policy(decision: PolicyDecision, type: PolicyDecisionType) → bool#

Parameters:

decision
type

do_enter_fullscreen() → bool#

do_insecure_content_detected(event: InsecureContentEvent) → None#

Parameters:: event

do_leave_fullscreen() → bool#

do_load_changed(load_event: LoadEvent) → None#

Parameters:: load_event

do_load_failed(load_event: LoadEvent, failing_uri: str, error: GError) → bool#

Parameters:

load_event
failing_uri
error

do_load_failed_with_tls_errors(failing_uri: str, certificate: TlsCertificate, errors: TlsCertificateFlags) → bool#

Parameters:

failing_uri
certificate
errors

do_mouse_target_changed(hit_test_result: HitTestResult, modifiers: int) → None#

Parameters:

hit_test_result
modifiers

do_permission_request(permission_request: PermissionRequest) → bool#

Parameters:: permission_request

do_print_(print_operation: PrintOperation) → bool#

Parameters:: print_operation

do_query_permission_state(query: PermissionStateQuery) → bool#

Parameters:: query

do_ready_to_show() → None#

do_resource_load_started(resource: WebResource, request: URIRequest) → None#

Parameters:

resource
request

do_run_as_modal() → None#

do_run_color_chooser(request: ColorChooserRequest) → bool#

Parameters:: request

do_run_file_chooser(request: FileChooserRequest) → bool#

Parameters:: request

do_script_dialog(dialog: ScriptDialog) → bool#

Parameters:: dialog

do_show_notification(notification: Notification) → bool#

Parameters:: notification

do_show_option_menu(menu: OptionMenu, rectangle: Rectangle) → bool#

Parameters:

menu
rectangle

do_submit_form(request: FormSubmissionRequest) → None#

Parameters:: request

do_user_message_received(message: UserMessage) → bool#

Parameters:: message

do_web_process_crashed() → bool#

do_web_process_terminated(reason: WebProcessTerminationReason) → None#

Parameters:: reason

Fields#

class WebView

parent_instance#

priv#