iOS之CALayer属性简介

/* CoreAnimation - CALayer.h
 
 Copyright (c) 2006-2017, Apple Inc.
 All rights reserved. */

#import <QuartzCore/CAMediaTiming.h>
#import <QuartzCore/CATransform3D.h>
#import <Foundation/NSObject.h>
#import <Foundation/NSNull.h>
#import <Foundation/NSArray.h>
#import <Foundation/NSDictionary.h>

@class NSEnumerator, CAAnimation, CALayerArray;
@protocol CAAction, CALayerDelegate;

NS_ASSUME_NONNULL_BEGIN

/* Bit definitions for `edgeAntialiasingMask' property. */

typedef NS_OPTIONS (unsigned int, CAEdgeAntialiasingMask)
{
    kCALayerLeftEdge      = 1U << 0,      /* Minimum X edge. */
    kCALayerRightEdge     = 1U << 1,      /* Maximum X edge. */
    kCALayerBottomEdge    = 1U << 2,      /* Minimum Y edge. */
    kCALayerTopEdge       = 1U << 3,      /* Maximum Y edge. */
};

/* Bit definitions for `maskedCorners' property. */

typedef NS_OPTIONS (NSUInteger, 
)
{
    kCALayerMinXMinYCorner = 1U << 0,
    kCALayerMaxXMinYCorner = 1U << 1,
    kCALayerMinXMaxYCorner = 1U << 2,
    kCALayerMaxXMaxYCorner = 1U << 3,
};

/** The base layer class. **/

CA_CLASS_AVAILABLE (10.5, 2.0, 9.0, 2.0)
@interface CALayer : NSObject <NSSecureCoding, CAMediaTiming>
{
@private
    struct _CALayerIvars {
        int32_t refcount;
        uint32_t magic;
        void *layer;
#if TARGET_OS_MAC && !TARGET_RT_64_BIT
        void * _Nonnull unused1[8];
#endif
    } _attr;
}

/** Layer creation and initialization. **/
//初始化方法
+ (instancetype)layer;
- (instancetype)init;
- (instancetype)initWithLayer:(id)layer;

//presentationLayer是通过modelLayer提供属性进行绘制的
//呈现层 用于显示动画
- (nullable instancetype)presentationLayer;

//模型层 设置的layer属性就是在这个层
- (instancetype)modelLayer;

/** Property methods. **/

//重写修改CALayer或其子类的默认值 ，key为属性名称，如果没有该属性返回nil
+ (nullable id)defaultValueForKey:(NSString *)key;

//需要子类重写，当CALayer或其子类属性被修改时调用此方法
//key为修改的属性名，返回YES是系统自动调用-display方法
+ (BOOL)needsDisplayForKey:(NSString *)key;

//指示指定键的值是否应该归档。
- (BOOL)shouldArchiveValueForKey:(NSString *)key;

//layer的大小
@property CGRect bounds;

//设置CALayer在父层中的位置
@property CGPoint position;

//z方向的位置
@property CGFloat zPosition;

//平面上的锚点（0-1），决定layer身上的哪个点在position的位置上
@property CGPoint anchorPoint;

//z方向上的锚点
@property CGFloat anchorPointZ;

//矩阵 仿射变换
@property CATransform3D transform;

//返回和设置仿射变换值
- (CGAffineTransform)affineTransform;
- (void)setAffineTransform:(CGAffineTransform)m;

//设置layer的坐标
@property CGRect frame;

//是否隐藏
@property(getter=isHidden) BOOL hidden;

//设置layer的背面是否被绘制，默认是YES，NO时当图层从相机视角消失是将不会被绘制。
@property(getter=isDoubleSided) BOOL doubleSided;

//默认为NO，设置为YES所有子图层相对于左上角的位置改为相对于左下角位置
@property(getter=isGeometryFlipped) BOOL geometryFlipped;

//获取当前layer内容在Y轴方向是否被翻转了
- (BOOL)contentsAreFlipped;

//获取父层layer
@property(nullable, readonly) CALayer *superlayer;

//从父层layer上移除
- (void)removeFromSuperlayer;

//获取所有子layer数组
@property(nullable, copy) NSArray<CALayer *> *sublayers;

//将layer添加到父视图
- (void)addSublayer:(CALayer *)layer;

//插入一个layer
- (void)insertSublayer:(CALayer *)layer atIndex:(unsigned)idx;
- (void)insertSublayer:(CALayer *)layer below:(nullable CALayer *)sibling;
- (void)insertSublayer:(CALayer *)layer above:(nullable CALayer *)sibling;

//用layer2替换layer
- (void)replaceSublayer:(CALayer *)layer with:(CALayer *)layer2;

//对子layer进行3D变换
@property CATransform3D sublayerTransform;

//图层蒙版layer
@property(nullable, strong) CALayer *mask;

//是否进行bounds切割，通常设置圆角时使用
@property BOOL masksToBounds;

/** Mapping between layer coordinate and time spaces. **/
//转换坐标点、矩形
- (CGPoint)convertPoint:(CGPoint)p fromLayer:(nullable CALayer *)l;
- (CGPoint)convertPoint:(CGPoint)p toLayer:(nullable CALayer *)l;
- (CGRect)convertRect:(CGRect)r fromLayer:(nullable CALayer *)l;
- (CGRect)convertRect:(CGRect)r toLayer:(nullable CALayer *)l;
//转换CAMediaTiming协议的相对时间
- (CFTimeInterval)convertTime:(CFTimeInterval)t fromLayer:(nullable CALayer *)l;
- (CFTimeInterval)convertTime:(CFTimeInterval)t toLayer:(nullable CALayer *)l;

/** Hit testing methods. **/

//返回包含某一点的最上层的子layer
- (nullable CALayer *)hitTest:(CGPoint)p;

//判断layer是否包含某一点
- (BOOL)containsPoint:(CGPoint)p;

/** Layer content properties and methods. **/

//设置layer的内容 ，一般设置CGImage的对象
@property(nullable, strong) id contents;

//获取内容的rect尺寸
@property CGRect contentsRect;

//设置内容对齐和填充方式（枚举）
@property(copy) NSString *contentsGravity;

//设置内容的缩放
@property CGFloat contentsScale
CA_AVAILABLE_STARTING (10.7, 4.0, 9.0, 2.0);

//设置一个矩形变形区域默认（0，0，1，1）取值0-1
@property CGRect contentsCenter;

//设置内容存储格式
@property(copy) NSString *contentsFormat
CA_AVAILABLE_STARTING (10.12, 10.0, 10.0, 3.0);

//设置缩小和放大模式
@property(copy) NSString *minificationFilter;
@property(copy) NSString *magnificationFilter;

//缩放因子
@property float minificationFilterBias;

//设置内容完全不透明 默认NO
@property(getter=isOpaque) BOOL opaque;

//重新加载绘制内容
- (void)display;

// 设置内容或某一区域内容加载
- (void)setNeedsDisplay;
- (void)setNeedsDisplayInRect:(CGRect)r;

//获取是否需要重新绘制
- (BOOL)needsDisplay;

//如果需要进行内容重新绘制
- (void)displayIfNeeded;

//设置为YES 内容改变后自动调用 - (void)setNeedsDisplay;方法
@property BOOL needsDisplayOnBoundsChange;

//延迟绘制命令，用于需要频繁重绘的视图
@property BOOL drawsAsynchronously
CA_AVAILABLE_STARTING (10.8, 6.0, 9.0, 2.0);

//绘制内容
- (void)drawInContext:(CGContextRef)ctx;

/** Rendering properties and methods. **/

//读取内容
- (void)renderInContext:(CGContextRef)ctx;

//用于限定层的边缘如何栅格化，默认是抗锯齿
@property CAEdgeAntialiasingMask edgeAntialiasingMask;

//YES时，要求edgeAntialiasingMask属性边抗锯齿，默认值是从Info.plist中UIViewEdgeAntialiasing属性获取，如果没有值默认NO
@property BOOL allowsEdgeAntialiasing;

//设置layer背景色
@property(nullable) CGColorRef backgroundColor;

//设置layer圆角半径
@property CGFloat cornerRadius;

//设置layer哪几个角显示圆角 支持动画
@property CACornerMask maskedCorners
CA_AVAILABLE_STARTING (10.13, 11.0, 11.0, 4.0);

//设置边框宽度
@property CGFloat borderWidth;

//设置边框颜色
@property(nullable) CGColorRef borderColor;

//设置透明度
@property float opacity;

//默认YES（iOS7之后）子layer最高透明度上限是父layer的透明度，NO各自控制
@property BOOL allowsGroupOpacity;

//一个coreImage过滤器 用于合成图层及其后面内容 可动画
@property(nullable, strong) id compositingFilter;

//应用于图层和其子图层内容的coreImage过滤器数组
@property(nullable, copy) NSArray *filters;

//应用于图层后面的内容的coreImage过滤器数组 可动画
@property(nullable, copy) NSArray *backgroundFilters;

//光栅化
@property BOOL shouldRasterize;

//当shouldRasterize设置为YES是，也就是光栅化之后 设置此属性防止retina屏幕像素化（默认值1）
@property CGFloat rasterizationScale;

/** Shadow properties. **/

//阴影颜色 可动画
@property(nullable) CGColorRef shadowColor;

//阴影透明度 可动画
@property float shadowOpacity;

//阴影偏移量 可动画
@property CGSize shadowOffset;

//阴影圆角半径 可动画
@property CGFloat shadowRadius;

//阴影路径 可动画
@property(nullable) CGPathRef shadowPath;

/** Layout methods. **/

//返回图层在其父图层的坐标空间中的首选大小
- (CGSize)preferredFrameSize;

//使图层无效，标记需要更新
- (void)setNeedsLayout;

//返回是否需要布局更新标志
- (BOOL)needsLayout;

//如果需要，重新计算布局
- (void)layoutIfNeeded;

//重新布局所有子layer
- (void)layoutSublayers;

/** Action methods. **/

//返回当前类的默认操作
+ (nullable id<CAAction>)defaultActionForKey:(NSString *)event;

//返回分配给指定键的动作对象
- (nullable id<CAAction>)actionForKey:(NSString *)event;

//包含图层动作的字典
@property(nullable, copy) NSDictionary<NSString *, id<CAAction>> *actions;

/** Animation methods. **/

//给layer渲染树添加指定动画对象
- (void)addAnimation:(CAAnimation *)anim forKey:(nullable NSString *)key;

//移除所有动画对象
- (void)removeAllAnimations;

//移除指定动画对象
- (void)removeAnimationForKey:(NSString *)key;

//返回字符串数组，标记当前layer附加的所有动画
- (nullable NSArray<NSString *> *)animationKeys;

//通过指定的标识返回一个动画对象
- (nullable CAAnimation *)animationForKey:(NSString *)key;


/** Miscellaneous properties. **/

//图层标识
@property(nullable, copy) NSString *name;

//代理
@property(nullable, weak) id <CALayerDelegate> delegate;

//一个用于存储未由图层显示定义的属性值的可选字典
@property(nullable, copy) NSDictionary *style;

@end

/** Action (event handler) protocol. **/

@protocol CAAction

//CAAction协议方法（action对象 隐式动画）
- (void)runActionForKey:(NSString *)event object:(id)anObject
              arguments:(nullable NSDictionary *)dict;

@end

/** NSNull protocol conformance. **/

@interface NSNull (CAActionAdditions) <CAAction>

@end

/** Delegate methods. **/

@protocol CALayerDelegate <NSObject>
@optional

//更新图层时回调
- (void)displayLayer:(CALayer *)layer;

//绘制图层时回调
- (void)drawLayer:(CALayer *)layer inContext:(CGContextRef)ctx;

//图层将要绘制是回调
- (void)layerWillDraw:(CALayer *)layer
CA_AVAILABLE_STARTING (10.12, 10.0, 10.0, 3.0);

//子layer布局时回调
- (void)layoutSublayersOfLayer:(CALayer *)layer;

//执行指定操作时回调
- (nullable id<CAAction>)actionForLayer:(CALayer *)layer forKey:(NSString *)event;

@end

/** Layer `contentsGravity' values. **/

CA_EXTERN NSString * const kCAGravityCenter
CA_AVAILABLE_STARTING (10.5, 2.0, 9.0, 2.0);
CA_EXTERN NSString * const kCAGravityTop
CA_AVAILABLE_STARTING (10.5, 2.0, 9.0, 2.0);
CA_EXTERN NSString * const kCAGravityBottom
CA_AVAILABLE_STARTING (10.5, 2.0, 9.0, 2.0);
CA_EXTERN NSString * const kCAGravityLeft
CA_AVAILABLE_STARTING (10.5, 2.0, 9.0, 2.0);
CA_EXTERN NSString * const kCAGravityRight
CA_AVAILABLE_STARTING (10.5, 2.0, 9.0, 2.0);
CA_EXTERN NSString * const kCAGravityTopLeft
CA_AVAILABLE_STARTING (10.5, 2.0, 9.0, 2.0);
CA_EXTERN NSString * const kCAGravityTopRight
CA_AVAILABLE_STARTING (10.5, 2.0, 9.0, 2.0);
CA_EXTERN NSString * const kCAGravityBottomLeft
CA_AVAILABLE_STARTING (10.5, 2.0, 9.0, 2.0);
CA_EXTERN NSString * const kCAGravityBottomRight
CA_AVAILABLE_STARTING (10.5, 2.0, 9.0, 2.0);
CA_EXTERN NSString * const kCAGravityResize
CA_AVAILABLE_STARTING (10.5, 2.0, 9.0, 2.0);
CA_EXTERN NSString * const kCAGravityResizeAspect
CA_AVAILABLE_STARTING (10.5, 2.0, 9.0, 2.0);
CA_EXTERN NSString * const kCAGravityResizeAspectFill
CA_AVAILABLE_STARTING (10.5, 2.0, 9.0, 2.0);

/** Layer `contentsFormat` values. **/

CA_EXTERN NSString * const kCAContentsFormatRGBA8Uint /* RGBA UInt8 per component */
CA_AVAILABLE_STARTING (10.12, 10.0, 10.0, 3.0);
CA_EXTERN NSString * const kCAContentsFormatRGBA16Float /* RGBA half-float 16-bit per component */
CA_AVAILABLE_STARTING (10.12, 10.0, 10.0, 3.0);
CA_EXTERN NSString * const kCAContentsFormatGray8Uint /* Grayscale with alpha (if not opaque) UInt8 per component */
CA_AVAILABLE_STARTING (10.12, 10.0, 10.0, 3.0);

/** Contents filter names. **/

CA_EXTERN NSString * const kCAFilterNearest
CA_AVAILABLE_STARTING (10.5, 2.0, 9.0, 2.0);
CA_EXTERN NSString * const kCAFilterLinear
CA_AVAILABLE_STARTING (10.5, 2.0, 9.0, 2.0);

/* Trilinear minification filter. Enables mipmap generation. Some
 * renderers may ignore this, or impose additional restrictions, such
 * as source images requiring power-of-two dimensions. */

CA_EXTERN NSString * const kCAFilterTrilinear
CA_AVAILABLE_STARTING (10.6, 3.0, 9.0, 2.0);

/** Layer event names. **/

CA_EXTERN NSString * const kCAOnOrderIn
CA_AVAILABLE_STARTING (10.5, 2.0, 9.0, 2.0);
CA_EXTERN NSString * const kCAOnOrderOut
CA_AVAILABLE_STARTING (10.5, 2.0, 9.0, 2.0);

/** The animation key used for transitions. **/

CA_EXTERN NSString * const kCATransition
CA_AVAILABLE_STARTING (10.5, 2.0, 9.0, 2.0);

NS_ASSUME_NONNULL_END