Skip to content

Commit cce3786

Browse files
committed
setup gitbook
1 parent c5134b5 commit cce3786

15 files changed

+703
-4
lines changed

.gitignore

+5-1
Original file line numberDiff line numberDiff line change
@@ -63,4 +63,8 @@ Carthage/Build
6363
fastlane/report.xml
6464
fastlane/Preview.html
6565
fastlane/screenshots
66-
fastlane/test_output
66+
fastlane/test_output
67+
68+
# Gitbook
69+
node_modules
70+
_book

README.md

+3-3
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
<img src="https://cdn.rawgit.com/lkzhao/Hero/427d5f2/Resources/Hero.svg" width="388"/>
22

3+
**Hero** is a library for building iOS view controller transitions. It provides a declarative layer on top of the UIKit's cumbersome transition APIs. Making custom transitions an easy task for developers.
4+
35
[![Carthage compatible](https://img.shields.io/badge/Carthage-Compatible-brightgreen.svg?style=flat)](https://github.com/Carthage/Carthage)
46
[![Version](https://img.shields.io/cocoapods/v/Hero.svg?style=flat)](http://cocoapods.org/pods/Hero)
57
[![License](https://img.shields.io/cocoapods/l/Hero.svg?style=flat)](https://github.com/lkzhao/Hero/blob/master/LICENSE?raw=true)
@@ -9,16 +11,14 @@
911
[![中文 README](https://img.shields.io/badge/%E4%B8%AD%E6%96%87-README-blue.svg?style=flat)](https://github.com/lkzhao/Hero/blob/master/README.zh-cn.md)
1012
[![Donate](https://img.shields.io/badge/Donate-PayPal-blue.svg)](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=NT5F7Y2MPV7RE)
1113

12-
**Hero** is a library for building iOS view controller transitions. It provides a layer on top of the UIKit's cumbersome transition APIs. Making custom transitions an easy task for developers.
13-
1414
<img src="https://cdn.rawgit.com/lkzhao/Hero/ebb3f2c/Resources/features.svg"/>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
1515
<img src="https://cdn.rawgit.com/lkzhao/Hero/ebb3f2c/Resources/features2.svg"/>
1616

1717
Hero is similar to Keynote's **Magic Move**. It checks the `heroID` property on all source and destination views. Every matched view pairs are then automatically transitioned from its old state to its new state.
1818

1919
Hero can also construct animations for unmatched views. It is easy to define these animations via the `heroModifiers` property. Hero will run these animations alongside the **Magic Move** animations. All of these animations can be **interactively controlled** by user gestures.
2020

21-
At view controller level, Hero provides several template transitions that you can set through `heroModalAnimationType`, `heroNavigationAnimationType`, & `heroTabBarAnimationType`. These can be used as the foundation of your custom transitions. Combine with `heroID` & `heroModifiers` to make truly some unique transitions.
21+
At view controller level, Hero provides several template transitions that you can set through `heroModalAnimationType`, `heroNavigationAnimationType`, & `heroTabBarAnimationType`. These can be used as the foundation of your custom transitions. Combine with `heroID` & `heroModifiers` to make your unique transitions.
2222

2323
<img src="https://cdn.rawgit.com/lkzhao/Hero/ebb3f2c/Resources/defaultAnimations.svg"/>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
2424
<img src="https://cdn.rawgit.com/lkzhao/Hero/ebb3f2c/Resources/defaultAnimations2.svg"/>

SUMMARY.md

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
docs/README.md

book.json

+14
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
{
2+
"gitbook": "3.2.2",
3+
"title": "Hero",
4+
"plugins": ["edit-link", "prism", "-highlight", "github", "anchorjs"],
5+
"pluginsConfig": {
6+
"edit-link": {
7+
"base": "https://github.com/lkzhao/Hero/tree/master",
8+
"label": "Edit This Page"
9+
},
10+
"github": {
11+
"url": "https://github.com/lkzhao/Hero/"
12+
}
13+
}
14+
}

docs/ChangeLog.md

+193
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,193 @@
1+
## 0.3.2
2+
* new properties for specifying default animations
3+
```swift
4+
extension UIViewController {
5+
/// default hero animation type for presenting & dismissing modally
6+
public var heroModalAnimationType: HeroDefaultAnimationType
7+
}
8+
extension UINavigationController {
9+
/// default hero animation type for push and pop within the navigation controller
10+
public var heroNavigationAnimationType: HeroDefaultAnimationType
11+
}
12+
extension UITabBarController {
13+
/// default hero animation type for switching tabs within the tab bar controller
14+
public var heroTabBarAnimationType: HeroDefaultAnimationType
15+
}
16+
```
17+
* bug fixes https://github.com/lkzhao/Hero/issues/90 https://github.com/lkzhao/Hero/issues/85
18+
* basic support for animating UIVisualEffectView's effect property in iOS 10
19+
20+
## 0.3.0
21+
* support `.overFullScreen` modalPresentationStyle
22+
* Implement many new default transitions. (fade was the only default transition before this update)
23+
24+
* **.push(direction: Direction)**
25+
* **.pull(direction: Direction)**
26+
* **.cover(direction: Direction)**
27+
* **.uncover(direction: Direction)**
28+
* **.slide(direction: Direction)**
29+
* **.zoomSlide(direction: Direction)**
30+
* **.pageIn(direction: Direction)**
31+
* **.pageOut(direction: Direction)**
32+
33+
* a few new modifiers:
34+
* **beginWith(modifiers:[HeroModifier])**
35+
* **durationMatchLongest**
36+
* **overlay(color:UIColor, opacity:CGFloat)**
37+
* **masksToBounds(_ masksToBounds: Bool)**
38+
39+
## 0.1.7
40+
* fix a zPosition regression introduced in 0.1.5
41+
42+
## 0.1.6
43+
* fix a regression introduced in 0.1.5 where animation for matched view might appear inconsistent.
44+
45+
## 0.1.5
46+
* fix a bug where toViewController's delegate callbacks are not being called
47+
* fix a bug where fromViewController's delegate callbacks receive incorrect parameters.
48+
* Add **useScaleBasedSizeChange** modifier.
49+
Force Hero use scale based size animation. This will convert all `.size` modifier into `.scale` modifier.
50+
This is to help Hero animate layers that doesn't support bounds animation. Also gives better performance when animating.
51+
52+
* fix a few bugs with `.useNoSnapshot`
53+
* new video player example.
54+
55+
## 0.1.4
56+
* fix a bug where changing orientation doesn't affect previous VC. https://github.com/lkzhao/Hero/issues/60
57+
* fix a bug where the presented view controller has incorrect frame. https://github.com/lkzhao/Hero/issues/63, https://github.com/lkzhao/Hero/issues/56
58+
* New **snapshot type** modifiers:
59+
* **useOptimizedSnapshot**
60+
61+
With this modifier, Hero will create snapshot optimized for different view type when animating.
62+
For custom views or views with masking, useOptimizedSnapshot might create snapshots
63+
that appear differently than the actual view.
64+
In that case, use .useNormalSnapshot or .useSlowRenderSnapshot to disable the optimization.
65+
* **useNormalSnapshot**
66+
67+
Create snapshot using snapshotView(afterScreenUpdates:).
68+
* **useLayerRenderSnapshot**
69+
70+
Create snapshot using layer.render(in: currentContext).
71+
This is slower than .useNormalSnapshot but gives more accurate snapshot for some views (eg. UIStackView).
72+
* **useNoSnapshot**
73+
74+
Force Hero to not create any snapshot when animating this view. Hence Hero will animate on the view directly.
75+
This will mess up the view hierarchy. Therefore, view controllers have to rebuild its view structure after the transition finishes.
76+
77+
* New navigation extension on UIViewController (mainly to support **unwinding**):
78+
* **func hero_dismissViewController()**
79+
80+
Dismiss the current view controller with animation. Will perform a navigationController.popViewController
81+
if the current view controller is contained inside a navigationController.
82+
* **func hero_replaceViewController(with:UIViewController)**
83+
84+
Replace the current view controller with another VC on the navigation/modal stack.
85+
* **func hero_unwindToRootViewController()**
86+
87+
Unwind to the root view controller using Hero.
88+
* **func hero_unwindToViewController(_ toViewController:)**
89+
90+
Unwind to a specific view controller using Hero.
91+
* **func hero_unwindToViewController(withSelector: Selector)**
92+
93+
Unwind to a view controller that responds to the given selector using Hero.
94+
* **func hero_unwindToViewController(withClass: AnyClass)**
95+
96+
Unwind to a view controller with given class using Hero.
97+
* **func hero_unwindToViewController(withMatchBlock: (UIViewController) -> Bool)**
98+
99+
Unwind to a view controller that the match block returns true on.
100+
101+
## 0.1.3
102+
* Support **local coordinate space**.
103+
104+
| Global coordinate space | Local (parent's) coordinate space |
105+
| ---- | ---- |
106+
| Animating views are **not** affected by parent views' attributes | Animating views are affected by parent views' attributes |
107+
| When parent view moves, subviews that have its own modifiers do **not** move with the parent view. I.e. they are being taken out of the view hierarchy. | When parent view moves, subviews that have its own modifiers move along with the parent view. I.e. similar to how a view behave when its parent view moves. |
108+
| Used for matched views & views with `source` modifier. Global is the default prior to 0.1.3 | Local is the default coordinate space after 0.1.3 |
109+
110+
* New **useGlobalCoordinateSpace** modifier. Force the view to use global coordinate space. I.e. won't move with its parent view.
111+
112+
## 0.1.2
113+
* `HeroPlugin` returning .infinity duration will be treated as wanting interactive transition
114+
* few bug fixes.
115+
* Update plugin API protocol to be more concise.
116+
117+
## 0.1.1
118+
* Swift Package Manager Support, Thanks to [@mRs-](https://github.com/mRs-)
119+
* Bug fixes #41, #36, & #38
120+
* Cleaner navigation bar animation.
121+
* Better alpha animation support.
122+
123+
## 0.1.0
124+
* add **HeroModifier** class and **HeroTargetState** struct
125+
* **HeroModifier** is a swift enum-like class that provides the same functionality of the original string-based **heroModifiers**.
126+
* **HeroTargetState** is a struct that holds view state informations. It can be build from **[HeroModifier]**. Mostly used internally and for building **HeroPlugin**.
127+
* change the original `heroModifiers:String?` to `heroModifierString:String?` **(breaking change!)**
128+
* add `heroModifiers:[HeroModifier]?` to **UIView**
129+
* add a shared singleton `Hero` object for controlling the interactive transition. Which can be accessed by `Hero.shared`
130+
* few changes to the protocols
131+
* protocol **HeroAnimator**
132+
133+
```swift
134+
func temporarilySet(view:UIView, to modifiers:HeroModifiers)
135+
// to
136+
func temporarilySet(view:UIView, targetState:HeroTargetState)
137+
```
138+
* protocol **HeroViewControllerDelegate**
139+
140+
```swift
141+
@objc optional func wantInteractiveHeroTransition(context:HeroInteractiveContext) -> Bool
142+
// to
143+
@objc optional func wantInteractiveHeroTransition() -> Bool
144+
```
145+
* remove **HeroInteractiveContext** protocol
146+
* update **HeroPlugin** to conform to the new protocols definitions.
147+
* rename a few modifiers:
148+
* **curve** **timingFunction**
149+
* **sourceID** **source**
150+
* **clearSubviewModifiers** **ignoreSubviewModifiers**
151+
* fix a bug with `heroReplaceViewController` API. [PR 30](https://github.com/lkzhao/Hero/pull/30)
152+
* fix a bug with **UIStackView** not animating correctly. [PR 22](https://github.com/lkzhao/Hero/pull/22)
153+
* add **recursive** `ignoreSubviewModifiers` modifier
154+
* add **radial** & **inverseRadial** cascade:
155+
156+
<img src="https://cloud.githubusercontent.com/assets/3359850/21759371/a95e0bea-d5f8-11e6-8568-d0e02ef2b6fe.gif" width="200" />
157+
158+
### To migrate from previous versions:
159+
160+
Do a whole-project **find & replace**(cmd+option+shift+F) for:
161+
162+
* **heroModifiers** **heroModifierString**
163+
* **curve** **timingFunction**
164+
* **sourceID** **source**
165+
* **clearSubviewModifiers** **ignoreSubviewModifiers**
166+
167+
Remember to also replace these inside the storyboard. In code, please migrate to the new type-safe `heroModifiers`. It provides better type-checking and more functionality.
168+
169+
## 0.0.5
170+
* Add live injection example
171+
* Make `snapshotView` available to all HeroAnimators.
172+
* Add `heroWillStartTransition` & `heroDidEndTransition` callbacks to `HeroViewControllerDelegate`
173+
* Fix animation for UIStackView https://github.com/lkzhao/Hero/pull/18
174+
* Smoother UIImageView animation for bounds change https://github.com/lkzhao/Hero/pull/16
175+
176+
## 0.0.4
177+
* Add Carthage support
178+
179+
## 0.0.3
180+
* Cleaner resume animation after an interactive transition.
181+
* plugin API: `seekTo(progress:Double)` changed to `seekTo(timePassed:TimeInterval)`
182+
* plugin API: `resume(progress:Double, reverse:Bool)` changed to `resume(timePassed:TimeInterval, reverse:Bool)`
183+
* provides dynamic duration by default.
184+
[material design(duration & timing)](https://material.io/guidelines/motion/duration-easing.html#duration-easing-dynamic-durations)
185+
186+
## 0.0.2
187+
* rename `clearSubviewClasses` to `clearSubviewModifiers`. was a naming mistake.
188+
* set default animation to be CABasicAnimation with the **Standard Curve** from [material design (easing)](https://material.io/guidelines/motion/duration-easing.html#duration-easing-natural-easing-curves).
189+
* add the new **arc** effect from [material design (movement)](https://material.io/guidelines/motion/movement.html#movement-movement-within-screen-bounds).
190+
* add **arc** effect to **Basic**, **Menu**, & **ListToGrid** examples.
191+
* add the ability to show arc path in the Debug Plugin.
192+
* ignore `HeroModifiers` for source view when matched with a target view with the same `HeroID`
193+
* some small optimization & bug fixes

docs/ContributionGuide.md

+24
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
# Issues
2+
If you run into problems, please open an issue.
3+
4+
When filling bugs, we can best help you if you include the following:
5+
6+
1. Screenshot of video of what happened.
7+
2. Description of what suppose to happen.
8+
3. An example project would be nice.
9+
10+
11+
# PR
12+
#### Before you do any work to the library. Be sure to create an issue first!!
13+
14+
We welcome pull requests. By contributing to Hero you agree that your contributions will be licensed under its MIT license. Your work is appreciated!
15+
16+
But before you do any real work, especially framework changes, check if there is any existing issues. Some people might be working on the issues already. For API changes, we need detailed discussion before continuing.
17+
18+
# Ways you can help
19+
* Help us test the latest master branch.
20+
* Grab existing issues. (Checkout the project tab for todos, make sure you reply to the issue to let us know that you have started working on it.)
21+
22+
# Code Style
23+
* 2 space indent
24+
* follow [Swift Style Guide](https://github.com/raywenderlich/swift-style-guide) as much as possible.

docs/CoordinateSpace.md

+21
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
### Global Coordinate Space (default before 0.1.3)
2+
3+
Animating views are **not** affected by parent views' attributes. Does not move with the parent view. I.e. They are being taken out of the view hierarchy once heroModifiers are applied. Use `useGlobalCoordinateSpace` modifier to force this behavior after 0.1.3.
4+
5+
<img src="https://cdn.rawgit.com/lkzhao/Hero/ecec15de7747d9541db9af62e4001da6bf0b3896/Resources/globalCoordinate.svg" />
6+
7+
### Local Coordinate Space (default after 0.1.3)
8+
9+
Animating views moves along with its parent view. Note that when a view is matched, or when `source` or `useGlobalCoordinateSpace` modifiers are used, the view will go back to global coordinate space.
10+
11+
<img src="https://cdn.rawgit.com/lkzhao/Hero/ecec15de7747d9541db9af62e4001da6bf0b3896/Resources/localCoordinate.svg" />
12+
13+
For the examples above, the following heroModifiers are applied.
14+
15+
```swift
16+
greyView.heroModifiers = [.translate(y:100)]
17+
blackView.heroModifiers = nil
18+
redView.heroModifiers = [.translate(x:50)]
19+
```
20+
21+
When using local coordinate space, the view is contained inside a global coordinate spaced view. Other global spaced view might appear on top of these local spaced views. If you want a view to appear on top of another global spaced view, you will have to change it to global spaced as well by using the `useGlobalCoordinateSpace` modifier.

docs/DefaultAnimations.md

+57
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
# Default Animations
2+
3+
Starting with **0.3.0**. Hero provides several default transitions. These can also be customized & combined with your custom `heroID` & `heroModifiers`. Makes transitions even easier to implement.
4+
5+
<img src="https://cdn.rawgit.com/lkzhao/Hero/ebb3f2c/Resources/defaultAnimations.svg"/>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
6+
<img src="https://cdn.rawgit.com/lkzhao/Hero/ebb3f2c/Resources/defaultAnimations2.svg"/>
7+
8+
## Methods for changing the default animations
9+
10+
Use the following properties to change default animation type for different presentation methods.
11+
12+
```swift
13+
extension UIViewController {
14+
/// default hero animation type for presenting & dismissing modally
15+
public var heroModalAnimationType: HeroDefaultAnimationType
16+
}
17+
extension UINavigationController {
18+
/// default hero animation type for push and pop within the navigation controller
19+
public var heroNavigationAnimationType: HeroDefaultAnimationType
20+
}
21+
extension UITabBarController {
22+
/// default hero animation type for switching tabs within the tab bar controller
23+
public var heroTabBarAnimationType: HeroDefaultAnimationType
24+
}
25+
```
26+
27+
## Supported default animations
28+
29+
Please checkout [HeroDefaultAnimations.swift](https://github.com/lkzhao/Hero/blob/master/Sources/HeroDefaultAnimations.swift#L25) for supported animations.
30+
31+
Many of these animations support directions(up, down, left, right).
32+
33+
## .auto Animation Type
34+
35+
`.auto` is the default animation type. It uses the following animations depending on the presentation style:
36+
37+
* `.none` if source root view or destination root view have existing animations (defined via `heroID` or `heroModifiers`).
38+
* `.push` & `.pull` if animating within a UINavigationController.
39+
* `.slide` if animating within a UITabbarController.
40+
* `.fade` if presenting modally.
41+
* `.none` if presenting modally with `modalPresentationStyle == .overFullScreen`.
42+
43+
## .selectBy(presenting:, dismissing:) Animation Type
44+
45+
Will determine the animation type by whether or not we are presenting or dismissing.
46+
47+
For example:
48+
49+
```swift
50+
.selectBy(presenting:.push(.left), dismissing:.pull(.right))
51+
```
52+
53+
Will use left push animation if presenting a VC, or right pull animation when dismissing a VC.
54+
55+
## Note
56+
57+
Other than `.auto` & `.none`, default animations will override `heroModifiers` on source & destination root views during the transition.

0 commit comments

Comments
 (0)