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 {}
-
-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)
-    }
-}
-
-
+/// A component that can exit.
 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) {