Litho relies on Yoga, a powerful layout engine that is able to create very complex UIs, for layout calculations. However, there are few exceptions where Yoga is not enough and you may need to implement your own measuring and layout.
Litho provides a custom layout API for accessing size information while the
ComponentTree is being created and measured, as well as the possibility to measure a component in isolation.
This API comes with a non-negligible performance overhead. Therefore, it is advisable to only use it when it is absolutely necessary.
A component layout tree depends on its own and/or children's size. For example, perhaps a component layout should use a child only if it fits within its size constraints. If the child doesn't fit, the layout should instead use another child as a fallback.
Children of a container have to be absolutely positioned manually based on their/parent size. Yoga can absolutely position children in a parent. However, the position itself might depend on the child sizes after being measured using the parent size constraints. Margins or paddings need to be manually taken into account if required.
Similar to the Android
MeasureSpec equivalent, Litho's
SizeSpec is composed of a size and a mode. The possible modes, same as for
A component can be measured in isolation for a given
Size object, passed as argument, will be populated with the resulting size.
In the following example, a
Text component is measured with unspecified
SizeSpec implying a single line of text indefinitely long.
During layout creation, the API can provide information about the
SizeSpecs a component is going to be measured with. To access this information, the
@OnCreateLayoutWithSizeSpec annotation needs to be used instead of
@OnCreateLayout. The arguments of the annotated method, besides the standard ComponentContext, are two more integers representing the width spec and the height spec.
In the following example, a
Text component is measured to check if the given text fits in the available space. An
Image component is otherwise used.
@CreateLayoutWithSizeSpec can be called more than once in cases where Yoga calls measure. If the previous layout can be used for the new size spec this call can be avoided. Implementing the
OnShouldCreateLayoutWithNewSizeSpec allows the spec to specify when the previous layout can be reused.
@OnShouldCreateLayoutWithNewSizeSpec indicates that the annotated method will be called when the component checks if it can use the previous layout with a new size spec. This is used in conjunction with
@OnCreateLayoutWithSizeSpec. The annotated method must have the following signature:
The annotated method should return
true if and only if the Layout Spec should create a new layout for the new size spec. If the method returns
false then the Component will use the previous layout. In addition, outputs can be set in
onCreateLayoutWithSizeSpec which can be referenced in
onShouldCreateLayoutWithNewSizeSpec method as follows: