1- # Material Motion Transitioning
1+ # Transitioning
22
3- [ ![ Build Status] ( https://travis-ci.org/material-motion/material-motion-transitioning-objc.svg?branch=develop )] ( https://travis-ci.org/material-motion/material-motion-transitioning-objc )
4- [ ![ codecov] ( https://codecov.io/gh/material-motion/material-motion-transitioning-objc/branch/develop/graph/badge.svg )] ( https://codecov.io/gh/material-motion/material-motion-transitioning-objc )
5- [ ![ CocoaPods Compatible] ( https://img.shields.io/cocoapods/v/MaterialMotionTransitioning.svg )] ( https://cocoapods.org/pods/MaterialMotionTransitioning )
6- [ ![ Platform] ( https://img.shields.io/cocoapods/p/MaterialMotionTransitioning.svg )] ( http://cocoadocs.org/docsets/MaterialMotionTransitioning )
7- [ ![ Docs] ( https://img.shields.io/cocoapods/metrics/doc-percent/MaterialMotionTransitioning.svg )] ( http://cocoadocs.org/docsets/MaterialMotionTransitioning )
3+ > Light-weight API for building UIViewController transitions.
4+
5+ [ ![ Build Status] ( https://travis-ci.org/material-motion/transitioning-objc.svg?branch=develop )] ( https://travis-ci.org/material-motion/transitioning-objc )
6+ [ ![ codecov] ( https://codecov.io/gh/material-motion/transitioning-objc/branch/develop/graph/badge.svg )] ( https://codecov.io/gh/material-motion/transitioning-objc )
7+ [ ![ CocoaPods Compatible] ( https://img.shields.io/cocoapods/v/Transitioning.svg )] ( https://cocoapods.org/pods/Transitioning )
8+ [ ![ Platform] ( https://img.shields.io/cocoapods/p/Transitioning.svg )] ( http://cocoadocs.org/docsets/Transitioning )
9+ [ ![ Docs] ( https://img.shields.io/cocoapods/metrics/doc-percent/Transitioning.svg )] ( http://cocoadocs.org/docsets/Transitioning )
10+
11+ This library standardizes the way transitions are built on iOS so that with a single line of code
12+ you can pick the custom transition you want to use:
13+
14+ ``` swift
15+ let viewController = MyViewController ()
16+ viewController.transitionController .transition = CustomTransition ()
17+ present (modalViewController, animated : true )
18+ ```
19+
20+ ``` objc
21+ MyViewController *viewController = [[MyViewController alloc ] init ];
22+ viewController.mdm_transitionController.transition = [[CustomTransition alloc ] init ];
23+ [self presentViewController: viewController animated: true completion: nil ] ;
24+ ```
25+
26+ The easiest way to make a transition with this library is to create a class that conforms to the
27+ `Transition` protocol:
28+
29+ ```swift
30+ final class CustomTransition: NSObject, Transition {
31+ func start(with context: TransitionContext) {
32+ CATransaction.begin()
33+
34+ CATransaction.setCompletionBlock {
35+ context.transitionDidEnd()
36+ }
37+
38+ // Add animations...
39+
40+ CATransaction.commit()
41+ }
42+ }
43+ ```
44+
45+ ``` objc
46+ @interface CustomTransition : NSObject <MDMTransition>
47+ @end
48+
49+ @implementation CustomTransition
50+
51+ - (void)startWithContext:(id<MDMTransitionContext >)context {
52+ [ CATransaction begin] ;
53+ [ CATransaction setCompletionBlock:^{
54+ [ context transitionDidEnd] ;
55+ }] ;
56+
57+ // Add animations...
58+
59+ [ CATransaction commit] ;
60+ }
61+
62+ @end
63+ ```
864
965## Installation
1066
1773>
1874> gem install cocoapods
1975
20- Add ` MaterialMotionTransitioning ` to your ` Podfile ` :
76+ Add `Transitioning ` to your `Podfile`:
2177
22- pod 'MaterialMotionTransitioning '
78+ pod 'Transitioning '
2379
2480Then run the following command:
2581
@@ -29,7 +85,7 @@ Then run the following command:
2985
3086Import the framework:
3187
32- @import MaterialMotionTransitioning ;
88+ @import Transitioning ;
3389
3490You will now have access to all of the APIs.
3591
@@ -38,25 +94,165 @@ You will now have access to all of the APIs.
3894Check out a local copy of the repo to access the Catalog application by running the following
3995commands:
4096
41- git clone https://github.com/material-motion/material-motion- transitioning-objc.git
42- cd material-motion- transitioning-objc
97+ git clone https://github.com/material-motion/transitioning-objc.git
98+ cd transitioning-objc
4399 pod install
44- open MaterialMotionTransitioning .xcworkspace
100+ open Transitioning .xcworkspace
45101
46102## Guides
47103
481041. [Architecture](#architecture)
49- 2 . [ How to ...] ( #how-to-... )
105+ 2. [How to create a simple transition](#how-to-create-a-simple-transition)
106+ 3. [How to customize presentation](#how-to-customize-presentation)
50107
51108### Architecture
52109
53- ### How to ...
110+ > Background: Transitions in iOS are customized by setting a `transitioningDelegate` on a view
111+ > controller. When a view controller is presented, UIKit will ask the transitioning delegate for an
112+ > animation, interaction, and presentation controller. These controllers are then expected to
113+ > implement the transition's motion.
114+
115+ Transitioning provides a thin layer atop these protocols with the following advantages:
116+
117+ - Every view controller has its own **transition controller**. This encourages choosing the
118+ transition based on the context.
119+ - Transitions are represented in terms of **backward/forward** rather than from/to. When presenting,
120+ we're moving forward. When dismissing, we're moving backward. This makes it easier to refer to
121+ each "side" of a transition consistently.
122+ - Transition objects can customize their behavior by conforming to more `TransitionWith*` protocols.
123+ This protocol-oriented design is more Swift-friendly than a variety of optional methods on a
124+ protocol.
125+ - But most importantly: **this library handles the plumbing, allowing you to focus on the motion**.
126+
127+ ### How to create a simple transition
128+
129+ In this guide we'll create scaffolding for a simple transition.
130+
131+ #### Step 1: Define a new Transition type
132+
133+ Transitions must be `NSObject` types that conform to the `Transition` protocol.
134+
135+ The sole method we're expected to implement, `start`, is invoked each time the view controller is
136+ presented or dismissed.
137+
138+ ```swift
139+ final class FadeTransition: NSObject, Transition {
140+ func start(with context: TransitionContext) {
141+
142+ }
143+ }
144+ ```
145+
146+ #### Step 2: Invoke the completion handler once all animations are complete
147+
148+ If using Core Animation explicitly:
149+
150+ ``` swift
151+ final class FadeTransition : NSObject , Transition {
152+ func start (with context : TransitionContext) {
153+ CATransaction.begin ()
154+
155+ CATransaction.setCompletionBlock {
156+ context.transitionDidEnd ()
157+ }
158+
159+ // Your motion...
160+
161+ CATransaction.commit ()
162+ }
163+ }
164+ ```
165+
166+ If using UIView implicit animations:
167+
168+ ``` swift
169+ final class FadeTransition : NSObject , Transition {
170+ func start (with context : TransitionContext) {
171+ UIView.animate (withDuration : context.duration , animations : {
172+ // Your motion...
173+
174+ }, completion : { didComplete in
175+ context.transitionDidEnd ()
176+ })
177+ }
178+ }
179+ ```
180+
181+ #### Step 3: Implement the motion
182+
183+ With the basic scaffolding in place, you can now implement your motion.
184+
185+ ### How to customize presentation
186+
187+ You'll customize the presentation of a transition when you need to do any of the following:
188+
189+ - Add views, such as dimming views, that live beyond the lifetime of the transition.
190+ - Change the destination frame of the presented view controller.
191+
192+ #### Step 1: Subclass UIPresentationController
193+
194+ You must subclass UIPresentationController in order to implement your custom behavior. If the user
195+ of your transition can customize any presentation behavior then you'll want to define a custom
196+ initializer.
197+
198+ > Note: Avoid storing the transition context in your presentation controller. Presentation
199+ > controllers live for as long as their associated view controller, while the transition context is
200+ > only valid while a transition is active. Each presentation and dismissal will receive its own
201+ > unique transition context. Storing the context in the presentation controller would keep the
202+ > context alive longer than it's meant to.
203+
204+ Override any ` UIPresentationController ` methods you'll need in order to implement your motion.
205+
206+ ``` swift
207+ final class MyPresentationController : UIPresentationController {
208+ }
209+ ```
210+
211+ #### Step 2: Implement TransitionWithPresentation on your transition
212+
213+ This ensures that your transition implement the required methods for presentation.
214+
215+ Presentation will only be customized if you return ` .custom ` from the
216+ ` defaultModalPresentationStyle ` method and a non-nil ` UIPresentationController ` subclass from the
217+ ` presentationController ` method.
218+
219+ ``` swift
220+ extension VerticalSheetTransition : TransitionWithPresentation {
221+ func defaultModalPresentationStyle () -> UIModalPresentationStyle {
222+ return .custom
223+ }
224+
225+ func presentationController (forPresented presented : UIViewController,
226+ presenting
227+ source ? ) -> UIPresentationController? {
228+ return MyPresentationController (presentedViewController : presented, presenting : presenting)
229+ }
230+ }
231+ ```
232+
233+ #### Optional Step 3: Implement Transition on your presentation controller
234+
235+ If your presentation controller needs to animate anything, you can conform to the ` Transition `
236+ protocol in order to receive a ` start ` invocation each time a transition begins. The presentation
237+ controller's ` start ` will be invoked before the transition's ` start ` .
238+
239+ > Note: It's possible for your presentation controller and your transition to have different ideas
240+ > of when a transition has completed, so consider which object should be responsible for invoking
241+ > ` transitionDidEnd ` . The ` Transition ` object is usually the one that calls this method.
242+
243+ ``` swift
244+ extension MyPresentationController : Transition {
245+ func start (with context : TransitionContext) {
246+ // Your motion...
247+ }
248+ }
249+ ```
54250
55251## Contributing
56252
57253We welcome contributions!
58254
59- Check out our [ upcoming milestones] ( https://github.com/material-motion/material-motion- transitioning-objc/milestones ) .
255+ Check out our [ upcoming milestones] ( https://github.com/material-motion/transitioning-objc/milestones ) .
60256
61257Learn more about [ our team] ( https://material-motion.github.io/material-motion/team/ ) ,
62258[ our community] ( https://material-motion.github.io/material-motion/team/community/ ) , and
0 commit comments