1 //  Copyright (c) 2018, Applidium. All rights reserved
2 //  OverlayContainerViewControllerDelegate.swift
3 //  OverlayContainer
4 //
5 //  Created by Gaétan Zanella on 23/11/2018.
6 //
7 
8 import UIKit
9 
10 /// The container delegate is responsible for defining the aspect and the behavior of the container.
11 public protocol OverlayContainerViewControllerDelegate: AnyObject {
12 
13     /// Asks the delegate for the number of notches in the container.
14     /// **Required**.
15     ///
16     /// - parameter containerViewController: The container requesting this information.
17     ///
18     /// - returns: The number of notches in `containerViewController`.
numberOfNotchesnull19     func numberOfNotches(in containerViewController: OverlayContainerViewController) -> Int
20 
21     /// Asks the delegate for the height of a notch in a specified location.
22     /// **Required**.
23     ///
24     /// - parameter containerViewController: The container requesting this information.
25     /// - parameter index: The index that locates the notch.
26     /// - parameter availableSpace: The height of the zone defined by the overlay.
27     ///
28     /// - returns: A nonnegative floating-point value that specifies the height that notch should be.
29     ///
30     /// - attention: The notches must be ordered from the smallest one (index 0) to the highest one
31     /// and must not exceed the available space.
32     func overlayContainerViewController(_ containerViewController: OverlayContainerViewController,
33                                         heightForNotchAt index: Int,
34                                         availableSpace: CGFloat) -> CGFloat
35 
36     /// Asks the delegate for a scroll view driving the overlay view controller translation.
37     ///
38     /// The container view controller can coordinate the scrolling of a scroll view
39     /// to the overlay view controller translation. The overlay will be moved up & down as the user scrolls.
40     /// The content offset of the scroll view will be adjusted accordingly.
41     ///
42     /// - parameter containerViewController: The container requesting this information.
43     /// - parameter overlayViewController: The overlay view controller.
44     ///
45     /// - returns: A scroll view to use as a translation driver.
46     func overlayContainerViewController(_ containerViewController: OverlayContainerViewController,
47                                         scrollViewDrivingOverlay overlayViewController: UIViewController) -> UIScrollView?
48 
49     /// Asks the delegate if the container should drag the overlay view controller
50     /// when the user starts a pan gesture at the specified location.
51     ///
52     /// The container view controller detects pan gestures on its own view.
53     /// It calls this method each time a pan gesture is detected.
54     /// If the gesture begins in the scroll view specified in `overlayContainerViewController(_:, scrollViewDrivingOverlay:)`,
55     /// the gesture is aborted and this method is not called.
56     ///
57     /// - parameter containerViewController: The container requesting this information.
58     /// - parameter overlayViewController: The overlay view controller.
59     /// - parameter point: The starting point of the gesture.
60     /// - parameter coordinateSpace: The coordinate space of point.
61     ///
62     /// - returns: `true` if the translation should start or `false` if it should not.
63     func overlayContainerViewController(_ containerViewController: OverlayContainerViewController,
64                                         shouldStartDraggingOverlay overlayViewController: UIViewController,
65                                         at point: CGPoint,
66                                         in coordinateSpace: UICoordinateSpace) -> Bool
67 
68     /// Tells the delegate when the user is about to start dragging the overlay view controller.
69     ///
70     /// - parameter containerViewController: The container requesting this information.
71     /// - parameter overlayViewController: The overlay view controller.
72     func overlayContainerViewController(_ containerViewController: OverlayContainerViewController,
73                                         willStartDraggingOverlay overlayViewController: UIViewController)
74 
75     /// Tells the delegate when the user finishs dragging the overlay view controller with the specified velocity.
76     ///
77     /// - parameter containerViewController: The container requesting this information.
78     /// - parameter overlayViewController: The overlay view controller.
79     /// - parameter velocity: The overlay velocity at the moment the touch was released.
80     func overlayContainerViewController(_ containerViewController: OverlayContainerViewController,
81                                         willEndDraggingOverlay overlayViewController: UIViewController,
82                                         atVelocity velocity: CGPoint)
83 
84     /// Tells the delegate when the container is about to move the overlay view controller to the specified notch.
85     ///
86     /// In some cases, the overlay view controller may not successfully reach the specified notch.
87     /// If the user cancels the translation for instance. Use `overlayContainerViewController(_:didMove:toNotchAt:)`
88     /// if you need to be notified each time the translation succeeds.
89     ///
90     /// - parameter containerViewController: The container requesting this information.
91     /// - parameter overlayViewController: The overlay view controller.
92     /// - parameter index: The notch index the overlay view controller is about to reach.
93     func overlayContainerViewController(_ containerViewController: OverlayContainerViewController,
94                                         willMoveOverlay overlayViewController: UIViewController,
95                                         toNotchAt index: Int)
96 
97     /// Tells the delegate when the container has moved the overlay view controller to the specified notch.
98     ///
99     /// - parameter containerViewController: The container requesting this information.
100     /// - parameter overlayViewController: The overlay view controller.
101     /// - parameter index: The notch index the overlay view controller has reached.
102     func overlayContainerViewController(_ containerViewController: OverlayContainerViewController,
103                                         didMoveOverlay overlayViewController: UIViewController,
104                                         toNotchAt index: Int)
105 
106     /// Tells the delegate whenever the overlay view controller is about to be translated.
107     ///
108     /// The delegate typically implements this method to coordinate changes alongside
109     /// the overlay view controller translation.
110     ///
111     /// For instance, the container may call this method for the following reasons:
112     ///
113     /// - The user is dragging the overlay view controller
114     /// - The user finishs dragging the overlay view controller and the container is about to move
115     /// to the notch specified by the current target notch policy
116     /// - You called `moveOverlay(toNotchAt:animated:completion:)`
117     ///
118     /// - parameter containerViewController: The container requesting this information.
119     /// - parameter overlayViewController: The overlay view controller.
120     /// - parameter transitionCoordinator: The transition coordinator object associated with the translation.
121     func overlayContainerViewController(_ containerViewController: OverlayContainerViewController,
122                                         willTranslateOverlay overlayViewController: UIViewController,
123                                         transitionCoordinator: OverlayContainerTransitionCoordinator)
124 
125     /// Asks the delegate for a translation function when dragging the specified view controller.
126     ///
127     /// The function is only used for translation based on the container pan gesture recognizer.
128     ///
129     /// - parameter containerViewController: The container requesting this information.
130     /// - parameter overlayViewController: The overlay view controller.
131     ///
132     /// - returns: A overlay translation function.
133     func overlayContainerViewController(_ containerViewController: OverlayContainerViewController,
134                                         overlayTranslationFunctionForOverlay overlayViewController: UIViewController) -> OverlayTranslationFunction?
135 
136     /// Asks the delegate for an object providing the translation end animator.
137     ///
138     /// - parameter containerViewController: The container requesting this information.
139     /// - parameter overlayViewController: The overlay view controller.
140     ///
141     /// - returns: A object implementing the `OverlayTransitioningDelegate` protocol.
142     func overlayContainerViewController(_ containerViewController: OverlayContainerViewController,
143                                         transitioningDelegateForOverlay overlayViewController: UIViewController) -> OverlayTransitioningDelegate?
144 
145     /// Asks the delegate if the container can reach the specified notch.
146     ///
147     /// - parameter containerViewController: The container requesting this information.
148     /// - parameter index: The index locating the notch.
149     /// - parameter overlayViewController: The overlay view controller.
150     ///
151     /// - returns: `true` if the overlay is allowed to reach the specified notch index or `false` if it should not.
152     func overlayContainerViewController(_ containerViewController: OverlayContainerViewController,
153                                         canReachNotchAt index: Int,
154                                         forOverlay overlayViewController: UIViewController) -> Bool
155 }
156