Skip to content

Latest commit

 

History

History
274 lines (223 loc) · 20.2 KB

APIs.md

File metadata and controls

274 lines (223 loc) · 20.2 KB
Raw

Animatable UI elements

To use IBAnimatable, we can drag and drop a UIKit element and connect it with Animatable UI element in Identity inspector. Here are the supported Animatable UI elements to map UIKit elements.

UIKit elements Animatable UI elements Description
UIView AnimatableView
UIScrollView AnimatableScrollView
UIBarButtonItem AnimatableBarButtonItem
UIButton AnimatableButton
UIButton AnimatableCheckBox Connect UIButton as AnimatableCheckBox to make CheckBox control
UIImageView AnimatableImageView
UILabel AnimatableLabel To style the text in Label, we can use Interface Builder built-in Attributed Text
UIStackView AnimatableStackView
UITableView AnimatableTableView
UITableViewCell AnimatableTableViewCell
UITextField AnimatableTextField
UITextView AnimatableTextView
UINavigationBar DesignableNavigationBar
UIViewController AnimatableViewController
UINavigationController AnimatableNavigationController
UITableViewController AnimatableTableViewController
UISlider AnimatableSlider
UIActivityIndicatorView AnimatableActivityIndicatorView List of animations available

Designable protocols

IBAnimatable provides a set of Designable protocols as below. Because of the power of protocol-oriented programming in Swift, we don't even have to use Animatable default UI elements e.g. AnimatableView to unlocked the power of IBAnimatable. We can conform to IBAnimatable protocols to use the default implementation in protocol extension to create other custom UI elements.

BarButtonItemDesignable

Property name Data type Description
roundedImage Optional<UIImage> By default, Interface Builder can only support outline images for Bar Button Item. With roundedImage, we can display a rounded image. The image can not be previewed in Interface Builder.

BlurDesignable

Property name Data type Description
blurEffectStyle Optional<String> Support three different blur effects: ExtraLight, Light and Dark, also can be found in emum BlurEffectStyle. The look of blur effect in Interface Builder is different from Simulator or device.
vibrancyEffectStyle Optional<String> Support three different blur effects: ExtraLight, Light and Dark, also can be found in emum BlurEffectStyle. Once specify the Vibrancy effect style, all subviews will apply this vibrancy effect. Pleace notice that once the vibrancy effect is applied, all the subviews will loose their constraints. The workaround for this is to reset programatically each of them.
blurOpacity CGFloat Opacity of the blur effect specified above. the default value is CGFloat.NaN, the value range is from 0.0 to 1.0.

BorderDesignable

Property name Data type Description
borderType Optional<String> border type: solid, dash, also can be found in emum BorderSide. If not specified, then display solid borders. Please notice: If we use maskType property then borderType will be ignored.
borderColor Optional<UIColor> border color
borderWidth CGFloat border width. Default value is CGFloat.NaN, the value is greater than 0.
borderSide Optional<String> border side: top, right, bottom or left, also can be found in emum BorderSide. Multiple sides can be configured with a comma separated list of sides (e.g. top,bottom). If not specified, then display four sides. Please notice: If we use maskType property then borderSide will be ignored.

CheckBoxDesignable

Property name Data type Description
checked Bool Default value is false
checkedImage Optional<UIImage> The image to display when CheckBox is checked.
uncheckedImage Optional<UIImage> The image to display when CheckBox is unchecked.

CornerDesignable

Property name Data type Description
cornerRadius CGFloat rounded corner radius. The default value is CGFloat.NaN, the value is greater than 0.
cornerSides Optional<String> corner side: topLeft, topRight, bottomLeft or bottomRight, also can be found in emum CornerSide. Multiple sides can be configured with a comma separated list of sides (e.g. topLeft,topRight). If not specified, then display four sides. Please notice: If we use maskType property then it will be replaced by cornerSide.

FillDesignable

Property name Data type Description
fillColor Optional<UIColor> fill color of the UI Element
opacity CGFloat opacity, alpha of the UI Element, the default value is CGFloat.NaN, the value is from 0.0 to 1.0.
predefinedColor Optional<String> Predefined color. All predefined colors are in enum ColorType. To find the predefined flat colors, you can use flatuicolors.com, all flat color start with Flat, e.g. PETER RIVER on the website maps to FlatPeterRiver in the enum.

GradientDesignable

Property name Data type Description
gradientMode Optional<GradientMode> Gradient mode. All gradient mode are in enum GradientMode, default value is .linear.
startColor Optional<UIColor> start gradient color
endColor Optional<UIColor> end gradient color
predefinedGradient Optional<String> Predefined gradients. All predefined gradients are in enum GradientType, To find the predefined gradients, you can use uigradients.com, e.g. Juicy Orange on the website maps to JuicyOrange in the enum.
startPoint Optional<String> start direction point, can find in enum GradientStartPoint .

NavigationBarDesignable

Property name Data type Description
solidColor Bool whether to display solid color only. The default value is false. Need to manually uncheck translucent in Interface Builder, otherwise, it will have constraint issue in IB although it is correct in run time.

MaskDesignable

Property name Data type Description
maskType Optional<String> Supported maks type: All predefined animations are in enum MaskType

Supported MaskType:

  • circle
  • ellipse
  • polygon: Can also specify the number of sides of the polygon, e.g. use Polygon(6) to have a polygon with 6 sides. If not specified, the default is 6 sides.
  • triangle
  • star: Can also specify the points of the Star, e.g. use Star(6) to have a star with 6 points. If not specified, the default is 5 points.
  • wave: Can use parameters to customize the Wave. Wave(down, 20, 5) means the Wave faces down, width is 20 and offset is 5. If not specified, the default value is Wave(up, 40, 0).
  • parallelogram: Can use parameters to customize the Parallelogram. Parallelogram(60) means the top left angle of the Parallelogram will have an angle of 60 degrees. The default value is Parallelogram(60). if angle == 90 it will be a rectangular Mask. if angle < 90 the parallelogram will be oriented to left.
  • heart
  • ring: Can also specify the radius of the Ring, e.g. use Ring(6) to have a ring with 6 as radius.
  • gear: Can also specify the radius of the Gear and the number of cogs , e.g. use Gear(6, 8) to have a gear with 6 as radius and 8 cogs.
  • superellipse: Can also specify the curve of Superellipse, e.g use superellipse(1) to have a diamond.
  • drop
  • plussign: Can also specify the thickness of the plus sign, e.g. use Plussign(10) to have a plug sign with 10 as thickness.
  • moon: Can also specify the angle to change the Moon shape.
  • insetBy: Must use the parameters to defined the inset for the inner rectangle e.g. use insetBy(10, 12).
  • rounded: Choose the radius to define the corner radius, eg. use rounded(10). Can also specify the CornerSides to choose rouned the corner, eg. use rounded(10, topLeft).
  • custom: Allows you to use your own bezier path as mask. Only usable from code (not from IB). You have to pass in parameter a closure that takes a CGSize (the current's view Size) and returns the UIBezierPath

PaddingDesignable

It is used in AnimatableTextField to add padding on either or both sides.

Property name Data type Description
paddingLeft CGFloat padding on left-hand side. The default value is CGFloat.NaN.
paddingRight CGFloat padding on right-hand side. The default value is CGFloat.NaN.
paddingSide CGFloat padding on both sides. The default value is CGFloat.NaN.

PlaceholderDesignable

Property name Data type Description
placeholderColor Optional<UIColor> placeholder text color in AnimatableTextField and AnimatableTextView.
placeholderText Optional<String> placeholder text in AnimatableTextView.

RootWindowDesignable

Property name Data type Description
rootWindowBackgroundColor Optional<UIColor> root window background color. Can be seen when we use flip transition.

RotationDesignable

Property name Data type Description
rotate CGFloat rotation of the UI element in degrees. The default value is CGFloat.NaN, value is from -360 to 360, if the value is negative, it rotates reverse.

ShadowDesignable

Drop shadow of the UI element, it is popular in Material Design. These properties are not able to render in IB correctly, it probably is an Interface Builder's bug.

Property name Data type Description
shadowColor Optional<UIColor> shadow color
shadowRadius CGFloat shadow corner radius. The default value is CGFloat.NaN, the value is greater than 0.
shadowOpacity CGFloat shadow opacity. The default value is CGFloat.NaN, the value is from 0.0 to 1.0.
shadowOffset CGPoint x is horizontal offset and y is vertical offset.

SideImageDesignable

Display a side hint image in AnimatableTextField

Property name Data type Description
leftImage Optional<UIImage> the image to display on the left-hand side.
leftImageLeftPadding CGFloat left padding of hint image. The default value is CGFloat.NaN.
leftImageRightPadding CGFloat right padding of hint image. The default value is CGFloat.NaN.
leftImageTopPadding CGFloat top padding of hint image. The default value is CGFloat.NaN. If not specified, the image will center vertically.
rightImage Optional<UIImage> the image to display on the right-hand side.
rightImageLeftPadding CGFloat left padding of hint image. The default value is CGFloat.NaN.
rightImageRightPadding CGFloat right padding of hint image. The default value is CGFloat.NaN.
rightImageTopPadding CGFloat top padding of hint image. The default value is CGFloat.NaN. If not specified, the image will center vertically.

StatusBarDesignable

Property name Data type Description
lightStatusBar Bool to display white or black text status bar. The default value is false to display black text.

TableViewCellDesignable

Property name Data type Description
removeSeparatorMargins Bool whether to remove separator margins in AnimatableTableViewCell. The default value is false. There maybe a bug of Interface Builder when setting "Separator Insert" to 0 doesn't work.

TintDesignable

Easily add color layer on top of the UI element especially AnimatableImageView.

Property name Data type Description
tintOpacity CGFloat opacity of tint color (white color). The default value is CGFloat.NaN.
shadeOpacity CGFloat opacity of shade color (black color). The default value is CGFloat.NaN.
toneColor Optional<UIColor> tone color
toneOpacity CGFloat opacity of tone color. The default value is CGFloat.NaN.

ViewControllerDesignable

Property name Data type Description
hideNavigationBar Bool whether to hide navigation bar. The default value is false.

RefreshControlDesignable

Property name Data type Description
hasRefreshControl Bool whether to add a UIRefreshControl. The default value is false.
refreshControlTintColor Optional<UIColor> tint color of the UIRefreshControl
refreshControlBackgroundColor Optional<UIColor> background color of the UIRefreshControl

Note: AnimatableTableView conforms to that protocol, but if your deployment target is less than 10, you will have to add your UIRefreshControl yourself:

let refreshControl: UIRefreshControl?
if #available(iOS 10.0, *) {
  refreshControl = tableView.refreshControl
} else {
  refreshControl = UIRefreshControl()
  tableView.addSubview(refreshControl!)
  tableView.configureRefreshController()
}
refreshControl?.addTarget(self, action: #selector(refresh(_:)), for: .valueChanged)

SliderImagesDesignable

Property name Data type Description
thumbImage Optional<UIImage> the thumb image when slider state is normal.
thumbHighlightedImage Optional<UIImage> the thumb image when slider state is highlighted.
minimumTrackImage Optional<UIImage> the minimum track image when slider state is normal.
minimumTrackHighlightedImage Optional<UIImage> the minimum track image when slider state is highlighted.
maximumTrackImage Optional<UIImage> the maximum track image when slider state is normal.
maximumTrackHighlightedImage Optional<UIImage> the maximum track image when slider state is highlighted.

Animatable protocol

Properties

Property name Data type Description
animationType Optional<String> Supported animations. All predefined animations are in enum AnimationType
autoRun Bool Whether to automatically start the animation. The default value is true. if it is true, the animation will automatically run when the view is loaded. If want to manually start the animation should set it to false.
duration CGFloat Animation duration in seconds. The default value is 0.7.
delay Double Delay to start the animation in seconds. The default value is 0.
damping CGFloat Used in UIView Spring animation (0 ~ 1 seconds). To smoothly decelerate the animation without oscillation, use a value of 1. Employ a damping ratio closer to zero to increase oscillation. The default value is 0.7. Notice: FadeOutIn, FadeInOut, Shake, Pop, Morph, Squeeze, Flash, Wobble and Swing animations do not use damping.
velocity CGFloat used in UIView Spring animation. A value of 1 corresponds to the total animation distance traversed in one second. For example, if the total animation distance is 200 points and you want the start of the animation to match a view velocity of 100 pt/s, use a value of 0.5. The default is 0.7. Notice: FadeOutIn, FadeInOut, Shake, Pop, Morph, Squeeze, Flash, Wobble and Swing animations do not use damping.
force CGFloat used to apply force to the animation. The number is higher, the animation property has more changes. e.g. for Pop animation, the higher force causes the view popping bigger. The default value is 1.
timingFunction TimingFunctionType used to specifies the speed curve of an animation. For Spring animation only linear, easeIn, easeOut and easeInOut could be used and velocity and damping parameters will be ignored. The default value is none.
repeatCount Float Used to specify the count to repeat the animation. Can only be used in Shake, Pop, Morph, Squeeze, Flash, Wobble, Swing, Rotate and RotateCCW (rotate counterclockwise) animations. The default value is 1.
x CGFloat Used to specify the absolute x to move in MoveTo animation and x offset in MoveBy. When used in MoveBy, negative means moving left and positive means moving right. The default value is CGFloat.NaN
y CGFloat Used to specify the absolute y to move in MoveTo animation and y offset in MoveBy. When used in MoveBy, negative means moving up and positive means moving down. The default value is CGFloat.NaN

TransitionAnimatable protocol

Property name Data type Description
transitionAnimationType Optional<String> Supported transition animations. Tap on "Playground" button to see all predefined transition animations, e.g. Fade, SystemCube(Left) and SystemPageCurl(Bottom). The transition type starts with System can only use in Push/Pop transitions, not Present/Dismiss transitions. Note: For SystemRotate seems that only SystemRotate(90) is working.
transitionDuration Double transition duration. The default value is defined in Constants (0.7 seconds)
interactiveGestureType Optional<String> interactive gesture type. used to specify the gesture to dismiss/pop current scence. All supported interactive gesture types are in InteractiveGestureType

Also see Transition Animators and Interactive Animators

ActivityIndicatorAnimatable

Fully documented in Activity indicator animations

Extension

UIViewController

With these methods, we can navigate back or dismiss current ViewController without any code in Interface Builder.

Method name Description
func unwindToViewController(sender: UIStoryboardSegue) Used in Interface Builder to unwind from Navigation Controller
func dismissCurrentViewController(sender: UIStoryboardSegue) Used in Interface Builder to dismiss current ViewController

CALayer

Method name Description
class func animate(animation: AnimatableExecution, completion: AnimatableCompletion? = nil) Simplify CALayer animations with completion closure

TransitionAnimatable protocol

Property name Data type Description
transitionAnimationType Optional<String> Supported transition animations. Tap on "Forgot Password" button to see all predefined transition animations, e.g. Fade, SystemCube(Left) and SystemPageCurl(Bottom). The transition type starts with System can only use in Push/Pop transitions, not Present/Dismiss transitions. Note: For SystemRotate seems that only SystemRotate(90) is working.
transitionDuration Double transition duration. The default value is defined in Constants (0.7 seconds)
interactiveGestureType Optional<String> interactive gesture type. used to specify the gesture to dismiss/pop current scence. All supported interactive gesture types are in InteractiveGestureType

Also see Transition Animators and Interactive Animators

Segues

See Segues