Update documentation and examples

Example/lottie-ios/LAControlsViewController.m

@@ -31,9 +31,9 @@ - (void)viewDidLoad {
 
  LOTAnimatedSwitch *toggle1 = [LOTAnimatedSwitch switchNamed:@"Switch"];
 
- /// Off animation is 0 to 0.5 progress.
  /// On animation is 0.5 to 1 progress.
  [toggle1 setProgressRangeForOnState:0.5 toProgress:1];
+ /// Off animation is 0 to 0.5 progress.
  [toggle1 setProgressRangeForOffState:0 toProgress:0.5];
 
  [toggle1 addTarget:self action:@selector(switchToggled:) forControlEvents:UIControlEventValueChanged];

README.md

@@ -10,6 +10,7 @@
 - [Debugging Lottie](#debugging)
 - [iOS View Controller Transitioning](#ios-view-controller-transitioning)
 - [Changing Animations At Runtime](#changing-animations-at-runtime)
+- [Adding Subviews to Animation](#adding-views-to-an-animation-at-runtime)
 - [Supported After Effects Features](#supported-after-effects-features)
 - [Currently Unsupported After Effects Features](#currently-unsupported-after-effects-features)
 - [Community Contributions](#community-contributions)
@@ -241,6 +242,102 @@ If you checkout LOTHelpers.h you will see two debug flags. `ENABLE_DEBUG_LOGGING
 
 LOTAnimationView provides `- (void)logHierarchyKeypaths` which will recursively log all settable keypaths for the animation. This is helpful for changing animationations at runtime.
 
+## Adding Views to an Animation at Runtime
+
+Not only can you [change animations at runtime](#changing-animations-at-runtime) with Lottie, you can also add custom UI to a LOTAnimation at runtime.
+The example below shows some advance uses of this to create a dynamic image loader.
+
+## A Dynamic Image Loading Spinner
+
+![Spinner](/_Gifs/spinner.gif)
+
+The example above shows a single LOTAnimationView that is set with a loading spinner animation. The loading spinner loops a portion of its animation while an image is downloaded asynchronously. When the download is complete, the image is added to the animation and the rest of the animation is played seamlessly. The image is cleanly animated in and a completion block is called.
+
+![Spinner_Alt](/_Gifs/spinner_Alternative.gif)
+
+Now, the animation has been changed by a designer and needs to be updated. All that is required is updating the JSON file in the bundle. No code change needed!
+
+![Spinner_Dark](/_Gifs/spinner_DarkMode.gif)
+
+Here, the design has decided to add a 'Dark Mode' to the app. Just a few lines of code change the color of the animation at runtime.
+
+
+Pretty powerful eh?
+
+Check out the code below for an example!
+
+```swift
+
+import UIKit
+import Lottie
+
+class ViewController: UIViewController {
+
+ var animationView: LOTAnimationView = LOTAnimationView(name: "SpinnerSpin");
+
+ override func viewDidLoad() {
+ super.viewDidLoad()
+
+ // Setup our animaiton view
+ animationView.contentMode = .scaleAspectFill
+ animationView.frame = CGRect(x: 20, y: 20, width: 200, height: 200)
+
+ self.view.addSubview(animationView)
+ // Lets change some of the properties of the animation
+ // We arent going to use the MaskLayer, so lets just hide it
+ animationView.setValue(0, forKeypath: "MaskLayer.Ellipse 1.Transform.Opacity", atFrame: 0)
+ // All of the strokes and fills are white, lets make them DarkGrey
+ animationView.setValue(UIColor.darkGray, forKeypath: "OuterRing.Stroke.Color", atFrame: 0)
+ animationView.setValue(UIColor.darkGray, forKeypath: "InnerRing.Stroke.Color", atFrame: 0)
+ animationView.setValue(UIColor.darkGray, forKeypath: "InnerRing.Fill.Color", atFrame: 0)
+
+ // Lets turn looping on, since we want it to repeat while the image is 'Downloading'
+ animationView.loopAnimation = true
+ // Now play from 0 to 0.5 progress and loop indefinitely.
+ animationView.play(fromProgress: 0, toProgress: 0.5, withCompletion: nil)
+
+ // Lets simulate a download that finishes in 4 seconds.
+ let dispatchTime = DispatchTime.now() + 4.0
+ DispatchQueue.main.asyncAfter(deadline: dispatchTime) {
+ self.simulateImageDownloaded()
+ }
+ }
+
+ func simulateImageDownloaded() {
+ // Our downloaded image
+ let image = UIImage(named: "avatar.jpg")
+ let imageView = UIImageView(image: image)
+
+ // We want the image to show up centered in the animation view at 150Px150P
+ // Convert that rect to the animations coordinate space
+ // The origin is set to -75, -75 because the origin is centered in the animation view
+ let imageRect = animationView.convert(CGRect(x: -75, y: -75, width: 150, height: 150), toLayerNamed: nil)
+
+ // Setup our image view with the rect and add rounded corners
+ imageView.frame = imageRect
+ imageView.layer.masksToBounds = true
+ imageView.layer.cornerRadius = imageRect.width / 2;
+
+ // Now we set the completion block on the currently running animation
+ animationView.completionBlock = { (result: Bool) in ()
+ // Add the image view to the layer named "TransformLayer"
+ self.animationView.addSubview(imageView, toLayerNamed: "TransformLayer", applyTransform: true)
+ // Now play the last half of the animation
+ self.animationView.play(fromProgress: 0.5, toProgress: 1, withCompletion: { (complete: Bool) in
+ // Now the animation has finished and our image is displayed on screen
+ print("Image Downloaded and Displayed")
+ })
+ }
+
+ // Turn looping off. Once the current loop finishes the animation will stop 
+ // and the completion block will be called.
+ animationView.loopAnimation = false
+ }
+
+}
+
+```
+
 ## Changing Animations At Runtime
 
 Lottie can do more than just play beautiful animations. Lottie allows you to **change** animations at runtime.
@@ -309,6 +406,55 @@ animationView2.setValue(UIColor.red, forKeypath: "BG-Off.Group 1.Fill 1.Color",
 
 Lottie allows you to change **any** property that is animatable in After Effects. If a keyframe does not exist, a linear keyframe is created for you. If a keyframe does exist then just its data is replaced.
 
+## Animated Controls and Switches
+
+Lottie also has a custom subclass of UIControl for creating custom animatable interactive controls.
+Currently Lottie has `LOTAnimatedSwitch` which is a toggle style switch control. Tapping on the switch plays either the On-Off or Off-On animation and sends out a UIControlStateValueChanged broadcast to all targets. It is used in the same way UISwitch is used with a few additions to setup the animation with Lottie.
+
+You initialize the switch either using the conveneince method or by supplying the animation directly.
+
+```
+// Convenience
+LOTAnimatedSwitch *toggle1 = [LOTAnimatedSwitch switchNamed:@"Switch"];
+ 
+// Manually 
+LOTComposition *comp = [LOTComposition animationNamed:@"Switch"];
+LOTAnimatedSwitch *toggle1 = [[LOTAnimatedSwitch alloc] initWithFrame:CGRectZero];
+[toggle1 setAnimationComp:comp];
+```
+
+You can also specify a specific portion of the animation's timeline for the On and Off animation.
+By default `LOTAnimatedSwitch` will play the animation forward for On and backwards for off.
+
+Lets say that the supplied animation animates ON from 0.5-1 progress and OFF from 0-0.5:
+
+```
+/// On animation is 0.5 to 1 progress.
+[toggle1 setProgressRangeForOnState:0.5 toProgress:1];
+/// Off animation is 0 to 0.5 progress.
+[toggle1 setProgressRangeForOffState:0 toProgress:0.5];
+```
+
+Also, all LOTAnimatedControls add support for changing appearance for state changes. This requires some setup in After Effects. Lottie will switch visible animated layers based on the controls state. This can be used to have Disabled, selected, or Highlighted states. These states are associated with layer names in After Effects, and are dynamically displayed as the control changes states.
+
+Lets say we have a toggle switch with a Normal and Disabled state. In Effects we have a composition that contains Precomps of the regular "Button" and disabled "Disabled" states. They have different visual styles.
+
+![Regular](_Gifs/switch_enabled.png)
+![Disabled](_Gifs/switch_disabled.png)
+
+Now in code we can associate `UIControlState` with these layers
+
+```
+// Specify the layer names for different states
+[statefulSwitch setLayerName:@"Button" forState:UIControlStateNormal];
+[statefulSwitch setLayerName:@"Disabled" forState:UIControlStateDisabled];
+
+// Changes visual appearance by switching animation layer to "Disabled"
+statefulSwitch.enabled = NO;
+
+// Changes visual appearance by switching animation layer to "Button"
+statefulSwitch.enabled = YES;
+```
 
 ## Supported After Effects Features