omaralbeik / FlexColorPicker

Modern color picker library written in Swift 4.2 that can be easily extended and customized. It aims to provide great UX and performance with stable, quality code.

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

Build Status License Badge Pod Version Badge Swift Version Badge

Flex Color Picker

Modern color picker library written in Swift 4.2 that can be easily extended and customized. It aims to provide great UX and performance with stable, quality code. Includes controls for both HSB and RGB color models.

Default Flex Color Picker Preview Color Picker with All Controls Preview

Supported Use Cases

  1. ready-to-use color picker that works great out-of-box
  2. agile library that supports components positioning with autolayout and customisation directly from storyboard
  3. framework that allows adding your own sliders, palettes & previews or modifying existing ones without changing the code of the library
  4. combine 3 approaches above freely to get the level of customisation that you need

Default Color Picker with Rectangular Palette Preview Custom Color Picker Controls Written in Swift Preview

Features

  • supports HSB and RGB color models, radial and rectangular hue/saturation palette
  • there is great UX "just set the delegate" view controller if you need something simple
  • freely combine, leave out or add your own picker components
  • well documented
  • highly customisable
  • storyboard support with realistic, design time preview and customisation directly from storyboard
  • small classes, robust, easy to understand code
  • can be used without subclassing specific controller
  • hackable: protocols for adding custom picker controls, open classes ready for subclassing

Instalation

Cocoapods

Add this to your podfile:

pod FlexColorPicker

You can also try the Demo project with following command:

pod try FlexColorPicker

Direct Instalation

If you do not use Cocoapods clone the color picker from repository with this command:

git clone https://github.com/RastislavMirek/FlexColorPicker

Then open the cloned project in XCode and compile target FlexColorPicker. File FlexColorPicker.framework will be created in Products directory. Open project that you want to add the color picker to in XCode, select project file, select your application's target on the left side, select General tab and add FlexColorPicker.framework under Embedded Binaries section.

Default HSB Color Picker Preview

How to Use

There are several ways how to use FlexColorPicker depending on how much customization you require. The fastest and simplest option is using DefaultColorPickerViewController.

Adding Default Color Picker

In storyboard, FlexColorPicker can be used by specifying Class of a view controller to be DefaultColorPickerViewController. That is done in Identity Inspector in right panel under Custom Class. Delegate of DefaultColorPickerViewController can only be set in code. Basic customisation of the controller is supported in storyboard via properties in Attributes Inspector.

In code, DefaultColorPickerViewController can be setup like this if using a navigation controller:

let colorPickerController = DefaultColorPickerViewController()
colorPickerController.delegate = self
navigationController?.pushViewController(colorPickerController, animated: true)

Or when presented modally:

let colorPickerController = DefaultColorPickerViewController()
colorPickerController.delegate = self
let navigationController = UINavigationController(rootViewController: colorPickerController)
present(navigationController, animated: true, completion: nil)

Customisation

FlexColorPicker consists of color controls and color picker controllers that manage them. Color controls are (usually) subclasses of UIControl that allow user to pick desired color. Predefined color controls include hue/saturation palettes (circular or rectangular), sliders for saturation, brightness and for RGB components and a picked color preview control. Additional can by added by implementing ColorControl protocol.

Available Color Controls

Each color control has some properties (some of them can be set in storyboard) that can be used for customisation of that control's look and feel. This is the list of included color controls:

ColorPreviewWithHex RadialPaletteControl RectangularPaletteControl SaturationSliderControl BrightnessSliderControl RedSliderControl GreenSliderControl BlueSliderControl

If you want to customize your color picker, you can choose and lay out color controls that you want, set their properties if needed and connect them add them to a color picker controller.

Working with Color Picker in XCode Storyboard

Connecting Color Controls

In storyboard, lay out color controls and set their classes in Identity Inspector to classes of controls you want to use. Then set controller's class to CustomColorPickerViewController, open its Connection Inspector and connect corresponding outlets the controls.

The same can be done in code simply by assigning color controls to appropriate properties of CustomColorPickerViewController.

If you cannot subclass CustomColorPickerViewController e.g. because your controller is a subclass of another class use ColorPickerController instead. It can also be used in storyboard as interface builder custom object. It has same properties as CustomColorPickerViewController (actually, CustomColorPickerViewController is just a convenience wrapper for ColorPickerController). You can also add color controls to it via ColorPickerController.addControl(:) so you are not limited to properties.

Once added to a color picker controller (e.g. ColorPickerController) a color control will be synchronized with other controls managed by the same controller together selecting a single color.

Extending & Overriding

FlexColorPicker is made to be tweaked and extended with minimum effort. You can add you own color control by implementing ColorControl protocol or extending one of following subclass-ready classes:

In many cases there will be no need to subclass ColorSliderControl or ColorPaletteControl. They both relay on their color delegates in how they handle color updates, present themselves and how they interpret user interactions. Therefore, you can instead implement ColorSliderDelegate or ColorPaletteDelegate protocols respectively to change look and behavior without changing the code of the control itself.

Demo project has good examples on both approaches (overriding and composition) and their combination, feel free to check it.

Tips

When setting up slider controls in storyboard it is a good practise to set its background to be transparent. Alignment rectangle (rectangle that autolayout uses to lay out the control) is smaller than the actual frame of the slider to allow for extra hit box margin as well as background framing of the slider. Therefore, if background is solid white it can overlap other views close to it. ☛ If you do not want this behavior, set Hit Box Inset to 0 in Attributes Inspector or set hitBoxInset to 0 in code.

ColorPreviewWithHex can be tapped. When it it tapped, ColorPickerController calls ColorPickerDelegate.colorPicker(_:selectedColor:usingControl:) on its delegate. ☛ You can communicate this feature to your users or opt out by setting ColorPreviewWithHex.tapToConfirm to false.

If a palette color controls is added as subview of UIScrollView it might cause issues because palette color controls make use of pan gestures as well as UIScrollView. UIScrollView will take priority, making any palette control hard to work with. ☛ Using PaletteAwareScrollView instead of UIScrollView solves that issue.

Getting in Touch

If you like it, have a question or want to hire iOS developers shoot me a message at

[my first name, see profile] at [epytysae spelled backwards] dot [first 4 letters of word information]

Emails go directly to author of FlexColorPicker, cryptic format is just spam bot protection.

Suggestions, feedback, bug reports & pull requests are very welcomed.

Thanks

Visual of slider control was inspired by popular Objective-C library HRColorPicker. Thank you for using FlexColorPicker! If you just have 3 seconds to give back, please star this repository.

About

Modern color picker library written in Swift 4.2 that can be easily extended and customized. It aims to provide great UX and performance with stable, quality code.

License:MIT License


Languages

Language:Swift 98.6%Language:Ruby 1.0%Language:Objective-C 0.3%