A standard format for representing animation traits in Objective-C and Swift.
"Magic numbers" — those lonely, abandoned values without a home — are often one of the first things targeted in code review for cleanup. And yet, numbers related to animations may go unnoticed and left behind, scattered throughout a code base with little to no organizational diligence. These forgotten metrics form the backbone of mobile interactions and are often the ones needing the most care - so why are we ok leaving them scattered throughout a code base?
// Let's play "find the magic number": how many magic numbers are hidden in this code?
[UIView animateWithDuration:0.230
delay:0
options:UIViewAnimationOptionCurveEaseOut
animations:^{
myButton.position = updatedPosition;
}
completion:nil];
// Hint: the answer is not "one, the number 0.230".
The challenge with extracting animation magic numbers is that we often don't have a clear definition of what an animation is composed of. An animation is not simply determined by its duration, in the same way that a color is not simply determined by how red it is.
The traits of an animation — like the red, green, and blue components of a color — include the following:
- Delay.
- Duration.
- Timing curve.
- Repetition.
Within this library you will find simple data types for storing and representing animation traits so that the magic numbers that define your animations can find a place to call home.
Welcome home, lost numbers.
Sibling library: Motion Animator
While it is possible to use the Motion Interchange as a standalone library, the Motion Animator is designed to be the primary consumer of Motion Interchange data types. Consider using these libraries together, with MotionAnimator as your primary dependency.
MDMAnimationTraits *animationTraits =
[[MDMAnimationTraits alloc] initWithDuration:0.230
timingFunctionName:kCAMediaTimingFunctionEaseInEaseOut];
MDMMotionAnimator *animator = [[MDMMotionAnimator alloc] init];
[animator animateWithTraits:animationTraits animations:^{
view.alpha = 0;
}];
To learn more, visit the MotionAnimator GitHub page:
https://github.com/material-motion/motion-animator-objc
Installation
Installation with CocoaPods
CocoaPods is a dependency manager for Objective-C and Swift libraries. CocoaPods automates the process of using third-party libraries in your projects. See the Getting Started guide for more information. You can install it with the following command:
gem install cocoapods
Add MotionInterchange
to your Podfile
:
pod 'MotionInterchange'
Then run the following command:
pod install
Usage
Import the framework:
@import MotionInterchange;
You will now have access to all of the APIs.
Example apps/unit tests
Check out a local copy of the repo to access the Catalog application by running the following commands:
git clone https://github.com/material-motion/motion-interchange-objc.git
cd motion-interchange-objc
pod install
open MotionInterchange.xcworkspace
Guides
Animation traits
The primary data type you'll make use of is MDMAnimationTraits
. This class can store all of
the necessary traits that make up an animation, including:
- Delay.
- Duration.
- Timing curve.
- Repetition.
In Objective-C, you initialize a simple ease in/out cubic bezier instance like so:
MDMAnimationTraits *traits = [[MDMAnimationTraits alloc] initWithDuration:0.5];
And in Swift:
let traits = MDMAnimationTraits(duration: 0.5)
There are many more ways to initialize animation traits. Read the header documentation to see all of the available initializers.
Timing curves
A timing curve describes how quickly an animation progresses over time. Two types of timing curves are supported by Core Animation, and therefore by the MotionInterchange:
- Cubic bezier
- Spring
Cubic beziers are represented by the CAMediaTimingFunction object. To define an animation trait with a cubic bezier curve in Objective-C:
CAMediaTimingFunction *timingCurve =
[CAMediaTimingFunction functionWithName:kCAMediaTimingFunctionEaseInEaseOut];
MDMAnimationTraits *traits =
[[MDMAnimationTraits alloc] initWithDelay:0 duration:0.5 timingCurve:timingCurve];
And in Swift:
let timingCurve = CAMediaTimingFunction(name: kCAMediaTimingFunctionEaseInEaseOut)
let traits = MDMAnimationTraits(delay: 0, duration: 0.5, timingCurve: timingCurve)
You can also use the UIViewAnimationCurve type to initialize a timing curve in Objective-C:
MDMAnimationTraits *traits =
[[MDMAnimationTraits alloc] initWithDuration:0.5 animationCurve:UIViewAnimationCurveEaseIn];
And in Swift:
let traits = MDMAnimationTraits(duration: 0.5, animationCurve: .easeIn)
Springs are represented with the custom MDMSpringTimingCurve
type. To define an
animation trait with a spring curve in Objective-C:
MDMSpringTimingCurve *timingCurve =
[[MDMSpringTimingCurve alloc] initWithMass:1 tension:100 friction:10];
MDMAnimationTraits *traits =
[[MDMAnimationTraits alloc] initWithDelay:0 duration:0.5 timingCurve:timingCurve];
And in Swift:
let timingCurve = MDMSpringTimingCurve(mass: 1, tension: 100, friction: 10)
let traits = MDMAnimationTraits(delay: 0, duration: 0.5, timingCurve: timingCurve)
Springs can also be initialized using UIKit's damping ratio concept. The MDMSpringTimingCurveGenerator
type generates MDMSpringTimingCurve
instances when needed. A spring timing curve generator can be stored as the timingCurve
of an MDMAnimationTraits
instance.
MDMSpringTimingCurveGenerator *timingCurve =
[[MDMSpringTimingCurveGenerator alloc] initWithDuration:<#(NSTimeInterval)#> dampingRatio:<#(CGFloat)#>];
MDMAnimationTraits *traits =
[[MDMAnimationTraits alloc] initWithDelay:0 duration:0.5 timingCurve:timingCurve];
And in Swift:
let timingCurve = MDMSpringTimingCurveGenerator(duration: 0.5, dampingRatio: 0.5)
let traits = MDMAnimationTraits(delay: 0, duration: 0.5, timingCurve: timingCurve)
Contributing
We welcome contributions!
Check out our upcoming milestones.
Learn more about our team, our community, and our contributor essentials.
License
Licensed under the Apache 2.0 license. See LICENSE for details.