saucers/
lib.rs

1// Names generated by bindgen will preserve the original name in the C API.
2#![allow(non_upper_case_globals)]
3#![allow(non_camel_case_types)]
4#![allow(non_snake_case)]
5// Macros defined in this crate are meant to be used in unsafe context, making it unnecessary to require unsafe blocks
6// to be listed explicitly.
7#![allow(clippy::macro_metavars_in_unsafe)]
8// Unsafe APIs are only used internally.
9#![allow(clippy::missing_safety_doc)]
10// Functional APIs are used excessively for cleanups and event handling.
11// They do can lead to complex types, but should not generally affect readability.
12#![allow(clippy::type_complexity)]
13
14//! This is the Rust bindings for [saucer](https://github.com/saucer/saucer). The C++ webview library.
15//!
16//! This crate wraps around the C API of saucer and intends to provide safe items for using directly or as building
17//! blocks of frameworks.
18//!
19//! Examples can be found in the [`examples`](https://github.com/skjsjhb/saucers/tree/main/examples) directory. Here's
20//! a simple demonstration:
21//!
22//! ```no_run
23//! use saucers::app::App;
24//! use saucers::options::AppOptions;
25//! use saucers::prefs::Preferences;
26//! use saucers::webview::Webview;
27//! use saucers::webview::events::DomReadyEvent;
28//! use saucers::webview::events::FaviconEvent;
29//!
30//! fn main() {
31//!     // Create an app to manage the event cycle.
32//!     // The app returns a collector which must be kept to live longer than all `App`s and `Webview`s.
33//!     // It detects leaks internally and gives a panic when dropped incorrectly.
34//!     let (cc, app) = App::new(AppOptions::new("saucer"));
35//!
36//!     // Customize webview behavior using a preference set.
37//!     let mut prefs = Preferences::new(&app);
38//!     prefs.set_user_agent("saucer");
39//!
40//!     // Create a new webview instance.
41//!     let w = Webview::new(&prefs).unwrap();
42//!     drop(prefs);
43//!
44//!     // Register a one-time listener for DOM ready event.
45//!     // Use the turbofish syntax to specify the event type.
46//!     // Prefer using the handle argument instead of capturing to prevent cycle references.
47//!     w.once::<DomReadyEvent>(Box::new(move |w| {
48//!         w.execute("window.saucer.internal.send_message(`Hello! Your user agent is '${navigator.userAgent}'!`);");
49//!     }));
50//!
51//!     // Registers a repeatable event handler for favicon event.
52//!     let on_favicon_id = w.on::<FaviconEvent>(Box::new(|_, icon| {
53//!         println!("Wow, you have a favicon of {} bytes!", icon.data().size());
54//!     }));
55//!
56//!     // Handles incoming webview messages.
57//!     // This API forwards the message as-is, allowing more complex channels to be built on it.
58//!     w.on_message(|_, msg| {
59//!         println!("Browser: {msg}");
60//!     });
61//!
62//!     // Set several runtime properties for webview.
63//!     w.set_url("https://saucer.app");
64//!     w.set_size(1152, 648);
65//!     w.set_dev_tools(true);
66//!     w.set_title("Saucer + Rust");
67//!
68//!     // Show and run the app.
69//!     w.show();
70//!     app.run();
71//!
72//!     // An event handler can be cleared using its ID.
73//!     w.off::<FaviconEvent>(on_favicon_id);
74//!
75//!     // Rust will clean up everything in correct order. But to make it clear, we will drop it manually.
76//!     drop(w);
77//!     drop(app);
78//!     drop(cc);
79//! }
80//! ```
81pub mod app;
82mod capi;
83pub mod collector;
84pub mod embed;
85pub mod icon;
86mod macros;
87pub mod navigation;
88pub mod options;
89pub mod prefs;
90pub mod scheme;
91pub mod script;
92pub mod stash;
93pub mod webview;
94
95#[cfg(feature = "desktop-mod")]
96pub mod desktop;
97
98#[cfg(feature = "pdf-mod")]
99pub mod pdf;
100mod util;
saucers/lib.rs

saucers/
lib.rs
