// // ASLayoutable.h // AsyncDisplayKit // // Copyright (c) 2014-present, Facebook, Inc. All rights reserved. // This source code is licensed under the BSD-style license found in the // LICENSE file in the root directory of this source tree. An additional grant // of patent rights can be found in the PATENTS file in the same directory. // #import #import #import #import #import #import #import @class ASLayout; @class ASLayoutSpec; /** A constant that indicates that the parent's size is not yet determined in a given dimension. */ extern CGFloat const ASLayoutableParentDimensionUndefined; /** A constant that indicates that the parent's size is not yet determined in either dimension. */ extern CGSize const ASLayoutableParentSizeUndefined; /** Type of ASLayoutable */ typedef NS_ENUM(NSUInteger, ASLayoutableType) { ASLayoutableTypeLayoutSpec, ASLayoutableTypeDisplayNode }; NS_ASSUME_NONNULL_BEGIN /** * The ASLayoutable protocol declares a method for measuring the layout of an object. A layout * is defined by an ASLayout return value, and must specify 1) the size (but not position) of the * layoutable object, and 2) the size and position of all of its immediate child objects. The tree * recursion is driven by parents requesting layouts from their children in order to determine their * size, followed by the parents setting the position of the children once the size is known * * The protocol also implements a "family" of Layoutable protocols. These protocols contain layout * options that can be used for specific layout specs. For example, ASStackLayoutSpec has options * defining how a layoutable should shrink or grow based upon available space. * * These layout options are all stored in an ASLayoutOptions class (that is defined in ASLayoutablePrivate). * Generally you needn't worry about the layout options class, as the layoutable protocols allow all direct * access to the options via convenience properties. If you are creating custom layout spec, then you can * extend the backing layout options class to accommodate any new layout options. */ @protocol ASLayoutable #pragma mark - Getter /** * @abstract Returns type of layoutable */ @property (nonatomic, assign, readonly) ASLayoutableType layoutableType; /** * @abstract Returns if the layoutable can be used to layout in an asynchronous way on a background thread. */ @property (nonatomic, assign, readonly) BOOL canLayoutAsynchronous; /** * @abstract A size constraint that should apply to this ASLayoutable. */ @property (nonatomic, assign, readonly) ASLayoutableStyle *style; #pragma mark - Calculate layout /** * @abstract Asks the node to return a layout based on given size range. * * @param constrainedSize The minimum and maximum sizes the receiver should fit in. * * @return An ASLayout instance defining the layout of the receiver (and its children, if the box layout model is used). * * @discussion Though this method does not set the bounds of the view, it does have side effects--caching both the * constraint and the result. * * @warning Subclasses must not override this; it caches results from -calculateLayoutThatFits:. Calling this method may * be expensive if result is not cached. * * @see [ASDisplayNode(Subclassing) calculateLayoutThatFits:] */ - (ASLayout *)layoutThatFits:(ASSizeRange)constrainedSize; /** * Call this on children layoutables to compute their layouts within your implementation of -calculateLayoutThatFits:. * * @warning You may not override this method. Override -calculateLayoutThatFits: instead. * @warning In almost all cases, prefer the use of ASCalculateLayout in ASLayout * * @param constrainedSize Specifies a minimum and maximum size. The receiver must choose a size that is in this range. * @param parentSize The parent node's size. If the parent component does not have a final size in a given dimension, * then it should be passed as ASLayoutableParentDimensionUndefined (for example, if the parent's width * depends on the child's size). * * @discussion Though this method does not set the bounds of the view, it does have side effects--caching both the * constraint and the result. * * @return An ASLayout instance defining the layout of the receiver (and its children, if the box layout model is used). */ - (ASLayout *)layoutThatFits:(ASSizeRange)constrainedSize parentSize:(CGSize)parentSize; /** * Override this method to compute your layoutable's layout. * * @discussion Why do you need to override -calculateLayoutThatFits: instead of -layoutThatFits:parentSize:? * The base implementation of -layoutThatFits:parentSize: does the following for you: * 1. First, it uses the parentSize parameter to resolve the nodes's size (the one assigned to the size property). * 2. Then, it intersects the resolved size with the constrainedSize parameter. If the two don't intersect, * constrainedSize wins. This allows a component to always override its childrens' sizes when computing its layout. * (The analogy for UIView: you might return a certain size from -sizeThatFits:, but a parent view can always override * that size and set your frame to any size.) * 3. It caches it result for reuse * * @param constrainedSize A min and max size. This is computed as described in the description. The ASLayout you * return MUST have a size between these two sizes. */ - (ASLayout *)calculateLayoutThatFits:(ASSizeRange)constrainedSize; /** * In certain advanced cases, you may want to override this method. Overriding this method allows you to receive the * layoutable's size, parentSize, and constrained size. With these values you could calculate the final constrained size * and call -calculateLayoutThatFits: with the result. * * @warning Overriding this method should be done VERY rarely. */ - (ASLayout *)calculateLayoutThatFits:(ASSizeRange)constrainedSize restrictedToSize:(ASLayoutableSize)size relativeToParentSize:(CGSize)parentSize; #pragma mark - Deprecated /** * @abstract Calculate a layout based on given size range. * * @param constrainedSize The minimum and maximum sizes the receiver should fit in. * * @return An ASLayout instance defining the layout of the receiver and its children. * * @deprecated Deprecated in version 2.0: Use ASCalculateRootLayout or ASCalculateLayout instead */ - (ASLayout *)measureWithSizeRange:(ASSizeRange)constrainedSize ASDISPLAYNODE_DEPRECATED; @end #pragma mark - ASLayoutableStyle extern NSString * const ASLayoutableStyleWidthProperty; extern NSString * const ASLayoutableStyleMinWidthProperty; extern NSString * const ASLayoutableStyleMaxWidthProperty; extern NSString * const ASLayoutableStyleHeightProperty; extern NSString * const ASLayoutableStyleMinHeightProperty; extern NSString * const ASLayoutableStyleMaxHeightProperty; extern NSString * const ASLayoutableStyleSpacingBeforeProperty; extern NSString * const ASLayoutableStyleSpacingAfterProperty; extern NSString * const ASLayoutableStyleFlexGrowProperty; extern NSString * const ASLayoutableStyleFlexShrinkProperty; extern NSString * const ASLayoutableStyleFlexBasisProperty; extern NSString * const ASLayoutableStyleAlignSelfProperty; extern NSString * const ASLayoutableStyleAscenderProperty; extern NSString * const ASLayoutableStyleDescenderProperty; extern NSString * const ASLayoutableStyleLayoutPositionProperty; @protocol ASLayoutableStyleDelegate - (void)style:(__kindof ASLayoutableStyle *)style propertyDidChange:(NSString *)propertyName; @end @interface ASLayoutableStyle : NSObject #pragma mark - Delegate /** * @abstract Initializes the layoutable style with a specified delegate */ - (instancetype)initWithDelegate:(id)delegate; /** * @abstract The object that acts as the delegate of the style. * * @discussion The delegate must adopt the ASLayoutableStyleDelegate protocol. The delegate is not retained. */ @property (nullable, nonatomic, weak, readonly) id delegate; /** * @abstract A size constraint that should apply to this ASLayoutable. */ @property (nonatomic, assign, readonly) ASLayoutableSize size; /** * @abstract The width property specifies the height of the content area of an ASLayoutable. * The minWidth and maxWidth properties override width. * Defaults to ASRelativeDimensionTypeAuto */ @property (nonatomic, assign, readwrite) ASDimension width; /** * @abstract The height property specifies the height of the content area of an ASLayoutable * The minHeight and maxHeight properties override height. * Defaults to ASDimensionTypeAuto */ @property (nonatomic, assign, readwrite) ASDimension height; /** * @abstract The minHeight property is used to set the minimum height of a given element. It prevents the used value * of the height property from becoming smaller than the value specified for minHeight. * The value of minHeight overrides both maxHeight and height. * Defaults to ASDimensionTypeAuto */ @property (nonatomic, assign, readwrite) ASDimension minHeight; /** * @abstract The maxHeight property is used to set the maximum height of an element. It prevents the used value of the * height property from becoming larger than the value specified for maxHeight. * The value of maxHeight overrides height, but minHeight overrides maxHeight. * Defaults to ASDimensionTypeAuto */ @property (nonatomic, assign, readwrite) ASDimension maxHeight; /** * @abstract The minWidth property is used to set the minimum width of a given element. It prevents the used value of * the width property from becoming smaller than the value specified for minWidth. * The value of minWidth overrides both maxWidth and width. * Defaults to ASDimensionTypeAuto */ @property (nonatomic, assign, readwrite) ASDimension minWidth; /** * @abstract The maxWidth property is used to set the maximum width of a given element. It prevents the used value of * the width property from becoming larger than the value specified for maxWidth. * The value of maxWidth overrides width, but minWidth overrides maxWidth. * Defaults to ASDimensionTypeAuto */ @property (nonatomic, assign, readwrite) ASDimension maxWidth; /** * @abstract Set max and width properties from given size */ - (void)setSizeWithCGSize:(CGSize)size; /** * @abstract Set minHeight, maxHeight and minWidth, maxWidth properties from given size */ - (void)setExactSizeWithCGSize:(CGSize)size; #pragma mark - ASStackLayoutable /** * @abstract Additional space to place before this object in the stacking direction. * Used when attached to a stack layout. */ @property (nonatomic, assign) CGFloat spacingBefore; /** * @abstract Additional space to place after this object in the stacking direction. * Used when attached to a stack layout. */ @property (nonatomic, assign) CGFloat spacingAfter; /** * @abstract If the sum of childrens' stack dimensions is less than the minimum size, should this object grow? * Used when attached to a stack layout. */ @property (nonatomic, assign) BOOL flexGrow; /** * @abstract If the sum of childrens' stack dimensions is greater than the maximum size, should this object shrink? * Used when attached to a stack layout. */ @property (nonatomic, assign) BOOL flexShrink; /** * @abstract Specifies the initial size in the stack dimension for this object. * Default to ASRelativeDimensionAuto * Used when attached to a stack layout. */ @property (nonatomic, assign) ASDimension flexBasis; /** * @abstract Orientation of the object along cross axis, overriding alignItems * Used when attached to a stack layout. */ @property (nonatomic, assign) ASStackLayoutAlignSelf alignSelf; /** * @abstract Used for baseline alignment. The distance from the top of the object to its baseline. */ @property (nonatomic, assign) CGFloat ascender; /** * @abstract Used for baseline alignment. The distance from the baseline of the object to its bottom. */ @property (nonatomic, assign) CGFloat descender; #pragma mark - ASStaticLayoutable /** * @abstract The position of this object within its parent spec. */ @property (nonatomic, assign) CGPoint layoutPosition; @end NS_ASSUME_NONNULL_END