//
//  ZOZolaZoomTransition.h
//  Copyright (c) 2015 Zola, Inc.
//
//  Created by Charles Scalesse
//
//  Permission is hereby granted, free of charge, to any person obtaining a
//  copy of this software and associated documentation files (the
//  "Software"), to deal in the Software without restriction, including
//  without limitation the rights to use, copy, modify, merge, publish,
//  distribute, sublicense, and/or sell copies of the Software, and to
//  permit persons to whom the Software is furnished to do so, subject to
//  the following conditions:
//
//  The above copyright notice and this permission notice shall be included
//  in all copies or substantial portions of the Software.
//
//  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
//  OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
//  MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
//  IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
//  CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
//  TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
//  SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

#import <UIKit/UIKit.h>

@protocol ZOZolaZoomTransitionDelegate;

typedef NS_ENUM(NSInteger, ZOTransitionType) {
    ZOTransitionTypePresenting,
    ZOTransitionTypeDismissing
};

/**
 `ZOZolaZoomTransition` is an animated transition used extensively in the Zola iOS application.
 In addition to zooming a target view, it also animates the entire heirarchy in which the target
 view is a part of, resulting in a fluid "z-level" animation effect. `ZOZolaZoomTransition`
 conforms to `UIViewControllerAnimatedTransitioning` and is intended to be used with navigation
 controller transitions.
 
 @warning `ZOZolaZoomTransition` makes use of `UIApplication`'s `beginIgnoringInteractionEvents` and
 `endIgnoringInteractionEvents` methods which are not available inside of app extensions. To use
 `ZOZolaZoomTransition` in an extension, define the following preprocessor macro in the extension 
 target's build settings: ZO_APP_EXTENSIONS=1
 */
@interface ZOZolaZoomTransition : NSObject <UIViewControllerAnimatedTransitioning>

/**
 Initializes a `ZOZolaZoomTransition` instance with a target view.
 
 This is the designated initializer.
 
 @param targetView The view to be zoomed
 @param type The animation type, presenting or dismissing
 @param duration The animation duration
 @param delegate The transition delegate
 
 @return The newly-initialized `ZOZolaZoomTransition` instance
 */
- (instancetype)initWithTargetView:(UIView *)targetView
                              type:(ZOTransitionType)type
                          duration:(NSTimeInterval)duration
                          delegate:(id<ZOZolaZoomTransitionDelegate>)delegate NS_DESIGNATED_INITIALIZER;

/**
 Convienence initializer for syntactical sugar.
 
 @param targetView The view to be zoomed
 @param type The animation type, presenting or dismissing
 @param duration The animation duration
 @param delegate The transition delegate
 
 @return The newly-initialized `ZOZolaZoomTransition` instance
 */
+ (instancetype)transitionFromView:(UIView *)targetView
                              type:(ZOTransitionType)type
                          duration:(NSTimeInterval)duration
                          delegate:(id<ZOZolaZoomTransitionDelegate>)delegate;

/**
 @warning Only the designated initializer or the convienece initializer
 should be used to create a new `ZOZolaZoomTransition` instance
 */
- (instancetype)init NS_UNAVAILABLE;

/**
 The "fade-through" color used during the animation. Default is `[UIColor whiteColor]`.
 */
@property (strong, nonatomic) UIColor *fadeColor;

@end

/**
 The delegate of `ZOZolaZoomTransition` must adopt the `ZOZolaZoomTransitionDelegate` protocol.
 Optional methods of the protocol allow the delegate to provide supplementary views to enhance
 the transition.
 */
@protocol ZOZolaZoomTransitionDelegate <NSObject>

@required

/**
 The starting frame for the target view. This frame must be returned relative to the
 fromViewController's view. For convienence, this view is provided explicitly.
 For example:
 
 `return [startingView convertRect:startingView.bounds toView:relativeView];`
 
 @param zoomTransition The `ZOZolaZoomTransition` instance
 @param targetView The target view
 @param relativeView The "from" view controller's view
 @param fromViewController The "from" view controller
 @param toViewController The "to" view controller
 
 @return The starting frame for the target view, relative to the fromViewController's view
 */
- (CGRect)zolaZoomTransition:(ZOZolaZoomTransition *)zoomTransition
        startingFrameForView:(UIView *)targetView
              relativeToView:(UIView *)relativeView
          fromViewController:(UIViewController *)fromViewController
            toViewController:(UIViewController *)toViewController;

/**
 The finishing frame for the target view. This frame must be returned relative to the
 toViewController's view. For convienence, this view is provided explicitly.
 For example, consider the scenario where the targetView is zooming to the frame of
 some arbitrary destination view in the "to" view controller's view:
 
 `return [destinationView convertRect:destinationView.bounds toView:relativeView];`
 
 @param zoomTransition The `ZOZolaZoomTransition` instance
 @param targetView The target view
 @param relativeView The "to" view controller's view
 @param fromViewController The "from" view controller
 @param toViewController The "to" view controller
 
 @return The finishing frame for the target view, relative to the toViewController's view
 */
- (CGRect)zolaZoomTransition:(ZOZolaZoomTransition *)zoomTransition
       finishingFrameForView:(UIView *)targetView
              relativeToView:(UIView *)relativeView
          fromViewController:(UIViewController *)fromViewComtroller
            toViewController:(UIViewController *)toViewController;

@optional

/**
 `ZOZolaZoomTransition` supports an optional array of supplementary views that will be drawn
 on top of, and animated with, the other views in the animation. Two common use cases for 
 supplementary views are:
 
 1. To draw views that are on top of, but not a child of, the target view.
 2. To draw views that are clipped by the edge of the screen when the transition begins
    and therefore appear cut off during the animation.
 
 @warning If `supplementaryViewsForZolaZoomTransition:` is implemented,
 `zolaZoomTransition:frameForSupplementaryView:` must be implemented as well.
 
 @param zoomTransition The `ZOZolaZoomTransition` instance
 
 @return The array of supplementary views
 */
- (NSArray *)supplementaryViewsForZolaZoomTransition:(ZOZolaZoomTransition *)zoomTransition;

/**
 The frame for a supplementary view. This frame must be returned relative to the originating
 view controller's view. The originating view controller is the "from" view controller during
 presentation, and the "to" view controller during dismissal. For convienence, this view is
 provided explicitly. For example:
 
 `return [supplementaryView convertRect:supplementaryView.bounds toView:relativeView];`
 
 @param zoomTransition The `ZOZolaZoomTransition` instance
 @param supplementaryView The supplementary view
 @param relativeView The originating view controller's view
 
 @return The frame for the supplementary view, relative to the originating view controller's view
 */
- (CGRect)zolaZoomTransition:(ZOZolaZoomTransition *)zoomTransition
   frameForSupplementaryView:(UIView *)supplementaryView
              relativeToView:(UIView *)relativeView;

@end