diff options
| author |  Héctor Ramón Jiménez <hector0193@gmail.com> | 2019-11-22 22:14:04 +0100 |
|---|---|---|
| committer | Héctor Ramón Jiménez <hector0193@gmail.com> | 2019-11-22 22:14:04 +0100 |
| commit | fa227255b02adbbfa99801a7baaa4d6d387f7302 (patch) | |
| tree | 1b9b4c97a6b6a054ff73cd69ac9b1493f50392c3 /web/src/lib.rs | |
| parent | 048909b45dfecef73bfacf3b5aa67462470ccca2 (diff) | |
| download | iced-fa227255b02adbbfa99801a7baaa4d6d387f7302.tar.gz iced-fa227255b02adbbfa99801a7baaa4d6d387f7302.tar.bz2 iced-fa227255b02adbbfa99801a7baaa4d6d387f7302.zip | |
Write docs for `iced_web`
Diffstat (limited to 'web/src/lib.rs')
| -rw-r--r-- | web/src/lib.rs | 90 |
1 files changed, 89 insertions, 1 deletions
diff --git a/web/src/lib.rs b/web/src/lib.rs index 00a85cf5..77a963ba 100644 --- a/web/src/lib.rs +++ b/web/src/lib.rs @@ -1,3 +1,61 @@ +//! A web runtime for Iced, targetting the DOM. +//! +//!  +//! +//! `iced_web` takes [`iced_core`] and builds a WebAssembly runtime on top. It +//! achieves this by introducing a `Widget` trait that can be used to produce +//! VDOM nodes. +//! +//! The crate is currently a __very experimental__, simple abstraction layer +//! over [`dodrio`]. +//! +//! [`iced_core`]: https://github.com/hecrj/iced/tree/master/core +//! [`dodrio`]: https://github.com/fitzgen/dodrio +//! +//! # Usage +//! The current build process is a bit involved, as [`wasm-pack`] does not +//! currently [support building binary crates](https://github.com/rustwasm/wasm-pack/issues/734). +//! +//! Therefore, we instead build using the `wasm32-unknown-unknown` target and +//! use the [`wasm-bindgen`] CLI to generate appropriate bindings. +//! +//! For instance, let's say we want to build the [`tour` example]: +//! +//! ```bash +//! cd examples +//! cargo build --example tour --target wasm32-unknown-unknown +//! wasm-bindgen ../target/wasm32-unknown-unknown/debug/examples/tour.wasm --out-dir tour --web +//! ``` +//! +//! Then, we need to create an `.html` file to load our application: +//! +//! ```html +//! <!DOCTYPE html> +//! <html> +//! <head> +//! <meta http-equiv="Content-type" content="text/html; charset=utf-8"/> +//! <title>Tour - Iced</title> +//! </head> +//! <body> +//! <script type="module"> +//! import init from "./tour/tour.js"; +//! +//! init('./tour/tour_bg.wasm'); +//! </script> +//! </body> +//! </html> +//! ``` +//! +//! Finally, we serve it using an HTTP server and access it with our browser. +//! +//! [`wasm-pack`]: https://github.com/rustwasm/wasm-pack +//! [`wasm-bindgen`]: https://github.com/rustwasm/wasm-bindgen +//! [`tour` example]: https://github.com/hecrj/iced/blob/master/examples/tour.rs +#![deny(missing_docs)] +#![deny(missing_debug_implementations)] +#![deny(unused_results)] +#![deny(unsafe_code)] +#![deny(rust_2018_idioms)] use dodrio::bumpalo; use std::cell::RefCell; @@ -6,6 +64,7 @@ mod element; pub mod widget; pub use bus::Bus; +pub use dodrio; pub use element::Element; pub use iced_core::{ Align, Background, Color, Font, HorizontalAlignment, Length, @@ -13,13 +72,42 @@ pub use iced_core::{ }; pub use widget::*; +/// An interactive web application. +/// +/// This trait is the main entrypoint of Iced. Once implemented, you can run +/// your GUI application by simply calling [`run`](#method.run). It will take +/// control of the `<title>` and the `<body>` of the document. +/// +/// An [`Application`](trait.Application.html) can execute asynchronous actions +/// by returning a [`Command`](struct.Command.html) in some of its methods. pub trait Application { + /// The type of __messages__ your [`Application`] will produce. + /// + /// [`Application`]: trait.Application.html type Message; + /// Handles a __message__ and updates the state of the [`Application`]. + /// + /// This is where you define your __update logic__. All the __messages__, + /// produced by either user interactions or commands, will be handled by + /// this method. + /// + /// Any [`Command`] returned will be executed immediately in the background. + /// + /// [`Application`]: trait.Application.html + /// [`Command`]: struct.Command.html fn update(&mut self, message: Self::Message); - fn view(&mut self) -> Element<Self::Message>; + /// Returns the widgets to display in the [`Application`]. + /// + /// These widgets can produce __messages__ based on user interaction. + /// + /// [`Application`]: trait.Application.html + fn view(&mut self) -> Element<'_, Self::Message>; + /// Runs the [`Application`]. + /// + /// [`Application`]: trait.Application.html fn run(self) where Self: 'static + Sized, |