PickerView

🔸 A customizable alternative to UIPickerView in Swift.

Code Quality Rank: L5

Programming language: Swift

License: MIT License

Tags: UI    

Latest version: v0.4.0

README

PickerView

PickerView is an easy to use and customize alternative to UIPickerView written in Swift. It was developed to provide a highly customizable experience, so you can implement your custom designed UIPickerView.

Requirements

It requires Xcode 8.0+ and Swift 3.0.

NOTE: When PickerView was first built it wasn't thought to support Objective-C projects, but the community demanded it and recently we've released the version 0.2.0 which supports Objective-C projects. After some tests we noticed some bugs when using from Objective-C, so we've this issue open and we need some help to fix that, so if you are making some adjustments to run in your Objective-C project, please, contribute with us to fix these problems. Thanks.

Your project deployment target must be iOS 8.0+

Installation

CocoaPods

PickerView is available through CocoaPods. To install it, simply add the following line to your Podfile:

pod "PickerView"

Manually

You can also install it manually just draging PickerView file to your project.

Usage

To run the example project, clone the repo, and run pod install from the Example directory first.

PickerView is very simple to use, you can use it with Interface Builder or through code, it works similar as UIPickerView you need to implement PickerViewDataSource and PickerViewDelegate protocols to provide the basic information and make it works.

You can customize the text appearance, the scrolling style (default or infinite scrolling) and the selection style (selection indicators and overlays with custom UIView's or even an UIImage to highlight the selected row).

Interface Builder

Drag a UIView to your view controller (and put the constraints if you want).

Change the class to PickerView on the Identity Inspector and make the @IBOutlet connection.

From Code

Create a new PickerView.

let examplePicker = PickerView()
examplePicker.translatesAutoresizingMaskIntoConstraints = false

Add to your view and put your custom constraints.

view.addSubview(examplePicker)
view.addConstraints([yourCustomConstraints])

Set the PickerViewDataSource and PickerViewDelegate

Don't forget to set the datasource and delegate of your PickerView:

// ...
// The `examplePicker` below is the same that you created through code or connected via @IBOutlet
examplePicker.dataSource = self
examplePicker.delegate = self
// ...

Implement PickerViewDataSource

The PickerViewDataSource protocol consists in two required methods:

@objc public protocol PickerViewDataSource: class {
    func pickerViewNumberOfRows(_ pickerView: PickerView) -> Int
    func pickerView(_ pickerView: PickerView, titleForRow row: Int) -> String
}

You need to return the pickerViewNumberOfRows as we see below:

func pickerViewNumberOfRows(_ pickerView: PickerView) -> Int {
    return itemsThatYouWantToPresent.count 
}

And the title for each row:

func pickerView(_ pickerView: PickerView, titleForRow row: Int) -> String {
    let item = itemsThatYouWantToPresent[row]
    return item.text
}

Done. Now you'll need to implement one more protocol and then we are all set.

Implement PickerViewDelegate

The PickerViewDelegate consists in five methods:

@objc public protocol PickerViewDelegate: class {
    func pickerViewHeightForRows(_ pickerView: PickerView) -> CGFloat
    optional func pickerView(_ pickerView: PickerView, didSelectRow row: Int)
    optional func pickerView(_ pickerView: PickerView, didTapRow row: Int)
    optional func pickerView(_ pickerView: PickerView, styleForLabel label: UILabel, highlighted: Bool)
    optional func pickerView(_ pickerView: PickerView, viewForRow row: Int, highlighted: Bool, reusingView view: UIView?) -> UIView?
}

Firstly you must provide the pickerViewHeightForRows(_:):

func pickerViewHeightForRows(_ pickerView: PickerView) -> CGFloat {
    return 50.0 // In this example I'm returning arbitrary 50.0pt but you should return the row height you want.
}

Then is the method where you can do something with the row selected in PickerView:

func pickerView(_ pickerView: PickerView, didSelectRow row: Int) {
    let selectedItem = itemsThatYouWantToPresent[row] 
    print("The selected item is \(selectedItem.name)") 
}

PickerView enable the user to tap a visible row to select it. We've a delegate method to track this tap behavior, so pickerView(_: PickerView, didTapRow row: Int) is called only when the user selects a row by tapping it:

func pickerView(_ pickerView: PickerView, didTapRow row: Int) {
    print("The row \(row) was tapped by the user") 
}

The following method allows you to customize the label that will present your items in PickerView. Use the flag `highlighted' to provide a differrent style when the item is selected:

func pickerView(_ pickerView: PickerView, styleForLabel label: UILabel, highlighted: Bool) {
    label.textAlignment = .Center

    if highlighted { 
        label.font = UIFont.systemFontOfSize(25.0)
        label.textColor = view.tintColor
    } else {
        label.font = UIFont.systemFontOfSize(15.0)
        label.textColor = .lightGrayColor()
    }
}

If you want to provide a totally customized view instead of presenting just a row with a text label inside

func pickerView(_ pickerView: PickerView, viewForRow row: Int, highlighted: Bool, reusingView view: UIView?) -> UIView? {
    var customView = view

    // Verify if there is a view to reuse, if not, init your view. 
    if customView == nil {
        // Init your view
        customView = MyCustomView()
    }

    // **IMPORTANT**: As you are providing a totally custom view, PickerView doesn't know where to bind the data provided on PickerViewDataSource, so you will need to bind the data in this method. 
    customView.yourCustomTextLabel.text = itemsThatYouWantToPresent[row].text

    // Don't forget to make your style customizations for highlighted state 
    let alphaBasedOnHighlighted: CGFloat = highlighted ? 1.0 : 0.5
    customView.yourCustomTextLabel.alpha = alphaBasedOnHighlighted

    return customView
}

Label or Custom View?

Even if func pickerView(_ pickerView: PickerView, styleForLabel label: UILabel, highlighted: Bool) and func pickerView(_ pickerView: PickerView, viewForRow row: Int, highlited: Bool, reusingView view: UIView?) are optional methods in PickerViewDelegate you must implement at least one of them. If you want to present your data using only a label (which you can customize too), implement the first one, but if you want to present your data in a totally customized view, you should implement the second one.

NOTE: If you implement the two methods mentioned above, PickerView will always present your data using the custom view you provided.

Cool! You are ready to build and run your application with PickerView, it ill works with the default configurations and the text appearance you provided in PickerViewDelegate on the next section we will cover the scrolling and selection style customizations.

Custom Appearance

As you can customize the text appearance through PickerViewDelegate, you have two more options to customize your PickerView: scrolling style and selection style.

Scrolling Style

Is defined by the scrollingStyle property of PickerView that is of type ScrollingStyle a nested enum that has two member values: .Default and .Infinite. It is explicit and you might already know what it does, but let me explain better:

.Default: The default scrolling experience, the user can scroll through your PickerView item's but he will reach the bottom or the top of your picker when it doesn't have more items to show.

.Infinite: With this scrolling style the user will loop through the items of your PickerView and never reach the end, it provides an infinite scrolling experience.

Selection Style

Is defined by the selectionStyle property of PickerView that is of type SelectionStyle a nested enum that has four member values: .None, .DefaultIndicator, .Overlay and .Image. For your better understanding, follow the explanation below:

.None: Don't uses any aditional view to highlight the selection, only the highlighted label style customization provided by delegate.

.DefaultIndicator: Provides a simple selection indicator on the bottom of the highlighted row with full width and 2pt of height. The default color is its superview tintColor but you have free access to customize the DefaultIndicator through the defaultSelectionIndicator property.

.Overlay: Provide a full width and height (the height you provided on delegate) view that overlay the highlighted row. The default color is its superview tintColor and the alpha is set to 0.25, but you have free access to customize it through the selectionOverlay property.

Tip: You can set the alpha to 1.0 and background color to .clearColor() and add your custom selection view as a selectionOverlay subview to make it looks as you want (don't forget to properly add the constraints related to selectionOverlay to keep your experience with any screen size).

.Image: Provide a full width and height image view selection indicator (the height you provided on delegate) without any image. You must have a selection indicator as an image and set it to the image view through the selectionImageView property.

Who's Using It?

See what projects are using PickerView on our wiki page.

Contribute

Feel free to submit your pull request, suggest any update, report a bug or create a feature request.

Before you start contributing, please take a look on our contributing guide.

Just want to say hello? -> ofilipealvarenga at gmail.com

Contributors

Author: @filipealva

See the people who helps to improve this project: Contributors ♥

Special thanks to: @bguidolim and @jairobjunior.

Starring is caring 🌟

If you liked the project and want it to continue, please star it. It is a way for me to know the impact of the project. Thank you <3

License

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

Donate