html_view/
lib.rs

1//! html_view: A lightweight, cross-platform HTML viewer for Rust.
2//!
3//! This library provides a simple API to display HTML content in a native window,
4//! similar to `matplotlib.pyplot.show()` in Python.
5//!
6//! # Quick Start
7//!
8//! ```no_run
9//! use html_view;
10//!
11//! fn main() -> Result<(), html_view::ViewerError> {
12//!     html_view::show("<h1>Hello, World!</h1>")?;
13//!     Ok(())
14//! }
15//! ```
16//!
17//! # Features
18//!
19//! - Display inline HTML, local files, directories, or remote URLs
20//! - Blocking and non-blocking modes
21//! - Window configuration (size, position, title)
22//! - Security controls for navigation and remote content
23//! - Cross-platform (Windows, macOS, Linux)
24
25mod error;
26mod launcher;
27mod locator;
28mod options;
29mod result;
30
31pub use error::ViewerError;
32pub use locator::{AppLocator, DefaultAppLocator};
33pub use options::{ViewerOptions, ViewerWaitMode};
34pub use result::{ViewerHandle, ViewerResult};
35
36// Re-export commonly used types from shared crate
37pub use html_view_shared::{
38    BehaviourOptions, DialogOptions, EnvironmentOptions, ToolbarOptions, ViewerContent,
39    ViewerExitReason, ViewerExitStatus, WindowOptions,
40};
41
42use launcher::launch_viewer;
43
44/// Display inline HTML in a new viewer window and block until the window is closed.
45///
46/// This is the simplest way to show HTML content. It uses default window and
47/// behaviour options with secure defaults.
48///
49/// # Example
50///
51/// ```no_run
52/// html_view::show("<h1>Hello!</h1>").unwrap();
53/// ```
54///
55/// # Errors
56///
57/// Returns an error if the viewer binary cannot be found or launched, or if
58/// there's an I/O error during the process.
59pub fn show<S: Into<String>>(html: S) -> Result<(), ViewerError> {
60    let options = ViewerOptions::inline_html(html);
61    match open(options)? {
62        ViewerResult::Blocking(_status) => Ok(()),
63        ViewerResult::NonBlocking(_) => unreachable!("inline_html uses Blocking mode"),
64    }
65}
66
67pub fn show_with_options<S: Into<String>>(
68    html: S,
69    window_options: WindowOptions,
70) -> Result<(), ViewerError> {
71    let mut options = ViewerOptions::inline_html(html);
72    options.window = window_options;
73
74    match open(options)? {
75        ViewerResult::Blocking(_status) => Ok(()),
76        ViewerResult::NonBlocking(_) => unreachable!("inline_html uses Blocking mode"),
77    }
78}
79
80/// Open a viewer window with the given options.
81///
82/// Returns either a blocking result with the exit status or a non-blocking
83/// handle, depending on `options.wait`.
84///
85/// # Example
86///
87/// ```no_run
88/// use html_view::{ViewerOptions, ViewerWaitMode};
89///
90/// let mut options = ViewerOptions::inline_html("<h1>Test</h1>");
91/// options.wait = ViewerWaitMode::NonBlocking;
92///
93/// match html_view::open(options).unwrap() {
94///     html_view::ViewerResult::NonBlocking(mut handle) => {
95///         // Do other work...
96///         let status = handle.wait().unwrap();
97///         println!("Viewer exited: {:?}", status);
98///     }
99///     _ => unreachable!(),
100/// }
101/// ```
102///
103/// # Errors
104///
105/// Returns an error if the viewer binary cannot be found or launched, or if
106/// there's an I/O error during the process.
107pub fn open(options: ViewerOptions) -> Result<ViewerResult, ViewerError> {
108    launch_viewer(options, &DefaultAppLocator)
109}
html_view/lib.rs

html_view/
lib.rs
