document; refactor focus; highlight scene/track titles

crates/tek_core/src/engine.rs

@@ -118,12 +118,12 @@ impl<E: Engine, W: Widget<Engine = E>> Widget for Option<W> {
         self.as_ref().map(|widget|widget.render(to)).unwrap_or(Ok(()))
     }
 }
-/// A component that consists of other components
+/// A [Widget] that contains other [Widget]s
 pub trait Content: Send + Sync {
     type Engine: Engine;
     fn content (&self) -> impl Widget<Engine = <Self as Content>::Engine>;
 }
-/// Every component is renderable
+/// Every struct that has [Content] is a renderable [Widget].
 impl<E: Engine, W: Content<Engine = E>> Widget for W {
     type Engine = E;
     fn layout (&self, to: E::Size) -> Perhaps<E::Size> {
@@ -136,6 +136,34 @@ impl<E: Engine, W: Content<Engine = E>> Widget for W {
         }
     }
 }
+/// A custom [Widget] defined by passing layout and render closures in place.
+pub struct CustomWidget<
+    E: Engine,
+    L: Send + Sync + Fn(E::Size)->Perhaps<E::Size>,
+    R: Send + Sync + Fn(&mut E::Output)->Usually<()>
+>(L, R, PhantomData<E>);
+impl<
+    E: Engine,
+    L: Send + Sync + Fn(E::Size)->Perhaps<E::Size>,
+    R: Send + Sync + Fn(&mut E::Output)->Usually<()>
+> CustomWidget<E, L, R> {
+    pub fn new (layout: L, render: R) -> Self {
+        Self(layout, render, Default::default())
+    }
+}
+impl<
+    E: Engine,
+    L: Send + Sync + Fn(E::Size)->Perhaps<E::Size>,
+    R: Send + Sync + Fn(&mut E::Output)->Usually<()>
+> Widget for CustomWidget<E, L, R> {
+    type Engine = E;
+    fn layout (&self, to: E::Size) -> Perhaps<E::Size> {
+        self.0(to)
+    }
+    fn render (&self, to: &mut E::Output) -> Usually<()> {
+        self.1(to)
+    }
+}
 /// Handle input
 pub trait Handle<E: Engine>: Send + Sync {
     fn handle (&mut self, context: &E::Input) -> Perhaps<E::Handled>;
@@ -174,45 +202,15 @@ impl<H, E: Engine> Handle<E> for Arc<RwLock<H>> where H: Handle<E> {
         self.write().unwrap().handle(context)
     }
 }
-/// A UI component that can render itself and handle input
+/// A UI component that can render itself as a [Widget], and [Handle] input.
 pub trait Component<E: Engine>: Widget<Engine = E> + Handle<E> {}
-/// Everything that implements [Render] and [Handle] is a [Component].
+/// Everything that implements [Widget] and [Handle] is a [Component].
 impl<E: Engine, C: Widget<Engine = E> + Handle<E>> Component<E> for C {}
-/// A UI component that can render itself and handle input
+/// A UI component that has [Content] and can [Handle] input.
 pub trait ContentComponent<E: Engine>: Widget<Engine = E> + Handle<E> {}
-/// Everything that implements [Render] and [Handle] is a [Component].
+/// Everything that implements [Content] and [Handle] is a [Component].
 impl<E: Engine, C: Content<Engine = E> + Handle<E>> ContentComponent<E> for C {}
-
+/// A component that can exit.
-pub struct CustomWidget<
-    E: Engine,
-    L: Send + Sync + Fn(E::Size)->Perhaps<E::Size>,
-    R: Send + Sync + Fn(&mut E::Output)->Usually<()>
->(L, R, PhantomData<E>);
-
-impl<
-    E: Engine,
-    L: Send + Sync + Fn(E::Size)->Perhaps<E::Size>,
-    R: Send + Sync + Fn(&mut E::Output)->Usually<()>
-> CustomWidget<E, L, R> {
-    pub fn new (layout: L, render: R) -> Self {
-        Self(layout, render, Default::default())
-    }
-}
-impl<
-    E: Engine,
-    L: Send + Sync + Fn(E::Size)->Perhaps<E::Size>,
-    R: Send + Sync + Fn(&mut E::Output)->Usually<()>
-> Widget for CustomWidget<E, L, R> {
-    type Engine = E;
-    fn layout (&self, to: E::Size) -> Perhaps<E::Size> {
-        self.0(to)
-    }
-    fn render (&self, to: &mut E::Output) -> Usually<()> {
-        self.1(to)
-    }
-}
-
-
 pub trait Exit: Send {
     fn exited (&self) -> bool;
     fn exit (&mut self);
@@ -220,109 +218,12 @@ pub trait Exit: Send {
         Box::new(self)
     }
 }
-
+/// Marker trait for [Component]s that can [Exit].
-/// Marker trait for [Component]s that can [Exit]
 pub trait ExitableComponent<E>: Exit + Component<E> where E: Engine {
     /// Perform type erasure for collecting heterogeneous components.
     fn boxed (self) -> Box<dyn ExitableComponent<E>> where Self: Sized + 'static {
         Box::new(self)
     }
 }
+/// All [Components]s that implement [Exit] implement [ExitableComponent].
 impl<E: Engine, C: Component<E> + Exit> ExitableComponent<E> for C {}
-
-/// A component that may contain [Focusable] components.
-pub trait Focus <const N: usize, E: Engine>: Widget<Engine = E> + Handle<E> {
-    fn focus (&self) -> usize;
-    fn focus_mut (&mut self) -> &mut usize;
-    fn focusable (&self) -> [&dyn Focusable<E>;N];
-    fn focusable_mut (&mut self) -> [&mut dyn Focusable<E>;N];
-
-    fn focused (&self) -> &dyn Focusable<E> {
-        let focus = self.focus();
-        self.focusable()[focus]
-    }
-    fn focused_mut (&mut self) -> &mut dyn Focusable<E> {
-        let focus = self.focus();
-        self.focusable_mut()[focus]
-    }
-    fn focus_prev (&mut self) {
-        let focus = self.focus();
-        self.focus_set(if focus > 0 { focus - 1 } else { N - 1 });
-    }
-    fn focus_next (&mut self) {
-        let focus = self.focus();
-        self.focus_set(if focus < N - 1 { focus + 1 } else { 0 });
-    }
-    fn focus_set (&mut self, focus: usize) {
-        *self.focus_mut() = focus;
-        let focusable = self.focusable_mut();
-        for index in 0..N {
-            focusable[index].set_focused(index == focus);
-        }
-    }
-}
-
-/// A component that may be focused.
-pub trait Focusable<E: Engine>: Widget<Engine = E> + Handle<E> {
-    fn is_focused (&self) -> bool;
-    fn set_focused (&mut self, focused: bool);
-}
-
-impl<F: Focusable<E>, E: Engine> Focusable<E> for Option<F>
-    where Option<F>: Widget<Engine = E>
-{
-    fn is_focused (&self) -> bool {
-        match self {
-            Some(focusable) => focusable.is_focused(),
-            None => false
-        }
-    }
-    fn set_focused (&mut self, focused: bool) {
-        if let Some(focusable) = self {
-            focusable.set_focused(focused)
-        }
-    }
-}
-
-/// Implement the [Focus] trait for a component.
-#[macro_export] macro_rules! focus {
-    ($struct:ident ($focus:ident) : $count:expr => [
-       $($focusable:ident),*
-    ]) => {
-        impl Focus<$count, E> for $struct {
-            fn focus (&self) -> usize {
-                self.$focus
-            }
-            fn focus_mut (&mut self) -> &mut usize {
-                &mut self.$focus
-            }
-            fn focusable (&self) -> [&dyn Focusable<E>;$count] {
-                [
-                    $(&self.$focusable as &dyn Focusable<E>,)*
-                ]
-            }
-            fn focusable_mut (&mut self) -> [&mut dyn Focusable<E>;$count] {
-                [
-                    $(&mut self.$focusable as &mut dyn Focusable<E>,)*
-                ]
-            }
-        }
-    }
-}
-
-/// Implement the [Focusable] trait for a component.
-#[macro_export] macro_rules! focusable {
-    ($struct:ident) => {
-        focusable!($struct (focused));
-    };
-    ($struct:ident ($focused:ident)) => {
-        impl Focusable for $struct {
-            fn is_focused (&self) -> bool {
-                self.$focused
-            }
-            fn set_focused (&mut self, focused: bool) {
-                self.$focused = focused
-            }
-        }
-    }
-}

crates/tek_core/src/focus.rs

@@ -0,0 +1,99 @@
+use crate::*;
+
+/// A component that may contain [Focusable] components.
+pub trait Focus <const N: usize, E: Engine>: Widget<Engine = E> + Handle<E> {
+    fn focus (&self) -> usize;
+    fn focus_mut (&mut self) -> &mut usize;
+    fn focusable (&self) -> [&dyn Focusable<E>;N];
+    fn focusable_mut (&mut self) -> [&mut dyn Focusable<E>;N];
+
+    fn focused (&self) -> &dyn Focusable<E> {
+        let focus = self.focus();
+        self.focusable()[focus]
+    }
+    fn focused_mut (&mut self) -> &mut dyn Focusable<E> {
+        let focus = self.focus();
+        self.focusable_mut()[focus]
+    }
+    fn focus_prev (&mut self) {
+        let focus = self.focus();
+        self.focus_set(if focus > 0 { focus - 1 } else { N - 1 });
+    }
+    fn focus_next (&mut self) {
+        let focus = self.focus();
+        self.focus_set(if focus < N - 1 { focus + 1 } else { 0 });
+    }
+    fn focus_set (&mut self, focus: usize) {
+        *self.focus_mut() = focus;
+        let focusable = self.focusable_mut();
+        for index in 0..N {
+            focusable[index].set_focused(index == focus);
+        }
+    }
+}
+
+/// A component that may be focused.
+pub trait Focusable<E: Engine>: Widget<Engine = E> + Handle<E> {
+    fn is_focused (&self) -> bool;
+    fn set_focused (&mut self, focused: bool);
+}
+
+impl<F: Focusable<E>, E: Engine> Focusable<E> for Option<F>
+    where Option<F>: Widget<Engine = E>
+{
+    fn is_focused (&self) -> bool {
+        match self {
+            Some(focusable) => focusable.is_focused(),
+            None => false
+        }
+    }
+    fn set_focused (&mut self, focused: bool) {
+        if let Some(focusable) = self {
+            focusable.set_focused(focused)
+        }
+    }
+}
+
+/// Implement the [Focus] trait for a component.
+#[macro_export] macro_rules! focus {
+    ($struct:ident ($focus:ident) : $count:expr => [
+       $($focusable:ident),*
+    ]) => {
+        impl Focus<$count, E> for $struct {
+            fn focus (&self) -> usize {
+                self.$focus
+            }
+            fn focus_mut (&mut self) -> &mut usize {
+                &mut self.$focus
+            }
+            fn focusable (&self) -> [&dyn Focusable<E>;$count] {
+                [$(&self.$focusable as &dyn Focusable<E>,)*]
+            }
+            fn focusable_mut (&mut self) -> [&mut dyn Focusable<E>;$count] {
+                [$(&mut self.$focusable as &mut dyn Focusable<E>,)*]
+            }
+        }
+    }
+}
+
+/// Implement the [Focusable] trait for a component.
+#[macro_export] macro_rules! focusable {
+    ($struct:ident) => {
+        focusable!($struct (focused));
+    };
+    ($struct:ident ($focused:ident)) => {
+        impl Focusable for $struct {
+            fn is_focused (&self) -> bool { self.$focused }
+            fn set_focused (&mut self, f: bool) { self.$focused = f }
+        }
+    }
+}
+
+#[macro_export] macro_rules! focusables {
+    ($($item:expr),* $(,)?) => { [$(&$item as &dyn Focusable<_>),+] }
+}
+
+#[macro_export] macro_rules! focusables_mut {
+    ($($item:expr),* $(,)?) => { [$(&mut $item as &mut dyn Focusable<_>),+] }
+}
+

crates/tek_core/src/lib.rs

@@ -39,6 +39,7 @@ submod! {
     audio
     edn
     engine
+    focus
     space
     time
     tui

crates/tek_core/src/space.rs

@@ -107,6 +107,8 @@ pub trait Area<N: Number>: Copy {
     #[inline] fn shrink_y (&self, y: N) -> [N;4] { [self.x(), self.y(), self.w(), self.h() - y] }
     #[inline] fn set_w    (&self, w: N) -> [N;4] { [self.x(), self.y(), w, self.h()] }
     #[inline] fn set_h    (&self, h: N) -> [N;4] { [self.x(), self.y(), self.w(), h] }
+    #[inline] fn clip_h   (&self, h: N) -> [N;4] { [self.x(), self.y(), self.w(), self.h().min(h)] }
+    #[inline] fn clip_w   (&self, w: N) -> [N;4] { [self.x(), self.y(), self.w().min(w), self.h()] }
 }
 
 impl<N: Number> Area<N> for (N, N, N, N) {

crates/tek_sequencer/src/main_arranger.rs

@@ -1,11 +1,7 @@
 include!("lib.rs");
-
 use tek_core::clap::{self, Parser};
-
+pub fn main () -> Usually<()> { ArrangerCli::parse().run() }
-pub fn main () -> Usually<()> {
+/// Parses CLI arguments to the `tek_arranger` invocation.
-    ArrangerCli::parse().run()
-}
-
 #[derive(Debug, Parser)]
 #[command(version, about, long_about = None)]
 pub struct ArrangerCli {
@@ -25,8 +21,8 @@ pub struct ArrangerCli {
     #[arg(short, long, default_value_t = 8)]
     scenes: usize,
 }
-
 impl ArrangerCli {
+    /// Run the arranger TUI from CLI arguments.
     fn run (&self) -> Usually<()> {
         let mut arranger = Arranger::new("");
         let mut transport = self.transport.then_some(TransportToolbar::new(None));
@@ -57,7 +53,7 @@ impl ArrangerCli {
         Ok(())
     }
 }
-
+/// Root level object for standalone `tek_arranger`
 struct ArrangerStandalone<E: Engine> {
     /// Controls the JACK transport.
     transport:      Option<TransportToolbar<E>>,
@@ -68,7 +64,7 @@ struct ArrangerStandalone<E: Engine> {
     /// 
     focus:          usize,
 }
-
+/// The standalone arranger consists of transport, clip grid, and sequencer.
 impl Content for ArrangerStandalone<Tui> {
     type Engine = Tui;
     fn content (&self) -> impl Widget<Engine = Tui> {
@@ -95,7 +91,7 @@ impl Content for ArrangerStandalone<Tui> {
         })
     }
 }
-
+/// Handle top-level events in standalone arranger.
 impl Handle<Tui> for ArrangerStandalone<Tui> {
     fn handle (&mut self, from: &TuiInput) -> Perhaps<bool> {
         match from.event() {
@@ -113,9 +109,9 @@ impl Handle<Tui> for ArrangerStandalone<Tui> {
                 self.focus_prev();
             },
             key!(KeyCode::Down) => {
-                if self.focus == 0 || (
+                if self.focus == 0 {
-                    self.focus == 1 && self.arranger.is_last_row()
+                    self.focus_next();
-                ) {
+                } else if self.focus == 1 && self.arranger.is_last_row() {
                     self.focus_next();
                 } else {
                     return self.focused_mut().handle(from)
@@ -133,7 +129,7 @@ impl Handle<Tui> for ArrangerStandalone<Tui> {
         Ok(Some(true))
     }
 }
-
+/// Focusable items in standalone arranger.
 impl Focus<2, Tui> for ArrangerStandalone<Tui> {
     fn focus (&self) -> usize {
         self.focus
@@ -142,15 +138,9 @@ impl Focus<2, Tui> for ArrangerStandalone<Tui> {
         &mut self.focus
     }
     fn focusable (&self) -> [&dyn Focusable<Tui>;2] {
-        [
+        focusables!(self.transport, self.arranger)
-            &self.transport as &dyn Focusable<Tui>,
-            &self.arranger  as &dyn Focusable<Tui>,
-        ]
     }
     fn focusable_mut (&mut self) -> [&mut dyn Focusable<Tui>;2] {
-        [
+        focusables_mut!(self.transport, self.arranger)
-            &mut self.transport as &mut dyn Focusable<Tui>,
-            &mut self.arranger  as &mut dyn Focusable<Tui>,
-        ]
     }
 }

crates/tek_sequencer/src/sequencer.rs

@@ -683,8 +683,10 @@ impl<'a> Widget for VerticalArrangerCursor<'a> {
                 to.render_in(clip_area, &CORNERS)?;
                 to.fill_bg(clip_area, Color::Rgb(40, 50, 30));
             } else if let Some(track_area) = track_area {
+                to.render_in(track_area.clip_h(2), &CORNERS)?;
                 to.fill_bg(track_area, Color::Rgb(40, 50, 30));
             } else if let Some(scene_area) = scene_area {
+                to.render_in(scene_area.clip_w(offset-1), &CORNERS)?;
                 to.fill_bg(scene_area, Color::Rgb(40, 50, 30));
             }
         }
@@ -2000,22 +2002,10 @@ impl Focus<5, Tui> for TransportToolbar<Tui> {
         &mut self.focus
     }
     fn focusable (&self) -> [&dyn Focusable<Tui>;5] {
-        [
+        focusables!(self.playing, self.bpm, self.quant, self.sync, self.clock)
-            &self.playing as &dyn Focusable<Tui>,
-            &self.bpm     as &dyn Focusable<Tui>,
-            &self.quant   as &dyn Focusable<Tui>,
-            &self.sync    as &dyn Focusable<Tui>,
-            &self.clock   as &dyn Focusable<Tui>,
-        ]
     }
     fn focusable_mut (&mut self) -> [&mut dyn Focusable<Tui>;5] {
-        [
+        focusables_mut!(self.playing, self.bpm, self.quant, self.sync, self.clock)
-            &mut self.playing as &mut dyn Focusable<Tui>,
-            &mut self.bpm     as &mut dyn Focusable<Tui>,
-            &mut self.quant   as &mut dyn Focusable<Tui>,
-            &mut self.sync    as &mut dyn Focusable<Tui>,
-            &mut self.clock   as &mut dyn Focusable<Tui>,
-        ]
     }
 }