WebView
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 defaultWebContext
.Creates a new
WebView
with the defaultWebContext
and noUserContentManager
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
- 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[[...], None] | None = None, *user_data: Any) None
Asynchronously call
body
witharguments
in the script world with nameworld_name
of the main frame current context inweb_view
. Thearguments
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. Ifworld_name
isNone
, the default world is used. Any value that is notNone
is a distin ct world. Thesource_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 isFalse
, this method will do nothing. If you want to use this method but still prevent web content from executing its own JavaScript, then useSettings
:enable-javascript-markup.When the operation is finished,
callback
will be called. You can then callcall_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 ifbody
is a nul-terminated stringarguments – a
Variant
with formata{sv}
storing the function arguments, orNone
world_name – the name of a
WebKitScriptWorld
orNone
to use the defaultsource_uri – the source URI
cancellable – a
Cancellable
orNone
to ignorecallback – a
AsyncReadyCallback
to call when the script finisheduser_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
- can_execute_editing_command(command: str, cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: 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 callcan_execute_editing_command_finish()
to get the result of the operation.- Parameters:
command – the command to check
cancellable – a
Cancellable
orNone
to ignorecallback – a
AsyncReadyCallback
to call when the request is satisfieduser_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_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
- download_uri(uri: str) Download
Requests downloading of the specified URI string for
web_view
.- Parameters:
uri – the URI to download
- evaluate_javascript(script: str, length: int, world_name: str | None = None, source_uri: str | None = None, cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) None
Asynchronously evaluate
script
in the script world with nameworld_name
of the main frame current context inweb_view
. Ifworld_name
isNone
, the default world is used. Any value that is notNone
is a distinct world. Thesource_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 isFalse
, this method will do nothing. If you want to use this method but still prevent web content from executing its own JavaScript, then useSettings
:enable-javascript-markup.When the operation is finished,
callback
will be called. You can then callevaluate_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 ifscript
is a nul-terminated stringworld_name – the name of a
WebKitScriptWorld
orNone
to use the defaultsource_uri – the source URI
cancellable – a
Cancellable
orNone
to ignorecallback – a
AsyncReadyCallback
to call when the script finisheduser_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
forweb_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
withargument
forweb_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 givenWebView
.The
BackForwardList
is owned by theWebView
.
- 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 alsoset_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_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 ofweb_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 theWebView
for the text to look for.
- get_input_method_context() InputMethodContext | None
Get the
InputMethodContext
currently in use byweb_view
.Get the
InputMethodContext
currently in use byweb_view
, orNone
if no input method is being used.Added in version 2.28.
- get_inspector() WebInspector
Get the
WebInspector
associated toweb_view
- 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 toweb_view
.Added in version 2.40.
- 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 toweb_view
.If no other
Settings
have been explicitly applied toweb_view
withset_settings()
, the defaultSettings
will be returned. This method always returns a validSettings
object. To modify any of theweb_view
settings, you can either create a newSettings
object withnew()
, setting the desired preferences, and then replace the existingweb_view
settings withset_settings()
or get the existingweb_view
settings and update it directly.Settings
objects can be shared by multipleWebView
would affect otherSettings
.
- get_snapshot(region: SnapshotRegion, options: SnapshotOptions, cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) None
Asynchronously retrieves a snapshot of
web_view
forregion
.options
specifies how the snapshot should be rendered.When the operation is finished,
callback
will be called. You must callget_snapshot_finish()
to get the result of the operation.- Parameters:
region – the
SnapshotRegion
for this snapshotoptions –
SnapshotOptions
for the snapshotcancellable – a
Cancellable
callback – a
AsyncReadyCallback
user_data – user data
- get_snapshot_finish(result: AsyncResult) Texture
Finishes an asynchronous operation started with
get_snapshot()
.- Parameters:
result – a
AsyncResult
- 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 ofweb_view
.Retrieves the
TlsCertificate
associated with the main resource ofweb_view
, and theTlsCertificateFlags
showing what problems, if any, have been found with that certificate. If the connection is not HTTPS, this function returnsFalse
. This function should be called after a response has been received from the server, so you can connect toWebView
::load-changed and call this function when it’s emitted withCOMMITTED
event.Note that this function provides no information about the security of the web page if the current
TLSErrorsPolicy
isIGNORE
, 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 currentTLSErrorsPolicy
isFAIL
, 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:
<orderedlist> <listitem><para>
When nothing has been loaded yet on
web_view
the active URI isNone
.</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()
orgo_forward()
, the requested URI is the original URI of the previous/next item in theBackForwardList
ofweb_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 givenBackForwardListItem
.</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 withREDIRECTED
event, the active URI is already updated to the redirected URI.</para></listitem> <listitem><para>
</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 theWebView
::decide-policy signal handler.See also
use_with_policies()
.Added in version 2.30.
- get_window_properties() WindowProperties
Get the
WindowProperties
object.Get the
WindowProperties
object containing the properties that the window containingweb_view
should have.
- 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.
- go_back() None
Loads the previous history item.
You can monitor the load operation by connecting to
WebView
::load-changed signal.
- go_forward() None
Loads the next history item.
You can monitor the load operation by connecting to
WebView
::load-changed signal.
- go_to_back_forward_list_item(list_item: BackForwardListItem) None
Loads the specific history item
list_item
.You can monitor the load operation by connecting to
WebView
::load-changed signal.- Parameters:
list_item – a
BackForwardListItem
- is_controlled_by_automation() bool
Get whether a
WebView
was created withWebView
:is-controlled-by-automation property enabled.Only :obj:`~gi.repository.WebKit.WebView`<!– –>s controlled by automation can be used in an automation session.
Added in version 2.18.
- 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 aWebView
is not editable.Added in version 2.8.
- is_loading() bool
Gets the value of the
WebView
:is-loading property.You can monitor when a
WebView
is loading a page by connecting to notify::is-loading signal ofweb_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.
- is_playing_audio() bool
Gets the value of the
WebView
:is-playing-audio property.You can monitor when a page in a
WebView
is playing audio by connecting to the notify::is-playing-audio signal ofweb_view
. This is useful when the application wants to provide visual feedback when a page is producing sound.Added in version 2.8.
- load_alternate_html(content: str, content_uri: str, base_uri: str | None = None) None
Load the given
content
string for the URIcontent_uri
.This allows clients to display page-loading errors in the
WebView
itself. When this method is called fromWebView
::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 asload_html()
.- Parameters:
content – the new content to display as the main page of the
web_view
content_uri – the URI for the alternate page content
base_uri – the base URI for relative locations or
None
- load_bytes(bytes: Bytes, mime_type: str | None = None, encoding: str | None = None, base_uri: str | None = None) None
Load the specified
bytes
intoweb_view
using the givenmime_type
andencoding
.When
mime_type
isNone
, it defaults to “text/html”. Whenencoding
isNone
, it defaults to “UTF-8”. Whenbase_uri
isNone
, it defaults to “about:blank”. You can monitor the load operation by connecting toWebView
::load-changed signal.Added in version 2.6.
- Parameters:
bytes – input data to load
mime_type – the MIME type of
bytes
, orNone
encoding – the character encoding of
bytes
, orNone
base_uri – the base URI for relative locations or
None
- load_html(content: str, base_uri: str | None = None) None
Load the given
content
string with the specifiedbase_uri
.If
base_uri
is notNone
, relative URLs in thecontent
will be resolved againstbase_uri
and absolute local paths must be children of thebase_uri
. For security reasons absolute local paths that are not children ofbase_uri
will cause the web process to terminate. If you need to include URLs incontent
that are local paths in a different directory thanbase_uri
you can build a data URI for them. Whenbase_uri
isNone
, it defaults to “about:blank”. The mime type of the document will be “text/html”. You can monitor the load operation by connecting toWebView
::load-changed signal.- Parameters:
content – The HTML string to load
base_uri – The base URI for relative locations or
None
- load_plain_text(plain_text: str) None
Load the specified
plain_text
string intoweb_view
.The mime type of document will be “text/plain”. You can monitor the load operation by connecting to
WebView
::load-changed signal.- Parameters:
plain_text – The plain text to load
- load_request(request: URIRequest) None
Requests loading of the specified
URIRequest
.You can monitor the load operation by connecting to
WebView
::load-changed signal.- Parameters:
request – a
URIRequest
to load
- load_uri(uri: str) None
Requests loading of the specified URI string.
You can monitor the load operation by connecting to
WebView
::load-changed signal.- Parameters:
uri – an URI string
- reload() None
Reloads the current contents of
web_view
.See also
reload_bypass_cache()
.
- reload_bypass_cache() None
Reloads the current contents of
web_view
without using any cached data.
- restore_session_state(state: WebViewSessionState) None
Restore the
web_view
session state fromstate
Added in version 2.12.
- Parameters:
state – a
WebViewSessionState
- save(save_mode: SaveMode, cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) None
Asynchronously save the current web page.
Asynchronously save the current web page associated to the
WebView
into a self-contained format using the mode specified insave_mode
.When the operation is finished,
callback
will be called. You can then callsave_finish()
to get the result of the operation.- Parameters:
save_mode – the
SaveMode
specifying how the web page should be saved.cancellable – a
Cancellable
orNone
to ignorecallback – a
AsyncReadyCallback
to call when the request is satisfieduser_data – the data to pass to callback function
- save_finish(result: AsyncResult) InputStream
Finish an asynchronous operation started with
save()
.- Parameters:
result – a
AsyncResult
- save_to_file(file: File, save_mode: SaveMode, cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) None
Asynchronously save the current web page.
Asynchronously save the current web page associated to the
WebView
into a self-contained format using the mode specified insave_mode
and writing it tofile
.When the operation is finished,
callback
will be called. You can then callsave_to_file_finish()
to get the result of the operation.- Parameters:
file – the
File
where the current web page should be saved to.save_mode – the
SaveMode
specifying how the web page should be saved.cancellable – a
Cancellable
orNone
to ignorecallback – a
AsyncReadyCallback
to call when the request is satisfieduser_data – the data to pass to callback function
- save_to_file_finish(result: AsyncResult) bool
Finish an asynchronous operation started with
save_to_file()
.- Parameters:
result – a
AsyncResult
- send_message_to_page(message: UserMessage, cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) None
Send
message
to theWebKitWebPage
corresponding toweb_view
.If
message
is floating, it’s consumed. If you don’t expect any reply, or you simply want to ignore it, you can passNone
ascallback
. When the operation is finished,callback
will be called. You can then callsend_message_to_page_finish()
to get the message reply.Added in version 2.28.
- Parameters:
message – a
UserMessage
cancellable – a
Cancellable
orNone
to ignorecallback – (nullable): A
AsyncReadyCallback
to call when the request is satisfied orNone
user_data – the data to pass to callback function
- send_message_to_page_finish(result: AsyncResult) UserMessage
Finish an asynchronous operation started with
send_message_to_page()
.Added in version 2.28.
- Parameters:
result – a
AsyncResult
- set_background_color(rgba: 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 inweb_view
specifies a background color, it will take precedence over thergba
color. By default theweb_view
background color is opaque white. Note that the parent window must have a RGBA visual andWidget
:app-paintable property set toTrue
for backgrounds colors to work.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); }
Added in version 2.8.
- Parameters:
rgba – a
RGBA
- set_camera_capture_state(state: MediaCaptureState) None
Set the camera capture state of a
WebView
.If
Settings
:enable-mediastream isFalse
, this method will have no visible effect. Once the state of the device has been set toNONE
it cannot be changed anymore. The page can however request capture again using the mediaDevices API.Added in version 2.34.
- Parameters:
state – a
MediaCaptureState
- set_cors_allowlist(allowlist: Sequence[str] | None = None) None
Sets the
allowlist
for CORS.Sets the
allowlist
for which Cross-Origin Resource Sharing checks are disabled inweb_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.
Added in version 2.34.
- Parameters:
allowlist – an allowlist of URI patterns, or
None
- 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
None
removes the character encoding override.- Parameters:
charset – a character encoding name or
None
- set_display_capture_state(state: MediaCaptureState) None
Set the display capture state of a
WebView
.If
Settings
:enable-mediastream isFalse
, this method will have no visible effect. Once the state of the device has been set toNONE
it cannot be changed anymore. The page can however request capture again using the mediaDevices API.Added in version 2.34.
- Parameters:
state – a
MediaCaptureState
- set_editable(editable: bool) None
Sets whether the user is allowed to edit the HTML document.
If
editable
isTrue
,web_view
allows the user to edit the HTML document. Ifeditable
isFalse
, an element inweb_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 aWebView
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
WebView
editable without altering the document or DOM structure.Added in version 2.8.
- Parameters:
editable – a
gboolean
indicating the editable state
- set_input_method_context(context: InputMethodContext | None = None) None
Set the
InputMethodContext
to be used byweb_view
.Set the
InputMethodContext
to be used byweb_view
, orNone
to not use any input method. Note that the sameInputMethodContext
can’t be set on more than oneWebView
at the same time.Added in version 2.28.
- Parameters:
context – the
InputMethodContext
to set, orNone
- set_is_muted(muted: bool) None
Sets the mute state of
web_view
.Added in version 2.30.
- Parameters:
muted – mute flag
- set_microphone_capture_state(state: MediaCaptureState) None
Set the microphone capture state of a
WebView
.If
Settings
:enable-mediastream isFalse
, this method will have no visible effect. Once the state of the device has been set toNONE
it cannot be changed anymore. The page can however request capture again using the mediaDevices API.Added in version 2.34.
- Parameters:
state – a
MediaCaptureState
- set_settings(settings: Settings) None
Sets the
Settings
to be applied toweb_view
.The existing
Settings
ofweb_view
will be replaced bysettings
. New settings are applied immediately onweb_view
. The sameSettings
object can be shared by multiple :obj:`~gi.repository.WebKit.WebView`<!– –>s.- Parameters:
settings – a
Settings
- 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.- Parameters:
zoom_level – the zoom level
- 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
WebView
::load-failed signal will be emitted withCANCELLED
error.
- terminate_web_process() None
Terminates the web process associated to
web_view
.When the web process gets terminated using this method, the
WebView
::web-process-terminated signal is emitted withTERMINATED_BY_API
as the reason for termination.Added in version 2.34.
- 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
WebView
::close signal is emitted, otherwise nothing happens.Added in version 2.12.
Properties
- class WebView
- props.automation_presentation_type: AutomationBrowsingContextPresentation
The
AutomationBrowsingContextPresentation
ofWebView
. This should only be used when creating a newWebView
as a response toAutomationSession
::create-web-view signal request. If the new WebView was added to a new tab of current browsing context windowTAB
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 toACTIVE
.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
orMUTED
.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 asUserContentManager
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
orMUTED
.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 seeset_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
. Seeget_favicon()
for more details.
- props.is_controlled_by_automation: bool
Whether the
WebView
is controlled by automation. This should only be used when creating a newWebView
as a response toAutomationSession
::create-web-view signal request.Added in version 2.18.
- props.is_loading: bool
Whether the
WebView
is currently loading a page. This property becomesTrue
as soon as a new load operation is requested and before theWebView
::load-changed signal is emitted withSTARTED
and at that point the active URI is the requested one. When the load operation finishes the property is set toFalse
beforeWebView
::load-changed is emitted withFINISHED
.
- props.is_muted: bool
Whether the
WebView
audio is muted. WhenTrue
, audio is silenced. It may still be playing, i.e.WebView
:is-playing-audio may beTrue
.Added in version 2.30.
- props.is_playing_audio: bool
Whether the
WebView
is currently playing audio from a page. This property becomesTrue
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 toFalse
.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 toACTIVE
.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
orMUTED
.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 viewAdded in version 2.40.
- props.page_id: int
The identifier of the
WebKitWebPage
corresponding to theWebView
.Added in version 2.28.
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.title: str
The main frame document title of this
WebView
. If the title has not been received yet, it will beNone
.
- 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 <https://developer.chrome.com/docs/extensions/mv3/intro/mv3-migration/``content`
-security-policy>`_.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. Seeset_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 therequest
argument. To handle this signal asynchronously you should keep a ref of the request and returnTrue
. To disable HTTP authentication entirely, connect to this signal and simply returnTrue
.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 theweb_view
withtry_close()
. It is the owner’s responsibility to handle this signal to hide or destroy theWebView
, if necessary.
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()
orinsert()
to add newContextMenuItem`<!-- -->s to ``context_menu`
,move_item()
to reorder existing items, orremove()
to remove an existing item. The signal handler should returnFalse
, and the menu represented bycontext_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 returnFalse
so that the menu will be shown. You can also ignore the proposedContextMenu
, build your ownGtkMenu
and returnTrue
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 bycontext_menu
will be shown, if it returnTrue
the context menu will not be shown.The proposed
ContextMenu
passed incontext_menu
argument is only valid during the signal emission.- Parameters:
context_menu – the proposed
ContextMenu
hit_test_result – a
HitTestResult
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 createdWebView
.The
NavigationAction
parameter contains information about the navigation action that triggered this signal.The new
WebView
must be related toweb_view
, seeWebView
:related-view for more details.The new
WebView
should not be displayed to the user until theWebView
::ready-to-show signal is emitted.- 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 thedecision
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 :func:`~gi.repository.WebKit.PolicyDecision.use` return FALSE; } return TRUE; }
It is possible to make policy decision asynchronously, by simply calling
ref()
on thedecision
argument and returningTrue
to block the default signal handler. If the last reference is removed on aPolicyDecision
and no decision has been made explicitly,use()
will be the default policy decision. The default signal handler will simply calluse()
. Only the first policy decision chosen for a givenPolicyDecision
will have any affect.- Parameters:
decision – the
PolicyDecision
decision_type – a
PolicyDecisionType
denoting the type ofdecision
- 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
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 (seeInsecureContentEvent
).- 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 theWebView
::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 withSTARTED
when a new load request is made andFINISHED
when the load finishes successfully or due to an error. When the ongoing load operation failsWebView
::load-failed signal is emitted beforeWebView
::load-changed is emitted withFINISHED
. If a redirection is received from the server, this signal is emitted withREDIRECTED
after the initial emission withSTARTED
and beforeCOMMITTED
. When the page content starts arriving the signal is emitted withCOMMITTED
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 beSTARTED
. If it happened while loading a committed data sourceload_event
will beCOMMITTED
. Since a load error causes the load operation to finish, the signal WebKitWebView::load-changed will always be emitted withFINISHED
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.
- 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 offailing_uri
use webkit_web_context_allow_tls_certificate_for_host().To handle this signal asynchronously you should call
ref()
oncertificate
and returnTrue
.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 ofcertificate
- 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. Themodifiers
argument is a bitmask ofModifierType
flags indicating the state of modifier keys. The signal is emitted again when the mouse is moved out of the current element with a newhit_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 therequest
argument and returningTrue
to block the default signal handler. If the last reference is removed on aPermissionRequest
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 specificPermissionRequest
that could allow or deny it. Check the documentation of classes implementingPermissionRequest
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()
onquery
and returningTrue
. If the last reference ofquery
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 createdWebView
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 theWindowProperties
ofweb_view
. See alsoget_window_properties()
.
- resource_load_started(resource: WebResource, request: URIRequest) None
Emitted when a new resource is going to be loaded. The
request
parameter contains theURIRequest
that will be sent to the server. You can monitor the load operation by connecting to the different signals ofresource
.- Parameters:
resource – a
WebResource
request – a
URIRequest
- run_as_modal() None
Emitted after
WebView
::ready-to-show on the newly createdWebView
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 parentWebView
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 therequest
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 therequest
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 thedialog
argument and callingclose()
when done. If the last reference is removed on aScriptDialog
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
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, usingmenu
to get the details of all items that should be displayed. The area of the element in theWebView
is given asrectangle
parameter, it can be used to position the menu. To handle this signal asynchronously you should keep a ref of themenu
.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 untilsubmit()
is called.It is possible to handle the form submission request asynchronously, by simply calling
ref()
on therequest
argument and callingsubmit()
when done to continue with the form submission. If the last reference is removed on aFormSubmissionRequest
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 theWebKitWebPage
corresponding toweb_view
. You can reply to the message usingsend_reply()
.You can handle the user message asynchronously by calling
ref()
onmessage
and returningTrue
. If the last reference ofmessage
is removed and the message has not been replied to, the operation in theWebKitWebPage
will finish with errorMESSAGE
.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
- Parameters:
context_menu
hit_test_result
- do_decide_policy(decision: PolicyDecision, type: PolicyDecisionType) bool
- Parameters:
decision
type
- do_insecure_content_detected(event: InsecureContentEvent) None
- Parameters:
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_resource_load_started(resource: WebResource, request: URIRequest) None
- Parameters:
resource
request
- 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
- Parameters:
menu
rectangle
- do_submit_form(request: FormSubmissionRequest) None
- Parameters:
request
- do_user_message_received(message: UserMessage) bool
- Parameters:
message
- do_web_process_terminated(reason: WebProcessTerminationReason) None
- Parameters:
reason