Animation and Haptics: add various ViewController animation protocols

This fleshes out the protocols required for the `ViewController` class
interfaces.

Author: compnerd

Sources/SwiftWin32/Animation and Haptics/Property-Based Animations/CubicTimingParameters.swift

@@ -0,0 +1,40 @@
+// Copyright © 2021 Saleem Abdulrasool <[email protected]>
+// SPDX-License-Identifier: BSD-3-Clause
+
+/// The timing information for animations in the form of a cubic Bézier curve.
+public class CubicTimingParameters {
+  // MARK - Initializing a Cubic Timing Parameters Object
+
+  /// Initializes the object with the system’s default timing curve.
+  public init() {
+    self.animationCurve = .linear
+    self.controlPoint1 = .zero
+    self.controlPoint2 = Point(x: 1, y: 1)
+  }
+
+  /// Initializes the object with the specified builtin timing curve.
+  public init(animationCurve curve: View.AnimationCurve) {
+    self.animationCurve = curve
+    self.controlPoint1 = .zero
+    self.controlPoint2 = .zero
+  }
+
+  /// Initializes the object with the specified control points for a cubic
+  /// Bézier curve.
+  public init(controlPoint1 point1: Point, controlPoint2 point2: Point) {
+    self.animationCurve = .linear
+    self.controlPoint1 = point1
+    self.controlPoint2 = point2
+  }
+
+  // MARK - Getting the Timing Parameters
+
+  /// The standard builtin animation curve to use for timing.
+  public private(set) var animationCurve: View.AnimationCurve
+
+  /// The first control point for the cubic Bézier curve.
+  public private(set) var controlPoint1: Point
+
+  /// The second control point of the cubic Bézier curve.
+  public private(set) var controlPoint2: Point
+}

Sources/SwiftWin32/Animation and Haptics/Property-Based Animations/SpringTimingParameters.swift

@@ -0,0 +1,44 @@
+// Copyright © 2021 Saleem Abdulrasool <[email protected]>
+// SPDX-License-Identifier: BSD-3-Clause
+
+/// The timing information for animations that mimics the behavior of a spring.
+public class SpringTimingParameters {
+  // MARK - Initializing a Spring Timing Parameters Object
+
+  /// Creates a default timing parameters object.
+  ///
+  /// This method sets the initial velocity of any animated properties to 0.0
+  /// and sets the damping ratio to 4.56.
+  public init() {
+    self.initialVelocity = .zero
+  }
+
+  /// Creates a timing parameters object with the specified damping ratio.
+  ///
+  /// This method sets the initial velocity of any animated properties to 0.0.
+  public convenience init(dampingRatio ratio: Double) {
+    self.init(dampingRatio: ratio, initialVelocity: .zero)
+  }
+
+  /// Creates a timing parameters object with the specified damping ratio and
+  /// initial velocity.
+  public init(dampingRatio ratio: Double, initialVelocity velocity: Vector) {
+    self.initialVelocity = velocity
+  }
+
+  /// Creates a timing parameters object with the specified spring stiffness,
+  /// mass, damping coefficient, and initial velocity.
+  ///
+  /// The damping ratio for the spring is computed from the formula:
+  /// `damping / (2 * sqrt (stiffness * mass))`.
+  public init(mass: Double, stiffness: Double, damping: Double,
+              initialVelocity velocity: Vector) {
+    self.initialVelocity = velocity
+  }
+
+  // MARK - Getting the Initial Velocity
+
+  /// The target property’s rate of change at the start of a spring animation,
+  /// enabling a smooth transition into the animation.
+  public private(set) var initialVelocity: Vector
+}

Sources/SwiftWin32/Animation and Haptics/Property-Based Animations/TimingCurveProvider.swift

@@ -0,0 +1,38 @@
+// Copyright © 2021 Saleem Abdulrasool <[email protected]>
+// SPDX-License-Identifier: BSD-3-Clause
+
+/// Constants indicating the type of timing information to use.
+public enum TimingCurveType: Int {
+  /// Use the built-in timing curves. Specify this value when you want to use
+  /// one of the constants in the `View.AnimationCurve` type. Specify the
+  /// desired curve using the `cubicTimingParameters` property.
+  case builtin
+
+  /// Use a custom cubic Bézier curve. Specify the curve information using the
+  /// `cubicTimingParameters` property.
+  case cubic
+
+  /// Use a custom spring animation. Specify the desired curve using the
+  /// `springTimingParameters` property.
+  case spring
+
+  /// Use a combination of timing parameters. This type of curve starts with the
+  /// curve defined by the `cubicTimingParameters` property and modifies it
+  /// using the spring information in the `springTimingParameters` property.
+  case composed
+}
+
+/// An interface for providing the timing information needed to perform
+/// animations.
+public protocol TimingCurveProvider {
+  // MARK - Getting the Timing Information
+
+  /// The type of timing information to use.
+  var timingCurveType: TimingCurveType { get }
+
+  /// The cubic timing parameters to use.
+  var cubicTimingParameters: CubicTimingParameters? { get }
+
+  /// The spring-based timing parameters to use.
+  var springTimingParameters: SpringTimingParameters? { get }
+}

Sources/SwiftWin32/Animation and Haptics/Property-Based Animations/ViewAnimating.swift

@@ -1,6 +1,8 @@
 // Copyright © 2021 Saleem Abdulrasool <[email protected]>
 // SPDX-License-Identifier: BSD-3-Clause
 
+import struct Foundation.TimeInterval
+
 /// Constants indicating positions within the animation.
 public enum ViewAnimatingPosition: Int {
   /// The end point of the animation. Use this constant when you want the final
@@ -17,3 +19,57 @@ public enum ViewAnimatingPosition: Int {
   /// value set by an animator object.
   case current
 }
+
+/// Constants indicating the current state of the animation.
+public enum ViewAnimatingState: Int {
+  /// The animations have not yet started executing. This is the initial state
+  /// of the animator object.
+  case inactive
+
+  /// The animator object is active and animations are either running or paused.
+  /// An animator moves to this state after the first call to `startAnimation()`
+  /// or `pauseAnimation()`. It stays in the active state until the animations
+  /// finish naturally or until you call the `stopAnimation(_:)` method.
+  case active
+
+  /// The animation is stopped. Putting an animation into this state ends the
+  /// animation and leaves any animatable properties at their current values,
+  /// instead of updating them to their intended final values. An animation
+  /// cannot be started while in this state.
+  case stopped
+}
+
+/// An interface for implementing custom animator objects.
+public protocol ViewAnimating {
+  // MARK - Starting and Stopping the Animations
+
+  /// Starts the animation from its current position.
+  func startAnimation()
+
+  /// Starts the animation after the specified delay.
+  func startAnimation(afterDelay delay: TimeInterval)
+
+  /// Pauses a running animation at its current position.
+  func pauseAnimation()
+
+  /// Stops the animations at their current positions.
+  func stopAnimation(_ withoutFinishing: Bool)
+
+  /// Finishes the animations and returns the animator to the inactive state.
+  func finishAnimation(at finalPositiong: ViewAnimatingPosition)
+
+  // MARK - Getting the Animator's State
+
+  /// The completion percentage of the animation.
+  var fractionComplete: Double { get set }
+
+  /// A boolean value indicating whether the animation is running in the reverse
+  /// direction.
+  var isReversed: Bool { get set }
+
+  /// The current state of the animation.
+  var state: ViewAnimatingState { get }
+
+  /// A boolean value indicating whether the animation is currently running.
+  var isRunning: Bool { get }
+}

Sources/SwiftWin32/Animation and Haptics/Property-Based Animations/ViewImplicitlyAnimating.swift

@@ -0,0 +1,37 @@
+// Copyright © 2021 Saleem Abdulrasool <[email protected]>
+// SPDX-License-Identifier: BSD-3-Clause
+
+/// An interface for modifying an animation while it is running.
+public protocol ViewImplicitlyAnimating: ViewAnimating {
+  // MARK - Modifying Animations
+
+  /// Adds the specified animation block to the animator.
+  func addAnimations(_ animation: @escaping () -> Void)
+
+  /// Adds the specified animation block to the animator with a delay.
+  func addAnimations(_ animation: @escaping () -> Void, delayFactor: Double)
+
+  /// Adds the specified completion block to the animator.
+  func addCompletion(_ completion: @escaping (ViewAnimatingPosition) -> Void)
+
+  /// Adjusts the final timing and duration of a paused animation.
+  func continueAnimation(withTimingParameters paramters: TimingCurveProvider?,
+                         durationFactor: Double)
+}
+
+extension ViewImplicitlyAnimating {
+  public func addAnimations(_ animation: @escaping () -> Void) {
+    self.addAnimations(animation, delayFactor: 0.0)
+  }
+
+  public func addAnimations(_ animation: @escaping () -> Void,
+                            delayFactor: Double) {
+  }
+
+  public func addCompletion(_ completion: @escaping (ViewAnimatingPosition) -> Void) {
+  }
+
+  public func continueAnimation(withTimingParameters paramters: TimingCurveProvider?,
+                                durationFactor: Double) {
+  }
+}

Sources/SwiftWin32/Animation and Haptics/View Controller Transitions/ViewControllerAnimatedTransitioning.swift

@@ -0,0 +1,41 @@
+// Copyright © 2021 Saleem Abdulrasool <[email protected]>
+// SPDX-License-Identifier: BSD-3-Clause
+
+import struct Foundation.TimeInterval
+
+/// A set of methods for implementing the animations for a custom view controller
+/// transition.
+public protocol ViewControllerAnimatedTransitioning {
+  // MARK - Performing a Transition
+
+  /// Tells your animator object to perform the transition animations.
+  func animateTransition(using transitionContext: ViewControllerContextTransitioning)
+
+  /// Tells your animator object that the transition animations have finished.
+  func animationEnded(_ transitionCompleted: Bool)
+
+  // MARK - Reporting Transition Duration
+
+  /// Asks your animator object for the duration (in seconds) of the transition
+  /// animation.
+  func transitionDuration(using transitionContext: ViewControllerContextTransitioning?)
+      -> TimeInterval
+
+  // MARK - Returning an Interruptible Animator
+
+  /// Returns the interruptible animator to use during the transition.
+  func interruptibleAnimator(using transitionContext: ViewControllerContextTransitioning)
+      -> ViewImplicitlyAnimating
+}
+
+extension ViewControllerAnimatedTransitioning {
+  public func animationEnded(_ transitionCompleted: Bool) {
+  }
+}
+
+extension ViewControllerAnimatedTransitioning {
+  func interruptibleAnimator(using transitionContext: ViewControllerContextTransitioning)
+      -> ViewImplicitlyAnimating {
+    fatalError("\(#function) not yet implemented")
+  }
+}

Sources/SwiftWin32/Animation and Haptics/View Controller Transitions/ViewControllerInteractiveTransitioning.swift

@@ -0,0 +1,43 @@
+// Copyright © 2021 Saleem Abdulrasool <[email protected]>
+// SPDX-License-Identifier: BSD-3-Clause
+
+/// A set of methods that enable an object (such as a navigation controller) to
+/// drive a view controller transition.
+public protocol ViewControllerInteractiveTransitioning {
+  // MARK - Starting an Interactive Transition
+
+  /// Called when the system needs to set up the interactive portions of a view
+  /// controller transition and start the animations.
+  func startInteractiveTransition(_ transitionContext: ViewControllerContextTransitioning)
+
+  /// A boolean value indicating whether the transition is interactive when it
+  /// starts.
+  ///
+  /// The value of this property is `true` when the transition is interactive
+  /// from the moment it starts. The property is `false` when the transition
+  /// starts off as noninteractive. However, even a transition that starts off
+  /// as noninteractive may become interactive later if it implements the
+  /// `interruptibleAnimator(using:)` method of the
+  /// `ViewControllerAnimatedTransitioning` protocol.
+  var wantsInteractiveStart: Bool { get }
+
+  // MARK - Providing a Transition's Completion Characteristics
+
+  /// Called when the system needs the animation completion curve for an
+  /// interactive view controller transition.
+  var completionCurve: View.AnimationCurve { get }
+
+  /// Called when the system needs the speed at which to complete an interactive
+  /// transition, after the interactive portion is finished.
+  var completionSpeed: Double { get }
+}
+
+extension ViewControllerInteractiveTransitioning {
+  public var wantsInteractiveStart: Bool { true }
+}
+
+extension ViewControllerInteractiveTransitioning {
+  public var completionCurve: View.AnimationCurve { .easeInOut }
+
+  public var completionSpeed: Double { 1.0 }
+}

Sources/SwiftWin32/Animation and Haptics/View Controller Transitions/ViewControllerTransitioningDelegate.swift

@@ -0,0 +1,74 @@
+// Copyright © 2021 Saleem Abdulrasool <[email protected]>
+// SPDX-License-Identifier: BSD-3-Clause
+
+/// A set of methods that vend objects used to manage a fixed-length or
+/// interactive transition between view controllers.
+public protocol ViewControllerTransitioningDelegate: AnyObject {
+  // MARK - Getting the Transition Animator Objects
+
+  /// Asks your delegate for the transition animator object to use when
+  /// presenting a view controller.
+  func animationController(forPresented presented: ViewController,
+                           presenting: ViewController, source: ViewController)
+      -> ViewControllerAnimatedTransitioning?
+
+  /// Asks your delegate for the transition animator object to use when
+  /// dismissing a view controller.
+  func animationController(forDismissed dismissed: ViewController)
+      -> ViewControllerAnimatedTransitioning?
+
+  // MARK - Getting the Interactive Animator Objects
+
+  /// Asks your delegate for the interactive animator object to use when
+  /// presenting a view controller.
+  func interactionControllerForPresentation(using animator: ViewControllerAnimatedTransitioning)
+      -> ViewControllerInteractiveTransitioning?
+
+  /// Asks your delegate for the interactive animator object to use when
+  /// dismissing a view controller.
+  func interactionControllerForDismissal(using animator: ViewControllerAnimatedTransitioning)
+      -> ViewControllerInteractiveTransitioning?
+
+  // MARK - Getting the Custom Presentation Controller
+
+  /// Asks your delegate for the custom presentation controller to use for
+  /// managing the view hierarchy when presenting a view controller.
+  func presentationController(forPresented presented: ViewController,
+                              presenting: ViewController?,
+                              source: ViewController)
+      -> PresentationController?
+}
+
+extension ViewControllerTransitioningDelegate {
+  public func animationController(forPresented presented: ViewController,
+                                  presenting: ViewController, source: ViewController)
+      -> ViewControllerAnimatedTransitioning? {
+    return nil
+  }
+
+  public func animationController(forDismissed dismissed: ViewController)
+      -> ViewControllerAnimatedTransitioning? {
+    return nil
+  }
+}
+
+extension ViewControllerTransitioningDelegate {
+  public func interactionControllerForPresentation(using animator: ViewControllerAnimatedTransitioning)
+      -> ViewControllerInteractiveTransitioning? {
+    return nil
+  }
+
+  public func interactionControllerForDismissal(using animator: ViewControllerAnimatedTransitioning)
+      -> ViewControllerInteractiveTransitioning? {
+    return nil
+  }
+}
+
+extension ViewControllerTransitioningDelegate {
+  public func presentationController(forPresented presented: ViewController,
+                                     presenting: ViewController?,
+                                     source: ViewController)
+      -> PresentationController? {
+    return nil
+  }
+}