TestsTested | ✓ |
LangLanguage | Obj-CObjective C |
License | Apache 2 |
ReleasedLast Release | Feb 2017 |
Maintained by Jeff Verkoeyen.
The Material Motion Runtime is a tool for describing motion declaratively.
This library does not do much on its own. What it does do, however, is enable the expression of motion as discrete units of data that can be introspected, composed, and sent over a wire.
This library encourages you to describe motion as data, or what we call plans. Plans are committed to a runtime. A runtime coordinates the creation of performers, objects responsible for translating plans into concrete execution.
Import the Material Motion Runtime framework:
@import MaterialMotionRuntime;
You will now have access to all of the APIs.
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/material-motion-runtime-objc.git
cd material-motion-runtime-objc
pod install
open MaterialMotionRuntime.xcworkspace
The Material Motion Runtime consists of two groups of APIs: a runtime/transaction object and a constellation of protocols loosely consisting of plan and performing types.
The Runtime object is a coordinating entity whose primary responsibility is to fulfill plans by creating performers. You can create many runtimes throughout the lifetime of your application. A good rule of thumb is to have one runtime per interaction or transition.
The Plan and Performing protocol each define the minimal characteristics required for an object to be considered either a plan or a performer, respectively, by the Material Motion Runtime.
Plans and performers have a symbiotic relationship. A plan is executed by the performer it defines. Performer behavior is configured by the provided plan instances.
Learn more about the Material Motion Runtime by reading the Starmap.
The following steps provide copy-pastable snippets of code.
Questions to ask yourself when creating a new plan type:
As general rules:
Code snippets:
In Objective-C:
@interface <#Plan#> : NSObject
@end
@implementation <#Plan#>
@end
In Swift:
class <#Plan#>: NSObject {
}
Performers are responsible for fulfilling plans. Fulfillment is possible in a variety of ways:
See the associated links for more details on each performing type.
Note: only one instance of a type of performer per target is ever created. This allows you to register multiple plans to the same target in order to configure a performer. See How to configure performers with plans for more details.
Code snippets:
In Objective-C:
@interface <#Performer#> : NSObject <MDMPerforming>
@end
@implementation <#Performer#> {
UIView *_target;
}
- (instancetype)initWithTarget:(id)target {
self = [super init];
if (self) {
assert([target isKindOfClass:[UIView class]]);
_target = target;
}
return self;
}
- (void)addPlan:(id<MDMPlan>)plan {
<#Plan#>* <#casted plan instance#> = plan;
// Do something with the plan.
}
@end
In Swift:
class <#Performer#>: NSObject, Performing {
let target: UIView
required init(target: Any) {
self.target = target as! UIView
super.init()
}
func addPlan(_ plan: Plan) {
let <#casted plan instance#> = plan as! <#Plan#>
// Do something with the plan.
}
}
Conforming to Plan requires:
Code snippets:
In Objective-C:
@interface <#Plan#> : NSObject <MDMPlan>
@end
@implementation <#Plan#>
- (Class)performerClass {
return [<#Plan#> class];
}
- (id)copyWithZone:(NSZone *)zone {
return [[[self class] allocWithZone:zone] init];
}
@end
In Swift:
class <#Plan#>: NSObject, Plan {
func performerClass() -> AnyClass {
return <#Performer#>.self
}
func copy(with zone: NSZone? = nil) -> Any {
return <#Plan#>()
}
}
Code snippets:
In Objective-C:
@interface MyClass ()
@property(nonatomic, strong) MDMRuntime* runtime;
@end
- (instancetype)init... {
...
self.runtime = [MDMRuntime new];
...
}
In Swift:
class MyClass {
let runtime = Runtime()
}
Code snippets:
In Objective-C:
[runtime addPlan:<#Plan instance#> to:<#View instance#>];
In Swift:
runtime.addPlan(<#Plan instance#>, to:<#View instance#>)
Code snippets:
In Objective-C:
@interface MyClass ()
@property(nonatomic, strong) MDMRuntime* runtime;
@end
- (instancetype)init... {
...
self.runtime = [MDMRuntime new];
...
}
In Swift:
class MyClass {
let runtime = Runtime()
}
Code snippets:
In Objective-C:
[runtime addPlan:<#Plan instance#> named:<#name#> to:<#View instance#>];
In Swift:
runtime.addPlan(<#Plan instance#>, named:<#name#>, to:<#View instance#>)
Make use of Swift's typed switch/casing to handle multiple plan types.
func addPlan(_ plan: Plan) {
switch plan {
case let <#plan instance 1#> as <#Plan type 1#>:
()
case let <#plan instance 2#> as <#Plan type 2#>:
()
case is <#Plan type 3#>:
()
default:
assert(false)
}
}
Code snippets:
In Objective-C:
@interface <#Performer#> (NamedPlanPerforming) <MDMNamedPlanPerforming>
@end
@implementation <#Performer#> (NamedPlanPerforming)
- (void)addPlan:(id<MDMNamedPlan>)plan named:(NSString *)name {
<#Plan#>* <#casted plan instance#> = plan;
// Do something with the plan.
}
- (void)removePlanNamed:(NSString *)name {
// Remove any configuration associated with the given name.
}
@end
In Swift:
extension <#Performer#>: NamedPlanPerforming {
func addPlan(_ plan: NamedPlan, named name: String) {
let <#casted plan instance#> = plan as! <#Plan#>
// Do something with the plan.
}
func removePlan(named name: String) {
// Remove any configuration associated with the given name.
}
}
A composition performer is able to emit new plans using a plan emitter. This feature enables the reuse of plans and the creation of higher-order abstractions.
Code snippets:
In Objective-C:
@interface <#Performer#> ()
@property(nonatomic, strong) id<MDMPlanEmitting> planEmitter;
@end
@interface <#Performer#> (Composition) <MDMComposablePerforming>
@end
@implementation <#Performer#> (Composition)
- (void)setPlanEmitter:(id<MDMPlanEmitting>)planEmitter {
self.planEmitter = planEmitter;
}
@end
In Swift:
// Store the emitter in your class' definition.
class <#Performer#>: ... {
...
var emitter: PlanEmitting!
...
}
extension <#Performer#>: ComposablePerforming {
var emitter: PlanEmitting!
func setPlanEmitter(_ planEmitter: PlanEmitting) {
emitter = planEmitter
}
}
Performers are only able to emit plans for their associated target.
Code snippets:
In Objective-C:
[self.planEmitter emitPlan:<#(nonnull id<MDMPlan>)#>];
In Swift:
emitter.emitPlan<#T##Plan#>)
Performers will often perform their actions over a period of time or while an interaction is active. These types of performers are called continuous performers.
A continuous performer is able to affect the active state of the runtime by generating is-active tokens. The runtime is considered active so long as an is-active token exists and has not been terminated. Continuous performers are expected to terminate a token when its corresponding work has completed.
For example, a performer that registers a platform animation might generate a token when the animation starts. When the animation completes the token would be terminated.
Code snippets:
In Objective-C:
@interface <#Performer#> ()
@property(nonatomic, strong) id<MDMIsActiveTokenGenerating> tokenGenerator;
@end
@interface <#Performer#> (Composition) <MDMComposablePerforming>
@end
@implementation <#Performer#> (Composition)
- (void)setIsActiveTokenGenerator:(id<MDMIsActiveTokenGenerating>)isActiveTokenGenerator {
self.tokenGenerator = isActiveTokenGenerator;
}
@end
In Swift:
// Store the emitter in your class' definition.
class <#Performer#>: ... {
...
var tokenGenerator: IsActiveTokenGenerating!
...
}
extension <#Performer#>: ContinuousPerforming {
func set(isActiveTokenGenerator: IsActiveTokenGenerating) {
tokenGenerator = isActiveTokenGenerator
}
}
You will likely need to store the token in order to be able to reference it at a later point.
Code snippets:
In Objective-C:
id<MDMIsActiveTokenable> token = [self.tokenGenerator generate];
tokenMap[animation] = token;
In Swift:
let token = tokenGenerator.generate()!
tokenMap[animation] = token
Code snippets:
In Objective-C:
[token terminate];
In Swift:
token.terminate()
Tracing allows you to observe internal events occurring within a runtime. This information may be used for the following purposes:
Use for other purposes is unsupported.
Code snippets:
In Objective-C:
@interface <#Custom tracer#> : NSObject <MDMTracing>
@end
@implementation <#Custom tracer#>
@end
In Swift:
class <#Custom tracer#>: NSObject, Tracing {
}
The documentation for the Tracing protocol enumerates the available methods.
Code snippets:
In Objective-C:
@implementation <#Custom tracer#>
- (void)didAddPlan:(id<MDMPlan>)plan to:(id)target {
}
@end
In Swift:
class <#Custom tracer#>: NSObject, Tracing {
func didAddPlan(_ plan: Plan, to target: Any) {
}
}
Code snippets:
In Objective-C:
[runtime addTracer:[MDMConsoleLoggingTracer new]];
In Swift:
runtime.addTracer(ConsoleLoggingTracer())
Code snippets:
In Objective-C:
@interface <#SomeClass#> () <MDMTimelineObserving>
@end
@implementation <#SomeClass#>
- (void)timeline:(MDMTimeline *)timeline didAttachScrubber:(MDMTimelineScrubber *)scrubber {
}
- (void)timeline:(MDMTimeline *)timeline didDetachScrubber:(MDMTimelineScrubber *)scrubber {
}
- (void)timeline:(MDMTimeline *)timeline scrubberDidScrub:(NSTimeInterval)timeOffset {
}
@end
In Swift:
extension <#SomeClass#>: TimelineObserving {
func timeline(_ timeline: Timeline, didAttach scrubber: TimelineScrubber) {
}
func timeline(_ timeline: Timeline, didDetach scrubber: TimelineScrubber) {
}
func timeline(_ timeline: Timeline, scrubberDidScrub timeOffset: TimeInterval) {
}
}
Code snippets:
In Objective-C:
[timeline addTimelineObserver:<#(nonnull id<MDMTimelineObserving>)#>];
In Swift:
timeline.addObserver(<#T##observer: TimelineObserving##TimelineObserving#>)
We welcome contributions!
Check out our upcoming milestones.
Learn more about our team, our community, and our contributor essentials.
Licensed under the Apache 2.0 license. See LICENSE for details.