Merge pull request #456 from kas-gui/work2

Rename Application → Runner

CHANGELOG.md

@@ -2,6 +2,10 @@
 The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+-   Rename `Application` → `Runner`
+
 ## [0.14.2] — 2023-12-12
 
 -   Add `kas-widgets::edit::InstantParseGuard` (#427)

crates/kas-core/src/action.rs

@@ -15,7 +15,7 @@ bitflags! {
     /// An `Action` produced at run-time should be passed to a context:
     /// `cx.action(self.id(), action)` (assuming `self` is a widget).
     /// An `Action` produced before starting the GUI may be discarded, for
-    /// example: `let _ = app.config_mut().font.set_size(24.0);`.
+    /// example: `let _ = runner.config_mut().font.set_size(24.0);`.
     ///
     /// Two `Action` values may be combined via bit-or (`a | b`).
     #[must_use]

crates/kas-core/src/draw/draw.rs

@@ -39,8 +39,8 @@ use std::time::Instant;
 /// }
 /// ```
 ///
-/// Note that this object is little more than a mutable reference to application
-/// shared draw state. As such, it is normal to pass *a new copy* created
+/// This object is effectively a fat pointer to draw state (both window-local
+/// and shared components). As such, it is normal to pass *a new copy* created
 /// via [`DrawIface::re`] as a method argument. (Note that Rust automatically
 /// "reborrows" reference types passed as method arguments, but cannot do so
 /// automatically for structs containing references.)

crates/kas-core/src/event/cx/cx_pub.rs

@@ -808,7 +808,7 @@ impl<'a> EventCx<'a> {
         log::trace!(target: "kas_core::event", "add_popup: {popup:?}");
 
         let parent_id = self.window.window_id();
-        let id = self.shared.add_popup(parent_id, popup.clone());
+        let id = self.runner.add_popup(parent_id, popup.clone());
         let nav_focus = self.nav_focus.clone();
         self.popups.push((id, popup, nav_focus));
         self.clear_nav_focus();
@@ -822,7 +822,7 @@ impl<'a> EventCx<'a> {
     /// available to a running UI. This method may be used instead.
     ///
     /// Requirement: the type `Data` must match the type of data passed to the
-    /// [`Application`](crate::app::Application) and used by other windows.
+    /// [`Runner`](crate::runner::Runner) and used by other windows.
     /// If not, a run-time error will result.
     ///
     /// Caveat: if an error occurs opening the new window it will not be
@@ -832,7 +832,7 @@ impl<'a> EventCx<'a> {
         let data_type_id = std::any::TypeId::of::<Data>();
         unsafe {
             let window: Window<()> = std::mem::transmute(window);
-            self.shared.add_window(window, data_type_id)
+            self.runner.add_window(window, data_type_id)
         }
     }
 
@@ -849,15 +849,15 @@ impl<'a> EventCx<'a> {
         {
             let (wid, popup, onf) = self.popups.remove(index);
             self.popup_removed.push((popup.id, wid));
-            self.shared.close_window(wid);
+            self.runner.close_window(wid);
 
             if let Some(id) = onf {
                 self.set_nav_focus(id, FocusSource::Synthetic);
             }
             return;
         }
 
-        self.shared.close_window(id);
+        self.runner.close_window(id);
     }
 
     /// Enable window dragging for current click
@@ -901,7 +901,7 @@ impl<'a> EventCx<'a> {
             };
         }
 
-        self.shared.get_clipboard()
+        self.runner.get_clipboard()
     }
 
     /// Attempt to set clipboard contents
@@ -913,7 +913,7 @@ impl<'a> EventCx<'a> {
             return;
         }
 
-        self.shared.set_clipboard(content)
+        self.runner.set_clipboard(content)
     }
 
     /// True if the primary buffer is enabled
@@ -945,7 +945,7 @@ impl<'a> EventCx<'a> {
             };
         }
 
-        self.shared.get_primary()
+        self.runner.get_primary()
     }
 
     /// Set contents of primary buffer
@@ -960,7 +960,7 @@ impl<'a> EventCx<'a> {
             return;
         }
 
-        self.shared.set_primary(content)
+        self.runner.set_primary(content)
     }
 
     /// Get a [`SizeCx`]
@@ -981,7 +981,7 @@ impl<'a> EventCx<'a> {
 
     /// Get a [`DrawShared`]
     pub fn draw_shared(&mut self) -> &mut dyn DrawShared {
-        self.shared.draw_shared()
+        self.runner.draw_shared()
     }
 
     /// Directly access Winit Window

crates/kas-core/src/event/cx/mod.rs

@@ -17,11 +17,11 @@ use std::pin::Pin;
 use std::time::Instant;
 
 use super::*;
-use crate::app::{AppShared, Platform, WindowDataErased};
 use crate::cast::Cast;
 use crate::config::WindowConfig;
 use crate::geom::Coord;
 use crate::messages::{Erased, MessageStack};
+use crate::runner::{Platform, RunnerT, WindowDataErased};
 use crate::util::WidgetHierarchy;
 use crate::{Action, Id, NavAdvance, Node, WindowId};
 
@@ -420,7 +420,7 @@ impl EventState {
 #[must_use]
 pub struct EventCx<'a> {
     state: &'a mut EventState,
-    shared: &'a mut dyn AppShared,
+    runner: &'a mut dyn RunnerT,
     window: &'a dyn WindowDataErased,
     messages: &'a mut MessageStack,
     pub(crate) target_is_disabled: bool,

crates/kas-core/src/event/cx/platform.rs

@@ -108,14 +108,14 @@ impl EventState {
     #[inline]
     pub(crate) fn with<'a, F: FnOnce(&mut EventCx)>(
         &'a mut self,
-        shared: &'a mut dyn AppShared,
+        runner: &'a mut dyn RunnerT,
         window: &'a dyn WindowDataErased,
         messages: &'a mut MessageStack,
         f: F,
     ) {
         let mut cx = EventCx {
             state: self,
-            shared,
+            runner,
             window,
             messages,
             target_is_disabled: false,
@@ -128,13 +128,13 @@ impl EventState {
     /// Handle all pending items before event loop sleeps
     pub(crate) fn flush_pending<'a, A>(
         &'a mut self,
-        shared: &'a mut dyn AppShared,
+        runner: &'a mut dyn RunnerT,
         window: &'a dyn WindowDataErased,
         messages: &'a mut MessageStack,
         win: &mut Window<A>,
         data: &A,
     ) -> Action {
-        self.with(shared, window, messages, |cx| {
+        self.with(runner, window, messages, |cx| {
             while let Some((id, wid)) = cx.popup_removed.pop() {
                 cx.send_event(win.as_node(data), id, Event::PopupClosed(wid));
             }
@@ -309,7 +309,7 @@ impl<'a> EventCx<'a> {
         let mut i = 0;
         while i < self.state.fut_messages.len() {
             let (_, fut) = &mut self.state.fut_messages[i];
-            let mut cx = std::task::Context::from_waker(self.shared.waker());
+            let mut cx = std::task::Context::from_waker(self.runner.waker());
             match fut.as_mut().poll(&mut cx) {
                 Poll::Pending => {
                     i += 1;

crates/kas-core/src/event/mod.rs

@@ -37,7 +37,7 @@
 //!     -   If the message stack is non-empty (see [`EventCx::push`]),
 //!         call [`Events::handle_messages`].
 //! 7.  If the message stack is not empty, call
-//!     [`AppData::handle_messages`](crate::app::AppData::handle_messages).
+//!     [`AppData::handle_messages`](crate::runner::AppData::handle_messages).
 //! 8.  Clear any messages still on the message stack, printing a warning to the
 //!     log. Messages *should* be handled during unwinding, though not doing so
 //!     is safe (and possibly useful during development).

crates/kas-core/src/lib.rs

@@ -38,7 +38,6 @@ pub use kas_macros::{cell_collection, collection, impl_anon, impl_scope, widget_
 pub use root::{Window, WindowCommand, WindowId};
 
 // public implementations:
-pub mod app;
 pub mod classes;
 pub mod config;
 pub mod dir;
@@ -51,6 +50,7 @@ pub mod hidden;
 pub mod layout;
 pub mod messages;
 pub mod prelude;
+pub mod runner;
 pub mod text;
 pub mod theme;
 pub mod util;

crates/kas-core/src/app/common.rs → crates/kas-core/src/runner/common.rs

@@ -13,7 +13,7 @@ use raw_window_handle as rwh;
 use std::time::Instant;
 use thiserror::Error;
 
-/// Possible failures from constructing an [`Application`](super::Application)
+/// Possible failures from constructing a [`Runner`](super::Runner)
 ///
 /// Some variants are undocumented. Users should not match these variants since
 /// they are not considered part of the public API.
@@ -174,8 +174,8 @@ impl Platform {
 
 /// Builder for a graphics backend
 ///
-/// See also [`Application`](super::Application).
-pub trait AppGraphicsBuilder {
+/// See also [`Runner`](super::Runner).
+pub trait GraphicsBuilder {
     /// The default theme
     type DefaultTheme: Default + Theme<Self::Shared>;
 

crates/kas-core/src/app/event_loop.rs → crates/kas-core/src/runner/event_loop.rs

@@ -5,7 +5,7 @@
 
 //! Event loop and handling
 
-use super::{AppData, AppGraphicsBuilder, AppState, Pending};
+use super::{AppData, GraphicsBuilder, Pending, State};
 use super::{ProxyAction, Window};
 use crate::theme::Theme;
 use crate::{Action, WindowId};
@@ -17,7 +17,7 @@ use winit::event_loop::{ActiveEventLoop, ControlFlow};
 use winit::window as ww;
 
 /// Event-loop data structure (i.e. all run-time state)
-pub(super) struct Loop<A: AppData, G: AppGraphicsBuilder, T: Theme<G::Shared>>
+pub(super) struct Loop<A: AppData, G: GraphicsBuilder, T: Theme<G::Shared>>
 where
     T::Window: kas::theme::Window,
 {
@@ -29,14 +29,14 @@ where
     /// Translates our WindowId to winit's
     id_map: HashMap<ww::WindowId, WindowId>,
     /// Application state passed from Toolkit
-    state: AppState<A, G, T>,
+    state: State<A, G, T>,
     /// Timer resumes: (time, window identifier)
     resumes: Vec<(Instant, WindowId)>,
 }
 
 impl<A: AppData, G, T> ApplicationHandler<ProxyAction> for Loop<A, G, T>
 where
-    G: AppGraphicsBuilder,
+    G: GraphicsBuilder,
     T: Theme<G::Shared>,
     T::Window: kas::theme::Window,
 {
@@ -164,11 +164,11 @@ where
     }
 }
 
-impl<A: AppData, G: AppGraphicsBuilder, T: Theme<G::Shared>> Loop<A, G, T>
+impl<A: AppData, G: GraphicsBuilder, T: Theme<G::Shared>> Loop<A, G, T>
 where
     T::Window: kas::theme::Window,
 {
-    pub(super) fn new(mut windows: Vec<Box<Window<A, G, T>>>, state: AppState<A, G, T>) -> Self {
+    pub(super) fn new(mut windows: Vec<Box<Window<A, G, T>>>, state: State<A, G, T>) -> Self {
         Loop {
             suspended: true,
             windows: windows.drain(..).map(|w| (w.window_id, w)).collect(),

crates/kas-core/src/app/mod.rs → crates/kas-core/src/runner/mod.rs

@@ -3,29 +3,30 @@
 // You may obtain a copy of the License in the LICENSE-APACHE file or at:
 //     https://www.apache.org/licenses/LICENSE-2.0
 
-//! Application, platforms and backends
+//! Runner, platforms and backends
 
-#[cfg(winit)] mod app;
 mod common;
 #[cfg(winit)] mod event_loop;
+#[cfg(winit)] mod runner;
 #[cfg(winit)] mod shared;
 #[cfg(winit)] mod window;
 
 use crate::messages::MessageStack;
 #[cfg(winit)] use crate::WindowId;
-#[cfg(winit)] use app::PlatformWrapper;
 #[cfg(winit)] use event_loop::Loop;
-#[cfg(winit)] pub(crate) use shared::{AppShared, AppState};
+#[cfg(winit)] use runner::PlatformWrapper;
+#[cfg(winit)] pub(crate) use shared::RunnerT;
+#[cfg(winit)] use shared::State;
 #[cfg(winit)]
 pub(crate) use window::{Window, WindowDataErased};
 
-#[cfg(winit)]
-pub use app::{AppBuilder, Application, ApplicationInherent, ClosedError, Proxy};
 pub use common::{Error, Platform, Result};
+#[cfg(winit)]
+pub use runner::{Builder, ClosedError, Proxy, Runner, RunnerInherent};
 
 #[cfg_attr(not(feature = "internal_doc"), doc(hidden))]
 #[cfg_attr(docsrs, doc(cfg(internal_doc)))]
-pub use common::{AppGraphicsBuilder, WindowSurface};
+pub use common::{GraphicsBuilder, WindowSurface};
 
 #[cfg_attr(not(feature = "internal_doc"), doc(hidden))]
 #[cfg_attr(docsrs, doc(cfg(internal_doc)))]
@@ -53,7 +54,7 @@ impl AppData for () {
 
 #[crate::autoimpl(Debug)]
 #[cfg(winit)]
-enum Pending<A: AppData, G: AppGraphicsBuilder, T: kas::theme::Theme<G::Shared>> {
+enum Pending<A: AppData, G: GraphicsBuilder, T: kas::theme::Theme<G::Shared>> {
     AddPopup(WindowId, WindowId, kas::PopupDescriptor),
     // NOTE: we don't need G, T here if we construct the Window later.
     // But this way we can pass a single boxed value.
@@ -276,7 +277,7 @@ mod test {
     }
 
     struct AGB;
-    impl AppGraphicsBuilder for AGB {
+    impl GraphicsBuilder for AGB {
         type DefaultTheme = crate::theme::SimpleTheme;
 
         type Shared = DrawShared;