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 layoutElementType

Declared 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 canLayoutAsynchronous

Declared In

ASLayoutElement.h

  style required method

A size constraint that should apply to this ASLayoutElement.

@property (nonatomic, assign, readonly) ASLayoutElementStyle *style

Declared In

ASLayoutElement.h

  debugName required method

Optional name that is printed by ascii art string and displayed in description.

@property (nullable, nonatomic, copy) NSString *debugName

Declared In

ASLayoutElement.h

– layoutThatFits: required method

Asks the node to return a layout based on given size range.

- (ASLayout *)layoutThatFits:(ASSizeRange)constrainedSize

Parameters

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)parentSize

Parameters

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)constrainedSize

Parameters

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)parentSize

Discussion

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)constrainedSize

Parameters

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