Merge pull request #221 from mitchmindtree/user_functions

Add window-specific view and event user function support. Add app update user function.

CHANGELOG.md

@@ -16,6 +16,10 @@
 - The `view` function is now called separately for each frame for each window,
   rather than a single frame for all windows at once. The window a frame is
   associated with can be determined via `Frame::window_id`.
+- A suite of new event handling functions have been added as an alternative to
+  matching on the raw `Event` type. This has simplified a lot of the examples.
+  See the `app::Builder` and `window::Builder` docs for the newly available
+  methods and more documentation.
 
 # Version 0.8.0 (2018-07-19)
 

Cargo.toml

@@ -42,6 +42,9 @@ winit = "0.18"
 
 # --------------- Nannou Examples
 [[example]]
+name = "all_functions"
+path = "examples/all_functions.rs"
+[[example]]
 name = "loop_mode"
 path = "examples/loop_mode.rs"
 [[example]]

examples/all_functions.rs

@@ -0,0 +1,139 @@
+extern crate nannou;
+
+use nannou::prelude::*;
+
+fn main() {
+    nannou::app(model)
+        .event(event)
+        .update(update)
+        .view(view)
+        .run();
+}
+
+struct Model {}
+
+fn model(app: &App) -> Model {
+    app.new_window()
+        .with_dimensions(720, 720)
+        .event(window_event)
+        .raw_event(raw_window_event)
+        .key_pressed(key_pressed)
+        .key_released(key_released)
+        .mouse_moved(mouse_moved)
+        .mouse_pressed(mouse_pressed)
+        .mouse_released(mouse_released)
+        .mouse_wheel(mouse_wheel)
+        .mouse_entered(mouse_entered)
+        .mouse_exited(mouse_exited)
+        .touch(touch)
+        .touchpad_pressure(touchpad_pressure)
+        .moved(window_moved)
+        .resized(window_resized)
+        .hovered_file(hovered_file)
+        .hovered_file_cancelled(hovered_file_cancelled)
+        .dropped_file(dropped_file)
+        .focused(window_focused)
+        .unfocused(window_unfocused)
+        .closed(window_closed)
+        .build()
+        .unwrap();
+    Model {}
+}
+
+fn event(_app: &App, _model: &mut Model, event: Event) {
+    match event {
+        Event::WindowEvent { id: _, raw: _, simple: _  } => {}
+        Event::DeviceEvent(_device_id, _event) => {}
+        Event::Update(_dt) => {}
+        Event::Awakened => {}
+        Event::Suspended(_b) => {}
+    }
+}
+
+fn update(_app: &App, _model: &mut Model, _update: Update) {
+}
+
+fn view(_app: &App, _model: &Model, frame: Frame) -> Frame {
+    frame.clear(DARK_BLUE);
+    frame
+}
+
+fn window_event(_app: &App, _model: &mut Model, event: WindowEvent) {
+    match event {
+        KeyPressed(_key) => {}
+        KeyReleased(_key) => {}
+        MouseMoved(_pos) => {}
+        MousePressed(_button) => {}
+        MouseReleased(_button) => {}
+        MouseEntered => {}
+        MouseExited => {}
+        MouseWheel(_amount, _phase) => {}
+        Moved(_pos) => {}
+        Resized(_size) => {}
+        Touch(_touch) => {}
+        TouchPressure(_pressure) => {}
+        HoveredFile(_path) => {}
+        DroppedFile(_path) => {}
+        HoveredFileCancelled => {}
+        Focused => {}
+        Unfocused => {}
+        Closed => {}
+    }
+}
+
+fn raw_window_event(_app: &App, _model: &mut Model, _event: nannou::winit::WindowEvent) {
+}
+
+fn key_pressed(_app: &App, _model: &mut Model, _key: Key) {
+}
+
+fn key_released(_app: &App, _model: &mut Model, _key: Key) {
+}
+
+fn mouse_moved(_app: &App, _model: &mut Model, _pos: Point2) {
+}
+
+fn mouse_pressed(_app: &App, _model: &mut Model, _button: MouseButton) {
+}
+
+fn mouse_released(_app: &App, _model: &mut Model, _button: MouseButton) {
+}
+
+fn mouse_wheel(_app: &App, _model: &mut Model, _dt: MouseScrollDelta, _phase: TouchPhase) {
+}
+
+fn mouse_entered(_app: &App, _model: &mut Model) {
+}
+
+fn mouse_exited(_app: &App, _model: &mut Model) {
+}
+
+fn touch(_app: &App, _model: &mut Model, _touch: TouchEvent) {
+}
+
+fn touchpad_pressure(_app: &App, _model: &mut Model, _pressure: TouchpadPressure) {
+}
+
+fn window_moved(_app: &App, _model: &mut Model, _pos: Point2) {
+}
+
+fn window_resized(_app: &App, _model: &mut Model, _dim: Vector2) {
+}
+
+fn window_focused(_app: &App, _model: &mut Model) {
+}
+
+fn window_unfocused(_app: &App, _model: &mut Model) {
+}
+
+fn window_closed(_app: &App, _model: &mut Model) {
+}
+
+fn hovered_file(_app: &App, _model: &mut Model, _path: std::path::PathBuf) {
+}
+
+fn hovered_file_cancelled(_app: &App, _model: &mut Model) {
+}
+
+fn dropped_file(_app: &App, _model: &mut Model, _path: std::path::PathBuf) {
+}

examples/basics/1_nannou_events.rs

@@ -2,65 +2,61 @@ extern crate nannou;
 
 use nannou::prelude::*;
 
-// every rust program has to have a main function which gets
-// called when the program is run.
+// Every rust program has to have a main function which gets called when the program is run.
+// In the main function, we build the nannou app and run it.
 fn main() {
-    nannou::app(model).event(event).simple_window(view).run();
+    nannou::app(model).update(update).run();
 }
 
-// model represents the state of our app
+// Model represents the state of our application. We don't have any state in this demonstration, so
+// for now it is just an empty struct.
 struct Model;
 
-// put your setup code here, to run once before the application loop:
-fn model(_app: &App) -> Model {
+// This function is where we setup the application and create the `Model` for the first time.
+fn model(app: &App) -> Model {
+    // Create a window that can receive user input like mouse and keyboard events.
+    app.new_window().event(event).view(view).build().unwrap();
     Model
 }
 
-// put your update code here, to set variables and handle
-// keyboard and mouse events before drawing each frame:
-fn event(_app: &App, model: Model, event: Event) -> Model {
-    match event {
-        Event::WindowEvent {
-            simple: Some(event),
-            ..
-        } => {
-            // Print events as they occur to the console
-            println!("{:#?}", event);
-
-            match event {
-                // KEY EVENTS
-                KeyPressed(_key) => {}
-
-                KeyReleased(_key) => {}
-
-                // MOUSE EVENTS
-                MouseMoved(_pos) => {}
-
-                MouseDragged(_pos, _button) => {}
-
-                MousePressed(_button) => {}
-
-                MouseReleased(_button) => {}
-
-                MouseEntered => {}
-
-                MouseExited => {}
-
-                // WINDOW EVENTS
-                Resized(_size) => {}
-
-                Moved(_pos) => {}
-
-                _other => (),
-            }
-        }
+// Update the state of your application here. By default, this gets called right before `view`.
+fn update(_app: &App, _model: &mut Model, _update: Update) {
+}
 
-        // update gets called just before view every frame
-        Event::Update(_dt) => {}
+// We can also update the application based on events received by the window like key presses and
+// mouse movement here.
+fn event(_app: &App, _model: &mut Model, event: WindowEvent) {
+    // Print events as they occur to the console
+    println!("{:?}", event);
 
-        _ => (),
+    // We can `match` on the event to do something different depending on the kind of event.
+    match event {
+        // Keyboard events
+        KeyPressed(_key) => {}
+        KeyReleased(_key) => {}
+
+        // Mouse events
+        MouseMoved(_pos) => {}
+        MousePressed(_button) => {}
+        MouseReleased(_button) => {}
+        MouseWheel(_amount, _phase) => {}
+        MouseEntered => {}
+        MouseExited => {}
+
+        // Touch events
+        Touch(_touch) => {}
+        TouchPressure(_pressure) => {}
+
+        // Window events
+        Moved(_pos) => {}
+        Resized(_size) => {}
+        HoveredFile(_path) => {}
+        DroppedFile(_path) => {}
+        HoveredFileCancelled => {}
+        Focused => {}
+        Unfocused => {}
+        Closed => {}
     }
-    model
 }
 
 // put your main code here, to run repeatedly:

examples/basics/2_variables_window_console.rs

@@ -3,24 +3,18 @@ extern crate nannou;
 use nannou::prelude::*;
 
 fn main() {
-    nannou::app(model).event(event).view(view).run();
+    nannou::app(model).view(view).run();
 }
 
-struct Model {
-    window: WindowId,
-}
+struct Model;
 
 fn model(app: &App) -> Model {
-    // Construct and define the size of our window using .with_dimensions(.,.)
-    // Argument 1 = width of window; Argument 2 = height of window
-    let window = app.new_window().with_dimensions(640, 480).build().unwrap();
-
-    // Below are the different variable types available in Rust
-    let i = 50; // Ints store whole numbers
-    let f = 36.6; // Floats are used to store numbers with decimals or fractions of numbers
-    let b = true; // Boolean values can be either 'true' or 'false'
-    let c = '!'; // Char can only hold a single character
-    let message = "hello world"; // Strings hold a collection of characters
+    // Below are some of the different primitive types available in Rust.
+    let i = 50; // Integers store whole numbers.
+    let f = 36.6; // Floats are used to store numbers with decimals or fractions.
+    let b = true; // Boolean values can be either 'true' or 'false'.
+    let c = '!'; // Characters represent a single UTF8 character.
+    let message = "hello world"; // Strings are a sequence of characters.
 
     // Print the values stored in our varibales to the console
     println!("i = {}", i);
@@ -29,11 +23,10 @@ fn model(app: &App) -> Model {
     println!("c = {}", c);
     println!("message = {}", message);
 
-    Model { window }
-}
+    // Construct and define the size of our window using `.with_dimensions(width, height)`.
+    app.new_window().with_dimensions(640, 480).build().unwrap();
 
-fn event(_app: &App, model: Model, _event: Event) -> Model {
-    model
+    Model
 }
 
 fn view(_app: &App, _model: &Model, frame: Frame) -> Frame {

examples/basics/3_variable_scope.rs

@@ -2,60 +2,44 @@ extern crate nannou;
 
 use nannou::prelude::*;
 
-// This is how you make a global constant value. Accessible anywhere in your app
+// This is how you make a global constant value.
+// Constant values are accessible anywhere in your app but cannot be changed.
 const GLOBAL: i32 = 10;
 
 fn main() {
-    nannou::app(model).event(event).view(view).run();
+    nannou::app(model).run();
 }
 
 struct Model {
     foo: i32,
     bar: f64,
 }
 
-fn model(_app: &App) -> Model {
-    // Initialise our models variables
+fn model(app: &App) -> Model {
+    // Make a window.
+    app.new_window().event(event).view(view).build().unwrap();
+    // Initialise our model's fields.
     let foo = 80;
     let bar = 3.14;
-
-    // Construct and return the model with our initialised values
+    // Construct and return the model with our initialised values.
     Model { foo, bar }
 }
 
-fn event(_app: &App, model: Model, event: Event) -> Model {
+fn event(_app: &App, model: &mut Model, event: WindowEvent) {
     match event {
-        Event::WindowEvent {
-            simple: Some(event),
-            ..
-        } => {
-            match event {
-                // KEY EVENTS
-                KeyPressed(_key) => {
-                    println!("foo = {}", model.foo);
-                    println!("bar = {}", model.bar);
-                }
-
-                KeyReleased(_key) => {
-                    let local_var = 94;
-                    println!("local_variable to KeyReleased = {}", local_var);
-                }
-
-                // MOUSE EVENTS
-                MousePressed(_button) => {
-                    println!("global scope: GLOBAL = {}", GLOBAL);
-                }
-
-                _other => (),
-            }
+        KeyPressed(_key) => {
+            println!("foo = {}", model.foo);
+            println!("bar = {}", model.bar);
         }
-
-        // update gets called just before view every frame
-        Event::Update(_dt) => {}
-
-        _ => (),
+        KeyReleased(_key) => {
+            let local_var = 94;
+            println!("local_variable to KeyReleased = {}", local_var);
+        }
+        MousePressed(_button) => {
+            println!("global scope: GLOBAL = {}", GLOBAL);
+        }
+        _other => (),
     }
-    model
 }
 
 fn view(_app: &App, _model: &Model, frame: Frame) -> Frame {