Add more control over event loop

Author: NoraCodes

iui/examples/inputs.rs

@@ -50,7 +50,8 @@ fn main() {
         (input_group, slider, spinner, entry, multi)
     };
 
-    // Set up the outputs for the application.
+    // Set up the outputs for the application. Organization is very similar to the
+    // previous setup.
     let (output_group, add_label, sub_label, text_label, bigtext_label) = {
         let output_group = Group::new(&ui, "Outputs");
         let output_vbox = VerticalBox::new(&ui);
@@ -76,66 +77,52 @@ fn main() {
     window.set_child(&ui, hbox);
     window.show(&ui);
 
-    // This update_view function is defined inline so that it can capture the environment, rather than
-    // needing to be passed ui, the labels, and the state each time it is invoked.
-    // It is wrapped in a refcounted pointer so it can be shared with several other closures.
-    let update_view = Rc::new({
-        let ui = ui.clone();
-        let add_label = add_label.clone();
-        let sub_label = sub_label.clone();
-        let state = state.clone();
-        move || {
-            let state = state.borrow();
-            add_label.set_text(&ui, &format!("Added: {}", state.slider_val + state.spinner_val));
-            sub_label.set_text(&ui, &format!("Subtracted: {}", state.slider_val - state.spinner_val));
-            text_label.set_text(&ui, &format!("Text: {}", state.entry_val));
-            bigtext_label.set_text(&ui, &format!("Multiline Text: {}", state.multi_val));
-        }
-    });
-
     // These on_changed functions allow updating the application state when a
     // control changes its value.
-    // Note the calls to update_view after each change to the state!
 
     slider.on_changed(&ui, {
-        let update_view = update_view.clone();
         let state = state.clone();
-        move |val| {
-            state.borrow_mut().slider_val = val;
-            update_view();
-        }
+        move |val| { state.borrow_mut().slider_val = val; }
     });
 
     spinner.on_changed(&ui, {
-        let update_view = update_view.clone();
         let state = state.clone();
-        move |val| {
-            state.borrow_mut().spinner_val = val;
-            update_view();
-        }
+        move |val| { state.borrow_mut().spinner_val = val; }
     });
 
     entry.on_changed(&ui, {
-        let update_view = update_view.clone();
         let state = state.clone();
-        move |val| {
-            state.borrow_mut().entry_val = val;
-            update_view();
-        }
+        move |val| { state.borrow_mut().entry_val = val; }
     });
 
     multi.on_changed(&ui, {
-        let update_view = update_view.clone();
         let state = state.clone();
-        move |val| {
-            state.borrow_mut().multi_val = val;
-            update_view();
-        }
+        move |val| { state.borrow_mut().multi_val = val; }
     });
 
-    // The initial call to update_view sets up the initial GUI state.
-    update_view();
 
-    // Start the application.
-    ui.main();
+    // This update_view function is defined inline so that it can capture the environment, rather than
+    // needing to be passed ui, the labels, and the state each time it is invoked.
+    // It is defined last so that it can operate with the minimum number of `.clone()` calls (since
+    // the code won't need to access the controls after this).
+    // It is wrapped in a refcounted pointer so it can be shared with several other closures.
+    let update_view = Rc::new({
+        let ui = ui.clone();
+        move || {
+            let state = state.borrow();
+
+            // Update all the labels
+            add_label.set_text(&ui, &format!("Added: {}", state.slider_val + state.spinner_val));
+            sub_label.set_text(&ui, &format!("Subtracted: {}", state.slider_val - state.spinner_val));
+            text_label.set_text(&ui, &format!("Text: {}", state.entry_val));
+            bigtext_label.set_text(&ui, &format!("Multiline Text: {}", state.multi_val));
+        }
+    });
+
+    // Rather than just invoking ui.run(), using EventLoop gives a lot more control
+    // over the user interface event loop.
+    // Here, the on_tick() callback is used to update the view against the state.
+    let mut event_loop = ui.event_loop();
+    event_loop.on_tick(&ui, move || { update_view(); });
+    event_loop.run(&ui);
 }

iui/src/controls/entry.rs

@@ -137,7 +137,7 @@ impl TextEntry for Entry {
     fn value(&self, _ctx: &UI) -> String {
         unsafe { CStr::from_ptr(ui_sys::uiEntryText(self.uiEntry)).to_string_lossy().into_owned() }
     }
-    fn set_value(&self, ctx: &UI, value: &str) {
+    fn set_value(&self, _ctx: &UI, value: &str) {
         let cstring = CString::new(value.as_bytes().to_vec()).unwrap();
         unsafe { ui_sys::uiEntrySetText(self.uiEntry, cstring.as_ptr()) }
     }

iui/src/ffi_tools.rs

@@ -1,5 +1,7 @@
 //! Utilities to manage the state of the interface to the libUI bindings.
 use std::sync::atomic::{AtomicBool, Ordering, ATOMIC_BOOL_INIT};
+use std::mem;
+use libc::c_void;
 
 static INITIALIZED: AtomicBool = ATOMIC_BOOL_INIT;
 
@@ -30,3 +32,8 @@ pub unsafe fn unset_initialized() {
 pub fn is_initialized() -> bool {
     INITIALIZED.load(Ordering::SeqCst)
 }
+
+// Transmute a void-void callback into a Box<Box<FnMut()>>> and call it 
+pub extern "C" fn void_void_callback(data: *mut c_void) {
+    unsafe { mem::transmute::<*mut c_void, Box<Box<FnMut()>>>(data)() }
+}

iui/src/lib.rs

@@ -11,6 +11,8 @@
 //! underlying library.
 //! 
 //! After initialization, all the functionality used for creating actual UIs is in the [`controls`](controls/index.html) module. 
+//! 
+//! Fine-grained control of the event loop is avilable via the [`EventLoop`](struct.EventLoop.html) struct.
 
 #[macro_use]
 extern crate bitflags;
@@ -24,7 +26,7 @@ mod error;
 mod ffi_tools;
 pub mod controls;
 
-pub use ui::UI;
+pub use ui::{UI, EventLoop};
 pub use error::UIError;
 
 /// Common imports are packaged into this module. It's meant to be glob-imported: `use iui::prelude::*`.

iui/src/ui.rs

@@ -1,11 +1,14 @@
 use ui_sys;
 use error::UIError;
 use ffi_tools;
+use libc::{c_void, c_int};
 
 use std::rc::Rc;
 use std::marker::PhantomData;
 use std::ffi::CStr;
 use std::mem;
+use std::thread::sleep;
+use std::time::Duration;
 
 use controls::Window;
 
@@ -89,13 +92,125 @@ impl UI {
         }
     }
 
-    /// Hands control of this thread to the UI toolkit, allowing it to display the UI and respond to events. Does not return until the UI [quit](struct.UI.html#method.quit)s.
+    /// Hands control of this thread to the UI toolkit, allowing it to display the UI and respond to events. 
+    /// Does not return until the UI [quit](struct.UI.html#method.quit)s.
+    /// 
+    /// For more control, use the `EventLoop` struct.
     pub fn main(&self) {
-        unsafe { ui_sys::uiMain() }
+        self.event_loop().run(self);
+    }
+
+    /// Returns an `EventLoop`, a struct that allows you to step over iterations or events in the UI.
+    pub fn event_loop(&self) -> EventLoop {
+        unsafe { ui_sys::uiMainSteps() };
+        return EventLoop { _pd: PhantomData, callback: None }
     }
 
     /// Running this function causes the UI to quit, exiting from [main](struct.UI.html#method.main) and no longer showing any widgets.
+    /// 
+    /// Run in every window's default `on_closing` callback.
     pub fn quit(&self) {
         unsafe { ui_sys::uiQuit() }
     }
+
+    /// Add a callback to the UI queue. These callbacks are run when the UI main() method is called,
+    /// in the order in which they were queued.
+    /// 
+    /// # Example
+    /// 
+    /// ```
+    /// use iui::prelude::*;
+    /// 
+    /// let ui = UI::init().unwrap();
+    /// 
+    /// // Let the UI exit immediately
+    /// ui.quit();
+    /// 
+    /// ui.queue_main(|| { println!("Runs first") } );
+    /// ui.queue_main(|| { println!("Runs second") } );
+    /// ```
+    pub fn queue_main<F: FnMut()>(&self, callback: F) {
+        unsafe {
+            let mut data: Box<Box<FnMut()>> = Box::new(Box::new((callback)));
+            ui_sys::uiQueueMain(
+                ffi_tools::void_void_callback,
+                &mut *data as *mut Box<FnMut()> as *mut c_void,
+            );
+            mem::forget(data);
+        }
+    }
+
+    /// Set a callback to be run when the application quits.
+    pub fn on_should_quit<F: FnMut()>(&self, callback: F) {
+        unsafe {
+            let mut data: Box<Box<FnMut()>> = Box::new(Box::new(callback));
+            ui_sys::uiOnShouldQuit(
+                ffi_tools::void_void_callback,
+                &mut *data as *mut Box<FnMut()> as *mut c_void,
+            );
+            mem::forget(data);
+        }
+    }
+}
+
+/// Provides fine-grained control over the user interface event loop, exposing the `on_tick` event
+/// which allows integration with other event loops, custom logic on event ticks, etc.
+pub struct EventLoop {
+    // This PhantomData prevents UIToken from being Send and Sync
+    _pd: PhantomData<*mut ()>,
+    // This callback gets run during "run_delay" loops.
+    callback: Option<Box<FnMut()>>
+}
+
+impl EventLoop {
+    /// Set the given callback to run when the event loop is executed.
+    /// Note that if integrating other event loops you should consider
+    /// the potential benefits and drawbacks of the various run modes.
+    pub fn on_tick<F: FnMut() + 'static>(&mut self, _ctx: &UI, callback: F) {
+        self.callback = Some(Box::new(callback));
+    }
+
+    /// Executes a tick in the event loop, returning immediately.
+    /// The `on_tick` callback is executed after the UI step.
+    /// 
+    /// Returns `true` if the application should continue running, and `false`
+    /// if it should quit.
+    pub fn next_tick(&mut self, _ctx: &UI) -> bool {
+        let result = unsafe { ui_sys::uiMainStep(false as c_int) == 1 };
+        if let Some(ref mut c) = self.callback {
+            c();
+        }
+        result
+    }
+
+    /// Hands control to the event loop until the next UI event occurs.
+    /// The `on_tick` callback is executed after the UI step.
+    /// 
+    /// Returns `true` if the application should continue running, and `false`
+    /// if it should quit.
+    pub fn next_event_tick(&mut self, _ctx: &UI) -> bool {
+        let result = unsafe { ui_sys::uiMainStep(true as c_int) == 1 };
+        if let Some(ref mut c) = self.callback {
+            c();
+        }
+        result
+    }
+
+    /// Hands control to the event loop until [`UI::quit()`](struct.UI.html#method.quit) is called,
+    /// running the callback given with `on_tick` after each UI event.
+    pub fn run(&mut self, ctx: &UI) {
+        loop {
+            if !self.next_event_tick(ctx) { break; }
+        }
+    }
+
+    /// Hands control to the event loop until [`UI::quit()`](struct.UI.html#method.quit) is called,
+    /// running the callback given with `on_tick` approximately every
+    /// `delay` milliseconds.
+    pub fn run_delay(&mut self, ctx: &UI, delay_ms: u32) {
+        loop {
+            if !self.next_tick(ctx) { break; }
+        }
+        sleep(Duration::new(0, delay_ms * 1000000))
+    }
 }

ui-sys/src/ffi.rs

@@ -17,6 +17,8 @@ extern {
     pub fn uiFreeInitError(err: *const c_char);
 
     pub fn uiMain();
+    pub fn uiMainStep(wait: c_int) -> c_int;
+    pub fn uiMainSteps();
     pub fn uiQuit();
 
     pub fn uiQueueMain(f: extern "C" fn(data: *mut c_void), data: *mut c_void);

ui-sys/src/lib.rs

@@ -25,6 +25,8 @@ extern {
     pub fn uiFreeInitError(err: *const c_char);
 
     pub fn uiMain();
+    pub fn uiMainStep(wait: c_int) -> c_int;
+    pub fn uiMainSteps();
     pub fn uiQuit();
 
     pub fn uiQueueMain(f: extern "C" fn(data: *mut c_void), data: *mut c_void);