README.md 5.06 KB
Newer Older
Zach Knox's avatar
Zach Knox committed
1
2
3
4
# DeckTransition

[![CI Status](http://img.shields.io/travis/HarshilShah/DeckTransition.svg)](https://travis-ci.org/HarshilShah/DeckTransition)
[![Version](https://img.shields.io/github/release/HarshilShah/DeckTransition.svg)](https://github.com/HarshilShah/DeckTransition/releases/latest)
5
6
7
![Package Managers](https://img.shields.io/badge/supports-CocoaPods%20%7C%20Carthage-orange.svg)
[![Documentation](https://cdn.rawgit.com/HarshilShah/DeckTransition/master/docs/badge.svg)](https://harshilshah.github.com/DeckTransition)
[![License](https://img.shields.io/badge/license-MIT-999999.svg)](https://github.com/HarshilShah/DeckTransition/blob/master/LICENSE)
Zach Knox's avatar
Zach Knox committed
8
9
10
11
12
13
[![Contact](https://img.shields.io/badge/contact-%40HarshilShah1910-3a8fc1.svg)](https://twitter.com/HarshilShah1910)

DeckTransition is an attempt to recreate the card-like transition found in the iOS 10 Apple Music and iMessage apps.

Hereʼs a GIF showing it in action.

14
![Demo](https://raw.githubusercontent.com/HarshilShah/DeckTransition/master/Resources/demo.gif)
Zach Knox's avatar
Zach Knox committed
15
16
17

## Requirements

18
- Swift 4.2
Zach Knox's avatar
Zach Knox committed
19
20
21
22
23
24
25
26
27
- iOS 9 or later

## Installation

### CocoaPods

To install DeckTransition using [CocoaPods](http://cocoapods.org), add the following line to your Podfile:

```
Zach Knox's avatar
Zach Knox committed
28
pod 'DeckTransition', '~> 2.0'
Zach Knox's avatar
Zach Knox committed
29
30
31
32
33
34
35
```

### Carthage

To install DeckTransition using [Carthage](https://github.com/Carthage/Carthage), add the following line to your Cartfile:

```
Zach Knox's avatar
Zach Knox committed
36
github "HarshilShah/DeckTransition" ~> 2.0
Zach Knox's avatar
Zach Knox committed
37
38
```

39
40
41
42
## Documentation

You can find [the docs here](https://harshilshah.github.io/DeckTransition "Documentation"). Documentation is generated with [Jazzy](https://github.com/realm/jazzy), and hosted on [GitHub Pages](https://pages.github.com).

Zach Knox's avatar
Zach Knox committed
43
44
45
46
47
48
## Usage

### Basics

Set `modalPresentationCapturesStatusBarAppearance` to `true` in your modal view controller, and override the `preferredStatusBarStyle` variable to return `.lightContent`.

Zach Knox's avatar
Zach Knox committed
49
Additionally, the `UIScrollView` instances which should be tracked for the swipe-to-dismiss gesture should have their `backgroundColor` set to `.clear`.
Zach Knox's avatar
Zach Knox committed
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68

### Presentation

The transition can be called from code or using a storyboard.

To use via storyboards, just setup a custom segue (`kind` set to `custom`), and set the `class` to `DeckSegue`.

Hereʼs a snippet showing usage via code. Just replace `ModalViewController()` with your view controller's class and youʼre good to go.

```swift
let modal = ModalViewController()
let transitionDelegate = DeckTransitioningDelegate()
modal.transitioningDelegate = transitionDelegate
modal.modalPresentationStyle = .custom
present(modal, animated: true, completion: nil)
```

### Dismissal

Zach Knox's avatar
Zach Knox committed
69
By default, DeckTransition has a swipe-to-dismiss gesture which is automatically enabled when your modalʼs main `UIScrollView` is scrolled to the top.
Zach Knox's avatar
Zach Knox committed
70

Zach Knox's avatar
Zach Knox committed
71
You can opt-out of this behaviour by passing in `false` for the `isSwipeToDismissEnabled` parameter while initialising your `DeckTransitioningDelegate`.
Zach Knox's avatar
Zach Knox committed
72

Zach Knox's avatar
Zach Knox committed
73
### `UIScrollView` detection
Zach Knox's avatar
Zach Knox committed
74

Zach Knox's avatar
Zach Knox committed
75
DeckTransition has an internal heuristic to determine which `UIScrollView` should be tracked for the swipe-to-dismiss gesture. In general, this should be sufficient for and cover most use cases.
Zach Knox's avatar
Zach Knox committed
76

Zach Knox's avatar
Zach Knox committed
77
However there are some edge cases, and should you run into one, these can we worked around by making your modal view controller conform to the `DeckTransitionViewControllerProtocol` protocol. More information about this can be found in the documentation page about [UIScrollView detection](https://harshilshah.github.io/DeckTransition/uiscrollview-detection.html).
Zach Knox's avatar
Zach Knox committed
78

Zach Knox's avatar
Zach Knox committed
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
### Snapshots

For a variety of reasons, and especially because of iOS 11's safe area layout, DeckTransition uses a snapshot of your presenting view controller's view instead of using the view directly. This view is automatically updated whenever the frame is resized.

However, there can be some cases where you might want to update the snapshot view by yourself, and this can be achieved using the following one line snippet:

```swift
(presentationController as? DeckSnapshotUpdater)?.requestPresentedViewSnapshotUpdate()
```

All this does is request the presentation controller to update the snapshot.

You can also choose to update snapshot directly from the presenting view controller, as follows:

```swift
(presentedViewController?.presentationController as? DeckSnapshotUpdater)?.requestPresentedViewSnapshotUpdate()
```

It's worth noting that updating the snapshot is an expensive process and should only be used if necessary, for example if you are updating your entire app's theme.

Zach Knox's avatar
Zach Knox committed
99
100
## Apps Using DeckTransition
- [Petty](https://zachsim.one/projects/petty) by [Zach Simone](https://twitter.com/zachsimone)
Zach Knox's avatar
Zach Knox committed
101
- [Bitbook](https://bitbookapp.com) by [Sammy Gutierrez](https://sammygutierrez.com)
102
- [BookPlayer](https://github.com/GianniCarlo/Audiobook-Player) by [Gianni Carlo](https://twitter.com/GCarlo89)
103
- [What's Open for iOS](https://git.gmu.edu/srct/whats-open-ios) by [Mason SRCT](https://srct.gmu.edu/)
Zach Knox's avatar
Zach Knox committed
104
105
106
107
108

Feel free to submit a PR if you’re using this library in your apps

## Author

Zach Knox's avatar
Zach Knox committed
109
Written by [Harshil Shah](https://twitter.com/HarshilShah1910)
Zach Knox's avatar
Zach Knox committed
110
111
112
113

## License

DeckTransition is available under the MIT license. See the LICENSE file for more info.