Add examples

Author: jakmeier

.cargo/config

@@ -0,0 +1,2 @@
+[build]
+target = "wasm32-unknown-unknown"

Cargo.toml

@@ -10,4 +10,7 @@ readme = "README.md"
 
 [dependencies]
 lazy_static = "1.4"
-stdweb = "0.4"
+stdweb = "0.4"
+
+[dev-dependencies]
+wasm-bindgen-test = "0.3"

README.md

@@ -7,6 +7,9 @@ It works with absolute positions and can therefore be used to place HTML text el
 
 TODO
 
+### Running the examples
+To run the examples included in the library, it's recommended to install [cargo-web](https://github.com/koute/cargo-web) and then simply call `cargo web start --example hello-world`. See the [examples](./examples) folder for all available examples. 
+
 ## Implementation policy for Panes
 * Compatibility with stable Rust
 * Light-weight (only major dependency is [stdweb](https://github.com/koute/stdweb))

Web.toml

@@ -0,0 +1 @@
+default-target = "wasm32-unknown-unknown"

examples/dynamic_pane.rs

@@ -0,0 +1,60 @@
+use stdweb::js;
+use stdweb::web::*;
+use stdweb::unstable::TryInto;
+fn main() {
+    stdweb::initialize();
+    panes::init().unwrap();
+
+    // Create a new pane with a div as grid container.
+    // Because we want low-level access afterwards, it is important here that 
+    // the div starts at the first line. Otherwise, there will be a text node before the div
+    let html = 
+    r#"<div style="display: grid; grid-template-columns: repeat(5, 1fr); grid-gap: 10px; overflow: auto;"></div>"#;
+    let pane = panes::new_pane(100,100,550,550,html).unwrap();
+
+    // Get low-level access to the DOM node representing the grid container
+    let node = pane.get_first_inner_node().unwrap();
+
+
+    /* Now we are in webstd territory */
+
+    // UpCast to an HtmlElement
+    let table: HtmlElement = node.try_into().expect("Should be HTML");
+
+    // Append a single element to the grid
+    table.append_html(
+        r#"<div style="background-color: blue; height: 100px;">"#
+    ).unwrap();
+
+    // Clone table reference so we can move it into closure
+    let cloned_table = table.clone();
+    // Append more dynamically, using a closure registered as event listener on space bar key
+    let append_closure = move || {
+        cloned_table.append_html(
+            r#"<div style="background-color: blue; height: 100px;">"#
+        ).unwrap();
+    };
+    // Registration is here done using the webstd js macro
+    js!{
+        document.addEventListener("keydown", event => {
+            if (event.code === "Space") {
+              @{append_closure}()
+            }
+          })
+    }
+
+    // Also register to remove one on backspace
+    let delete_closure = move || {
+        if let Some(child) = table.last_child() {
+            table.remove_child(&child).unwrap();
+        }
+    };
+    // Registration is here done using the webstd js macro
+    js!{
+        document.addEventListener("keydown", event => {
+            if (event.code === "Backspace") {
+              @{delete_closure}()
+            }
+          })
+    }
+}

examples/hello_world.rs

@@ -0,0 +1,16 @@
+#![allow(unused_must_use)]
+fn main() {
+    // Initialize stdweb and panes
+    stdweb::initialize();
+    panes::init();
+
+    // Create a new pane at offset (100,100) from body
+    // with size 500px/500px and then create a single
+    // text node inside it with the text "Hello world"
+    let x = 100;
+    let y = 100;
+    let w = 500;
+    let h = 500;
+    let html = "Hello world";
+    panes::new_pane(x,y,w,h,html);
+}

examples/toggle_panes.rs

@@ -0,0 +1,36 @@
+use stdweb::web::set_timeout;
+use panes::PaneHandle;
+
+fn main() {
+    stdweb::initialize();
+    panes::init().expect("Init failed");
+
+    // Create two new panes with some HTML in it
+    let html0 = r#"
+    <div style="background-color:grey; color: white; height: 100%;">
+        <div style="text-align: end; position: absolute; bottom: 0; right: 0;">
+            Hi!
+        </div>
+    </div>
+    "#;
+    let html1 = r#"
+    <div style="background-color:grey; color:white; height: 100%;">
+        <div>
+            Bye!
+        </div>
+    </div>
+    "#;
+    let pane0 = panes::new_pane(100,100,100,100,html0).unwrap();
+    let pane1 = panes::new_pane(200,200,100,100,html1).unwrap();
+
+    toggle(pane0, pane1);
+}
+
+// Function that takes to panes, shows the first and hides the second 
+// and then calls itself again delayed, with the two panes swapped
+fn toggle(a: PaneHandle, b: PaneHandle) {
+    a.show().expect("Error");
+    b.hide().expect("Error");
+    let closure = move || { toggle(b,a); };
+    set_timeout(closure, 1000);
+}

src/lib.rs

@@ -19,7 +19,7 @@ use style::*;
 /// Mounts the panes to the HTML body
 pub fn init() -> Result<(), PanesError> {
     let mut state = get_mut()?;
-    if state.is_none() {
+    if state.is_some() {
         return Err(PanesError::AlreadyInitialized);
     }
     *state = Some(GlobalState::mount_body()?);
@@ -29,14 +29,17 @@ pub fn init() -> Result<(), PanesError> {
 /// Extended initialization function.
 /// Mounts the panes as a child of the HTML element with the defined ID.
 /// The specified dimensions restrict the area in which panes are visible.
+/// # Example
 /// ```
-/// let width = 1280;
-/// let height = 720;
+/// let width = 1280
+/// let height = 720
 /// panes::init_ex("panes-root", 0, 0, width, height);
 /// ```
 pub fn init_ex(id: &str, x: u32, y: u32, width: u32, height: u32) -> Result<(), PanesError>  {
     let mut state = get_mut()?;
-    assert!(state.is_none(), "Repeated initialization");
+    if state.is_some() {
+        return Err(PanesError::AlreadyInitialized);
+    }
 
     let document = stdweb::web::document();
     let root = document.get_element_by_id(id).ok_or(PanesError::MissingRoot(id.to_owned()))?;

src/pane_handle.rs

@@ -3,7 +3,7 @@
 //! Almost the entire library interface is defined in this module.
 
 use crate::*;
-use stdweb::web::HtmlElement;
+use stdweb::web::{HtmlElement, Node};
 use stdweb::unstable::TryInto;
 
 /// External representation of a Pane.
@@ -39,22 +39,36 @@ impl PaneHandle {
         let _pane = get_mut()?.as_mut().ok_or(PanesError::NotInitialized)?.delete_pane(self);
         Ok(())
     }
-    /// Get a reference to a DOM node associated with the pane.
+    /// Get a reference to the DOM element associated with the pane.
+    /// The provided HTML when creating a new pane will be the child node(s) of the returned element.
     /// 
     /// The returned [`HtmlElement`] is from the crate [`stdweb`], allowing library users to
     /// escape the Panes crate and access the DOM directly.
     /// 
-    /// The provided HTML when creating a new pane will be the child node(s) of the returned element.
-    /// 
     /// TODO: Example
     /// 
     /// [`HtmlElement`]: https://docs.rs/stdweb/*/stdweb/web/struct.HtmlElement.html
     /// [`stdweb`]: https://docs.rs/stdweb/*/stdweb/
-    pub fn get_node(&self) -> Result<HtmlElement, PanesError> {
+    pub fn get_parent_element(&self) -> Result<HtmlElement, PanesError> {
         get()?.as_ref()
             .ok_or(PanesError::NotInitialized)?
             .get_node(&self)?.clone()
             .try_into()
             .map_err(|e|PanesError::BrowserError(Box::new(e)))
     }
+    /// Get a reference to the DOM node created by the provided HTML when creating the pane.
+    /// If multiple nodes have been created, the first node is returned.
+    /// 
+    /// The returned [`Node`] is from the crate [`stdweb`], allowing library users to
+    /// escape the Panes crate and access the DOM directly.
+    /// 
+    /// TODO: Example
+    /// 
+    /// [`Node`]: https://docs.rs/stdweb/*/stdweb/web/struct.Node.html
+    /// [`stdweb`]: https://docs.rs/stdweb/*/stdweb/
+    pub fn get_first_inner_node(&self) -> Result<Node, PanesError> {
+        self.get_parent_element()?
+            .first_child()
+            .ok_or(PanesError::MissingChild)
+    }
 }