Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/ThasianX/ElegantPages

The elegant full screen page view missed in SwiftUI
https://github.com/ThasianX/ElegantPages

elegantpages pageview pageviewcontroller swift-package-manager swiftui swiftui-animations swiftui-components swiftui-example

Last synced: 2 months ago
JSON representation

The elegant full screen page view missed in SwiftUI

Awesome Lists containing this project

README 

        
# ElegantPages





    Platforms

    

    License: MIT




ElegantPages is an efficient and customizable full screen page view written in SwiftUI.










- [Introduction](#introduction)

- [Basic Usage](#basic-usage)

- [How It Works](#how-it-works)

- [Customization](#customization)

- [Demos](#demos)

- [Requirements](#requirements)

- [Contributing](#contributing)

- [Installation](#installation)

- [License](#license)



## Introduction



`ElegantPages` comes with 2 types of components, [`ElegantPagesView`](https://github.com/ThasianX/ElegantPages/blob/master/Sources/ElegantPages/Pages/Internal/ElegantPagesView.swift) and [`ElegantListView`](https://github.com/ThasianX/ElegantPages/blob/master/Sources/ElegantPages/Lists/Internal/ElegantListView.swift). 



For simpler usage, `ElegantPagesView` is recommended as it loads all page views immediately.



For more complex usage, `ElegantListView` is recommended as it loads page views on demand([learn more](#how-it-works)).



The elegance of both these views is that they work as a paging component should be intended to work. One bug that is often seen in SwiftUI is that `ScrollView`, `List`, or any `Gesture` almost certainly interferes with other gestures in the view. However, `ElegantPages` fixes this issue and scrolling through a paging component even with embedded `Gestures` works elegantly.



## Basic usage



The `ElegantPagesView` component is available through [`ElegantHPages`](https://github.com/ThasianX/ElegantPages/blob/master/Sources/ElegantPages/Pages/Public/ElegantHPages.swift) and [`ElegantVPages`](https://github.com/ThasianX/ElegantPages/blob/master/Sources/ElegantPages/Pages/Public/ElegantVPages.swift).



```swift



import ElegantPages



struct ElegantVPagesExample: View {



    let manager = ElegantPagesManager(startingPage: 1, pageTurnType: .earlyCutOffDefault)



    var body: some View {

        ElegantVPages(manager: manager) {

            CustomButtonView()

            CustomView()

            CustomListView()

        }

    }



}

```



The `ElegantListView` component is available through [`ElegantHList`](https://github.com/ThasianX/ElegantPages/blob/master/Sources/ElegantPages/Lists/Public/ElegantHList.swift) and [`ElegantVList`](https://github.com/ThasianX/ElegantPages/blob/master/Sources/ElegantPages/Lists/Public/ElegantVList.swift).



```swift



import ElegantPages



let listData = (1...40).map { _ in "Ideally, this should be more dynamic content to make the most use out of this list" }



struct ElegantVListExample: View {



    let manager = ElegantListManager(pageCount: vListData.count, pageTurnType: .earlyCutOffDefault)

    

    var body: some View {

        ElegantVList(manager: manager,

                     pageTurnType: .earlyCutOffDefault) { page in 

            ExampleView(page: page).erased

        }

    }



}



struct ExampleView: View {



    let page: Int



    var body: some View {

        VStack {

            Text("Page \(page)")

                .font(.largeTitle)

            Text(listData[page])

                .font(.title)

        }

        .padding()

    }

    

}



```



## How it works



`ElegantPagesView` is pretty simple. It uses a [function builder](https://github.com/apple/swift-evolution/blob/9992cf3c11c2d5e0ea20bee98657d93902d5b174/proposals/XXXX-function-builders.md) to gather the page views and puts them in either a `HStack` or `VStack` depending on the type of `ElegantPages` view chosen. As a result, all views are created immediately. 



`ElegantListView` is quite interesting. For more flexibility, it uses a `@ViewBuilder` to get the view for any given page(it's the closure at the end of the `ElegantVList` declaration. When it is first initialized, it calls this closure at most 3 times, to get the views for the starting pages. These views are used to initialize an array of at most 3 `UIHostingControllers`, whose `rootViews` are set to a specific origin in a `UIViewController`. Here's the catch, at any given moment, there are at most only 3 pages loaded. As the user scrolls to the next page, old pages are removed and new pages are inserted; the views themselves are juggled as their origins are changed per page turn. This keeps overall memory usage down and also makes scrolling blazingly fast. If you're curious, take a [peek](https://github.com/ThasianX/ElegantPages/blob/master/Sources/ElegantPages/Lists/Internal/ElegantListController.swift).



## Customization



The following aspects of any `ElegantPages` component can be customized:



#### `pageTurnType`: Whether to scroll to the next page early or until the user lets go of the drag



```swift 



public enum PageTurnType {



    case regular(pageTurnDelta: CGFloat)

    case earlyCutoff(config: EarlyCutOffConfiguration)



}



public struct EarlyCutOffConfiguration {



    public let scrollResistanceCutOff: CGFloat

    public let pageTurnCutOff: CGFloat

    public let pageTurnAnimation: Animation

    

}



```



A regular page turn only turns the page after the user ends their drag. 



- The `pageTurnDelta` represents the percentage of how far across the screen the user has to drag in order for the page to turn when they let go. The default value for this is 0.3, as part of an extension of `PageTurnType`. 

- The default regular page turn can be accessed through `PageTurnType.regularDefault`



An early cutoff page turn turns the page when the user drags a certain distance across the screen.



- `scrollResistanceCutOff`: The distance that the view is offset as the user drags.

- `pageTurnCutOff`: The distance across the screen the user has to drag before the page is turned(once this value is reached, the page automatically gets turned to and the user's ongoing gesture is invalidated). 

- `pageTurnAnimation`: The animation used when the page is turned

- The default early cut off page turn can be accessed through `PageTurnType.earlyCutOffDefault`



In case `scrollResistanceCutOff` isn't clear, here's an example. Say we have a horizontally draggable view. If you drag 80 pixels to the right, the offset that is visible to you is also 80 pixels. The amount you scroll is equal to the visible offset. However, if you have a scroll resistance of say 40 pixels, after dragging 80 pixels to the right, you only see that the view has moved 40 pixels to the right. That is why it is called resistance.



###$ `viewForPage`: datasource method called whenever a new page is displayed that asks for the view of the new page. Available only for `ElegantList` components



```swift 



// Use as a function

ElegantVList(..., viewForPage: exampleView)



func exampleView(for page: Int) -> AnyView { ExampleView(...) }



// Use as a closure

ElegantHList(...) { page in ExampleView(...) }

    

```



#### `onPageChanged`: called whenever a new page is shown. Available for all `ElegantPages` components.



```swift 



ElegantVList(...)

    .onPageChanged(...)



ElegantHList(...)

    .onPageChanged(...)

    

ElegantHPages(...)

    .onPageChanged(...)

    

ElegantVPages(...)

    .onPageChanged(...)

    

```



#### `frame`: used to set a custom height or width for `ElegantList` components



```swift 



// You may want a smaller width for the VList. However, height for the VList will always be the screen height

ElegantVList(...)

    .frame(width: ...)



// You may want a smaller height for the HList. However, width for the HList will always be the screen width

ElegantHList(...)

    .frame(height: ...)

    

```



## Demos



The demo shown in the GIF can be checked out on [ElegantCalendar](https://github.com/ThasianX/ElegantCalendar).



For simpler demos, look at the [example repo](https://github.com/ThasianX/ElegantPages/tree/master/Example).



## Installation



`ElegantPages` is available using the [Swift Package Manager](https://swift.org/package-manager/):



Using Xcode 11, go to `File -> Swift Packages -> Add Package Dependency` and enter https://github.com/ThasianX/ElegantPages



If you are using `Package.swift`, you can also add `ElegantPages` as a dependency easily.



```swift



let package = Package(

  name: "TestProject",

  dependencies: [

    .package(url: "https://github.com/ThasianX/ElegantPages", from: "1.4.0")

  ],

  targets: [

    .target(name: "TestProject", dependencies: ["ElegantPages"])

  ]

)



```



## Requirements



- iOS 13.0+

- Xcode 11.0+



## Contributing



If you find a bug, or would like to suggest a new feature or enhancement, it'd be nice if you could [search the issue tracker](https://github.com/ThasianX/ElegantPages/issues) first; while we don't mind duplicates, keeping issues unique helps us save time and considates effort. If you can't find your issue, feel free to [file a new one](https://github.com/ThasianX/ElegantPages/issues/new).



## License



This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details