GitHunt
JI

jiachenyee/ScrollSelection

Select UIBarButtonItems, UIButtons & UISearchBars Simply by Scrolling Up

swiftuibarbuttonitemuikituinavigationcontrolleruiscrollview

ScrollSelection

Swift Package Manager

Select UIBarButtonItems in Navigation Bars by Scrolling Up.

No need for Reachability or awkwardly holding your phone to reach a button in the top corner.

Quick-Start Guide

In your ViewController's Swift file,

import ScrollSelection

var scrollSelection: ScrollSelection!

override func viewDidLoad() {
    super.viewDidLoad()
    
    scrollSelection = createScrollSelection() 

    scrollView.delegate = self 
    // If you are using tableViews, use `tableView.delegate = self`
    // If you are using textViews, use `textView.delegate = self`
}

Setting up in ScrollView/TextView/TableView Delegate

func scrollViewDidScroll(_ scrollView: UIScrollView) {
    scrollSelection.didScroll()
}

func scrollViewDidEndDragging(_ scrollView: UIScrollView, willDecelerate decelerate: Bool) {
    scrollSelection.didEndDragging()
}

func scrollViewDidEndDecelerating(_ scrollView: UIScrollView) {
    scrollSelection.didEndDecelerating()
}

Scroll Selection using UIButton/UISearchBar

                                     // Add a search bar to scrollSelection
scrollSelection.selectionSequence = [.searchBar(mySearchBar), 

                                     // Add a custom button
                                     .button(myButton),
                                     
                                     // Default, right and left bar buttons
                                     .rightBarButtons,
                                     .leftBarButtons]

Customisations and Documentation

Note: For updated documentation information, make use of the Quick Help section (or ⌥-click the declaration)

UIViewController Extension (for quick set-up)

Create Scroll Selection

Summary

Set-Up Scroll Selection on this View Controller

Declaration

func createScrollSelection(withOffset offsetMultiplier: CGFloat = 70, 
                           usingStyle style: [ScrollSelection.Style] = ScrollSelection.Style.defaultStyle) -> ScrollSelection

Parameters

  • withOffset offsetMultiplier
    • Distance between each button selection
    • Default Value: 70
  • usingStyle style
    • Scroll Selection Style. Use ScrollSelection.Style.defaultStyle for default implementation or remove this parameter
    • Default Value: ScrollSelection.Style.defaultStyle
    • Refer to Style for the various style information

Returns

An instance of Scroll Selection that is already set up

Usage

In your viewDidLoad function,

override func viewDidLoad() {
    super.viewDidLoad()
    
    // Default implementation
    scrollSelection = createScrollSelection() 

    // Custom implementation
    scrollSelection = createScrollSelection(withOffset: 70, usingStyle: ScrollSelection.Style.defaultStyle) 
}
Update Bar Buttons

Summary

Update bar buttons with Scroll Selection

Declaration

func updateBarButtons(barButtonSide direction: ScrollSelection.Direction = .all)

Discussion

Call this function whenever a change is made to the navigation bar buttons

Parameters

  • barButtonSide direction
    • .left corresponds to the left bar buttons, .right corresponds to the right bar buttons, .all updates all buttons.
    • Default Value: .all
    • Refer to Direction for the various direction information

Usage

After updating left bar button items,

scrollSelection.updateBarButtons(barButtonSide: .left)

UIScrollViewDelegate Implementation

Did Scroll

Summary

Update ScrollSelection when the scrollview scrolls

Declaration

func didScroll()

Discussion

Updates scroll selection by highlighting or removing highlights on corresponding buttons

Usage

To be called in scrollViewDidScroll function that is part of UIScrollViewDelegate

extension ViewController: UIScrollViewDelegate {
    func scrollViewDidScroll(_ scrollView: UIScrollView) {
        scrollSelection.didScroll()
    }
}
Did End Dragging

Summary

Update ScrollSelection when user stops dragging scrollView

Declaration

func didEndDragging()

Discussion

Called when scrollView is released (ends dragging) and thus, scroll selection will select the corresponding bar button

Usage

To be called in scrollViewDidEndDragging function that is part of UIScrollViewDelegate

extension ViewController: UIScrollViewDelegate {
    func scrollViewDidEndDragging(_ scrollView: UIScrollView, willDecelerate decelerate: Bool) {
        scrollSelection.didEndDragging()
    }
}
Did End Decelerating

Summary

Update ScrollSelection once the scrollView stops decelerating

Declaration

func didEndDecelerating()

Discussion

Called when scrollView is ends deceerating and thus, scroll selection will reset to original state

Usage

To be called in scrollViewDidEndDecelerating function that is part of UIScrollViewDelegate

extension ViewController: UIScrollViewDelegate {
    func scrollViewDidEndDecelerating(_ scrollView: UIScrollView) {
        scrollSelection.didEndDecelerating()
    }
}

Customising ScrollSelection

Offset Multiplier

Summary

Y-Axis offset between selecting buttons

Declaration

var offsetMultiplier: CGFloat!

Discussion

Should be automatically set in by init or the UIViewController Implementation

Scroll View

Summary

Target UIScrollView for Scroll Selection

Declaration

var scrollView: UIScrollView?

Usage



Discussion


Should be automatically set in by init or the UIViewController Implementation


Scroll Selection will ignore all scrollViews except for the targetted one.


Usage


scrollSelection.scrollView = myScrollView





Haptic Style

Summary


Haptic feedback styles


Declaration


var hapticStyle: HapticsStyle = .variableIncreasing


Discussion


It uses .variableIncreasing as default value.


Refer to HapticsStyle for the various styles


Usage


scrollSelection.hapticStyle = .variableIncreasing





Style

Summary


Current scroll selection style


Declaration


var style: [Style]!


Discussion


Should be automatically set in by init or the UIViewController Implementation.


Refer to Scroll Selection Styles for the various styles


Usage


// Using the default style
scrollSelection.style = ScrollSelection.Style.defaultStyle 

// Using a custom style
scrollSelection.style = [.circularHighlight(using: .systemRed, expands: true)]




Scroll Selection Styles



Highlight

Summary


Changes the Button tint color during Scroll Selection


Declaration


public static func highlight(using color: UIColor = UIColor.systemBlue.withAlphaComponent(0.7)) -> Style


Parameters


    

  • using color

      

    • Color to change to
      • 

    • Default Value: .systemBlue with alpha of 0.7
      • 

    

    • 



Returns


A scroll selection style





Circular Highlight

Summary


Adds a circular highlight/background to the button that is being selected


Declaration


public static func circularHighlight(using color: UIColor = .systemGray4,
                                     expands: Bool = true, 
                                     fades: Bool = true) -> Style


Parameters


    

  • using color

      

    • Color of highlight
      • 

    • Default Value: .systemGray4 with alpha of 0.7
      • 

    

    • 

  • expands

      

    • If true, circular highlights will expand radially to show emphasis on the button as the user scrolls up. Otherwise, it will stay static and the highlight will not expand.
      • 

    

    • 

  • fades

      

    • If true, circular highlight background will fade as the user scrolls up. Otherwise, it will jump from one to another, without fading.
      • 

    

    • 



Returns


A scroll selection style




Haptic Styles



Normal

Summary


Normal Haptic Style


Declaration


case normal


Discussion


Normal corresponds to UISelectionFeedbackGenerator().selectionChanged(). A more subtle haptic style.





Variable Increasing

Summary


Default style,

feedback becomes more pronounced as user scrolls up


Declaration


case variableIncreasing


Discussion


First Button -> Last Button
Weak         -> Strong






Variable Decreasing

Summary


Haptic feedback becomes less pronounced as user scrolls up


Declaration


case variableDecreasing


Discussion


First Button -> Last Button
Strong       -> Weak





Direction



Left

Summary


Update Left Bar Buttons


Declaration


public static let left: Direction = Direction(rawValue: 1 << 0)





Right

Summary


Update Right Bar Buttons


Declaration


public static let right: Direction = Direction(rawValue: 1 << 1)





All

Summary


Update Both Left and Right Bar Buttons


Declaration


public static let all: Direction = [.left, .right]




Activating and Deactivating



Activate

Summary


Activate Scroll Selection


Declaration


func activate()





Deactivate

Summary


Deactivate Scroll Selection


Declaration


func deactivate()


Languages
Swift100.0%
Contributors
JI
Apache License 2.0
Created September 22, 2020
Updated August 2, 2024