Skip to content

Commit

Permalink
chore: sync README with crate docs (#1459)
Browse files Browse the repository at this point in the history 
closes #1458
  • Loading branch information
@amrbashir
amrbashir authored Jan 22, 2025
1 parent 0185644 commit f007e65
Show file tree
Hide file tree
Showing 2 changed files with 120 additions and 91 deletions.
154 changes: 75 additions & 79 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,68 +7,64 @@
[![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, and Linux.

<div align="center">
<a href="https://gfycat.com/needywetelk">
<img src="https://thumbs.gfycat.com/NeedyWetElk-size_restricted.gif">
</a>
</div>

## Overview

WRY connects the web engine on each platform and provides easy to use and unified interface to render WebView.
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`.

## Usage

The minimum example to create a Window and browse a website looks like following:

```rust
fn main() -> wry::Result<()> {
use tao::{
event::{Event, StartCause, WindowEvent},
event_loop::{ControlFlow, EventLoop},
window::WindowBuilder,
};
use wry::WebViewBuilder;

let event_loop = EventLoop::new();
let window = WindowBuilder::new()
.with_title("Hello World")
.build(&event_loop)
.unwrap();

let webview = WebViewBuilder::new()
.with_url("https://tauri.app")
.build(&window)?;

event_loop.run(move |event, _, control_flow| {
*control_flow = ControlFlow::Wait;

match event {
Event::NewEvents(StartCause::Init) => println!("Wry has started!"),
Event::WindowEvent {
event: WindowEvent::CloseRequested,
..
} => *control_flow = ControlFlow::Exit,
_ => (),
}
});
Cross-platform WebView rendering library in Rust that supports all major desktop platforms like Windows, macOS, Linux, Android and iOS.

## Examples

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

```rs
use wry::{WebView, WebViewBuilder};
use winit::{application::ApplicationHandler, event::WindowEvent, event_loop::{ActiveEventLoop, EventLoop}, window::{Window, WindowId}};

#[derive(Default)]
struct App {
webview_window: Option<(Window, WebView)>,
}
```

There are also more samples under `examples`, you can enter commands like the following to try them:
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();

```
cargo run --example multiwindow
self.webview_window = Some((window, 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();
```

For more information, please read the documentation below.
If you also want to support Wayland too, then we recommend you use `WebViewBuilderExtUnix::new_gtk` on Linux.
See the following example using `tao`.

## [Documentation](https://docs.rs/wry)
```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;

let event_loop = EventLoop::new();
let window = WindowBuilder::new().build(&event_loop).unwrap();

let builder = WebViewBuilder::new().with_url("https://tauri.app");

#[cfg(not(target_os = "linux"))]
let webview = builder.build(&window).unwrap();
#[cfg(target_os = "linux")]
let webview = builder.build_gtk(window.gtk_window()).unwrap();
```

For more information, please read the crate [documentation](https://docs.rs/wry) .

## Platform-specific notes

Expand Down Expand Up @@ -98,40 +94,40 @@ sudo dnf install gtk3-devel webkit2gtk4.1-devel

### Nix & NixOS

```Nix
```Nix
# shell.nix
let
# Unstable Channel | Rolling Release
pkgs = import (fetchTarball("channel:nixpkgs-unstable")) { };
packages = with pkgs; [
pkg-config
webkitgtk_4_1
];
in
pkgs.mkShell {
buildInputs = packages;
}
```
let
# Unstable Channel | Rolling Release
pkgs = import (fetchTarball("channel:nixpkgs-unstable")) { };
packages = with pkgs; [
pkg-config
webkitgtk_4_1
];
in
pkgs.mkShell {
buildInputs = packages;
}
```

```sh
nix-shell shell.nix
```
```sh
nix-shell shell.nix
```

#### GUIX

```scheme
```scheme
;; manifest.scm
(specifications->manifest
'("pkg-config" ; Helper tool used when compiling
"webkitgtk" ; Web content engine fot GTK+
))
```
(specifications->manifest
'("pkg-config" ; Helper tool used when compiling
"webkitgtk" ; Web content engine fot GTK+
))
```

```sh
guix shell -m manifest.scm
````
```

### macOS

Expand Down
57 changes: 45 additions & 12 deletions src/lib.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,12 +11,11 @@
//! ## Examples
//!
//! This example leverages the [`HasWindowHandle`] and supports Windows, macOS, iOS, Android and Linux (X11 Only).
//! See the following example using [`winit`].
//! See the following example using [`winit`]:
//!
//! ```no_run
//! # use wry::{WebViewBuilder, raw_window_handle};
//! # use winit::{application::ApplicationHandler, event::WindowEvent, event_loop::{ActiveEventLoop, EventLoop}, window::{Window, WindowId}};
//!
//! #[derive(Default)]
//! struct App {
//! window: Option<Window>,
Expand Down Expand Up @@ -44,7 +43,7 @@
//! ```
//!
//! If you also want to support Wayland too, then we recommend you use [`WebViewBuilderExtUnix::new_gtk`] on Linux.
//! See the following example using [`tao`].
//! See the following example using [`tao`]:
//!
//! ```no_run
//! # use wry::WebViewBuilder;
Expand Down Expand Up @@ -72,7 +71,6 @@
//! ```no_run
//! # use wry::{WebViewBuilder, raw_window_handle, Rect, dpi::*};
//! # use winit::{application::ApplicationHandler, event::WindowEvent, event_loop::{ActiveEventLoop, EventLoop}, window::{Window, WindowId}};
//!
//! #[derive(Default)]
//! struct App {
//! window: Option<Window>,
Expand Down Expand Up @@ -138,18 +136,21 @@
//!
//! ## Platform Considerations
//!
//! Note that on Linux, we use webkit2gtk webviews so if the windowing library doesn't support gtk (as in [`winit`])
//! Here is the underlying web engine each platform uses, and some dependencies you might need to install.
//!
//! ### 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.
//!
//! ```no_run
//! # use wry::{WebViewBuilder, raw_window_handle};
//! # use wry::{WebView, WebViewBuilder};
//! # use winit::{application::ApplicationHandler, event::WindowEvent, event_loop::{ActiveEventLoop, EventLoop}, window::{Window, WindowId}};
//!
//! #[derive(Default)]
//! struct App {
//! window: Option<Window>,
//! webview: Option<wry::WebView>,
//! webview_window: Option<(Window, WebView)>,
//! }
//!
//! impl ApplicationHandler for App {
Expand All @@ -160,8 +161,7 @@
//! .build(&window)
//! .unwrap();
//!
//! self.window = Some(window);
//! self.webview = Some(webview);
//! self.webview_window = Some((window, webview));
//! }
//!
//! fn window_event(&mut self, _event_loop: &ActiveEventLoop, _window_id: WindowId, event: WindowEvent) {}
Expand All @@ -180,7 +180,40 @@
//! event_loop.run_app(&mut app).unwrap();
//! ```
//!
//! ## Android
//! #### Linux Dependencies
//!
//! ##### Arch Linux / Manjaro:
//!
//! ```bash
//! sudo pacman -S webkit2gtk-4.1
//! ```
//!
//! ##### Debian / Ubuntu:
//!
//! ```bash
//! sudo apt install libwebkit2gtk-4.1-dev
//! ```
//!
//! ##### Fedora
//!
//! ```bash
//! sudo dnf install gtk3-devel webkit2gtk4.1-devel
//! ```
//!
//! ### macOS
//!
//! WebKit is native on macOS so everything should be fine.
//!
//! If you are cross-compiling for macOS using [osxcross](https://github.com/tpoechtrager/osxcross) and encounter a runtime panic like `Class with name WKWebViewConfiguration could not be found` it's possible that `WebKit.framework` has not been linked correctly, to fix this set the `RUSTFLAGS` environment variable:
//!
//! ```bash
//! RUSTFLAGS="-l framework=WebKit" cargo build --target=x86_64-apple-darwin --release
//! ```
//! ### Windows
//!
//! WebView2 provided by Microsoft Edge Chromium is used. So wry supports Windows 7, 8, 10 and 11.
//!
//! ### Android
//!
//! In order for `wry` to be able to create webviews on Android, there is a few requirements that your application needs to uphold:
//! 1. You need to set a few environment variables that will be used to generate the necessary kotlin
Expand Down

0 comments on commit f007e65

Please sign in to comment.