Struct wry::webview::WebViewBuilder
source · pub struct WebViewBuilder<'a> {
pub webview: WebViewAttributes,
/* private fields */
}
Expand description
Builder type of WebView
.
WebViewBuilder
/ WebView
are the basic building blocks to construct WebView contents and
scripts for those who prefer to control fine grained window creation and event handling.
WebViewBuilder
provides ability to setup initialization before web engine starts.
Fields§
§webview: WebViewAttributes
Implementations§
source§impl<'a> WebViewBuilder<'a>
impl<'a> WebViewBuilder<'a>
Indicates whether horizontal swipe gestures trigger backward and forward page navigation.
Platform-specific
This configuration only impacts macOS. Documentation.
sourcepub fn with_transparent(self, transparent: bool) -> Self
pub fn with_transparent(self, transparent: bool) -> Self
sourcepub fn with_background_color(self, background_color: RGBA) -> Self
pub fn with_background_color(self, background_color: RGBA) -> Self
Specify the webview background color. This will be ignored if transparent
is set to true
.
The color uses the RGBA format.
Platfrom-specific:
- macOS / iOS: Not implemented.
- Windows:
- on Windows 7, transparency is not supported and the alpha value will be ignored.
- on Windows higher than 7: translucent colors are not supported so any alpha value other than
0
will be replaced by255
sourcepub fn with_visible(self, visible: bool) -> Self
pub fn with_visible(self, visible: bool) -> Self
Sets whether the WebView should be transparent.
sourcepub fn with_initialization_script(self, js: &str) -> Self
pub fn with_initialization_script(self, js: &str) -> Self
Initialize javascript code when loading new pages. When webview load a new page, this
initialization code will be executed. It is guaranteed that code is executed before
window.onload
.
Platform-specific
- Android: The Android WebView does not provide an API for initialization scripts, so we prepend them to each HTML head. They are only implemented on custom protocol URLs.
sourcepub fn with_custom_protocol<F>(self, name: String, handler: F) -> Selfwhere
F: Fn(&Request<Vec<u8>>) -> Result<Response<Cow<'static, [u8]>>> + 'static,
pub fn with_custom_protocol<F>(self, name: String, handler: F) -> Selfwhere
F: Fn(&Request<Vec<u8>>) -> Result<Response<Cow<'static, [u8]>>> + 'static,
Register custom file loading protocols with pairs of scheme uri string and a handling closure.
The closure takes a Request and returns a Response
Warning
Pages loaded from custom protocol will have different Origin on different platforms. And
servers which enforce CORS will need to add exact same Origin header in Access-Control-Allow-Origin
if you wish to send requests with native fetch
and XmlHttpRequest
APIs. Here are the
different Origin headers across platforms:
- macOS:
<scheme_name>://<path>
(so it will bewry://examples
incustom_protocol
example) - Linux: Though it’s same as macOS, there’s a bug that Origin header in the request will be
empty. So the only way to pass the server is setting
Access-Control-Allow-Origin: *
. - Windows:
https://<scheme_name>.<path>
(so it will behttps://wry.examples
incustom_protocol
example) - Android: Custom protocol on Android is fixed to
https://tauri.wry/
due to its design and our approach to use it. On Android, We only handle the scheme name and ignore the closure. So when you load the url likewry://assets/index.html
, it will becomehttps://tauri.wry/assets/index.html
. Android hasassets
andresource
path finder to locate your files in those directories. For more information, see Loading in-app content page. - iOS: Same as macOS. To get the path of your assets, you can call
CFBundle::resources_path
. So url likewry://assets/index.html
could get the html file in assets directory.
sourcepub fn with_ipc_handler<F>(self, handler: F) -> Selfwhere
F: Fn(&Window, String) + 'static,
pub fn with_ipc_handler<F>(self, handler: F) -> Selfwhere
F: Fn(&Window, String) + 'static,
Set the IPC handler to receive the message from Javascript on webview to host Rust code.
The message sent from webview should call window.ipc.postMessage("insert_message_here");
.
sourcepub fn with_file_drop_handler<F>(self, handler: F) -> Selfwhere
F: Fn(&Window, FileDropEvent) -> bool + 'static,
pub fn with_file_drop_handler<F>(self, handler: F) -> Selfwhere
F: Fn(&Window, FileDropEvent) -> bool + 'static,
Set a handler closure to process incoming FileDropEvent
of the webview.
Blocking OS Default Behavior
Return true
in the callback to block the OS’ default behavior of handling a file drop.
Note, that if you do block this behavior, it won’t be possible to drop files on <input type="file">
forms.
Also note, that it’s not possible to manually set the value of a <input type="file">
via JavaScript for security reasons.
sourcepub fn with_url_and_headers(self, url: &str, headers: HeaderMap) -> Result<Self>
pub fn with_url_and_headers(self, url: &str, headers: HeaderMap) -> Result<Self>
Load the provided URL with given headers when the builder calling WebViewBuilder::build
to create the
WebView
. The provided URL must be valid.
sourcepub fn with_url(self, url: &str) -> Result<Self>
pub fn with_url(self, url: &str) -> Result<Self>
Load the provided URL when the builder calling WebViewBuilder::build
to create the
WebView
. The provided URL must be valid.
sourcepub fn with_html(self, html: impl Into<String>) -> Result<Self>
pub fn with_html(self, html: impl Into<String>) -> Result<Self>
Load the provided HTML string when the builder calling WebViewBuilder::build
to create the
WebView
. This will be ignored if url
is provided.
Warning
The Page loaded from html string will have different Origin on different platforms. And
servers which enforce CORS will need to add exact same Origin header in Access-Control-Allow-Origin
if you wish to send requests with native fetch
and XmlHttpRequest
APIs. Here are the
different Origin headers across platforms:
- macOS:
http://localhost
- Linux:
http://localhost
- Windows:
null
- Android: Not supported
- iOS: Not supported
PLatform-specific:
- Windows: the string can not be larger than 2 MB (2 * 1024 * 1024 bytes) in total size
sourcepub fn with_web_context(self, web_context: &'a mut WebContext) -> Self
pub fn with_web_context(self, web_context: &'a mut WebContext) -> Self
Set the web context that can share with multiple WebView
s.
sourcepub fn with_user_agent(self, user_agent: &str) -> Self
pub fn with_user_agent(self, user_agent: &str) -> Self
Set a custom user-agent for the WebView.
sourcepub fn with_devtools(self, devtools: bool) -> Self
pub fn with_devtools(self, devtools: bool) -> Self
Enable or disable web inspector which is usually called dev tool.
Note this only enables dev tool to the webview. To open it, you can call
WebView::open_devtools
, or right click the page and open it from the context menu.
Platform-specific
- macOS: This will call private functions on macOS. It’s still enabled if set in debug build on mac,
but requires
devtools
feature flag to actually enable it in release build. - Android: Open
chrome://inspect/#devices
in Chrome to get the devtools window. Wry’sWebView
devtools API isn’t supported on Android. - iOS: Open Safari > Develop > [Your Device Name] > [Your WebView] to get the devtools window.
sourcepub fn with_hotkeys_zoom(self, zoom: bool) -> Self
pub fn with_hotkeys_zoom(self, zoom: bool) -> Self
Whether page zooming by hotkeys or gestures is enabled
Platform-specific
macOS / Linux / Android / iOS: Unsupported
Set a navigation handler to decide if incoming url is allowed to navigate.
The closure takes a String
parameter as url and return bool
to determine the url. True is
allowed to navigate and false is not.
sourcepub fn with_download_started_handler(
self,
started_handler: impl FnMut(String, &mut PathBuf) -> bool + 'static
) -> Self
pub fn with_download_started_handler(
self,
started_handler: impl FnMut(String, &mut PathBuf) -> bool + 'static
) -> Self
Set a download started handler to manage incoming downloads.
The closure takes two parameters - the first is a String
representing the url being downloaded from and and the
second is a mutable PathBuf
reference that (possibly) represents where the file will be downloaded to. The latter
parameter can be used to set the download location by assigning a new path to it - the assigned path must be
absolute. The closure returns a bool
to allow or deny the download.
sourcepub fn with_download_completed_handler(
self,
download_completed_handler: impl Fn(String, Option<PathBuf>, bool) + 'static
) -> Self
pub fn with_download_completed_handler(
self,
download_completed_handler: impl Fn(String, Option<PathBuf>, bool) + 'static
) -> Self
Sets a download completion handler to manage downloads that have finished.
The closure is fired when the download completes, whether it was successful or not.
The closure takes a String
representing the URL of the original download request, an Option<PathBuf>
potentially representing the filesystem path the file was downloaded to, and a bool
indicating if the download
succeeded. A value of None
being passed instead of a PathBuf
does not necessarily indicate that the download
did not succeed, and may instead indicate some other failure - always check the third parameter if you need to
know if the download succeeded.
Platform-specific:
- macOS: The second parameter indicating the path the file was saved to is always empty, due to API limitations.
sourcepub fn with_clipboard(self, clipboard: bool) -> Self
pub fn with_clipboard(self, clipboard: bool) -> Self
Enables clipboard access for the page rendered on Linux and Windows.
macOS doesn’t provide such method and is always enabled by default. But you still need to add menu item accelerators to use shortcuts.
sourcepub fn with_new_window_req_handler(
self,
callback: impl Fn(String) -> bool + 'static
) -> Self
pub fn with_new_window_req_handler(
self,
callback: impl Fn(String) -> bool + 'static
) -> Self
Set a new window request handler to decide if incoming url is allowed to be opened.
The closure takes a String
parameter as url and return bool
to determine if the url can be
opened in a new window. Returning true will open the url in a new window, whilst returning false
will neither open a new window nor allow any navigation.
sourcepub fn with_accept_first_mouse(self, accept_first_mouse: bool) -> Self
pub fn with_accept_first_mouse(self, accept_first_mouse: bool) -> Self
Sets whether clicking an inactive window also clicks through to the webview. Default is false
.
Platform-specific
This configuration only impacts macOS.
sourcepub fn with_document_title_changed_handler(
self,
callback: impl Fn(&Window, String) + 'static
) -> Self
pub fn with_document_title_changed_handler(
self,
callback: impl Fn(&Window, String) + 'static
) -> Self
Set a handler closure to process the change of the webview’s document title.