Add support for customizing the timeScaleFactor as part of a CATransaction (#25)

* Add support for customizing the timeScaleFactor as part of a CATransaction.

If an animator is shared across a variety of animations, it can often be preferable to change the animator's behavior only within the context of a single transaction.

For example, if all animations in a transaction should have their duration scaled by a certain amount a client would previously have had to cache the previous timeScaleFactror, set the new one on the animator, and then restore the timeScaleFactor once the animations were added.

The CATransaction API introduced by this change makes it easier for clients to make per-transaction timeScaleFactor changes like so:

```swift
CATransaction.begin()
CATransaction.mdm_setTimeScaleFactor(0.5)

animator.animate(with: timing, to: layer, withValues: [0, 1], keyPath: .rotation)

CATransaction.commit()
```

* Forgot an a.

Author: jverkoey

examples/apps/Catalog/MotionAnimatorCatalog.xcodeproj/project.pbxproj

@@ -8,6 +8,7 @@
 
 /* Begin PBXBuildFile section */
 		2AA864EDA683CEF5FAA721BE /* Pods_UnitTests.framework in Frameworks */ = {isa = PBXBuildFile; fileRef = 2DBE814C7B88BAD6337052DB /* Pods_UnitTests.framework */; };
+		660636021FACC24300C3DFB8 /* TimeScaleFactorTests.swift in Sources */ = {isa = PBXBuildFile; fileRef = 660636011FACC24300C3DFB8 /* TimeScaleFactorTests.swift */; };
 		666FAA841D384A6B000363DA /* AppDelegate.swift in Sources */ = {isa = PBXBuildFile; fileRef = 666FAA831D384A6B000363DA /* AppDelegate.swift */; };
 		666FAA8B1D384A6B000363DA /* Assets.xcassets in Resources */ = {isa = PBXBuildFile; fileRef = 666FAA8A1D384A6B000363DA /* Assets.xcassets */; };
 		666FAA8E1D384A6B000363DA /* LaunchScreen.storyboard in Resources */ = {isa = PBXBuildFile; fileRef = 666FAA8C1D384A6B000363DA /* LaunchScreen.storyboard */; };
@@ -43,6 +44,7 @@
 		2DBE814C7B88BAD6337052DB /* Pods_UnitTests.framework */ = {isa = PBXFileReference; explicitFileType = wrapper.framework; includeInIndex = 0; path = Pods_UnitTests.framework; sourceTree = BUILT_PRODUCTS_DIR; };
 		50D808A6F9E944D54276D32F /* Pods_MotionAnimatorCatalog.framework */ = {isa = PBXFileReference; explicitFileType = wrapper.framework; includeInIndex = 0; path = Pods_MotionAnimatorCatalog.framework; sourceTree = BUILT_PRODUCTS_DIR; };
 		52820916F8FAA40E942A7333 /* Pods-UnitTests.release.xcconfig */ = {isa = PBXFileReference; includeInIndex = 1; lastKnownFileType = text.xcconfig; name = "Pods-UnitTests.release.xcconfig"; path = "../../../Pods/Target Support Files/Pods-UnitTests/Pods-UnitTests.release.xcconfig"; sourceTree = "<group>"; };
+		660636011FACC24300C3DFB8 /* TimeScaleFactorTests.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = TimeScaleFactorTests.swift; sourceTree = "<group>"; };
 		666FAA801D384A6B000363DA /* MotionAnimatorCatalog.app */ = {isa = PBXFileReference; explicitFileType = wrapper.application; includeInIndex = 0; path = MotionAnimatorCatalog.app; sourceTree = BUILT_PRODUCTS_DIR; };
 		666FAA831D384A6B000363DA /* AppDelegate.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; name = AppDelegate.swift; path = Catalog/AppDelegate.swift; sourceTree = "<group>"; };
 		666FAA8A1D384A6B000363DA /* Assets.xcassets */ = {isa = PBXFileReference; lastKnownFileType = folder.assetcatalog; path = Assets.xcassets; sourceTree = "<group>"; };
@@ -204,6 +206,7 @@
 			children = (
 				66FD99F91EE9FBBE00C53A82 /* MotionAnimatorTests.m */,
 				668726491EF04B4C00113675 /* MotionAnimatorTests.swift */,
+				660636011FACC24300C3DFB8 /* TimeScaleFactorTests.swift */,
 			);
 			path = unit;
 			sourceTree = "<group>";
@@ -479,6 +482,7 @@
 			isa = PBXSourcesBuildPhase;
 			buildActionMask = 2147483647;
 			files = (
+				660636021FACC24300C3DFB8 /* TimeScaleFactorTests.swift in Sources */,
 				6687264A1EF04B4C00113675 /* MotionAnimatorTests.swift in Sources */,
 				66FD99FA1EE9FBBE00C53A82 /* MotionAnimatorTests.m in Sources */,
 			);

src/CATransaction+MotionAnimator.h

@@ -0,0 +1,39 @@
+/*
+ Copyright 2017-present The Material Motion Authors. All Rights Reserved.
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+ */
+
+#import <Foundation/Foundation.h>
+#import <QuartzCore/QuartzCore.h>
+
+@interface CATransaction (MotionAnimator)
+
+/**
+ Accessor for the "timeScaleFactor" per-thread transaction property.
+
+ Returns the transaction-specific time scale factor to be applied to animator animations.
+ */
++ (nullable NSNumber *)mdm_timeScaleFactor;
+
+/**
+ Setter for the "timeScaleFactor" per-thread transaction property.
+
+ Sets a transaction-specific time scale factor to be applied to animator animations.
+
+ @param timeScaleFactor If nil, the animator's `timeScaleFactor` will be used instead. Should be a
+                        CGFloat value type.
+ */
++ (void)mdm_setTimeScaleFactor:(nullable NSNumber *)timeScaleFactor;
+
+@end

src/CATransaction+MotionAnimator.m

@@ -0,0 +1,31 @@
+/*
+ Copyright 2017-present The Material Motion Authors. All Rights Reserved.
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+ */
+
+#import "CATransaction+MotionAnimator.h"
+
+static NSString *const kTimeScaleFactorKey = @"mdm_timeScaleFactor";
+
+@implementation CATransaction (MotionAnimator)
+
++ (NSNumber *)mdm_timeScaleFactor {
+  return [CATransaction valueForKey:kTimeScaleFactorKey];
+}
+
++ (void)mdm_setTimeScaleFactor:(nullable NSNumber *)timeScaleFactor {
+  return [CATransaction setValue:timeScaleFactor forKey:kTimeScaleFactorKey];
+}
+
+@end

src/MDMMotionAnimator.m

@@ -18,6 +18,7 @@
 
 #import <UIKit/UIKit.h>
 
+#import "CATransaction+MotionAnimator.h"
 #import "private/CABasicAnimation+MotionAnimator.h"
 #import "private/MDMUIKitValueCoercion.h"
 #import "private/MDMDragCoefficient.h"
@@ -62,7 +63,7 @@ - (void)animateWithTiming:(MDMMotionTiming)timing
     return;
   }
 
-  CGFloat timeScaleFactor = MDMSimulatorAnimationDragCoefficient() * _timeScaleFactor;
+  CGFloat timeScaleFactor = [self computedTimeScaleFactor];
   CABasicAnimation *animation = MDMAnimationFromTiming(timing, timeScaleFactor);
 
   if (animation) {
@@ -126,5 +127,21 @@ - (void)addCoreAnimationTracer:(void (^)(CALayer *, CAAnimation *))tracer {
   [_tracers addObject:[tracer copy]];
 }
 
+- (CGFloat)computedTimeScaleFactor {
+  CGFloat timeScaleFactor;
+  id transactionTimeScaleFactor = [CATransaction mdm_timeScaleFactor];
+  if (transactionTimeScaleFactor != nil) {
+#if CGFLOAT_IS_DOUBLE
+    timeScaleFactor = [transactionTimeScaleFactor doubleValue];
+#else
+    timeScaleFactor = [transactionTimeScaleFactor floatValue];
+#endif
+  } else {
+    timeScaleFactor = _timeScaleFactor;
+  }
+
+  return MDMSimulatorAnimationDragCoefficient() * timeScaleFactor;
+}
+
 @end
 

src/MotionAnimator.h

@@ -14,6 +14,7 @@
  limitations under the License.
  */
 
+#import "CATransaction+MotionAnimator.h"
 #import "MDMAnimatableKeyPaths.h"
 #import "MDMMotionAnimator.h"
 

tests/unit/MotionAnimatorTests.swift

@@ -70,4 +70,3 @@ class MotionAnimatorTests: XCTestCase {
     }
   }
 }
-

tests/unit/TimeScaleFactorTests.swift

@@ -0,0 +1,110 @@
+/*
+ Copyright 2017-present The Material Motion Authors. All Rights Reserved.
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+ */
+
+import XCTest
+import MotionAnimator
+
+class TimeScaleFactorTests: XCTestCase {
+
+  let timing = MotionTiming(delay: 0,
+                            duration: 1,
+                            curve: .init(type: .bezier, data: (0, 0, 0, 0)),
+                            repetition: .init(type: .none, amount: 0, autoreverses: false))
+  var layer: CALayer!
+  var addedAnimations: [CAAnimation]!
+  var animator: MotionAnimator!
+
+  override func setUp() {
+    super.setUp()
+
+    addedAnimations = []
+    animator = MotionAnimator()
+    animator.addCoreAnimationTracer { (_, animation) in
+      self.addedAnimations.append(animation)
+    }
+
+    layer = CALayer()
+  }
+
+  override func tearDown() {
+    layer = nil
+    addedAnimations = nil
+    animator = nil
+
+    super.tearDown()
+  }
+
+  func testDefaultTimeScaleFactorDoesNotModifyDuration() {
+    animator.animate(with: timing, to: layer, withValues: [0, 1], keyPath: .rotation)
+
+    XCTAssertEqual(addedAnimations.count, 1)
+    let animation = addedAnimations.last!
+    XCTAssertEqual(animation.duration, 1)
+  }
+
+  func testExplicitTimeScaleFactorChangesDuration() {
+    animator.timeScaleFactor = 0.5
+
+    animator.animate(with: timing, to: layer, withValues: [0, 1], keyPath: .rotation)
+
+    XCTAssertEqual(addedAnimations.count, 1)
+    let animation = addedAnimations.last!
+    XCTAssertEqual(animation.duration, timing.duration * 0.5)
+  }
+
+  func testTransactionTimeScaleFactorChangesDuration() {
+    CATransaction.begin()
+    CATransaction.mdm_setTimeScaleFactor(0.5)
+
+    animator.animate(with: timing, to: layer, withValues: [0, 1], keyPath: .rotation)
+    CATransaction.commit()
+
+    XCTAssertEqual(addedAnimations.count, 1)
+    let animation = addedAnimations.last!
+    XCTAssertEqual(animation.duration, timing.duration * 0.5)
+  }
+
+  func testTransactionTimeScaleFactorOverridesAnimatorTimeScaleFactor() {
+    animator.timeScaleFactor = 2
+
+    CATransaction.begin()
+    CATransaction.mdm_setTimeScaleFactor(0.5)
+
+    animator.animate(with: timing, to: layer, withValues: [0, 1], keyPath: .rotation)
+
+    CATransaction.commit()
+
+    XCTAssertEqual(addedAnimations.count, 1)
+    let animation = addedAnimations.last!
+    XCTAssertEqual(animation.duration, timing.duration * 0.5)
+  }
+
+  func testNilTransactionTimeScaleFactorUsesAnimatorTimeScaleFactor() {
+    animator.timeScaleFactor = 2
+
+    CATransaction.begin()
+    CATransaction.mdm_setTimeScaleFactor(0.5)
+    CATransaction.mdm_setTimeScaleFactor(nil)
+
+    animator.animate(with: timing, to: layer, withValues: [0, 1], keyPath: .rotation)
+
+    CATransaction.commit()
+
+    XCTAssertEqual(addedAnimations.count, 1)
+    let animation = addedAnimations.last!
+    XCTAssertEqual(animation.duration, timing.duration * 2)
+  }
+}