pdil / PDColorPicker

Branch	Status	Coverage
master (v0.8.3)
develop

🎨 PDColorPicker is an open source iOS library that lets developers include a color picker in their apps, allowing users to easily select colors in a variety of formats. This library is open for collaboration with the community so anyone is invited to submit issues or pull requests.

Demo	Table of Contents
	📄 Requirements 💻 Installation CocoaPods Carthage Manual 📝 Usage 📲 Drag and Drop 🎨 PDColorPicker in other apps 🙋‍♂️ Author ⚖️ License

📄 Requirements

• iOS 9.0 or later (iOS 11.0+ for drag and drop)
• Xcode 10.2 or later
• Swift 5 or later

💻 Installation

Cocoapods

PDColorPicker is available through CocoaPods.

If you have not done so already, run pod setup from the root directory of your application.

To install PDColorPicker, simply add the following line to the Podfile:

pod 'PDColorPicker'

This line should be added to the app's target so that it looks something like this:

use_frameworks!

target 'TARGET_NAME' do
  pod 'PDColorPicker'

  # other pods...
end

Older Swift Versions

If the project is not built for Swift 4.2, install from the swift-3.2, swift-4.1 or the swift-4.2 branches:

pod 'PDColorPicker', :git => 'https://github.com/pdil/PDColorPicker.git', :branch => 'swift-4.2'

Note that this build may not include all of the latest features of PDColorPicker.

Build the CocoaPods frameworks by running the following command in the Terminal from the root project directory:

$ pod install

Open the newly created .xcworkspace file and build the project to make PDColorPicker available.

Note: Be sure to always work inside the .xcworkspace file and not the .xcodeproj file, otherwise Xcode will not be able to locate the dependencies and PDColorPicker will not be accessible.

Carthage

PDColorPicker is available through Carthage.

If you haven't installed Carthage yet, use Homebrew to install it:

$ brew update
$ brew install carthage

Create a Cartfile inside the root project directory with the following line (or add this line if you already have a Cartfile):

github "pdil/PDColorPicker"

Older Swift Versions

If the project is not built for Swift 4.2, install from the swift-3.2, swift-4.1 or the swift-4.2 branches:

github "pdil/PDColorPicker" "swift-4.2"

Note that this build may not include the latest features of PDColorPicker.

Build the Carthage frameworks by running the following command in the Terminal from the root project directory:

$ carthage update

This will build the framework inside the Carthage/build folder.

Lastly, add the framework to your project:

• In Xcode, select the project in the Project Navigator in Xcode (blue icon).
• Open the "General" tab on the top bar.
• Drag PDColorPicker.framework from the Carthage/build folder into the "Embedded Binaries" section.

Manual (not recommended)

• Download the .swift files inside PDColorPicker/Classes and add them to your project.
• Add the files to the appropriate target(s) within the project.
• Import PDColorPicker as you normally would.

📝 Usage

import UIKit
import PDColorPicker  // 1.

class MyViewController: UIViewController, Dimmable {
    // ...
  
    func presentColorPicker() {
        // 2.
        let colorPickerVC = PDColorPickerViewController(initialColor: .blue, tintColor: .black)

        // 3.
        colorPickerVC.completion = {
            [weak self] newColor in

            self?.undim() // 7.

            guard let color = newColor else {
                print("The user tapped cancel, no color was selected.")
                return
            }

            print("A new color was selected! HSBA: \(String(describing: color))")
         }
  
         // 4.
         dim() // see Dimmable documentation for extra options
    
         // 5.
         present(colorPickerVC, animated: true)
    }
  
    // ...
}

1. Import the PDColorPicker framework.
2. Instantiate a new PDColorPickerViewController.
3. Set the completion handler of the color picker, indicating what the presenting view controller should do with the color result. Note: this can also be set in the PDColorPickerViewController initializer.
4. Implement the Dimmable protocol and dim the presenting view controller (optional but highly recommended).
5. Present the color picker as a modal view controller.
6. Use the color picker to select a color. When Save or Cancel is tapped, the completion handler specified in the initializer will automatically provide the new color. If the user taps cancel, nil is returned.
7. Be sure to undim the view once the completion handler is called.

Bonus

To achieve the white status bar while the presenting view controller is dimmed, set UIViewControllerBasedStatusBarAppearance to YES in your Info.plist.

You can also copy the code here into the plist file:

<key>UIViewControllerBasedStatusBarAppearance</key>
<true/>

📲 Drag and Drop

Drag and drop is also supported in projects that target iOS 11.0 or later.

See PDColorReceiverExample for an example on how to consume a color that is dragged into your app. The drag and drop implementation of PDColorPicker exposes a basic UIColor so that it can be read by apps that don't necessarily import PDColorPicker.

Of course, if the destination app imports PDColorPicker, it will have access to the convenient PDColor class which it could instantiate with the received UIColor:

func dropInteraction(_ interaction: UIDropInteraction, performDrop session: UIDropSession) {
  session.loadObjects(ofClass: UIColor.self) {
    guard let color = $0.first as? UIColor else { return }

    let pdColor = PDColor(color: color)
    print(pdColor.hex)
  }
}

🎨 PDColorPicker in other apps

Here is a list of apps that use PDColorPicker to let their users select colors:

• 🌮 FoodEase
• 🎨 Paint Shapes

If your app is using PDColorPicker, let me know and I'll add it to this list (include an emoji to represent your app in the list, the app name, and a web or download URL)!

🙋‍♂️ Author

Paolo Di Lorenzo

⚖️ License

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