refactor!: add webview id to protocol handlers and improve API ergonomics

.changes/custom-protocol-label.md

@@ -0,0 +1,28 @@
+---
+"wry": "minor"
+---
+
+This release contains quite the breaking changes, because even though [email protected], ignored duplicate custom protocols, On Linux when using a shared web context, the custom protocol handler can only be registered once so we are bringing the duplicate custom protocols on Linux again, Windows and macOS are not affected. If using a shared web context, make sure to register a protocol only once on Linux (other platforms should be registed multiple times), use `WebContext::is_custom_protocol_registered` with `#[cfg(target_os = "linux")]`.
+
+We also noticed that it is hard to know which webview made a request to the custom protocol so we added a method to attach an ID to a webview, and changed relevant custom protocol APIs to take a new argument that passes the specified id back to protocol handler.
+
+We also made a few changes to the builder, specifically `WebViewBuilder::new` and `WebViewBuilder::build` methods to make them more ergonomic to work with.
+
+- Added `Error::DuplicateCustomProtocol` enum variant.
+- Added `Error::ContextDuplicateCustomProtocol` enum variant.
+- On Linux, return an error in `WebViewBuilder::build` if registering a custom protocol multiple times.
+- Added `WebContext::is_custom_protocol_registered` to check if a protocol has been regsterd for this web context.
+- Added `WebViewId` alias type.
+- **Breaking** Changed `WebViewAttributes` to have a lifetime parameter.
+- Added `WebViewAttributes.id` field to specify an id for the webview.
+- Added `WebViewBuilder::with_id` method to specify an id for the webview.
+- Added `WebViewAttributes.context` field to specify a shared context for the webview.
+- **Breaking** Changed `WebViewAttributes.custom_protocols` field,`WebViewBuilder::with_custom_protocol` method and `WebViewBuilder::with_asynchronous_custom_protocol` method handler function to take `WebViewId` as the first argument to check which webview made the request to the protocol.
+- **Breaking** Changed `WebViewBuilder::with_web_context` to be a static method to create a builder with a webcontext, instead of it being a setter method. It is now an alternative to `WebviewBuilder::new`
+- Added `WebViewBuilder::with_attributes` to create a webview builder with provided attributes.
+- **Breaking** Changed `WebViewBuilder::new` to take no arguments.
+- **Breaking** Changed `WebViewBuilder::build` method to take a reference to a window to create the webview in it.
+- **Breaking** Removed `WebViewBuilder::new_as_child`.
+- Added `WebViewBuilder::build_as_child` method, which takes a reference to a window to create the webview in it.
+- **Breaking** Removed `WebViewBuilderExtUnix::new_gtk`.
+- Added `WebViewBuilderExtUnix::build_gtk`.

README.md

@@ -40,9 +40,10 @@ fn main() -> wry::Result<()> {
     .with_title("Hello World")
     .build(&event_loop)
     .unwrap();
-  let _webview = WebViewBuilder::new(&window)
+
+  let webview = WebViewBuilder::new()
     .with_url("https://tauri.app")
-    .build()?;
+    .build(&window)?;
 
   event_loop.run(move |event, _, control_flow| {
     *control_flow = ControlFlow::Wait;

examples/async_custom_protocol.rs

@@ -18,42 +18,41 @@ fn main() -> wry::Result<()> {
   let event_loop = EventLoop::new();
   let window = WindowBuilder::new().build(&event_loop).unwrap();
 
+  let builder = WebViewBuilder::new()
+    .with_asynchronous_custom_protocol("wry".into(), move |_webview_id, request, responder| {
+      match get_wry_response(request) {
+        Ok(http_response) => responder.respond(http_response),
+        Err(e) => responder.respond(
+          http::Response::builder()
+            .header(CONTENT_TYPE, "text/plain")
+            .status(500)
+            .body(e.to_string().as_bytes().to_vec())
+            .unwrap(),
+        ),
+      }
+    })
+    // tell the webview to load the custom protocol
+    .with_url("wry://localhost");
+
   #[cfg(any(
     target_os = "windows",
     target_os = "macos",
     target_os = "ios",
     target_os = "android"
   ))]
-  let builder = WebViewBuilder::new(&window);
-
+  let _webview = builder.build(&window)?;
   #[cfg(not(any(
     target_os = "windows",
     target_os = "macos",
     target_os = "ios",
     target_os = "android"
   )))]
-  let builder = {
+  let _webview = {
     use tao::platform::unix::WindowExtUnix;
     use wry::WebViewBuilderExtUnix;
     let vbox = window.default_vbox().unwrap();
-    WebViewBuilder::new_gtk(vbox)
+    builder.build_gtk(vbox)?
   };
-  let _webview = builder
-    .with_asynchronous_custom_protocol("wry".into(), move |request, responder| {
-      match get_wry_response(request) {
-        Ok(http_response) => responder.respond(http_response),
-        Err(e) => responder.respond(
-          http::Response::builder()
-            .header(CONTENT_TYPE, "text/plain")
-            .status(500)
-            .body(e.to_string().as_bytes().to_vec())
-            .unwrap(),
-        ),
-      }
-    })
-    // tell the webview to load the custom protocol
-    .with_url("wry://localhost")
-    .build()?;
 
   event_loop.run(move |event, _, control_flow| {
     *control_flow = ControlFlow::Wait;

examples/custom_protocol.rs

@@ -18,42 +18,81 @@ fn main() -> wry::Result<()> {
   let event_loop = EventLoop::new();
   let window = WindowBuilder::new().build(&event_loop).unwrap();
 
+  let builder = WebViewBuilder::new()
+    .with_id("id2")
+    .with_custom_protocol(
+      "wry".into(),
+      move |_webview_id, request| match get_wry_response(request) {
+        Ok(r) => r.map(Into::into),
+        Err(e) => http::Response::builder()
+          .header(CONTENT_TYPE, "text/plain")
+          .status(500)
+          .body(e.to_string().as_bytes().to_vec())
+          .unwrap()
+          .map(Into::into),
+      },
+    )
+    // tell the webview to load the custom protocol
+    .with_url("wry://localhost");
+
   #[cfg(any(
     target_os = "windows",
     target_os = "macos",
     target_os = "ios",
     target_os = "android"
   ))]
-  let builder = WebViewBuilder::new(&window);
-
+  let _webview = builder.build(&window)?;
   #[cfg(not(any(
     target_os = "windows",
     target_os = "macos",
     target_os = "ios",
     target_os = "android"
   )))]
-  let builder = {
+  let _webview = {
     use tao::platform::unix::WindowExtUnix;
     use wry::WebViewBuilderExtUnix;
     let vbox = window.default_vbox().unwrap();
-    WebViewBuilder::new_gtk(vbox)
+    builder.build_gtk(vbox)?
   };
 
-  let _webview = builder
-    .with_custom_protocol("wry".into(), move |request| {
-      match get_wry_response(request) {
+  let window = WindowBuilder::new().build(&event_loop).unwrap();
+
+  let builder = WebViewBuilder::new()
+    .with_id("id1")
+    .with_custom_protocol(
+      "wry".into(),
+      move |_webview_id, request| match get_wry_response(request) {
         Ok(r) => r.map(Into::into),
         Err(e) => http::Response::builder()
           .header(CONTENT_TYPE, "text/plain")
           .status(500)
           .body(e.to_string().as_bytes().to_vec())
           .unwrap()
           .map(Into::into),
-      }
-    })
+      },
+    )
     // tell the webview to load the custom protocol
-    .with_url("wry://localhost")
-    .build()?;
+    .with_url("wry://localhost");
+
+  #[cfg(any(
+    target_os = "windows",
+    target_os = "macos",
+    target_os = "ios",
+    target_os = "android"
+  ))]
+  let _webview = builder.build(&window)?;
+  #[cfg(not(any(
+    target_os = "windows",
+    target_os = "macos",
+    target_os = "ios",
+    target_os = "android"
+  )))]
+  let _webview = {
+    use tao::platform::unix::WindowExtUnix;
+    use wry::WebViewBuilderExtUnix;
+    let vbox = window.default_vbox().unwrap();
+    builder.build_gtk(vbox)?
+  };
 
   event_loop.run(move |event, _, control_flow| {
     *control_flow = ControlFlow::Wait;

examples/custom_titlebar.rs

@@ -241,34 +241,32 @@ fn main() -> wry::Result<()> {
     }
   };
 
+  let builder = WebViewBuilder::new()
+    .with_html(HTML)
+    .with_ipc_handler(handler)
+    .with_accept_first_mouse(true);
+
   #[cfg(any(
     target_os = "windows",
     target_os = "macos",
     target_os = "ios",
     target_os = "android"
   ))]
-  let builder = WebViewBuilder::new(&window);
-
+  let webview = builder.build(&window)?;
   #[cfg(not(any(
     target_os = "windows",
     target_os = "macos",
     target_os = "ios",
     target_os = "android"
   )))]
-  let builder = {
+  let webview = {
     use tao::platform::unix::WindowExtUnix;
     use wry::WebViewBuilderExtUnix;
     let vbox = window.default_vbox().unwrap();
-    WebViewBuilder::new_gtk(vbox)
+    builder.build_gtk(vbox)?
   };
 
-  let mut webview = Some(
-    builder
-      .with_html(HTML)
-      .with_ipc_handler(handler)
-      .with_accept_first_mouse(true)
-      .build()?,
-  );
+  let mut webview = Some(webview);
 
   event_loop.run(move |event, _, control_flow| {
     *control_flow = ControlFlow::Wait;

examples/gtk_multiwebview.rs

@@ -16,74 +16,69 @@ fn main() -> wry::Result<()> {
   let event_loop = EventLoop::new();
   let window = WindowBuilder::new().build(&event_loop).unwrap();
 
-  #[cfg(not(any(
-    target_os = "windows",
-    target_os = "macos",
-    target_os = "ios",
-    target_os = "android"
-  )))]
-  let fixed = {
-    use gtk::prelude::*;
-    use tao::platform::unix::WindowExtUnix;
-
-    let fixed = gtk::Fixed::new();
-    let vbox = window.default_vbox().unwrap();
-    vbox.pack_start(&fixed, true, true, 0);
-    fixed.show_all();
-    fixed
-  };
-
-  let create_webview_builder = || {
+  let build_webview = |builder: WebViewBuilder<'_>| -> wry::Result<wry::WebView> {
     #[cfg(any(
       target_os = "windows",
       target_os = "macos",
       target_os = "ios",
       target_os = "android"
     ))]
-    return WebViewBuilder::new_as_child(&window);
+    let webview = builder.build(&window)?;
 
     #[cfg(not(any(
       target_os = "windows",
       target_os = "macos",
       target_os = "ios",
       target_os = "android"
     )))]
-    {
+    let webview = {
+      use gtk::prelude::*;
+      use tao::platform::unix::WindowExtUnix;
       use wry::WebViewBuilderExtUnix;
-      WebViewBuilder::new_gtk(&fixed)
-    }
+
+      let fixed = gtk::Fixed::new();
+      let vbox = window.default_vbox().unwrap();
+      vbox.pack_start(&fixed, true, true, 0);
+      fixed.show_all();
+      builder.build_gtk(&fixed)?
+    };
+
+    Ok(webview)
   };
 
   let size = window.inner_size().to_logical::<u32>(window.scale_factor());
 
-  let webview = create_webview_builder()
+  let builder = WebViewBuilder::new()
     .with_bounds(Rect {
       position: LogicalPosition::new(0, 0).into(),
       size: LogicalSize::new(size.width / 2, size.height / 2).into(),
     })
-    .with_url("https://tauri.app")
-    .build()?;
-  let webview2 = create_webview_builder()
+    .with_url("https://tauri.app");
+  let webview = build_webview(builder)?;
+
+  let builder2 = WebViewBuilder::new()
     .with_bounds(Rect {
       position: LogicalPosition::new(size.width / 2, 0).into(),
       size: LogicalSize::new(size.width / 2, size.height / 2).into(),
     })
-    .with_url("https://github.com/tauri-apps/wry")
-    .build()?;
-  let webview3 = create_webview_builder()
+    .with_url("https://github.com/tauri-apps/wry");
+  let webview2 = build_webview(builder2)?;
+
+  let builder3 = WebViewBuilder::new()
     .with_bounds(Rect {
       position: LogicalPosition::new(0, size.height / 2).into(),
       size: LogicalSize::new(size.width / 2, size.height / 2).into(),
     })
-    .with_url("https://twitter.com/TauriApps")
-    .build()?;
-  let webview4 = create_webview_builder()
+    .with_url("https://twitter.com/TauriApps");
+  let webview3 = build_webview(builder3)?;
+
+  let builder4 = WebViewBuilder::new()
     .with_bounds(Rect {
       position: LogicalPosition::new(size.width / 2, size.height / 2).into(),
       size: LogicalSize::new(size.width / 2, size.height / 2).into(),
     })
-    .with_url("https://google.com")
-    .build()?;
+    .with_url("https://google.com");
+  let webview4 = build_webview(builder4)?;
 
   event_loop.run(move |event, _, control_flow| {
     *control_flow = ControlFlow::Wait;

examples/multiwebview.rs

@@ -44,34 +44,34 @@ fn main() -> wry::Result<()> {
 
   let size = window.inner_size().to_logical::<u32>(window.scale_factor());
 
-  let webview = WebViewBuilder::new_as_child(&window)
+  let webview = WebViewBuilder::new()
     .with_bounds(Rect {
       position: LogicalPosition::new(0, 0).into(),
       size: LogicalSize::new(size.width / 2, size.height / 2).into(),
     })
     .with_url("https://tauri.app")
-    .build()?;
-  let webview2 = WebViewBuilder::new_as_child(&window)
+    .build(&window)?;
+  let webview2 = WebViewBuilder::new()
     .with_bounds(Rect {
       position: LogicalPosition::new(size.width / 2, 0).into(),
       size: LogicalSize::new(size.width / 2, size.height / 2).into(),
     })
     .with_url("https://github.com/tauri-apps/wry")
-    .build()?;
-  let webview3 = WebViewBuilder::new_as_child(&window)
+    .build(&window)?;
+  let webview3 = WebViewBuilder::new()
     .with_bounds(Rect {
       position: LogicalPosition::new(0, size.height / 2).into(),
       size: LogicalSize::new(size.width / 2, size.height / 2).into(),
     })
     .with_url("https://twitter.com/TauriApps")
-    .build()?;
-  let webview4 = WebViewBuilder::new_as_child(&window)
+    .build(&window)?;
+  let webview4 = WebViewBuilder::new()
     .with_bounds(Rect {
       position: LogicalPosition::new(size.width / 2, size.height / 2).into(),
       size: LogicalSize::new(size.width / 2, size.height / 2).into(),
     })
     .with_url("https://google.com")
-    .build()?;
+    .build(&window)?;
 
   event_loop
     .run(move |event, evl| {