Table of contents

A few months ago I had a chance to implement an expandable menu that behaves same as the one in a popular iOS application (like Airbnb). Then I thought it would be great to have it available in form of a library. Now I want to share with you some solutions that I have created in order to implement beautiful scroll driven animations.

scroll driven animations

The library supports 3 states. The main goal is to achieve smooth transitions between states while scrolling UIScrollView.

Supprted states for UIScrollView
Supported states

UIScrollView

UIScrollView is an iOS SDK view that supports scrolling and zooming. It is used as a superclass of UITableView and UICollectionView, so you can use them wherever UIScrollView is supported.

UIScrollView uses UIPanGestureRecognizer internally to detect scrolling gestures. Scrolling state of UIScrollView is defined as contentOffset: CGPoint property. Scrollable area is union of contentInsets and contentSize. So the starting contentOffset is CGPoint(x: -contentInsets.left, y: -contentInsets.right) and ending is CGPoint(x: contentSize.width — frame.width+contentInsets.right, y: contentSize.height — frame.height+contentInsets.bottom).

UIScrollView has a bounces: Bool property. In case bounces is on contentOffset can change to value above/below limits. We need to keep that in mind.

We are interested in contentOffset: CGPoint property for changing our menu state. The main way of observing scroll view contentOffset is setting an object to delegate property and implementing scrollViewDidScroll(UIScrollView) method. There is no way to use delegate without affecting other client code in Swift (because NSProxy is not available) so I have decided to use Key-Value Observing.

Observable

I have created Observable class that can wrap any type of observing.

CODE:https://gist.github.com/EvgenyMatviyenko/6c39227d90703c3ad71ca20a52b7c68b.js

And two Observable subclasses:

  • KVObservable — for wrapping Key-Value Observing.

CODE:https://gist.github.com/EvgenyMatviyenko/b4e428bf3efac0cd00f409bd3529fb2b.js

  • GestureStateObservable — for wrapping target-action observing of UIGestureRecognizer state.

CODE:https://gist.github.com/EvgenyMatviyenko/c6a84b02a2b554003041593a8c680492.js

Scrollable

To make library testable I have implemented Scrollable protocol. I also needed a way to make UIScrollView provide Observables for contentOffset, contentSize and panGestureRecognizer.state. Protocol conformance is a good way to do this. Apart from observables it contains all properties that library needs to use. It also contains updateContentOffset(CGPoint, animated: Bool) method to set contentOffset with animation.

CODE:https://gist.github.com/EvgenyMatviyenko/569406bae0711d6cf0388c55fd200dbc.js

I have not used a native setContentOffset(...) method of UIScrollView for updating contentOffset cause UIKit animations API is more flexible IMO. The problem here is that setting contentOffset directly to property doesn’t stop UIScrollView deceleration, so updateContentOffset(…) method stops it via setting current contentOffset without animation.

State

I wanted to have predictable menu state. That is why I have isolated all mutable state in State struct that contains offset, isExpandedStateAvailable and configuration properties.

CODE:https://gist.github.com/EvgenyMatviyenko/0eabc17a067724e312bb28be157e2285.js

offset is just an inverted height of menu. I decided to use offset instead of height, because scrolling down decreases height when scrolling up increases. offset is being calculated like offset = previousOffset + (contentOffset.y — previousContentOffset.y);

  • isExpandedStateAvailable property determines should offset go below -normalStateHeight to -expandedStateHeight or not;
  • configuration is a struct that contains menu height constants.

CODE:https://gist.github.com/EvgenyMatviyenko/3bc8e164503b15373977d9730deaecea.js

BarController

BarController is the main object that makes all state calculation magic and provides state changes to users.

CODE:https://gist.github.com/EvgenyMatviyenko/243f0d2b609f6220d9c60cb23db21cea.js

It takes stateReducer, configuration and stateObserver as initializer arguments.

  • stateObserver closure is called on a didSet observer of state property. It notifies library user about state changes.
  • stateReducer is a function that takes previous state, some scrolling context params and returns a new state. Injecting it through initializer provides decoupling between state calculation logic and BarController object itself.

CODE:https://gist.github.com/EvgenyMatviyenko/3210dc0e822b7920fa4ace5f31bdf62b.js

Default state reducer calculates difference between contentOffset.y and previousContentOffset.y and applies provided transformers one-by-one. After that it returns new state with offset = previousState.offset + deltaY.

CODE:https://gist.github.com/EvgenyMatviyenko/05acafda2a86858a6d6e9acab705dcf4.js

The library uses 3 transformers for reducing state:

  • ignoreTopDeltaYTransformer — makes sure that scrolling above top of UIScrollView is being ignored and does not affect BarController state;

CODE:https://gist.github.com/EvgenyMatviyenko/15b5a1e12e408fe0df6e15492529cd7c.js

  • ignoreBottomDeltaYTransformer — same as ignoreTopDeltaYTransformer, but for scrolling below bottom;

CODE:https://gist.github.com/EvgenyMatviyenko/f13b1120725d588d509b20b586a17a81.js

  • cutOutStateRangeDeltaYTransformer — cuts out extra delta Y, that goes out of minimum/maximum limits of BarController supported states.

CODE:https://gist.github.com/EvgenyMatviyenko/28fa3450bd939947aa18c22b8273a9ce.js

BarController calls a stateReducer and sets result as a state every time contentOffset changes.

CODE:https://gist.github.com/EvgenyMatviyenko/6cb00a53e678fcaf1a7d7411f804a43c.js

For now the library is able to transform contentOffset changes into internal state changes, but isExpandedStateAvailable state property is never being mutated as well as state transitions are not being finished.

That is where panGestureRecognizer.state observing comes in:

CODE:https://gist.github.com/EvgenyMatviyenko/621b2f432a704853c8e69360867750da.js

  • Pan gesture sets isExpandedStateAvailable state property to true in case panning began in the top of scrolling or in case we already have an expanded state;

CODE:https://gist.github.com/EvgenyMatviyenko/d9bf64f63e397d0315f1b26e02ecf147.js

  • Pan gesture change sets isExpandedStateAvailable if state offset reached normal state;

CODE:https://gist.github.com/EvgenyMatviyenko/d73e2340fd09ff484049038a3e40111e.js

  • Pan gesture end finds offset that is most near current state, adds a difference to current content offset and calls updateContentOffset(CGPoint, animated: Bool) with result content offset to end state transition animation.

CODE:https://gist.github.com/EvgenyMatviyenko/92f694d788b3640af68bbad356b0e29e.js

So expanded state becomes available only when the user starts scrolling at the top of available scrollable area. If expanded state was available and user scrolls below normal state, expanded state turns off. And if the user ends the panning gesture during state transition BarController updates content offset with animation to finish it.

Binding UIScrollView to BarController

BarController contains 2 public methods that the user can use to assign UIScrollView. In most cases the user should use set(scrollView: UIScrollView) method. There is also preconfigure(scrollView: UIScrollView) method, it configures the scroll view’s visual state to be consistent with the current BarController state. It should be used when the scroll view is about to be swapped. For example the user can replace current scroll view with animation and want second scroll view to be visually configured in the beginning of animation. After animation completion the user should call set(scrollView: UIScrollView). preconfigure(scrollView: UIScrollView) method is not needed to be called if UIScrollView is set once, cause set(scrollView: UIScrollView) calls it internally.

preconfigure method finds difference between contentSize height and frame height and puts it as a bottom content inset so that the menu remains expandable, configures contentInsets.top and scrollIndicatorInsets.top and sets initial contentOffset to make the new scroll view visually consistent with the state offset.

CODE:https://gist.github.com/EvgenyMatviyenko/eab92f86d5632f195f38054f6be9e5d8.js

API

To inform users about state changes BarController calls injected stateObserver function with changed State model object.

State struct has several public methods for getting useful information from internal state:

  • height()— returns reversed offset, actually height of menu;

CODE:https://gist.github.com/EvgenyMatviyenko/e49cc21ea951f680cfccb65748f1da0c.js

  • transitionProgress()— returns transition progress from 0 to 2, where 0 — compact state, 1 — normal state, 2 — expanded state;

CODE:https://gist.github.com/EvgenyMatviyenko/a076596e2e7a87ae8a78d07fdd76618c.js

  • value(compactNormalRange: ValueRangeType, normalExpandedRange: ValueRangeType) — returns transition progress mapped to one of 2 range types according to the current StateRange.

CODE:https://gist.github.com/EvgenyMatviyenko/f5643318894ba4fb25226f2a960b253a.js

Here is an example from AirBarExampleApp with a use of State public methods. airBar.frame.height is animated with height() and backgroundView.alpha is animated using value(...). Background view alpha here is interpolated from transition progress to (0, 1) range in compact-normal transition and constantly 1 in normal-expanded transition.

CODE:https://gist.github.com/EvgenyMatviyenko/b09234a7c2d167b01c8d2bbf5021e6f4.js

Conclusions

As a result, I got a beautiful scroll driven menu with predictable state and a lot of experience working with UIScrollView.

The library, example application and installation guide can be found here:

[embed]https://github.com/uptechteam/AirBar[/embed]

Feel free to use it for your own purposes. Let me know if you have any difficulties with it.

Thank you for reading!

We did the investigation of the topic for the Freebird Rides app we’ve built here at Uptech.