Skip to content

Latest commit

 

History

History
363 lines (280 loc) · 9.28 KB

README.md

File metadata and controls

363 lines (280 loc) · 9.28 KB
Raw

Overlay

Build Status Carthage Compatible CocoaPods Compatible

Overlay is a very flexible UI framework designed for Swift.

Note: Overlay is still under development and many things are subject to change.

Features

  • Protocol oriented design
  • Interface Builder support
  • Comprehensive unit test coverage
  • Complete documentation

Requirements

iOS 9+ / Xcode 9+ / Swift 4+

Installation

Carthage

Carthage is a decentralized dependency manager. To install Overlay, add the following line to your Cartfile:

github "TintPoint/Overlay" ~> 0.7

CocoaPods

CocoaPods is a centralized dependency manager. To install Overlay, add the following line to your Podfile:

pod 'Overlay', '~> 0.7'

Example

Overlay allows one to write declarative yet type-safe UI code, something looks like this:

@IBDesignable
class StandardTextField: UITextField, CustomTextColor, CustomPlaceholderTextColor, CustomFont, CustomTextAlignment {
    let textColorStyle: ColorStyle = Color.primary
    let placeholderTextColorStyle: ColorStyle = Color.secondary
    let fontStyle: FontStyle = Font.default
    let textAlignmentStyle: TextAlignmentStyle = TextAlignment.body
}

Getting Started

Define a custom class that conforms to protocols with Custom prefix (list of available protocols can be found here). For example, to customize the background color attribute of a view, write the following code.

class CustomView: UIView, CustomBackgroundColor {
    let backgroundColorStyle: ColorStyle = UIColor.white
}

The compiler will emit an error if CustomView's superclass (in this case, UIView) is not BackgroundColorCustomizable, or backgroundColorStyle is not implemented by CustomView. UIColor is already conformed to ColorStyle protocol so it can be used here. Font and other attributes can also be customized similarly.

CustomView can be used like other views, but it is recommended to use it with Interface Builder.

Open the storyboard file (or nib file), select the view you want to change, navigate to Identity Inceptor, and set Custom Class to CustomView.

Creating views programmatically is also supported.

let customView = CustomView()
customView.refresh() // make sure to call refresh() after initialization

Advanced Usage

Custom Style

In order to fully take advantage of the power of Swift's type checker, it is recommended to define custom enums (or structs with private initializers) that conform to protocols with Style postfix (list of available styles can be found here).

enum CustomColor: ColorStyle {
    case normal, disabled
    func normal() -> UIColor {
        switch self {
        case .normal: return UIColor.white
        case .disabled: return UIColor.black
        }
    }
}

Previous example can be rewritten as the following code.

class CustomView: UIView, CustomBackgroundColor {
    let backgroundColorStyle: ColorStyle = CustomColor.normal
}

Style Group

For views which have more than one states (e.g. UIButton), their appearance usually needs to change base on state changes. All custom styles have corresponding style groups that support this feature (list of available style groups can be found here).

class CustomButton: UIButton, CustomBackgroundColor {
    let backgroundColorStyle: ColorStyle = ColorGroup(normal: CustomColor.normal, disabled: CustomColor.disabled)
}

It is also possible to implement app-specific style groups by conforming to protocols with StyleGroup postfix.

enum CustomColorGroup: ColorStyleGroup {
    case standard
    func normal() -> UIColor {
        return UIColor.white
    }
    func disabled() -> UIColor? {
        return UIColor.black
    }
}

class CustomButton: UIButton, CustomBackgroundColor {
    let backgroundColorStyle: ColorStyle = CustomColorGroup.standard
}

States defined in a style group but aren't supported by the view using it will be ignored. Currently, it is required to call refresh() after changing the state.

button.isEnabled = true
button.refresh()

Other Attributes

Overlay supports customizing views' colors, fonts, images, texts and text alignments.

However, it is still possible to customize other attributes by adopting protocols with Design postfix.

class BorderView: UIView, CustomViewDesign {
    let design: (UIView) -> Void = { view in
        view.layer.borderWidth = 1
    }
}

Custom Layout

Most views contain subviews. Overlay is designed with this in mind, but it's not its goal to handle subview layouts. Overlay should only handle views' style attributes (like colors and fonts), and the main application should handle views' layouts (like origin and size). CustomLayout protocol allows Overlay to work with Interface Builder together seamlessly.

Define a custom class that conforms to CustomLayout protocol. Then create a nib file and set its File's Owner to the newly defined class.

class ComplexView: UIView, CustomLayout {
    let contentNib: UINib = UINib(nibName: "ComplexView", bundle: Bundle(for: ComplexView.self))
}

The first root view inside ComplexView.xib will be loaded and added as a content view of ComplexView. Note: Added view's background color usually should be clear color.

Create IBOutlet and connect them like usual, if needed.

class ComplexView: UIView, CustomLayout {
    let contentNib: UINib = UINib(nibName: "ComplexView", bundle: Bundle(for: ComplexView.self))
    @IBOutlet weak var button: CustomButton?
}

Reference

Available Protocols

Custom Cell

  • CustomCell
  • CustomHeaderFooterView
  • CustomReusableView

Custom Design

  • CustomActivityIndicatorViewDesign
  • CustomBarButtonItemDesign
  • CustomBarItemDesign
  • CustomButtonDesign
  • CustomCollectionViewDesign
  • CustomControlDesign
  • CustomDatePickerDesign
  • CustomDesign
  • CustomImageViewDesign
  • CustomLabelDesign
  • CustomNavigationBarDesign
  • CustomPageControlDesign
  • CustomPickerViewDesign
  • CustomProgressViewDesign
  • CustomScrollViewDesign
  • CustomSearchBarDesign
  • CustomSegmentedControlDesign
  • CustomSliderDesign
  • CustomStackViewDesign
  • CustomStepperDesign
  • CustomSwitchDesign
  • CustomTabBarDesign
  • CustomTabBarItemDesign
  • CustomTableViewDesign
  • CustomTextFieldDesign
  • CustomTextViewDesign
  • CustomToolbarDesign
  • CustomViewDesign
  • CustomWebViewDesign

Custom Layout

  • CustomLayout

Custom Color

  • CustomBackgroundColor
  • CustomBadgeColor
  • CustomBarTintColor
  • CustomBorderColor
  • CustomColor
  • CustomMaximumTrackTintColor
  • CustomMinimumTrackTintColor
  • CustomOnTintColor
  • CustomPlaceholderTextColor
  • CustomProgressTintColor
  • CustomSectionIndexBackgroundColor
  • CustomSectionIndexColor
  • CustomSectionIndexTrackingBackgroundColor
  • CustomSeparatorColor
  • CustomShadowColor
  • CustomTextColor
  • CustomThumbTintColor
  • CustomTintColor
  • CustomTitleColor
  • CustomTitleShadowColor
  • CustomTrackTintColor
  • CustomUnselectedItemTintColor

Custom Font

  • CustomFont
  • CustomTitleFont

Custom Image

  • CustomBackgroundImage
  • CustomDecrementImage
  • CustomHighlightedImage
  • CustomImage
  • CustomIncrementImage
  • CustomLandscapeImagePhone
  • CustomMaximumTrackImage
  • CustomMaximumValueImage
  • CustomMinimumTrackImage
  • CustomMinimumValueImage
  • CustomOffImage
  • CustomOnImage
  • CustomProgressImage
  • CustomScopeBarButtonBackgroundImage
  • CustomSearchFieldBackgroundImage
  • CustomSelectedImage
  • CustomShadowImage
  • CustomThumbImage
  • CustomTrackImage

Custom Text

  • CustomPlaceholder
  • CustomPrompt
  • CustomScopeButtonTitles
  • CustomSegmentTitles
  • CustomText
  • CustomTitle

Custom Text Alignment

  • CustomTextAlignment
  • CustomTitleTextAlignment

Available Styles

  • ColorStyle
  • ColorStyleGroup
  • FontStyle
  • FontStyleGroup
  • ImageStyle
  • ImageStyleGroup
  • TextAlignmentStyle
  • TextAlignmentStyleGroup
  • TextStyle
  • TextStyleGroup

Available Style Groups

  • ColorGroup
  • FontGroup
  • ImageGroup
  • TextAlignmentGroup
  • TextGroup

Available States

ViewHideable

  • UIView and its subclasses

ViewFocusable

  • UIView and its subclasses

ViewDisable

  • UIBarButtonItem
  • UIBarItem
  • UIButton
  • UIControl
  • UIDatePicker
  • UILabel
  • UIPageControl
  • UIRefreshControl
  • UISegmentedControl
  • UISlider
  • UIStepper
  • UISwitch
  • UITabBarItem
  • UITextField

ViewSelectable

  • UIButton
  • UIControl
  • UIDatePicker
  • UIPageControl
  • UIRefreshControl
  • UISegmentedControl
  • UISlider
  • UIStepper
  • UISwitch
  • UITableViewCell
  • UITextField

ViewHighlightable

  • UIButton
  • UIControl
  • UIDatePicker
  • UIImageView
  • UILabel
  • UIPageControl
  • UIRefreshControl
  • UISegmentedControl
  • UISlider
  • UIStepper
  • UISwitch
  • UITableViewCell
  • UITextField