Document all the things

Author: 13r0ck

README.md

@@ -1,11 +1,131 @@
-Very much still a WIP. API is mostly final and this can create animations. Just missing large amounts of features to make this useful in any real project.
+# COSMIC TIME
+## An animation toolkit for Iced-rs/Iced
 
-TODOs before release:
+> This Project was build for [Cosmic DE](https://github.com/pop-os/cosmic-epoch). Though this will work for any project that depends on [Iced](https://github.com/iced-rs/iced).
+
+
+ The goal of this project is to provide a simple API to build and show
+ complex animations efficiently in applications built with Iced-rs/Iced.
+
+## Project Goals:
+* Full compatibility with Iced and The Elm Architecture.
+* Ease of use.
+* No math required for any animation.
+* No heap allocations in render loop.
+* Provide additional animatable widgets.
+* Custom widget support (create your own!).
+
+## Overview
+To wire cosmic-time into Iced there are five steps to do.
+
+1. Create a [`Timeline`] This is the type that controls the animations.
+```rust
+struct Counter {
+      timeline: Timeline
+}
+
+// ~ SNIP
+
+impl Application for Counter {
+    // ~ SNIP
+     fn new(_flags: ()) -> (Self, Command<Message>) {
+        (Self { timeline: Timeline::new()}, Command::none())
+     }
+}
+```
+2. Add at least one animation to your timeline. This can be done in your
+   Application's `new()` or `update()`, or both!
+```rust
+static CONTAINER: Lazy<id::Container> = Lazy::new(id::Container::unique);
+
+let animation = chain![
+  CONTAINER,
+  container(Duration::ZERO).width(10),
+  container(Duration::from_secs(10)).width(100)
+];
+self.timeline.set_chain(animation).start();
+
+```
+There are some different things here!
+  > static CONTAINER: Lazy<id::Container> = Lazy::new(id::Container::unique);
+
+  Cosmic Time refers to each animation with an Id. We export our own, but they are
+  Identical to the widget Id's Iced uses for widget operations.
+  Each animatable widget needs an Id. And each Id can only refer to one animation.
+
+  > let animation = chain![
+
+  Cosmic Time refers to animations as [`Chain`]s because of how we build then.
+  Each [`Keyframe`] is linked together like a chain. The Cosmic Time API doesn't
+  say "change your width from 10 to 100". We define each state we want the
+  widget to have `.width(10)` at `Duration::ZERO` then `.width(100)` at
+  `Duration::from_secs(10)`. Where the `Duration` is the time after the previous
+  [`keyframe`]. This is why we call the animations chains. We cannot get to the
+  next state without animating though all previous [`Keyframe`]s.
+
+  > self.timeline.set_chain(animation).start();
+
+  Then we need to add the animation to the [`Timeline`]. We call this `.set_chain`,
+  because there can only be one chain per Id.
+  If we `set_chain` with a different animation with the same Id, the first one is
+  replaced. This a actually a feature not a bug!
+  As well you can set multiple animations at once:
+  `self.timeline.set_chain(animation1).set_chain(animation2).start()`
+
+  > .start()
+
+  This one function call is important enough that we should look at it specifically.
+  Cosmic Time is atomic, given the animation state held in the [`Timeline`] at any
+  given time the global animations will be the exact same. The value used to 
+  calculate any animation's interpolation is global. And we use `.start()` to
+  sync them together.
+  Say you have two 5 seconds animations running at the same time. They should end
+  at the same time right? That all depends on when the widget thinks it's animation
+  should start. `.start()` tells all pending animations to start at the moment that
+  `.start()` is called. This guarantees they stay in sync.
+  IMPORTANT! Be sure to only call `.start()` once per call to `update()`.
+  The below is incorrect!
+  ```rust
+  self.timeline.set_chain(animation1).start();
+  self.timeline.set_chain(animation2).start();
+  ```
+  That code will compile, but will result in the animations not being in sync.
+
+3. Add the Cosmic time Subscription
+```rust
+  fn subscription(&self) -> Subscription<Message> {
+       self.timeline.as_subscription::<Event>().map(Message::Tick)
+   }
+```
+
+4. Map the subscription to update the timeline's state:
+```rust
+fn update(&mut self, message: Message) -> Command<Message> {
+       match message {
+           Message::Tick(now) => self.timeline.now(now),
+       }
+   }
+```
+  If you skip this step your animations will not progress!
+
+5. Show the widget in your `view()`!
+```rust
+anim!(CONTIANER, &self.timeline, contents)
+```
+
+All done!
+There is a bit of wiring to get Cosmic Time working, but after that it's only
+a few lines to create rather complex animations!
+See the Pong example to see how a full game of pong can be implemented in
+only a few lines!
+
+Done:
 - [x] No heap allocations in animation render loop
-- [x] Compile time type guarentee that animation id will match correct animation to correct widget type.
+- [x] Compile time type guarantee that animation id will match correct animation to correct widget type.
 - [x] Animatable container widget
 - [x] Looping animations
 - [x] Animation easing
+- [x] test for easing
 - [x] add space widget
 - [x] add button widget
 - [x] add row widget
@@ -14,16 +134,15 @@ TODOs before release:
 - [x] Use iced 0.8
 - [x] use iced 0.8's framerate subscription
 - [x] Add logic for different animation Ease values
-- [ ] Documentation
-- [ ] Add `Cosmic` cargo feature for compatibility with both iced and System76's temporary fork.
+- [x] Documentation
 - [x] optimize for `as_subscription` logic
 - [x] Add pause for animations
-- [ ] Lazy keyframes. (Keyframes that can use the position of a previous (active or not) animation to start another animation.)
+- [x] Lazy keyframes. (Keyframes that can use the position of a previous (active or not) animation to start another animation.)
 
-Other TODOs:
-- [x] test for easing
+TODOs:
+- [ ] Add `Cosmic` cargo feature for compatibility with both iced and System76's temporary fork.
+- [ ] Low motion accesability detection to disable animations.
 - [ ] general animation logic tests
+- [ ] Work on web via wasm-unknown-unknown builds
 - [ ] physics based animations
-- [ ] Low motion accesability detection to disable animations.
 - [ ] Figure out what else needs to be on this list
-- [ ] Work on web via wasm-unknown-unknown builds

src/keyframes.rs

@@ -25,6 +25,8 @@ pub use toggler::Toggler;
 
 use crate::Timeline;
 
+/// The macro used to cleanly and efficently build an animation chain.
+/// Works for ann Id's that implement `into_chain` and `into_chain_with_children`
 #[macro_export]
 macro_rules! chain{
   ($id:expr) => {
@@ -35,6 +37,7 @@ macro_rules! chain{
   };
 }
 
+/// The macro used to clean up animation's view code.
 #[macro_export]
 macro_rules! anim{
   ($id:expr, $($x:expr),+ $(,)?) => {

src/keyframes/button.rs

@@ -21,14 +21,17 @@ impl Id {
         Self(widget::Id::unique())
     }
 
+    /// Used by [`chain!`] macro
     pub fn into_chain(self) -> Chain {
         Chain::new(self)
     }
 
+    /// Used by [`chain!`] macro
     pub fn into_chain_with_children(self, children: Vec<Button>) -> Chain {
         Chain::with_children(self, children)
     }
 
+    /// Used by [`anim!`] macro
     pub fn as_widget<'a, Message, Renderer>(
         self,
         timeline: &crate::Timeline,

src/keyframes/column.rs

@@ -21,14 +21,17 @@ impl Id {
         Self(widget::Id::unique())
     }
 
+    /// Used by [`chain!`] macro
     pub fn into_chain(self) -> Chain {
         Chain::new(self)
     }
 
+    /// Used by [`chain!`] macro
     pub fn into_chain_with_children(self, children: Vec<Column>) -> Chain {
         Chain::with_children(self, children)
     }
 
+    /// Used by [`anim!`] macro
     pub fn as_widget<'a, Message, Renderer>(
         self,
         timeline: &crate::Timeline,

src/keyframes/container.rs

@@ -21,14 +21,17 @@ impl Id {
         Self(widget::Id::unique())
     }
 
+    /// Used by [`chain!`] macro
     pub fn into_chain(self) -> Chain {
         Chain::new(self)
     }
 
+    /// Used by [`chain!`] macro
     pub fn into_chain_with_children(self, children: Vec<Container>) -> Chain {
         Chain::with_children(self, children)
     }
 
+    /// Used by [`anim!`] macro
     pub fn as_widget<'a, Message, Renderer>(
         self,
         timeline: &crate::Timeline,

src/keyframes/helpers.rs

@@ -1,67 +1,97 @@
 use crate::keyframes::{Button, Column, Container, Row, Space, StyleButton, StyleContainer};
 use crate::MovementType;
 
+/// Create a button keyframe.
+/// Needs to be added into a chain. See [`chain!`] macro.
 pub fn button(at: impl Into<MovementType>) -> Button {
     Button::new(at)
 }
 
+/// Create a column keyframe.
+/// Needs to be added into a chain. See [`chain!`] macro.
 pub fn column(at: impl Into<MovementType>) -> Column {
     Column::new(at)
 }
 
+/// Create a container keyframe.
+/// Needs to be added into a chain. See [`chain!`] macro.
 pub fn container(at: impl Into<MovementType>) -> Container {
     Container::new(at)
 }
 
+/// Create a row keyframe.
+/// Needs to be added into a chain. See [`chain!`] macro.
 pub fn row(at: impl Into<MovementType>) -> Row {
     Row::new(at)
 }
 
+/// Create a space keyframe.
+/// Needs to be added into a chain. See [`chain!`] macro.
 pub fn space(at: impl Into<MovementType>) -> Space {
     Space::new(at)
 }
 
+/// Create a style_button keyframe.
+/// Needs to be added into a chain. See [`chain!`] macro.
 pub fn style_button(at: impl Into<MovementType>) -> StyleButton {
     StyleButton::new(at)
 }
 
+/// Create a style_container keyframe.
+/// Needs to be added into a chain. See [`chain!`] macro.
 pub fn style_container(at: impl Into<MovementType>) -> StyleContainer {
     StyleContainer::new(at)
 }
 
+/// A slightly different import to clean up makeing lazy keyframes.
 pub mod lazy {
     use crate::keyframes::{Button, Column, Container, Row, Space, StyleButton, StyleContainer};
     use crate::MovementType;
 
+    /// Create a lazy button keyframe.
+    /// Needs to be added into a chain. See [`chain!`] macro.
     pub fn button(at: impl Into<MovementType>) -> Button {
         Button::lazy(at)
     }
 
+    /// Create a lazy column keyframe.
+    /// Needs to be added into a chain. See [`chain!`] macro.
     pub fn column(at: impl Into<MovementType>) -> Column {
         Column::lazy(at)
     }
 
+    /// Create a lazy container keyframe.
+    /// Needs to be added into a chain. See [`chain!`] macro.
     pub fn container(at: impl Into<MovementType>) -> Container {
         Container::lazy(at)
     }
 
+    /// Create a lazy row keyframe.
+    /// Needs to be added into a chain. See [`chain!`] macro.
     pub fn row(at: impl Into<MovementType>) -> Row {
         Row::lazy(at)
     }
 
+    /// Create a lazy space keyframe.
+    /// Needs to be added into a chain. See [`chain!`] macro.
     pub fn space(at: impl Into<MovementType>) -> Space {
         Space::lazy(at)
     }
 
+    /// Create a lazy style_button keyframe.
+    /// Needs to be added into a chain. See [`chain!`] macro.
     pub fn style_button(at: impl Into<MovementType>) -> StyleButton {
         StyleButton::lazy(at)
     }
 
+    /// Create a lazy style_container keyframe.
+    /// Needs to be added into a chain. See [`chain!`] macro.
     pub fn style_container(at: impl Into<MovementType>) -> StyleContainer {
         StyleContainer::lazy(at)
     }
 }
 
+/// A slightly different import to clean up makeing animation Ids.
 pub mod id {
     pub use crate::keyframes::{
         button::Id as Button, column::Id as Column, container::Id as Container, row::Id as Row,

src/keyframes/row.rs

@@ -21,14 +21,17 @@ impl Id {
         Self(widget::Id::unique())
     }
 
+    /// Used by [`chain!`] macro
     pub fn into_chain(self) -> Chain {
         Chain::new(self)
     }
 
+    /// Used by [`chain!`] macro
     pub fn into_chain_with_children(self, children: Vec<Row>) -> Chain {
         Chain::with_children(self, children)
     }
 
+    /// Used by [`anim!`] macro
     pub fn as_widget<'a, Message, Renderer>(
         self,
         timeline: &crate::Timeline,

src/keyframes/space.rs

@@ -21,14 +21,17 @@ impl Id {
         Self(widget::Id::unique())
     }
 
+    /// Used by [`chain!`] macro
     pub fn into_chain(self) -> Chain {
         Chain::new(self)
     }
 
+    /// Used by [`chain!`] macro
     pub fn into_chain_with_children(self, children: Vec<Space>) -> Chain {
         Chain::with_children(self, children)
     }
 
+    /// Used by [`anim!`] macro
     pub fn as_widget(self, timeline: &crate::Timeline) -> widget::Space {
         Space::as_widget(self, timeline)
     }

src/keyframes/style_button.rs

@@ -22,14 +22,17 @@ impl Id {
         Self(widget::Id::unique())
     }
 
+    /// Used by [`chain!`] macro
     pub fn into_chain(self) -> Chain {
         Chain::new(self)
     }
 
+    /// Used by [`chain!`] macro
     pub fn into_chain_with_children(self, children: Vec<StyleButton>) -> Chain {
         Chain::with_children(self, children)
     }
 
+    /// Used by [`anim!`] macro
     pub fn as_widget<'a, Message, Renderer>(
         self,
         style: fn(u8) -> <Renderer::Theme as StyleSheet>::Style,

src/keyframes/style_container.rs

@@ -22,14 +22,17 @@ impl Id {
         Self(widget::Id::unique())
     }
 
+    /// Used by [`chain!`] macro
     pub fn into_chain(self) -> Chain {
         Chain::new(self)
     }
 
+    /// Used by [`chain!`] macro
     pub fn into_chain_with_children(self, children: Vec<StyleContainer>) -> Chain {
         Chain::with_children(self, children)
     }
 
+    /// Used by [`anim!`] macro
     pub fn as_widget<'a, Message, Renderer>(
         self,
         style: fn(u8) -> <Renderer::Theme as StyleSheet>::Style,