Usage Guide
Drag the Hero folder into your project. (Download)
pod "Hero"
- In the Identity Inspector, for every pair of source/destination views, give them the same
HeroIDattribute. - For any other views that you would like to animate, specify the animation effects in
HeroModifiersattribute. - Also in the Identity Inspector. Enable Hero Transition on your destination view controller.
- Before doing a transition, set the desired
heroID&HeroModifiersto source & destination views. - Enables Hero for the destination view controller
viewController.isHeroEnabled = trueFor UINavigationController & UITabBarController, you will need to enabled Hero on the navigation controller instance or the tab bar controller instance.
There are two important attributes to understand, HeroID and HeroModifiers. These are implemented as extensions(using associated objects) for UIView. Therefore, after the Hero library is imported, every UIView will have these two attributes. Both can be accessed from the Identity Inspector.
| Attribute Name | Description |
|---|---|
HeroID |
Identifier for the view. Hero will automatically transition between views with the same HeroID
|
HeroModifiers |
Specifies the extra animations performed alongside the main transition. |
HeroID is the identifier for the view. When doing a transition between two view controllers,
Hero will search through all the subviews for both view controllers and matches views with the same HeroID. Whenever a pair is discovered,
Hero will automatically transition the views from source state to the destination state.
Use HeroModifiers to specify animations alongside the main transition. It must be in the following syntax:
modifier1() modifier2(parameter1) modifier3(parameter1, parameter2) ...Modifiers can have parameters. Parameters must be between a pair of parentheses, seperated by a comma. Each modifier must be seperated by a space. Parameters can be string or number(float, int, & negative).
fade() translate(0, -250) rotate(-1.6, 0, 0) scale(1.5)
| Modifier Name | Description |
|---|---|
| fade | Fade in or out when transitioning |
| position(x,y) | Move to a position |
| size(w,h) | Grow/shrink to a size |
| scale(s) | Scale along both x & y axis |
| scale(x,y,z) | Scale in 3d |
| rotate(z) | Rotate in 2d |
| rotate(x,y,z) | Rotate in 3d |
| perpective(z) | Set the transform's perspective |
| translate(x,y,z) | Translate in 3d |
| Modifier Name | Description |
|---|---|
| delay(time) | Delay for the animation |
| duration(time) | Duration for the animation, if unspecified, the duration will be caculated based on the distance travelled |
| curve(curveName) | Timing function for the animation (linear, easeIn, easeOut, easeInOut, standard, deceleration, acceleration, sharp) |
| curve(c1x, c1y, c2x, c2y) | Custom cubic bezier timing function for the animation |
| spring(stiffness, damping) |
(iOS 9+) Use spring animation with custom stiffness & damping. The duration will be automatically calculated. Will be ignored if arc, curve, or duration is set. |
| zPosition(z) | The z axis height of the view during the animation phase. Not animatable. |
| zPositionIfMatched(z) | The z axis height of the view during the animation phase if being matched with another view by HeroID. Not animatable. |
| sourceID(HeroID) | Transition from a view with given heroID |
| arc(intensity) | Make position animation follow a natural arc curve. |
| cascade(deltaDelay, direction, delay, forceMatchedToWait) | Apply increasing delay to view's subview |
| clearSubviewModifiers | Disables all heroModifiers for view's direct subviews |
Some of the modifiers won't work with matched views(views with the same heroID). These are:
- fade
- scale
- translate
- transform
- rotate (x, y won't work, z axis will)
- cascade
NOTE: For other modifiers that works with matched views, the target view's modifiers will be used. the source view's modifiers will be ignored.
When animating position, if arc is enabled. the view will follow a natural arc curve instead of going to the target position directly. See material design for more details.
The intensity parameter is a number that determine the curve's intensity. A value of 0 means no curve. A value of 1 means a natural downward curve. This value can be negative or above 1. Default is 1.
Use the debug plugin and enable Show Curves to see the actually arc curve objects follows.
The sourceID modifier allows a view to be transitioned from a view with the matching heroID.
The cascade modifier automatically applies increasing delay heroModifiers to a view's direct subviews.
| Parameters | Description |
|---|---|
| deltaDelay | delay in between each animation |
| direction | the cascade direction, can be topToBottom, bottomToTop, leftToRight, & rightToLeft, default topToBottom
|
| delay | the initial delay before the first animation, default 0 |
| forceMatchedToWait | whether or not to delay matched views until all cascading animations have started, default false |
NOTE: matched views(views with the same heroID) won't have the cascading effect. however, you can use the 4th parameter to delay the start time of matched views until the last cascading animation have started. The matched views will animate simultaneously with the cascading views by default.
The clearSubviewModifiers modifier disables all heroModifiers attributes for a view's direct subviews.
Hero also support transitions within a navigation controller or a tabbar controller. Just set the 'isHeroEnabled' attribute to true on the UINavigationController instance. Same for UITabBarController.