From ea39c4e5bb29ffcfb1ad34f14dfb8be506181cc9 Mon Sep 17 00:00:00 2001 From: Amr Bashir Date: Fri, 24 Jan 2025 03:42:57 +0200 Subject: [PATCH] ci: run cargo-readme in covector PR (#1464) --- .../workflows/covector-version-or-publish.yml | 7 + README.md | 225 +++++++++++++----- src/lib.rs | 66 +++++ 3 files changed, 244 insertions(+), 54 deletions(-) diff --git a/.github/workflows/covector-version-or-publish.yml b/.github/workflows/covector-version-or-publish.yml index c4204eae0..c1c31807c 100644 --- a/.github/workflows/covector-version-or-publish.yml +++ b/.github/workflows/covector-version-or-publish.yml @@ -39,6 +39,13 @@ jobs: createRelease: true recognizeContributors: true + - name: install cargo-readme + if: steps.covector.outputs.commandRan == 'version' + run: cargo install cargo-readme --locked + + - run: cargo readme --no-license > README.md + if: steps.covector.outputs.commandRan == 'version' + - name: Create Pull Request With Versions Bumped id: cpr uses: tauri-apps/create-pull-request@v3 diff --git a/README.md b/README.md index 617d30b65..1d8c266c9 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,6 @@ -WRY Webview Rendering library +# wry + +

WRY Webview Rendering library

[![](https://img.shields.io/crates/v/wry?style=flat-square)](https://crates.io/crates/wry) [![](https://img.shields.io/docsrs/wry?style=flat-square)](https://docs.rs/wry/) [![License](https://img.shields.io/badge/License-MIT%20or%20Apache%202-green.svg)](https://opencollective.com/tauri) @@ -7,20 +9,22 @@ [![https://good-labs.github.io/greater-good-affirmation/assets/images/badge.svg](https://good-labs.github.io/greater-good-affirmation/assets/images/badge.svg)](https://good-labs.github.io/greater-good-affirmation) [![support](https://img.shields.io/badge/sponsor-Open%20Collective-blue.svg)](https://opencollective.com/tauri) -Cross-platform WebView rendering library in Rust that supports all major desktop platforms like Windows, macOS, Linux, Android and iOS. +Wry is a Cross-platform WebView rendering library. -## Examples +The webview requires a running event loop and a window type that implements [`HasWindowHandle`], +or a gtk container widget if you need to support X11 and Wayland. +You can use a windowing library like [`tao`] or [`winit`]. -This example leverages the `HasWindowHandle` trait from `raw-window-handle` crate and supports Windows, macOS, iOS, Android and Linux (X11 Only). -See the following example using `winit`. +### Examples -```rs -use wry::{WebView, WebViewBuilder}; -use winit::{application::ApplicationHandler, event::WindowEvent, event_loop::{ActiveEventLoop, EventLoop}, window::{Window, WindowId}}; +This example leverages the [`HasWindowHandle`] and supports Windows, macOS, iOS, Android and Linux (X11 Only). +See the following example using [`winit`]: +```rust #[derive(Default)] struct App { - webview_window: Option<(Window, WebView)>, + window: Option, + webview: Option, } impl ApplicationHandler for App { @@ -31,7 +35,8 @@ impl ApplicationHandler for App { .build(&window) .unwrap(); - self.webview_window = Some((window, webview)); + self.window = Some(window); + self.webview = Some(webview); } fn window_event(&mut self, _event_loop: &ActiveEventLoop, _window_id: WindowId, event: WindowEvent) {} @@ -42,17 +47,10 @@ let mut app = App::default(); event_loop.run_app(&mut app).unwrap(); ``` -If you also want to support Wayland too, then we recommend you use `WebViewBuilderExtUnix::new_gtk` on Linux. -See the following example using `tao`. - -```rs -use wry::WebViewBuilder; -use tao::{window::WindowBuilder, event_loop::EventLoop}; -#[cfg(target_os = "linux")] -use tao::platform::unix::WindowExtUnix; -#[cfg(target_os = "linux")] -use wry::WebViewBuilderExtUnix; +If you also want to support Wayland too, then we recommend you use [`WebViewBuilderExtUnix::new_gtk`] on Linux. +See the following example using [`tao`]: +```rust let event_loop = EventLoop::new(); let window = WindowBuilder::new().build(&event_loop).unwrap(); @@ -64,37 +62,136 @@ let webview = builder.build(&window).unwrap(); let webview = builder.build_gtk(window.gtk_window()).unwrap(); ``` -For more information, please read the crate [documentation](https://docs.rs/wry) . +### Child webviews + +You can use [`WebView::new_as_child`] or [`WebViewBuilder::new_as_child`] to create the webview as a child inside another window. This is supported on +macOS, Windows and Linux (X11 Only). + +```rust +#[derive(Default)] +struct App { + window: Option, + webview: Option, +} + +impl ApplicationHandler for App { + fn resumed(&mut self, event_loop: &ActiveEventLoop) { + let window = event_loop.create_window(Window::default_attributes()).unwrap(); + let webview = WebViewBuilder::new() + .with_url("https://tauri.app") + .with_bounds(Rect { + position: LogicalPosition::new(100, 100).into(), + size: LogicalSize::new(200, 200).into(), + }) + .build_as_child(&window) + .unwrap(); -## Platform-specific notes + self.window = Some(window); + self.webview = Some(webview); + } + + fn window_event(&mut self, _event_loop: &ActiveEventLoop, _window_id: WindowId, event: WindowEvent) {} +} + +let event_loop = EventLoop::new().unwrap(); +let mut app = App::default(); +event_loop.run_app(&mut app).unwrap(); +``` + +If you want to support X11 and Wayland at the same time, we recommend using +[`WebViewExtUnix::new_gtk`] or [`WebViewBuilderExtUnix::new_gtk`] with [`gtk::Fixed`]. + +```rust +let event_loop = EventLoop::new(); +let window = WindowBuilder::new().build(&event_loop).unwrap(); + +let builder = WebViewBuilder::new() + .with_url("https://tauri.app") + .with_bounds(Rect { + position: LogicalPosition::new(100, 100).into(), + size: LogicalSize::new(200, 200).into(), + }); + +#[cfg(not(target_os = "linux"))] +let webview = builder.build_as_child(&window).unwrap(); +#[cfg(target_os = "linux")] +let webview = { + # use gtk::prelude::*; + let vbox = window.default_vbox().unwrap(); // tao adds a gtk::Box by default + let fixed = gtk::Fixed::new(); + fixed.show_all(); + vbox.pack_start(&fixed, true, true, 0); + builder.build_gtk(&fixed).unwrap() +}; +``` + +### Platform Considerations Here is the underlying web engine each platform uses, and some dependencies you might need to install. -### Linux +#### Linux + +[WebKitGTK](https://webkitgtk.org/) is used to provide webviews on Linux which requires GTK, +so if the windowing library doesn't support GTK (as in [`winit`]) +you'll need to call [`gtk::init`] before creating the webview and then call [`gtk::main_iteration_do`] alongside +your windowing library event loop. + +```rust +#[derive(Default)] +struct App { + webview_window: Option<(Window, WebView)>, +} + +impl ApplicationHandler for App { + fn resumed(&mut self, event_loop: &ActiveEventLoop) { + let window = event_loop.create_window(Window::default_attributes()).unwrap(); + let webview = WebViewBuilder::new() + .with_url("https://tauri.app") + .build(&window) + .unwrap(); + + self.webview_window = Some((window, webview)); + } -Wry also needs [WebKitGTK](https://webkitgtk.org/) for WebView. So please make sure the following packages are installed: + fn window_event(&mut self, _event_loop: &ActiveEventLoop, _window_id: WindowId, event: WindowEvent) {} -#### Arch Linux / Manjaro: + // Advance GTK event loop