Skip to content

layout2-api-sizing.md

Latest commit

 

History

History
executable file
·
194 lines (160 loc) · 7.22 KB

layout2-api-sizing.md

File metadata and controls

executable file
·
194 lines (160 loc) · 7.22 KB
title Layout API Sizing
layout docs
permalink /docs/layout2-api-sizing.html
nextPage layout-transition-api.html

The easiest way to understand the compound dimension types in the Layout API is to see all the units in relation to one another.

Values (CGFloat, ASDimension)

ASDimension is essentially a normal CGFloat with support for representing either a point value, a relative percentage value, or an auto value.

This unit allows the same API to take in both fixed values, as well as relative ones.

Swift Objective-C 
// dimension returned is relative (%)
ASDimensionMake(@"50%");  
ASDimensionMakeWithFraction(0.5);
// dimension returned in points
ASDimensionMake(@"70pt");
ASDimensionMake(70);
ASDimensionMakeWithPoints(70);

// dimension returned is relative (%)
ASDimensionMake("50%")
ASDimensionMakeWithFraction(0.5)

// dimension returned in points
ASDimensionMake("70pt")
ASDimensionMake(70)
ASDimensionMakeWithPoints(70)

Example using ASDimension

ASDimension is used to set the flexBasis property on a child of an ASStackLayoutSpec. The flexBasis property specifies an object's initial size in the stack dimension, where the stack dimension is whether it is a horizontal or vertical stack.

In the following view, we want the left stack to occupy 40% of the horizontal width and the right stack to occupy 60% of the width.

We do this by setting the .flexBasis property on the two childen of the horizontal stack:

Swift Objective-C 
self.leftStack.style.flexBasis = ASDimensionMake(@"40%");
self.rightStack.style.flexBasis = ASDimensionMake(@"60%");
[horizontalStack setChildren:@[self.leftStack, self.rightStack]];

self.leftStack.style.flexBasis = ASDimensionMake("40%")
self.rightStack.style.flexBasis = ASDimensionMake("60%")

horizontalStack.children = [self.leftStack, self.rightStack]

Sizes (CGSize, ASLayoutSize)

ASLayoutSize is similar to a CGSize, but its width and height values may represent either a point or percent value. The type of the width and height are independent; either one may be a point or percent value.

Swift Objective-C 
ASLayoutSizeMake(ASDimension width, ASDimension height);
ASLayoutSizeMake(_ width: ASDimension, _ height: ASDimension)

`ASLayoutSize` is used for setting a layout element's `.preferredLayoutSize`, `.minLayoutSize` and `.maxLayoutSize` properties. It allows the same API to take in both fixed sizes, as well as relative ones.
Swift Objective-C 
// Dimension type "Auto" indicates that the layout element may 
// be resolved in whatever way makes most sense given the circumstances
ASDimension width = ASDimensionMake(ASDimensionUnitAuto, 0);  
ASDimension height = ASDimensionMake(@"50%");
layoutElement.style.preferredLayoutSize = ASLayoutSizeMake(width, height);

// Dimension type "Auto" indicates that the layout element may 
// be resolved in whatever way makes most sense given the circumstances
let width = ASDimensionMake(.auto, 0)
let height = ASDimensionMake("50%")
        
layoutElement.style.preferredLayoutSize = ASLayoutSizeMake(width, height)

If you do not need relative values, you can set the layout element's `.preferredSize`, `.minSize` and `.maxSize` properties. The properties take regular `CGSize` values.
Swift Objective-C 
layoutElement.style.preferredSize = CGSizeMake(30, 160);
layoutElement.style.preferredSize = CGSize(width: 30, height: 60)

Most of the time, you won't want to constrain both width and height. In these cases, you can individually set a layout element's size properties using `ASDimension` values.
Swift Objective-C 
layoutElement.style.width     = ASDimensionMake(@"50%");
layoutElement.style.minWidth  = ASDimensionMake(@"50%");
layoutElement.style.maxWidth  = ASDimensionMake(@"50%");
layoutElement.style.height    = ASDimensionMake(@"50%");
layoutElement.style.minHeight = ASDimensionMake(@"50%");
layoutElement.style.maxHeight = ASDimensionMake(@"50%");

layoutElement.style.width     = ASDimensionMake("50%")
layoutElement.style.minWidth  = ASDimensionMake("50%")
layoutElement.style.maxWidth  = ASDimensionMake("50%")

layoutElement.style.height    = ASDimensionMake("50%")
layoutElement.style.minHeight = ASDimensionMake("50%")
layoutElement.style.maxHeight = ASDimensionMake("50%")

Size Range (ASSizeRange)

UIKit doesn't provide a structure to bundle a minimum and maximum CGSize. So, ASSizeRange was created to support a minimum and maximum CGSize pair.

ASSizeRange is used mostly in the internals of the layout API. However, the constrainedSize value passed as an input to layoutSpecThatFits: is an ASSizeRange.

Swift Objective-C 
- (ASLayoutSpec *)layoutSpecThatFits:(ASSizeRange)constrainedSize;
func layoutSpecThatFits(_ constrainedSize: ASSizeRange) -> ASLayoutSpec

The constrainedSize passed to an ASDisplayNode subclass' layoutSpecThatFits: method is the minimum and maximum sizes that the node should fit in. The minimum and maximum CGSizes contained in constrainedSize can be used to size the node's layout elements.