ASLayoutElement Protocol Reference
| Conforms to | ASEnvironment ASLayoutElementExtensibility ASLayoutElementPrivate ASLayoutElementStylability NSFastEnumeration |
|---|---|
| Declared in | ASLayoutElement.h |
Overview
The ASLayoutElement 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 layoutElement 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 LayoutElement protocols. These protocols contain layout options that can be used for specific layout specs. For example, ASStackLayoutSpec has options defining how a layoutElement should shrink or grow based upon available space.
These layout options are all stored in an ASLayoutOptions class (that is defined in ASLayoutElementPrivate). Generally you needn’t worry about the layout options class, as the layoutElement 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.
layoutElementType
required method
Returns type of layoutElement
@property (nonatomic, assign, readonly) ASLayoutElementType layoutElementTypeDeclared In
ASLayoutElement.h
canLayoutAsynchronous
required method
Returns if the layoutElement can be used to layout in an asynchronous way on a background thread.
@property (nonatomic, assign, readonly) BOOL canLayoutAsynchronousDeclared In
ASLayoutElement.h
style
required method
A size constraint that should apply to this ASLayoutElement.
@property (nonatomic, assign, readonly) ASLayoutElementStyle *styleDeclared In
ASLayoutElement.h
debugName
required method
Optional name that is printed by ascii art string and displayed in description.
@property (nullable, nonatomic, copy) NSString *debugNameDeclared In
ASLayoutElement.h
– layoutThatFits:
required method
Asks the node to return a layout based on given size range.
- (ASLayout *)layoutThatFits:(ASSizeRange)constrainedSizeParameters
constrainedSize |
The minimum and maximum sizes the receiver should fit in. |
|---|
Return Value
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.
Declared In
ASLayoutElement.h
– layoutThatFits:parentSize:
required method
Call this on children layoutElements to compute their layouts within your implementation of -calculateLayoutThatFits:.
- (ASLayout *)layoutThatFits:(ASSizeRange)constrainedSize parentSize:(CGSize)parentSizeParameters
constrainedSize |
Specifies a minimum and maximum size. The receiver must choose a size that is in this range. |
|---|---|
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 ASLayoutElementParentDimensionUndefined (for example, if the parent’s width depends on the child’s size). |
Return Value
An ASLayout instance defining the layout of the receiver (and its children, if the box layout model is used).
Discussion
Warning: You may not override this method. Override -calculateLayoutThatFits: instead.
Warning: In almost all cases, prefer the use of ASCalculateLayout in ASLayout
Though this method does not set the bounds of the view, it does have side effects–caching both the constraint and the result.
Declared In
ASLayoutElement.h
– calculateLayoutThatFits:
required method
Override this method to compute your layoutElement’s layout.
- (ASLayout *)calculateLayoutThatFits:(ASSizeRange)constrainedSizeParameters
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. |
|---|
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 children's 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
Declared In
ASLayoutElement.h
– calculateLayoutThatFits:restrictedToSize:relativeToParentSize:
required method
In certain advanced cases, you may want to override this method. Overriding this method allows you to receive the layoutElement’s size, parentSize, and constrained size. With these values you could calculate the final constrained size and call -calculateLayoutThatFits: with the result.
- (ASLayout *)calculateLayoutThatFits:(ASSizeRange)constrainedSize restrictedToSize:(ASLayoutElementSize)size relativeToParentSize:(CGSize)parentSizeDiscussion
Warning: Overriding this method should be done VERY rarely.
Declared In
ASLayoutElement.h
– measureWithSizeRange:
required method
Calculate a layout based on given size range. (Deprecated: Deprecated in version 2.0: Use layoutThatFits: or layoutThatFits:parentSize: if used in ASLayoutSpec subclasses)
- (nonnull ASLayout *)measureWithSizeRange:(ASSizeRange)constrainedSizeParameters
constrainedSize |
The minimum and maximum sizes the receiver should fit in. |
|---|
Return Value
An ASLayout instance defining the layout of the receiver and its children.
Declared In
ASLayoutElement.h