Introduce Program and State

native/Cargo.toml

@@ -7,6 +7,9 @@ description = "A renderer-agnostic library for native GUIs"
 license = "MIT"
 repository = "https://github.com/hecrj/iced"
 
+[features]
+debug = []
+
 [dependencies]
 twox-hash = "1.5"
 unicode-segmentation = "1.6"

native/src/debug/basic.rs

@@ -0,0 +1,211 @@
+use std::{collections::VecDeque, time};
+
+#[derive(Debug)]
+pub struct Debug {
+    is_enabled: bool,
+
+    startup_start: time::Instant,
+    startup_duration: time::Duration,
+
+    update_start: time::Instant,
+    update_durations: TimeBuffer,
+
+    view_start: time::Instant,
+    view_durations: TimeBuffer,
+
+    layout_start: time::Instant,
+    layout_durations: TimeBuffer,
+
+    event_start: time::Instant,
+    event_durations: TimeBuffer,
+
+    draw_start: time::Instant,
+    draw_durations: TimeBuffer,
+
+    render_start: time::Instant,
+    render_durations: TimeBuffer,
+
+    message_count: usize,
+    last_messages: VecDeque<String>,
+}
+
+impl Debug {
+    pub fn new() -> Self {
+        let now = time::Instant::now();
+
+        Self {
+            is_enabled: false,
+            startup_start: now,
+            startup_duration: time::Duration::from_secs(0),
+
+            update_start: now,
+            update_durations: TimeBuffer::new(200),
+
+            view_start: now,
+            view_durations: TimeBuffer::new(200),
+
+            layout_start: now,
+            layout_durations: TimeBuffer::new(200),
+
+            event_start: now,
+            event_durations: TimeBuffer::new(200),
+
+            draw_start: now,
+            draw_durations: TimeBuffer::new(200),
+
+            render_start: now,
+            render_durations: TimeBuffer::new(50),
+
+            message_count: 0,
+            last_messages: VecDeque::new(),
+        }
+    }
+
+    pub fn toggle(&mut self) {
+        self.is_enabled = !self.is_enabled;
+    }
+
+    pub fn startup_started(&mut self) {
+        self.startup_start = time::Instant::now();
+    }
+
+    pub fn startup_finished(&mut self) {
+        self.startup_duration = time::Instant::now() - self.startup_start;
+    }
+
+    pub fn update_started(&mut self) {
+        self.update_start = time::Instant::now();
+    }
+
+    pub fn update_finished(&mut self) {
+        self.update_durations
+            .push(time::Instant::now() - self.update_start);
+    }
+
+    pub fn view_started(&mut self) {
+        self.view_start = time::Instant::now();
+    }
+
+    pub fn view_finished(&mut self) {
+        self.view_durations
+            .push(time::Instant::now() - self.view_start);
+    }
+
+    pub fn layout_started(&mut self) {
+        self.layout_start = time::Instant::now();
+    }
+
+    pub fn layout_finished(&mut self) {
+        self.layout_durations
+            .push(time::Instant::now() - self.layout_start);
+    }
+
+    pub fn event_processing_started(&mut self) {
+        self.event_start = time::Instant::now();
+    }
+
+    pub fn event_processing_finished(&mut self) {
+        self.event_durations
+            .push(time::Instant::now() - self.event_start);
+    }
+
+    pub fn draw_started(&mut self) {
+        self.draw_start = time::Instant::now();
+    }
+
+    pub fn draw_finished(&mut self) {
+        self.draw_durations
+            .push(time::Instant::now() - self.draw_start);
+    }
+
+    pub fn render_started(&mut self) {
+        self.render_start = time::Instant::now();
+    }
+
+    pub fn render_finished(&mut self) {
+        self.render_durations
+            .push(time::Instant::now() - self.render_start);
+    }
+
+    pub fn log_message<Message: std::fmt::Debug>(&mut self, message: &Message) {
+        self.last_messages.push_back(format!("{:?}", message));
+
+        if self.last_messages.len() > 10 {
+            let _ = self.last_messages.pop_front();
+        }
+
+        self.message_count += 1;
+    }
+
+    pub fn overlay(&self) -> Vec<String> {
+        if !self.is_enabled {
+            return Vec::new();
+        }
+
+        let mut lines = Vec::new();
+
+        fn key_value<T: std::fmt::Debug>(key: &str, value: T) -> String {
+            format!("{} {:?}", key, value)
+        }
+
+        lines.push(format!(
+            "{} {} - {}",
+            env!("CARGO_PKG_NAME"),
+            env!("CARGO_PKG_VERSION"),
+            env!("CARGO_PKG_REPOSITORY"),
+        ));
+        lines.push(key_value("Startup:", self.startup_duration));
+        lines.push(key_value("Update:", self.update_durations.average()));
+        lines.push(key_value("View:", self.view_durations.average()));
+        lines.push(key_value("Layout:", self.layout_durations.average()));
+        lines.push(key_value(
+            "Event processing:",
+            self.event_durations.average(),
+        ));
+        lines.push(key_value(
+            "Primitive generation:",
+            self.draw_durations.average(),
+        ));
+        lines.push(key_value("Render:", self.render_durations.average()));
+        lines.push(key_value("Message count:", self.message_count));
+        lines.push(String::from("Last messages:"));
+        lines.extend(
+            self.last_messages.iter().map(|msg| format!("    {}", msg)),
+        );
+
+        lines
+    }
+}
+
+#[derive(Debug)]
+struct TimeBuffer {
+    head: usize,
+    size: usize,
+    contents: Vec<time::Duration>,
+}
+
+impl TimeBuffer {
+    fn new(capacity: usize) -> TimeBuffer {
+        TimeBuffer {
+            head: 0,
+            size: 0,
+            contents: vec![time::Duration::from_secs(0); capacity],
+        }
+    }
+
+    fn push(&mut self, duration: time::Duration) {
+        self.head = (self.head + 1) % self.contents.len();
+        self.contents[self.head] = duration;
+        self.size = (self.size + 1).min(self.contents.len());
+    }
+
+    fn average(&self) -> time::Duration {
+        let sum: time::Duration = if self.size == self.contents.len() {
+            self.contents[..].iter().sum()
+        } else {
+            self.contents[..self.size].iter().sum()
+        };
+
+        sum / self.size.max(1) as u32
+    }
+}

native/src/debug/null.rs

@@ -0,0 +1,46 @@
+#[derive(Debug)]
+pub struct Debug;
+
+impl Debug {
+    pub fn new() -> Self {
+        Self
+    }
+
+    pub fn startup_started(&mut self) {}
+
+    pub fn startup_finished(&mut self) {}
+
+    pub fn update_started(&mut self) {}
+
+    pub fn update_finished(&mut self) {}
+
+    pub fn view_started(&mut self) {}
+
+    pub fn view_finished(&mut self) {}
+
+    pub fn layout_started(&mut self) {}
+
+    pub fn layout_finished(&mut self) {}
+
+    pub fn event_processing_started(&mut self) {}
+
+    pub fn event_processing_finished(&mut self) {}
+
+    pub fn draw_started(&mut self) {}
+
+    pub fn draw_finished(&mut self) {}
+
+    pub fn render_started(&mut self) {}
+
+    pub fn render_finished(&mut self) {}
+
+    pub fn log_message<Message: std::fmt::Debug>(
+        &mut self,
+        _message: &Message,
+    ) {
+    }
+
+    pub fn overlay(&self) -> Vec<String> {
+        Vec::new()
+    }
+}

native/src/lib.rs

@@ -34,7 +34,7 @@
 //! [`window::Backend`]: window/trait.Backend.html
 //! [`UserInterface`]: struct.UserInterface.html
 //! [renderer]: renderer/index.html
-#![deny(missing_docs)]
+//#![deny(missing_docs)]
 #![deny(missing_debug_implementations)]
 #![deny(unused_results)]
 #![forbid(unsafe_code)]
@@ -42,6 +42,7 @@
 pub mod keyboard;
 pub mod layout;
 pub mod mouse;
+pub mod program;
 pub mod renderer;
 pub mod subscription;
 pub mod widget;
@@ -54,6 +55,15 @@ mod hasher;
 mod runtime;
 mod user_interface;
 
+// We disable debug capabilities on release builds unless the `debug` feature
+// is explicitly enabled.
+#[cfg(feature = "debug")]
+#[path = "debug/basic.rs"]
+mod debug;
+#[cfg(not(feature = "debug"))]
+#[path = "debug/null.rs"]
+mod debug;
+
 pub use iced_core::{
     Align, Background, Color, Font, HorizontalAlignment, Length, Point,
     Rectangle, Size, Vector, VerticalAlignment,
@@ -64,10 +74,12 @@ pub use iced_futures::{executor, futures, Command};
 pub use executor::Executor;
 
 pub use clipboard::Clipboard;
+pub use debug::Debug;
 pub use element::Element;
 pub use event::Event;
 pub use hasher::Hasher;
 pub use layout::Layout;
+pub use program::Program;
 pub use renderer::Renderer;
 pub use runtime::Runtime;
 pub use subscription::Subscription;

native/src/program.rs

@@ -0,0 +1,39 @@
+//! Build interactive programs using The Elm Architecture.
+use crate::{Command, Element, Renderer};
+
+mod state;
+
+pub use state::State;
+
+/// An interactive, native cross-platform program.
+pub trait Program: Sized {
+    /// The graphics backend to use to draw the [`Program`].
+    ///
+    /// [`Program`]: trait.Program.html
+    type Renderer: Renderer;
+
+    /// The type of __messages__ your [`Program`] will produce.
+    ///
+    /// [`Application`]: trait.Program.html
+    type Message: std::fmt::Debug + Send;
+
+    /// Handles a __message__ and updates the state of the [`Program`].
+    ///
+    /// 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 by shells.
+    ///
+    /// [`Program`]: trait.Application.html
+    /// [`Command`]: struct.Command.html
+    fn update(&mut self, message: Self::Message) -> Command<Self::Message>;
+
+    /// Returns the widgets to display in the [`Program`].
+    ///
+    /// These widgets can produce __messages__ based on user interaction.
+    ///
+    /// [`Program`]: trait.Application.html
+    fn view(&mut self) -> Element<'_, Self::Message, Self::Renderer>;
+}

native/src/program/state.rs

@@ -0,0 +1,154 @@
+use crate::{
+    Cache, Clipboard, Command, Debug, Event, Program, Renderer, Size,
+    UserInterface,
+};
+
+#[allow(missing_debug_implementations)]
+pub struct State<P>
+where
+    P: Program + 'static,
+{
+    program: P,
+    cache: Option<Cache>,
+    primitive: <P::Renderer as Renderer>::Output,
+    queued_events: Vec<Event>,
+    queued_messages: Vec<P::Message>,
+}
+
+impl<P> State<P>
+where
+    P: Program + 'static,
+{
+    pub fn new(
+        mut program: P,
+        bounds: Size,
+        renderer: &mut P::Renderer,
+        debug: &mut Debug,
+    ) -> Self {
+        let user_interface = build_user_interface(
+            &mut program,
+            Cache::default(),
+            renderer,
+            bounds,
+            debug,
+        );
+
+        debug.draw_started();
+        let primitive = user_interface.draw(renderer);
+        debug.draw_finished();
+
+        let cache = Some(user_interface.into_cache());
+
+        State {
+            program,
+            cache,
+            primitive,
+            queued_events: Vec::new(),
+            queued_messages: Vec::new(),
+        }
+    }
+
+    pub fn program(&self) -> &P {
+        &self.program
+    }
+
+    pub fn primitive(&self) -> &<P::Renderer as Renderer>::Output {
+        &self.primitive
+    }
+
+    pub fn queue_event(&mut self, event: Event) {
+        self.queued_events.push(event);
+    }
+
+    pub fn queue_message(&mut self, message: P::Message) {
+        self.queued_messages.push(message);
+    }
+
+    pub fn update(
+        &mut self,
+        clipboard: Option<&dyn Clipboard>,
+        bounds: Size,
+        renderer: &mut P::Renderer,
+        debug: &mut Debug,
+    ) -> Option<Command<P::Message>> {
+        if self.queued_events.is_empty() && self.queued_messages.is_empty() {
+            return None;
+        }
+
+        let mut user_interface = build_user_interface(
+            &mut self.program,
+            self.cache.take().unwrap(),
+            renderer,
+            bounds,
+            debug,
+        );
+
+        debug.event_processing_started();
+        let mut messages = user_interface.update(
+            self.queued_events.drain(..),
+            clipboard,
+            renderer,
+        );
+        messages.extend(self.queued_messages.drain(..));
+        debug.event_processing_finished();
+
+        if messages.is_empty() {
+            debug.draw_started();
+            self.primitive = user_interface.draw(renderer);
+            debug.draw_finished();
+
+            self.cache = Some(user_interface.into_cache());
+
+            None
+        } else {
+            // When there are messages, we are forced to rebuild twice
+            // for now :^)
+            let temp_cache = user_interface.into_cache();
+
+            let commands =
+                Command::batch(messages.into_iter().map(|message| {
+                    debug.log_message(&message);
+
+                    debug.update_started();
+                    let command = self.program.update(message);
+                    debug.update_finished();
+
+                    command
+                }));
+
+            let user_interface = build_user_interface(
+                &mut self.program,
+                temp_cache,
+                renderer,
+                bounds,
+                debug,
+            );
+
+            debug.draw_started();
+            self.primitive = user_interface.draw(renderer);
+            debug.draw_finished();
+
+            self.cache = Some(user_interface.into_cache());
+
+            Some(commands)
+        }
+    }
+}
+
+fn build_user_interface<'a, P: Program>(
+    program: &'a mut P,
+    cache: Cache,
+    renderer: &mut P::Renderer,
+    size: Size,
+    debug: &mut Debug,
+) -> UserInterface<'a, P::Message, P::Renderer> {
+    debug.view_started();
+    let view = program.view();
+    debug.view_finished();
+
+    debug.layout_started();
+    let user_interface = UserInterface::build(view, size, cache, renderer);
+    debug.layout_finished();
+
+    user_interface
+}